First forward simulation with LMDz-SACS#

Here we run a forward simulation of LMDz-SACS Model including the comparison to observation data.

Please note here some instructions about how pyCIF deals with paths.

1. Prepare the executable#

In directory model_sources/DISPERSION_gch:

Edit compile_dispersion to select the resolution and parameter for filtering (first lines, user defined variables dim and para, available choices are detailed in the comments); save and close
Compile the fortran chemistry-transport model:

./compile_dispersion

In case of a previous compilation, running the command below ensures that previous compilations are removed before compiling again.

./compile_dispersion --clean

=> At this point, check that you obtain an executable named dispersion.e, about 30M in size.

2. Gather the input files#

Some files must be pre-processed and provided in the format directly read by LMDz-SACS:

XXXXXXXXXXXX NE GARDER ICIQUE CEUX QUI NE SONT PAS GERES PAR UN PRE-PROC OU CEUX QUI SONT A L’ORIGINE DES FICHIERS D’ENTREE MAIS DOIVENT ETRE VRAIMENT TROUVES TOUT FAITS ex: les flux de masse XXXXXXXXXXXXXX

LMDz-SACS requires multiple input files, which are generally precomputed by the online version of LMDz (for mass fluxes) or INCA (for prescribed species):

a definition of the horizontal LMDz grid and of the vertical coefficients Ap and Bp in a netcdf file
the mass fluxes, generally precomputed by the online version of LMDz
the emission files associated to each simulated tracer (or tracer family).

No simulation can run without these files.

Other files are required depending on the configuration to run.

If chemistry is taken into account, various fields are required, depending on the chemical scheme:

if any, the prescribed concentrations i.e. the concentration fields of species that react with the tracer(s). The binary files for the prescribed species (see do_chemistry) are generated by the CIF from NetCDF files with the lmdz_prescrconcs plugin.
if any, the 3d-production and loss fields (see do_chemistry) i.e. the fields of given (chemical) production and loss by chemistry not explicitly described in the chemical scheme. These are read by the CIF from NetCDF files with the lmdz_prodloss3d plugin.
if any deposited species, the associated deposition velocities (see do_chemistry) XXX a detailler dans la doc, tout comme les prescribedXXXX
the kinetic data for chemical reactions: pressure, temperatue and, if any photolysis reactions, the associated photolysis constant rates (see do_chemistry). These are read by the CIF from NetCDF files with the lmdz_photochem plugin.

Finally, a restart file is not mandatory but strongly recommended to prescribe realistic initial conditions. XX TO CHECK XX

XXXXXXXXXXXXXXXXXXXXXXX

So far, at least one observation must be provided in the last period of the simulation. To avoid running unnecessary simulations, it is indeed implemented that periods without observations are not run. The random plugin can be used to override this behavior.

3. Prepare the chemical scheme:#

The chemical scheme is a yaml file based on the following template:

 # Name of the chemical scheme
 schemeid: my_scheme

 # Active species : species to be transported in the model
 acspecies:
   SPEC1:
     restart_id: 1  # number used as ID for the species in the restart files to read/to be created
     mass: 16.0425  # molar mass
   SPEC2:
     restart_id: 3
     mass: 16.0

 # emitted species (among the active species)
 emis_species:
    SPEC1:

# State variables and J for photolysis
kinetic:
  dir: a_reference_directory
  file: file_containing_Js_prescribed_fields_and_state_variables.nc

# Prescribed species: they are not active and reacts with the emitted species
prescrconcs:
  P1:
  P2:
  P3:

# Deposited species, among the active species
deposition:
  SPEC2:
    dir: another_reference_directory
    file: file_containing_deposition_velocities

# Chemical reactions
reactions:
  r1: SPEC1+P1->AA+P2    k=1.125e-10
  r2: SPEC2+P2->BB+CC    k=3.75e-11
  r3: SPEC1+P2->CC       k(T)=Aexp(-B/T),A=2.45e-12,B=1775
  r4: SPEC1+P3->DD+EE    k(T)=Aexp(-B/T),A=7.1e-12,B=1270
  r5: SPEC2->CC          J=4

