Check list to prepare your simulation: configuration, input files, keywords, etc.

The goal of this howto is to sum up what you should not forget to run a simulation (for students and even for more experienced users).

The examples of this page are focused on offline simulations with ​libIGCM ("infrastructure développée à l'IPSL pour accéder, lancer et enchaîner simulation et post-traitements pour une simulation type"). Links to particular files are given for tag2.0​ (created in March 2018 for CMIPv1).

This checklist is also valid in other cases (LMDZOR, no libIGCM), although the details won't hold.

1) On which machine do I want to run?

It can be at TGCC(irene), LSCE(obelix), IDRIS(ada), IPSL mesocentre(ciclad/climserv), where libIGCM is maintained by the IPSL team. You first need to obtain a login. At TGCC and IDRIS, you need to integrate an existing project or set up a new one to obtain a login. You need to participate in the yearly demand for computing resources and the report of consumed cpu time for the previous year.

Before starting to install the model, it requires to set up the proper environment (paths, modules).

Read more here: ​https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/DocBenv

You can also run on your local linux machine, but in this case, you will have to deal alone with your running environment: libraries, compiler, etc. Find some information here: ​https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/DocBenv#HowtousetheIPSLmodelsandtoolswithalocalPC

2) Which code do I want to run?

2a) Choosing a revision

The best way is to use svn to download a referenced version of the code (trunk, tag, branch, perso). In this case, each version is referenced via a revision number, which corresponds to a different code, but also to potentially different "keywords" and their default values (more in 4). * Explain the links between the code and config...?

ADVICE: If you want to run two versions of ORCHIDEE (e.g. a new development and the reference version it originates from), you are strongly advised to create two different directories (e.g. NEW/modipsl/... and REF/modipsl/...). It's also the case of you want to run two simulations with same code but for hard-coded parameters (but in this case, it is often better to define the parameters as keywords that can be defined in your PARAM/run.def, see 4a, 4d).

2b) Code options not decided by a revision

The code of ORCHIDEE includes many "code" options, i.e. options to execute some parts of the code or not. These options are controlled by some configuration files, mostly config.card and PARAM/run.def (see 4a). In particular:

• old or new driver (for offline simulations, to deal with meteorological input files) *how is it set?
• use stomate or not (defined in config.card)
• activate DGVM, activate soil_freezing, etc... * complete the list, give the keywords

3) Installation and compilation

Read here about to download ORCHIDEE for offline use: Documentation/UserGuide/InstallingORCHIDEEBasic

The same method is used for offline and coupled configurations. Find the full documentation about installation and using of IPSL-cmc coupled models here: ​https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/Doc

or go directly to a brief description of the LMDZOR_v6 configuration (LMDZ coupled to ORCHIDEE) ​https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/DocHconfigBlmdzorv6

Always recompile your code if you made changes in the fortran code.

4) Configuration of your simulation

4a) The simplest option if you use libIGCM is to use a predefined configuration (in modipsl/config/ORCHIDEE_OL/). Each of the subdirectories constains the required elements to run a particular offline simulation:

• config.card​ => to choose the name, length, restart of your simulation (link to more details)
• PARAM/run.def​ => the choose the options of your simulation, via the "keywords". The number of these keywords is huge, and it has a large effect on the outcome of your simulation. The default values depend on the revision (see 2).
• COMP/orchidee_ol.card​ => defines the meteorological forcing files and your xml files (for xios) * explain howto run without xios; is there an howto to explain this?
• COMP/sechiba.card​ => defines the other input files, and some important user option for sechiba:
  • do we change the vegetation map every year of not (VEGET_UPDATE)?
  • frequency of the output and name of the corresponding output files
  • the last part of the file is about post-processing * is there an howto to explain this?
• COMP/stomate.card​ => defines some important user option for stomate:
  • do we use teh analytical spinup (SPINUP_ANALYTIC) ?
  • frequency of the output and name of the corresponding output files
  • the last part of the file is about post-processing * is there an howto to explain this?

4b) To create your own configuration, the simplest way is to modify an existing configuration: copy the corresponding directory with a new name in your modipsl/config/ORCHIDEE_OL/ and change what you want

4c) More on keywords

Give definition (externalized parameters), and explain the ones to be careful with after the merge to CN. * Explain more, links

ADVICE: Create a new directory in your modipsl/config/ORCHIDEE_OL/ for each different run you want to keep in the end. It's the case for instance if you want to run one ORCHIDEE with different parameter sets using the keywords to define the parameters.

4d) Spinup and initialization

A simulation requires initial conditions, which are defined by section #D-- Restarts - in config.card​.

There are two options: Restart = n ("from scratch" with arbitrary initial values) vs. Restart = y (we use state variables from a pre-existing simulation as initial conditions; only works if the two simulations have the same horizontal and vertical resolution, and the same processes thus state variables). In both cases, we usually need some warmup or spinup, unless we are just pursuing a simulation.

For the Carbon cycle spinup (bring all C pools into equilibrium recycling possibly some climate forcing) see Documentation/UserGuide/SpinUpCarbon

5) Run your simulation

Job, queues, etc. * Explain more, links

If your simulation crashes * Explain more, links, use of run.card, etc.

6) How to get some help

Step 1: Documentation and howto pages, training sessions, ...

Step 2: Ask your supervisor or close collaborators

Step 3: orchidee-help

7) Analyse your results

If your simulation(s) have run, you probably want to look at it(them)...

• Basic checks (global mean values compared to reference simulations and observations; water conservation and twbr, etc.)
• More on model evaluation and benchmarks * Explain more, links

8) How to archive your developments?

If your developments proved interesting, the ORCHIDEE community would be happy to benefit from them:

• Presentation of your results (share your report or paper, invite the group to your seminar/defense, present a talk an ORCHIDEE weekly of DEV meeting)
• Backup your development via svn on a branch or perso directory
• For inclusion in the trunk, this has to be proposed to the ORCHIDEE-Project group