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:

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.

4. 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.

Show/Hide Code

#####################
# 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.

Show/Hide Code

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).

Show/Hide Code

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.

Show/Hide Code

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

97
-180
-176.25
-172.5

...

172.5
176.25
180
96
90
88.1053
86.2105

...

-86.2105
-88.1053
-90
12 6

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:

Show/Hide code

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:
          ...