#######################################################################
How to add a new formula for computing the equivalent of satellite data
#######################################################################

.. role:: bash(code)
   :language: bash

The relevant sources are in :bash:`pycif/plugins/transforms/complex/satellites`.

0. If relevant i.e. if actual satellite data using the formula are available, prepare the script to generate the :bash:`monitor.nc` file for this satellite data. For more information about the :bash:`monitor.nc` file, see :doc:`Observations</documentation/input-outputs/monitor>`.

1. Choose a number for the new formula and describe it in __init__.py (the already available formulae show how to use latex maths).

2. Implement the matching formula in apply_AK.py: 
 
   a) in apply_ak for the forward mode: the formula as such. The available variables are:
         - :bash:`sim_ak`: the model's concentrations interpolated on the satellite's vertical grid
         - :bash:`dpavgs`: the pressures of the middles of the satellite's layers, deduced from the pressures for the satellite's grid provided as "pavg0" in the :bash:`monitor.nc` file
         - :bash:`aks`: the averaging kernels provided as "ak" in the :bash:`monitor.nc` file
         - :bash:`nbformula`: the number of the formula to use
         - :bash:`qa0`: the prior profiles provided as "qa0" in the :bash:`monitor.nc` file
         - :bash:`chosenlevel`: if relevant, the number of the satellite's level to use.


   b) in apply_ak_tl for the tangent-linear: the formula is differentiated with respect to the modelled concentrations. The available variables are:
         - :bash:`sim_ak_tl`: the tangent-linear model's concentrations interpolated on the satellite's vertical grid
         - :bash:`dpavgs, aks, nbformula, qa0, chosenlevel, sim_ak`: same as for the forward mode

   c) in apply_ak_ad for the adjoint: use the TL formula to obtain the adjoint of the concentrations, :bash:`obs_incr`. The available variables are:
         - :bash:`sim_ak, dpavgs, aks, nbformula, qa0, chosenlevel`: same as for the forward mode
         - :bash:`obs_incr`: the increments on the concentrations XXX A REFORMULER? XXX


3. In case required variables are not available in apply_AK.py but are provided together with the satellite data:
     a) add matching variables in :bash:`monitor.nc` and read them in forward.py by adding their names in :bash:`colsat` (using a condition on the number of the formula if relevant). The values of the new variable are available in :bash:`sat_aks`.
     b) It is possible to also add some simple operations such as unit conversion: see example of :bash:`pavgs` converted or not into hPa. Such an operation may require adding an optional argument in the yaml section for the component :bash:`satellites`: .
          i) add the information for the new argument in :bash:`__init__.py/input_arguments`, following the example of :bash:`pressure` or :bash:`chosenlev`
          ii) retrieve the value of the argument e.g. with :bash:`transf.itsname` in forward.py
     c) Check the order of the values e.g. top/bottom for a profile. Variables :bash:`qa0` and :bash:`aks` are created from the matching fields in :bash:`sat_aks` but reversing the order - other variables provided as profiles probably require the same treatment.
     d) Pass the values of the new variable as a parameter to apply_ak
     e) modify apply_AK.py/apply_ak and apply_ak_tl according to the previous additions
     f) duplicate the modifications in forward.py into adjoint.py: the reading of new variables in :bash:`colsat`, the simple opeations if relevant and apply_AK.py/apply_ak_ad

4. Test the implementation of the formula, using a :bash:`monitor.nc` file generated according to step 0:
     a) in the forward mode: check in the output file :bash:`$WORKDIR/obsoperator/fwd_0000/obsvect/satellites/SPEC/monitor.nc` (with SPEC the name of the species, i.e. parameter in the yaml, for which the data is provided) that the simulated products "sim" are consistent compared to the provided data "obs".
     b) run a test of the tangent-linear XXXnot yet re-implemented?XXX
     c) **run a test of the adjoint of the new formula**.

5. XXXpossibility of implementing this in the CIF as a recognized format of obs, same as for surface obs?XXXX