Context Navigation

CheckList

Timestamp:: 2020-06-03T17:16:45+02:00 (4 years ago)
Author:: luyssaert
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

Documentation/UserGuide/CheckList

-                      v35
+                      v36
 ''' 1a) On a machine maintained by the IPSL team'''
 It can be at TGCC (irene), LSCE (obelix), IDRIS (jean-zay), IPSL mesocentre (ciclad/climserv), anywhere libIGCM is maintained by the IPSL team. You first need to obtain a login. At TGCC and IDRIS, you need to be part of an existing project or set up a new one to obtain a login. You need to contribute to the annual request for computing resources and the annual report of consumed cpu time for the previous year.
+The big advantage of using one of the machines maintained by the IPSL team is that you will have access to all essential libraries (i.e. XIOS) and data files (different climate forcing files, different PFT maps, different soil maps, etc.). Such machines are at TGCC (irene), LSCE (obelix), IDRIS (jean-zay), IPSL mesocentre (ciclad/climserv), anywhere libIGCM is maintained by the IPSL team. You first need to obtain a login and for this restrictions apply. At TGCC and IDRIS, you need to be part of an existing project and working in France to be eligible to obtain a login. You will also have to contribute to the annual request for computing resources and the annual report of consumed cpu time for the previous year.
+Before starting to install the model, you must set up the proper environment (paths, modules).
+Read more here, which covers all the standard platforms supported by the IPSL:  https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/DocBenv
+Once you obtained a login for any of the aforementioned serves, you must set up the proper environment (paths, modules) before you will be able to correctly install the model. Read more here, which covers all the standard platforms supported by the IPSL:  https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/DocBenv
 ''' 1b) Else you're pretty much on you own'''
 …
 The best way is to use svn to download a referenced version of the code (trunk, tag, branch, perso). By using SVN, you can easily change between model versions (more information on SVN is found [https://forge.ipsl.jussieu.fr/orchidee/attachment/wiki/Documentation/UserGuide/svn10min_Ghattas_20140612.pdf in this PDF]), as well as incorporate bug fixes and updates from others.  In this case, each version is referenced by a revision number, which corresponds to different source code, but also to potentially different "keywords" and their default values (more in 4).  Therefore, only tests between identical revisions can be expected to be identical.
 Some revisions are "tagged" (e.g., ORCHIDEE 2.0).  A tagged revision is considered stable and does not change.  Other revisions are likely undergoing continual development and modification, with occasional commits breaking them.  Branches are "forks" from the main code (referred to as the "trunk"), in which developers are adding new features.  It takes significant effort and knowledge of the code base to merge some of these features, which means not every feature is present in every revision of ORCHIDEE.  Selecting a revision and branch should therefore take into account the research questions you are trying to address.  These pages contain further information on the [https://forge.ipsl.jussieu.fr/orchidee/wiki/SourceCode trunk] as well as the [https://forge.ipsl.jussieu.fr/orchidee/wiki/DevelopmentActivities branches].
+Some revisions are "tagged" (e.g., ORCHIDEE 2.0).  A tagged revision is considered stable and does not change.  Other revisions are likely undergoing continual development and modification, with occasional commits breaking them.  Branches are "forks" from the main code (referred to as the "trunk"), in which developers are adding new features.  It takes significant effort and knowledge of the code base to merge some of these features, which means not every feature is present in every revision of ORCHIDEE. Selecting a revision and branch should therefore take into account the research questions you are trying to address.  These pages contain further information on the [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/TrunkFunctionality4 trunk], [https://forge.ipsl.jussieu.fr/orchidee/wiki/SourceCode Tag2.0] as well as the [https://forge.ipsl.jussieu.fr/orchidee/wiki/DevelopmentActivities branches].
 The ORCHIDEE model is flexible, with many features controlled by input files.  The model also requires additional information (e.g., spatial and temporal extents) and input data (often called, "forcing files," including meteorological forcing data) in order to run.  The collection of input files that direct model behavior are referred to as the configuration.  More information on configurations is found below.
 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 take advantage of the "externalization" feature and define the parameters as keywords that can be defined in your PARAM/run.def, see  4a, 4d).
+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 if you want to run two simulations with same code but for hard-coded parameters (but in this case, it is often better to take advantage of the "externalization" feature and 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 4b). Since these options are not hard-coded, you can change them without recompiling. But they control your results, and you need to know them to explain your model version.
+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, PARAM/run.def (for older versions of the model including Tag2.0) and PARAM/orchidee.def (for the trunk; see 4b). Since these options are not hard-coded, you can change them without recompiling. But they affect your results, and you need to know them to explain your model version.
 These options depend in general on the branch of ORCHIDEE you are using. As a (non exhaustive) example, the following ones are available in the CMIP6 trunk (now tagged 2.0):
+These options depend in general on the branch of ORCHIDEE you are using. As a (non exhaustive) example, the following ones are available in the tagged 2.0 (which is the version used for CMIP6):
 - '''use the STOMATE module''', owing to which vegetation grows and responds to climatic conditions (STOMATE_OK_STOMATE, defined in config.card or PARAM/run.def)
 - '''activate the dynamic global vegetation model (DGVM)''', where the fraction of a grid cell covered by vegetation changes with climatic conditions (STOMATE_OK_DGVM in PARAM/run.def)
 …
 - activate soil_freezing, etc... (more details on flags and keywords in 4c)
+A rather comprehensive list of options that were added to the trunk since tag 2.0 can be found [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/TrunkFunctionality4 here]
 NOTE:  not all of these components can be activated at the same time and still give reliable results. Besides, somes options depend on some others ([wiki:Documentation/UserGuide/UserDefinedSoilParameters example]). It's important to test the configuration you select.
+NOTE:  not all of these components can be activated at the same time and still give reliable results. Besides, some options depend on some others ([wiki:Documentation/UserGuide/UserDefinedSoilParameters example]). It's important to test the configuration you select.
 ''' 2c) If you changed the code '''
 …
 Your are advised to test your code as much as possible before running large simulations:
 - compile and run over a couple days in [wiki:Documentation/UserGuide/flags debug mode] (for long simulations over large domains, debug mode in not advised as it make the execution much slower)
+- anticipate that a lot of time and efforts will be required to make the model run globally. A successful pixel run is by no means a valid indication that the model works at large scales. There are typically many exceptions that needs to be dealt with.
 - if your model crashes, turn to the [wiki:Documentation/UserGuide#Debuggingandprofiling Debug section] of the documentation
 If your model runs, check it runs correctly:
+- conservation, restartability (1+1=2)
+- water, carbon, nitrogen and energy much be conserved, the model must be restartable (1+1=2) and the results must be identical irrespective of the number of processors that was used in the calculations.
+- think of sanity checks and ensure that the when the model is run without your changes, the results have not changed compared to the revision you based your developments on.
 - verify that your results make sense compared to the revision you based your developments on
 == 3) Installation and compilation ==
 Read here about to download ORCHIDEE for offline (i.e., driven by separate meteorological forcing files) use: [wiki:Documentation/UserGuide/InstallingORCHIDEEBasic]. Information for downloading the [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/UserGuide/ORCHIDEEDOFOCOInstall CAN] and [https://forge.ipsl.jussieu.fr/orchidee/wiki/DevelopmentActivities/ORCHIDEE-CNP CNP] branches of ORCHIDEE also exists and can likely be adapted for any branch, but note that permission to access branches is generally restricted.
+Read here about how to download ORCHIDEE for offline (i.e., driven by separate meteorological forcing files) use: [wiki:Documentation/UserGuide/InstallingORCHIDEEBasic]. Information for downloading the  [https://forge.ipsl.jussieu.fr/orchidee/wiki/DevelopmentActivities/ORCHIDEE-CNP CNP] branch of ORCHIDEE also exists and can likely be adapted for any branch, but note that permission to access branches is generally restricted.
 The same method is used for offline and coupled configurations, where "coupled" typically refers to coupling ORCHIDEE to an atmospheric model that generates meteorological data at every time step. Find the full documentation about installation and using of IPSL-cmc coupled models [https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/Doc here], or go directly to a brief description of the [https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/DocHconfigBlmdzorv6 LMDZOR_v6 configuration] (LMDZ coupled to ORCHIDEE).
 …
 '''4a) The simplest option if you use libIGCM is to use a predefined configuration'''
+'''4a) The simplest option is to use predefined libIGCM configuration  '''
+They were defined for the [wiki:ReferenceSimulations reference simulations], each corresponding to a different [https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/Doc/Setup#Contentsofthesubmissiondirectory submission directory] in modipsl/config/ORCHIDEE_OL/:
+- ENSEMBLE to run an ensemble of 1D simulations at FLUXNET sites ([wiki:Documentation/UserGuide/FLUXNETValidation more details])
+- SPINUP_ANALYTIC_FG1, OOL_SEC_STO_FG1trans, OOL_SEC_STO_FG2, which are designed to be used one after the other to run a simulation with CRU-NCEP atmospheric forcing and the long spinup required for the carbon cycle ([wiki:Documentation/UserGuide/SpinUpCarbon#StandardprotocolforCarbon-relatedvariables more details])
+- [browser:tags/ORCHIDEE_2_0/ORCHIDEE_OL/OOL_SEC_STO_FG3 OOL_SEC_STO_FG3], for a run without spin-up (default restart state) under the WFDEI_GPCC atmospheric forcing
+- [browser:tags/ORCHIDEE_2_1/ORCHIDEE_OL/OOL_SEC_STO_FG3nd OOL_SEC_STO_FG3nd], for a run like FG3 but with the [wiki:Documentation/Forcings#a0.Generalinformation new driver] developped by Jan Polcher (this configuration is available starting at tag2.1)
+Several of these configurations are used in the [wiki:ReferenceSimulations reference simulations], each corresponding to a different [https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/Doc/Setup#Contentsofthesubmissiondirectory submission directory] in modipsl/config/ORCHIDEE_OL/. A detailed description of each of these configurations is listed [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/TrunkFunctionality4#Configurationsr6614 here]
+- ENSEMBLE to run at FLUXNET sites
+- SPINUP_ANALYTIC_FG1, OOL_SEC_STO_FG1trans, OOL_SEC_STO_FG2, which are designed to be used one after the other to run a simulation with CRU-NCEP atmospheric forcing and the long spinup required for the carbon and nitrogen cycle ([wiki:Documentation/UserGuide/SpinUpCarbon#StandardprotocolforCarbon-relatedvariables more details])
+- OOL_SEC_STO_FG3, for a run without spin-up (default restart state) under the WFDEI_GPCC atmospheric forcing
+- OOL_SEC_STO_FG3nd, for a run like FG3 but with the [wiki:Documentation/Forcings#a0.Generalinformation new driver] developped by Jan Polcher (this configuration is available starting at tag2.1)
+- OOL_SEC_STO_FG4 and OOL_SEC_STO_FG5 to use age classes, species-level PFTs, diameter classes, forest management, litter raking, species changes, management changes, etc
 - [browser:tags/ORCHIDEE_2_0/ORCHIDEE_OL/OOL_SEC OOL_SEC], without STOMATE (no dynamic phenology nor nutrient cycles).