Examples: here or here

It is then necessary to check that the associated LMDz-SACS input files are available.

1. Write the YAML file :#

a. PyCIF parameters#

section for PyCIF parameters:

#####################################################################
#####################################################################
# PYCIF parameters

# Verbose level
# 1 = Debugging
# 2 = Basic information
verbose : 1

# Log file (to be saved in $wordkir)
logfile: pycif.log

# Execution directory
workdir: /absolute/path/to/working/directory

# Initial date
# Use the following compatible format for the date:
# YYYY-mm-dd or YYYY-mm-dd HH:mm:ss
datei : 2011-07-01

# End date (same as for the initial date)
datef : 2011-07-31

In this section of the YAML, it is possible to define anchors to be used in the rest of the file.

b. mode#

Here, a forward simulation is the chosen mode for running the model. At the key-word for the class (mode), the various available plugins are listed in the cheat-sheet. For the chosen plugin, here the one for running a forward simulation, the name and version of the plugin are provided and the requirements are listed. The full description of the class mode gives access to arguments. For forward, there is no mandatory argument to specify but a few optional arguments can be used; the template yaml at the end of the page provides a full list of them. In our example below, only reload_results is used so as not to have to recompute the whole simulation in case of an interruption.
#####################
# pyCIF config file #
#####################

# Define here all parameters for pyCIF following YAML syntax
# For details on YAML syntax, please see:
# http://docs.ansible.com/ansible/latest/YAMLSyntax.html

###############################################################################
# pyCIF parameters

###############################################################################

# http://community-inversion.eu/documentation/plugins/modes/forward.html

mode:
  plugin:
    name: forward
    version: std

  reload_results: true
The requirements for our forward mode are Observation operator (obsoperator) and Control vector (controlvect). They are to be specified in the next sections of the yaml file.

c. obsoperator#

Our chemistry-transport model works from the flux space to the concentration space, which corresponds to the standard choice of obsoperator. For this standard obsoperator, there is no mandatory argument to specify but a few optional arguments can be used, as shown in the full template yaml. In our example, autorestart is used.
obsoperator:
  plugin:
    name: standard
    version: std
  autorestart: True
The requirements for our standard obsperator are controlvect, datavect, model, obsvect and platform.

d. controlvect#

So far, there is only the standard possibility for controlvect. For this standard controlvect, there is no mandatory argument to specify but a few optional arguments can be used. In our example, no optional argument is activated (the default values will apply).
controlvect:
  plugin:
    name: standard
    version: std
The requirements for the standard controlvect are datavect, domain, model and obsvect.

e. model#

The lmdz plugin is used to define the LMDz parameters which requires a “controle vector” NetCDF file defining several constants for LMDz:

model:
  plugin:
    name: LMDZ
    version: std

periods: 1MS # Length of simulation sub-periods

# Convection scheme: One of :
# 'TK' = 'Tiedke'
# 'KE' = 'Kerry Emmanuel'
# 'KE-Therm' = 'Kerry Emmanuel + some thermics'
conv_scheme: TK

physic: True # Include physics
do_chemistry: True # Include chemistry

fileexec: /absolute/path/to/dispersion.e # Executable
file_controle: /absolute/path/to/LMDz_controle_vector.nc

dump: False # Dump outputs into a NetCDF file

Show/Hide controle_vector.nc

netcdf LMDz_controle_vector {
dimensions:
  index = 100 ;
variables:
  double controle(index) ;
    controle:long_name = "LMDz constant parameters" ;

data:

  controle = 96, 95, 39, 0, 2000, 6400000, 7.272205e-05, 9.8, 1004.70885,
      0.285716, 86400, 10800, 1.30538662221103e+24, 5.02451481750085e+19,
      10591741.6416624, 1.77078159248505e+21, 1.05527896355447e+27, 50000,
      101325, 0, 0, 1, 1, 1, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ;
}

