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

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

  1. If relevant i.e. if actual satellite data using the formula are available, prepare the script to generate the monitor.nc file for this satellite data. For more information about the monitor.nc file, see Observations.

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

  3. Implement the matching formula in apply_AK.py:

    1. in apply_ak for the forward mode: the formula as such. The available variables are:
      • sim_ak: the model’s concentrations interpolated on the satellite’s vertical grid

      • 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 monitor.nc file

      • aks: the averaging kernels provided as “ak” in the monitor.nc file

      • nbformula: the number of the formula to use

      • qa0: the prior profiles provided as “qa0” in the monitor.nc file

      • chosenlevel: if relevant, the number of the satellite’s level to use.

    2. in apply_ak_tl for the tangent-linear: the formula is differentiated with respect to the modelled concentrations. The available variables are:
      • sim_ak_tl: the tangent-linear model’s concentrations interpolated on the satellite’s vertical grid

      • dpavgs, aks, nbformula, qa0, chosenlevel, sim_ak: same as for the forward mode

    3. in apply_ak_ad for the adjoint: use the TL formula to obtain the adjoint of the concentrations, obs_incr. The available variables are:
      • sim_ak, dpavgs, aks, nbformula, qa0, chosenlevel: same as for the forward mode

      • obs_incr: the increments on the concentrations XXX A REFORMULER? XXX

  4. In case required variables are not available in apply_AK.py but are provided together with the satellite data:
    1. add matching variables in monitor.nc and read them in forward.py by adding their names in colsat (using a condition on the number of the formula if relevant). The values of the new variable are available in sat_aks.

    2. It is possible to also add some simple operations such as unit conversion: see example of pavgs converted or not into hPa. Such an operation may require adding an optional argument in the yaml section for the component satellites: .
      1. add the information for the new argument in __init__.py/input_arguments, following the example of pressure or chosenlev

      2. retrieve the value of the argument e.g. with transf.itsname in forward.py

    3. Check the order of the values e.g. top/bottom for a profile. Variables qa0 and aks are created from the matching fields in sat_aks but reversing the order - other variables provided as profiles probably require the same treatment.

    4. Pass the values of the new variable as a parameter to apply_ak

    5. modify apply_AK.py/apply_ak and apply_ak_tl according to the previous additions

    6. duplicate the modifications in forward.py into adjoint.py: the reading of new variables in colsat, the simple opeations if relevant and apply_AK.py/apply_ak_ad

  5. Test the implementation of the formula, using a monitor.nc file generated according to step 0:
    1. in the forward mode: check in the output file $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”.

    2. run a test of the tangent-linear XXXnot yet re-implemented?XXX

    3. run a test of the adjoint of the new formula.

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