Context Navigation

← Previous Change
Wiki History
Next Change →

CheckList

Timestamp:: 2024-10-15T15:11:51+02:00 (4 months ago)
Author:: abierjon
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

Documentation/UserGuide/CheckList

-                      v40
+                      v41
 == Objective ==
 The objective of this item is to sum up what you remember when running a simulation. The item is written for students and even for more experienced users. The examples of this page are oriented towards offline simulations with [http://forge.ipsl.jussieu.fr/libigcm/wiki/WikiStart 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 [browser:tags/ORCHIDEE_2_0/ tag2.0] (created in March 2018 for CMIPv1). This checklist is largely valid for other model configurations such as LMDZOR or when running without making use of libIGCM. In those cases the details will most likley not hold.
+The objective of this item is to sum up what you remember when running a simulation. The item is written for students and even for more experienced users. The examples of this page are oriented towards offline simulations with [http://forge.ipsl.fr/libigcm/wiki/WikiStart 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 [browser:tags/ORCHIDEE_2_0/ tag2.0] (created in March 2018 for CMIPv1). This checklist is largely valid for other model configurations such as LMDZOR or when running without making use of libIGCM. In those cases the details will most likley not hold.
 == 1) On which machine do I want to run? ==
 …
 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.
 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
+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.fr/igcmg_doc/wiki/DocBenv
 ''' 1b) Else you're pretty much on you own'''
 You can also run on your local **linux** machine, but in this case, you will have to manage your running environment yourself: libraries, compiler, etc. Find some information [https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/DocBenv#HowtousetheIPSLmodelsandtoolswithalocalPC here], in addition to some of the links below (Installation and compilation). Please note that if you choose this option you may receive less support from the orchidee group. Except for specific reason this option is not recommended.
+You can also run on your local **linux** machine, but in this case, you will have to manage your running environment yourself: libraries, compiler, etc. Find some information [https://forge.ipsl.fr/igcmg_doc/wiki/DocBenv#HowtousetheIPSLmodelsandtoolswithalocalPC here], in addition to some of the links below (Installation and compilation). Please note that if you choose this option you may receive less support from the orchidee group. Except for specific reason this option is not recommended.
 == 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). 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.
+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.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/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].
+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.fr/orchidee/wiki/Documentation/TrunkFunctionality4 trunk], [https://forge.ipsl.fr/orchidee/wiki/SourceCode Tag2.0] as well as the [https://forge.ipsl.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.
 …
 - 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]
+A rather comprehensive list of options that were added to the trunk since tag 2.0 can be found [https://forge.ipsl.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, some options depend on some others ([wiki:Documentation/UserGuide/UserDefinedSoilParameters example]). It's important to test the configuration you select.
 …
 == 3) Installation and compilation ==
 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.