f. obsvect#

So far, there is only one possibility for obsvect. For the first simulation, there is no previous file to be read but the file generated by this simulation is dumped to be used in later simulations.
obsvect:
  plugin:
    name: standard
    version: std
  dump: True
In case all the monitor.nc files to use for comparison are ready and arranged in a directory into sub-folders by type (e.g. “OMI”, “IASI”) then sub-folders by species (e.g. “CH4”, “N2O”), then it is possible to simply indicate here the root directory.
obsvect:
  plugin:
    name: standard
    version: std
  dump: True
  dir_obsvect: directory_with_perfectly_ordained_and_formatted_monitor_netcdf_files/
If the branching is empty or not right, or the files are not named “monitor.nc”, then the information will not be used. Therefore, in most cases, information for measurements is provided in datavect, in the dedicated components.

The requirements for the standard obsvect are model and datavect.

g. platform#

To specify the computing platform on which to run, so that the CIF can chose the right configuration and perform targeted operations e.g. module load the relevant modules. Here the example is set at LSCE, on the obelix cluster.
platform:
  plugin:
    name: LSCE
    version: obelix
The only requirement is the model.

h. domain#

Two files are required to specify the LMDz domain with the LMDZ grid plugin: - a grid text file containing the horizontal grid coordinates - a “vcoord” NetCDF file

# Domain definition
domain:
  plugin:
    name: LMDZ
    version: std
  filegrid: /absolute/path/to/LMDz_grid.txt
  dir_vcoord: /path/to/vcoord/directory
  file_vcoord: LMDz_vcoord.nc

Show/Hide LMDz_grid.txt

Show/Hide LMDz_voord.nc

dimensions:
  temps = UNLIMITED ; // (0 currently)
  index = 100 ;
  rlonu = 97 ;
  rlatu = 96 ;
  rlonv = 97 ;
  rlatv = 95 ;
  sig = 40 ;
variables:
  double controle(index) ;
    controle:_FillValue = NaN ;
    controle:long_name = "controle parameters" ;
  double rlonu(rlonu) ;
    rlonu:_FillValue = NaN ;
    rlonu:long_name = "u points longitude" ;
    rlonu:units = "degrees_east" ;
  double rlatu(rlatu) ;
    rlatu:long_name = "u points latitude" ;
    rlatu:units = "degrees_north" ;
  double rlonv(rlonv) ;
    rlonv:long_name = "v points longitude" ;
    rlonv:units = "degrees_east" ;
  double rlatv(rlatv) ;
    rlatv:long_name = "v points latitude" ;
    rlatv:units = "degrees_north" ;
  double ap(sig) ;
    ap:long_name = "A coefficient for pressure" ;
    ap:units = "Pa" ;
  double bp(sig) ;
    bp:long_name = "B coefficient for pressure" ;
    bp:units = "None" ;
  double cu(rlatu, rlonu) ;
  double cv(rlatv, rlonv) ;
  double aire(rlatu, rlonv) ;
    aire:long_name = "grid cell area" ;
    aire:units = "m2" ;

i. chemistry#

Chemistry is usually defined in a separeted YAML file:
# Chemical scheme
chemistry:
  file_yaml: /absolute/path/to/chemistry.yaml

j. datavect#

The datavect plugin is used to define the various inputs:

datavect:
  plugin:
    name: standard
    version: std

  components:
    concs:
      parameters:
        XX:
          ...

    inicond:
      parameters:
        XX:
          plugin:
            type: field
            name: LMDZ
            version: ic
          ...
        ...

    meteo:
      plugin:
        name: LMDZ
        version: mass-fluxes
      ...

    kinetic:
      plugin:
        type: field
        name: LMDZ
        version: photochem
      ...

    prescrconcs:
      plugin:
        type: field
        name: LMDZ
        version: prescrconcs
      parameters:
        YY:
          ...
      ...

    flux:
      parameters:
        XX:
          ...