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 XXX written by previous simus? coming from restart,nc? Quel format? renvoyer vers output de LMDz dans la doc?XXX

  • 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 XXX a detailler dans la doc, tout comme les prescribedXXXX

  • 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)XXX a detailler dans la doc, tout comme les prescribedXXXX

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

XXXXXXXXXXXXXXXXXXXXXXX

So far, a monitor file with a least one observation in the last period of the simulation (see XXXXbelow) is required by the CIF. To avoid running unnecessary simulations, it is indeed implemented that periods without observations are not run. Useful feature or not?

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 :

  1. section for PyCIF parameters:

    #####################################################################
    #####################################################################
    # PYCIF parameters
    
    # Verbose level
    # 1 = Basic information
    # 2 = Debugging
    verbose : 1
    
    # Log file (to be saved in $wordkir)
    logfile: test_std
    
    # Execution directory
    workdir: /home/chimereicos/ipison/test_chimere_cif_n2o/
    
    # 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.

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

    mode:
      plugin:
        name: forward
        version: std
    

    The requirements for our forward mode are obsoperator XXpeut-on renvoyer a une section par son numero??XX and controlvect. They are to be specified in the next sections of the yaml file.

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

    #####################################################################
    #####################################################################
    # Observation operator
    # Used to run the model and translates information from model/measurement
    # spaces to control/observation spaces
    obsoperator:
      plugin:
        name: standard
        version: std
      autorestart: True
    

    The requirements for our standard obsperator are controlvect, datavect, model, obsvect and platform.

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

  5. model

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

    #####################################################################
    #####################################################################
    # Observation vector and observation uncertainties if needed
    # Also projects information from the observation to the model space
    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.

    #####################################################################
    #####################################################################
    # Observation vector and observation uncertainties if needed
    # Also projects information from the observation to the model space
    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 (see j V).

    The requirements for the standard obsvect are model (e) and datavect (j)

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

  8. domain

    ?

  9. chemistry

    ?

  10. datavect