+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.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).
+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.fr/igcmg_doc/wiki/Doc here], or go directly to a brief description of the [https://forge.ipsl.fr/igcmg_doc/wiki/DocHconfigBlmdzorv6 LMDZOR_v6 configuration] (LMDZ coupled to ORCHIDEE).
 Always recompile your code if you make changes in the fortran code. Further information on compiling ORCHIDEE can be found [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/UserGuide/CompileMethods here].
+Always recompile your code if you make changes in the fortran code. Further information on compiling ORCHIDEE can be found [https://forge.ipsl.fr/orchidee/wiki/Documentation/UserGuide/CompileMethods here].
 == 4) Configuration of your simulation ==
 …
 '''4a) The simplest option is to use predefined libIGCM configuration  '''
 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#Configurations here]
+Several of these configurations are used in the [wiki:ReferenceSimulations reference simulations], each corresponding to a different [https://forge.ipsl.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.fr/orchidee/wiki/Documentation/TrunkFunctionality4#Configurations 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])
 …
 '''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:
 - config.card => to choose the name, length, restart of your simulation ([https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/Doc/Setup#config.card more details])
 - PARAM/run.def, PARAM/orchidee.def and PARAM/orchidee_pft.def => Prior to r6616 the information contained in these three files was combined in a single file called PARAM/run.def. Since r6616 three different files have been defined to better match what is being done in LMDzOR. The concept and many details on these three files can be found  [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/TrunkFunctionality4#Parameterfiles here]. The basic idea is that those files enable the users to choose the options of their simulation, via "keywords". These keywords can be a flag (y or n to activate them or not) or they can be parameters values that you can change without recompiling the model. 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). More details on [https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/Doc/Setup#PARAMdirectory run.def] and see 4c for a list of keywords.
 - COMP/orchidee_ol.card => defines the meteorological forcing files and xml files (the latter of which are only used with XIOS; ORCHIDEE can also be run [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/UserGuide/DeactivateXIOS without XIOS], though it is not recommended). The list of available atmospheric forcing datasets is regularly updated [wiki:Documentation/Forcings here].
 - COMP/sechiba.card => defines the other input files ([https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/Ancillary list of available datasets]), and some important user option for sechiba:
+- config.card => to choose the name, length, restart of your simulation ([https://forge.ipsl.fr/igcmg_doc/wiki/Doc/Setup#config.card more details])
+- PARAM/run.def, PARAM/orchidee.def and PARAM/orchidee_pft.def => Prior to r6616 the information contained in these three files was combined in a single file called PARAM/run.def. Since r6616 three different files have been defined to better match what is being done in LMDzOR. The concept and many details on these three files can be found  [https://forge.ipsl.fr/orchidee/wiki/Documentation/TrunkFunctionality4#Parameterfiles here]. The basic idea is that those files enable the users to choose the options of their simulation, via "keywords". These keywords can be a flag (y or n to activate them or not) or they can be parameters values that you can change without recompiling the model. 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). More details on [https://forge.ipsl.fr/igcmg_doc/wiki/Doc/Setup#PARAMdirectory run.def] and see 4c for a list of keywords.
+- COMP/orchidee_ol.card => defines the meteorological forcing files and xml files (the latter of which are only used with XIOS; ORCHIDEE can also be run [https://forge.ipsl.fr/orchidee/wiki/Documentation/UserGuide/DeactivateXIOS without XIOS], though it is not recommended). The list of available atmospheric forcing datasets is regularly updated [wiki:Documentation/Forcings here].
+- COMP/sechiba.card => defines the other input files ([https://forge.ipsl.fr/orchidee/wiki/Documentation/Ancillary list of available datasets]), 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 [https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/Doc/Running#Simulation-Postprocessing post-processing]
+    * the last part of the file is about [https://forge.ipsl.fr/igcmg_doc/wiki/Doc/Running#Simulation-Postprocessing post-processing]
 - COMP/stomate.card => defines some important user option for stomate:
     * do we use the analytical spinup? (SPINUP_ANALYTIC, see wiki:Documentation/UserGuide/SpinUpCarbon)
     * frequency of the output and name of the corresponding output files
     * the last part of the file is about [https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/Doc/Running#Simulation-Postprocessing post-processing]
+    * the last part of the file is about [https://forge.ipsl.fr/igcmg_doc/wiki/Doc/Running#Simulation-Postprocessing post-processing]
 …
 The list of the keywords related externalized parameters is different for different versions of the code:
 - trunk up to v2.2 : [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/OrchideeParameters list of parameters] and [https://docs.google.com/spreadsheets/d/1DYVvvqxVoXFAqA_M_hvkd-Ooru6ZQ32Lz2oa8oKKA5E/edit#gid=1984497631 recommended range of values]
 - trunk v4.0 (since r6616): [http://forge.ipsl.jussieu.fr/orchidee/browser/trunk/ORCHIDEE/orchidee.default list of parameters]
+- trunk up to v2.2 : [https://forge.ipsl.fr/orchidee/wiki/Documentation/OrchideeParameters list of parameters] and [https://docs.google.com/spreadsheets/d/1DYVvvqxVoXFAqA_M_hvkd-Ooru6ZQ32Lz2oa8oKKA5E/edit#gid=1984497631 recommended range of values]
+- trunk v4.0 (since r6616): [http://forge.ipsl.fr/orchidee/browser/trunk/ORCHIDEE/orchidee.default list of parameters]
 WARNING:  some options or parameters depend on other options. It's important to test the configuration you select. [wiki:Documentation/UserGuide/UserDefinedSoilParameters Example].
 …
 A simulation requires initial conditions, which are defined by section #D-- Restarts - in the 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 spinup, unless we are just pursuing a simulation. Read more on the ways to set up your spinup on [wiki:Documentation/UserGuide/SpinUpCarbon Spinup : why, how and how long? The answer depends on the ORCHIDEE component].  It is also possible to do an [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/UserGuide/SpinupInJobBasic analytical spinup] that is faster.
+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 spinup, unless we are just pursuing a simulation. Read more on the ways to set up your spinup on [wiki:Documentation/UserGuide/SpinUpCarbon Spinup : why, how and how long? The answer depends on the ORCHIDEE component].  It is also possible to do an [https://forge.ipsl.fr/orchidee/wiki/Documentation/UserGuide/SpinupInJobBasic analytical spinup] that is faster.
 '''4e) Output'''
 ORCHIDEE output is controlled by separate modules, referred to as XIOS ([[https://forge.ipsl.jussieu.fr/orchidee/wiki/DevelopmentActivities/ORCHIDEE-CNP here] PDF] and [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/UserGuide/XIOSinConfig webpage]) and IOIPSL.  These modules greatly improve reading and writing data for large simulations, although the benefits may not be seen for single pixel and thus a single CPU run.
+ORCHIDEE output is controlled by separate modules, referred to as XIOS ([[https://forge.ipsl.fr/orchidee/wiki/DevelopmentActivities/ORCHIDEE-CNP here] PDF] and [https://forge.ipsl.fr/orchidee/wiki/Documentation/UserGuide/XIOSinConfig webpage]) and IOIPSL.  These modules greatly improve reading and writing data for large simulations, although the benefits may not be seen for single pixel and thus a single CPU run.
 If you want to change the variables that are output by your simulation, read the dedicated section [wiki:Documentation/UserGuide#Historyoutputfiles History/output files].
 …
 libIGCM is the environment that makes it easier to run simulations: gathering the required input files, copying them to the run directory, running the simulation, and then storing the output, in particular for multiple year simulations where you would otherwise have to manually copy restart files and name them appropriately.  The [wiki:Documentation/UserGuide#DifferentwaystoconfiguresimulationswithlibIGCM libIGCM section] of the HowTo has additional information about manipulating libIGCM in special cases.
 It is possible to run [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/UserGuide/TestCase1 simple offline test cases] and [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/UserGuide/TestCaseBatch larger parallel jobs] without libIGCM.  This can be useful when you are debugging your code.
+It is possible to run [https://forge.ipsl.fr/orchidee/wiki/Documentation/UserGuide/TestCase1 simple offline test cases] and [https://forge.ipsl.fr/orchidee/wiki/Documentation/UserGuide/TestCaseBatch larger parallel jobs] without libIGCM.  This can be useful when you are debugging your code.
 Job, queues, etc. [https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/DocFsimu][[BR]]
+Job, queues, etc. [https://forge.ipsl.fr/igcmg_doc/wiki/DocFsimu][[BR]]
 LSCE specific: batch system & jobs submission [https://intranet.lsce.ipsl.fr/informatique/en/calcul/batch.php]
 If your simulation crashes you will first need to decide whether the crash was caused by libIGCM or by ORCHIDEE itself. One easy (rather solid) way is to check your configuration folder (config/ORCHIDEE_OL/MYTEST). If a Debug folder was added it was ORCHIDEE that crashed. To be 100% sure open the Script-file in your configuration folder and search for ERROR. If the error refers to orchidee_ol.ksh it was ORCHIDEE that crashed.
 - If it was libIGCM that crashed, carefully read the error log in the Script file. Most often it will be a trivial problem such as a typo in a file name or a path. Guidelines to understand the logs produced by libIGCM can be found  [https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/Doc/CheckDebug here]
+- If it was libIGCM that crashed, carefully read the error log in the Script file. Most often it will be a trivial problem such as a typo in a file name or a path. Guidelines to understand the logs produced by libIGCM can be found  [https://forge.ipsl.fr/igcmg_doc/wiki/Doc/CheckDebug here]
 - If it was ORCHIDEE that crashed and you were using a single processor simply rerun the model after compiling it in debug mode. The model will of crash again (but not necessarily in the same place because PROD will not crash on divide by zero where DEBUG will crash) and will get an error-stack. This stack will tell you in which line the model crashed. The line number refers to some processed files that can be found in modeles/ORCHIDEE/build/ppcr/... but as a rule of thumb you need to subtract 9 lines from the error stack to get the correct line number in modeles/ORCHIDEE/scr_*/*.f90.
 - You can also make use of [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/TrunkFunctionality4#Consistencychecks the internal consistency checks] (starting r6616) to get an idea where the model crashes.
 - If the above options does not reveal the problem some serious debugging will be required. Look at the [wiki:Documentation/UserGuide#Debuggingandprofiling Debugging section] on the [https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/UserGuide HowTo], starting with the [wiki:Documentation/UserGuide/flags introductory page on debug flags].
 - The [https://forge.ipsl.jussieu.fr/igcmg_doc/wiki/Doc/Setup#config.card TEST and DEVT options in config.card] can be useful as they keep more log files accessible
+- You can also make use of [https://forge.ipsl.fr/orchidee/wiki/Documentation/TrunkFunctionality4#Consistencychecks the internal consistency checks] (starting r6616) to get an idea where the model crashes.
+- If the above options does not reveal the problem some serious debugging will be required. Look at the [wiki:Documentation/UserGuide#Debuggingandprofiling Debugging section] on the [https://forge.ipsl.fr/orchidee/wiki/Documentation/UserGuide HowTo], starting with the [wiki:Documentation/UserGuide/flags introductory page on debug flags].
+- The [https://forge.ipsl.fr/igcmg_doc/wiki/Doc/Setup#config.card TEST and DEVT options in config.card] can be useful as they keep more log files accessible
 == 6) How to get some help? ==
 …
 - Some validation data have been collected and harmonized by the ORCHIDEE group, see more info on [wiki:Documentation/Validation]
 - Tools are available to evaluate to model such as CLIMAF ([https://github.com/jservonnat/C-ESM-EP/wiki/The-C-ESM-EP-in-a-nutshell How to run C-ESM-EP atlas using CliMAF]). You can also have access to intermonitoring tools developed at IPSL (http://forge.ipsl.jussieu.fr/igcmg_doc/wiki/Doc/Running#Monitoringandintermonitoring)
+- Tools are available to evaluate to model such as CLIMAF ([https://github.com/jservonnat/C-ESM-EP/wiki/The-C-ESM-EP-in-a-nutshell How to run C-ESM-EP atlas using CliMAF]). You can also have access to intermonitoring tools developed at IPSL (http://forge.ipsl.fr/igcmg_doc/wiki/Doc/Running#Monitoringandintermonitoring)