First forward simulation with LMDz-SACS

First forward simulation with LMDz-SACS#

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

Please refer to this page for instructions on how pyCIF handles paths.

1. Prepare the executable#

In directory model_sources/DISPERSION_gch:

  • Edit compile_dispersion to select the resolution and filtering parameter (first lines; user-defined variables dim and para; available choices are described in the comments); save and close

  • Compile the fortran chemistry-transport model:

./compile_dispersion

To start from scratch in case of a previous compilation, run the command below to clean previous build artifacts before recompiling.

./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 read directly 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 is strongly recommended for prescribing realistic initial conditions.

XXXXXXXXXXXXXXXXXXXXXXX

At least one observation must be provided in the last period of the simulation. Periods without observations are skipped to avoid unnecessary computation. 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

Verify 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

This section of the YAML can also define anchors for use elsewhere in the file.

b. mode#

Here, a forward simulation is the chosen mode for running the model. Available plugins for the mode class are listed in the cheat-sheet. For the chosen plugin (forward simulation), provide its name and version, and note its requirements. The full description of the mode class lists all available arguments. For forward, no mandatory argument is required, but several optional arguments are available; the template YAML at the end of that page provides a complete list. In the example below, only reload_results is used, to avoid recomputing the whole simulation after 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 maps from flux space to concentration space, which corresponds to the standard choice of obsoperator. For this standard obsoperator, no mandatory argument is required, but several optional arguments are available, as shown in the full template YAML. In our example, autorestart is used.

obsoperator:
  plugin:
    name: standard
    version: std
  autorestart: True

The requirements for the standard obsoperator are controlvect, datavect, model, obsvect, and platform.

d. controlvect#

Currently, only the standard plugin is available for controlvect. For this standard controlvect, no mandatory argument is required, though several optional arguments are available. In this example, no optional argument is set, so default values apply.

controlvect:
  plugin:
    name: standard
    version: std

The requirements for the standard controlvect are datavect, domain, model and obsvect.

e. model#

The lmdz plugin defines the LMDz parameters. It requires a “controle vector” NetCDF file that specifies several LMDz constants:

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#

Currently, only one plugin is available for obsvect. For the first simulation, no previous file is read, but the file generated by the simulation is saved for use in later simulations.

obsvect:
  plugin:
    name: standard
    version: std
  dump: True

If all the monitor.nc files to use for comparison are ready and organized in a directory with sub-folders by type (e.g. OMI, IASI) and then by species (e.g. CH4, N2O), you can simply provide the root directory here.

obsvect:
  plugin:
    name: standard
    version: std
  dump: True
  dir_obsvect: directory_with_perfectly_ordained_and_formatted_monitor_netcdf_files/

If the directory structure is incorrect or files are not named monitor.nc, the information will not be used. In most cases, observation data is therefore provided in datavect via the dedicated components.

The requirements for the standard obsvect are model and datavect.

g. platform#

Specify the computing platform on which the simulation will run, so that the CIF can choose the right configuration and perform platform-specific operations such as module load for the relevant modules. In this example, the platform is set to 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

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 separate YAML file:

# Chemical scheme
chemistry:
  file_yaml: /absolute/path/to/chemistry.yaml

j. datavect#

The datavect plugin defines the various model 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:
          ...