= How to run a simple test case with ORCHIDEE using the trunk =
[[PageOutline]]
Author: J. Ghattas[[BR]]
Last revision: 2020/01/19, J. Ghattas, update done after inclusion of branch CN-CAN in the trunk[[BR]]
Last revision: 2022/01/14, J. Ghattas with input from Mandresy Rasolonjatovo
Last revision: 2023/03/09, XW with the options to the new driver 

== Objectives ==
Prepare and run a simple test case for ORCHIDEE trunk without using any script. All input files needed are listed on this page. This page is adapted for the use of ORCHIDEE trunk revision 6614 or later version. If you need to prepare a test case for ORCHIDEE_3, go to the following page: [wiki:TestCaseORCH3], or if you need a test case for ORCHIDEE_2_0, go to the following page: [wiki:TestCaseORCH2_0].

This page describes how to prepare the run directory and run ORCHIDEE interactively, i.e. to launch directly in the terminal without passing through the batch system. You can also run using a job and launch on the batch system, for that case go to the following page: [wiki:Documentation/UserGuide/TestCaseBatch] . [[BR]]

== Prepare input files ==
You need the following files :
   - executable orchidee_ol   
   - forcing_file.nc and other netcdf input files
   - xml files to configure output using XIOS
   - run.def, orchidee.def and orchidee_pft.def parameter files to set up the simulation

Create a directory where you will run the model and copy input files as follow. 
=== Executable orchidee_ol ===
Install and compile the model to get the executable orchidee_ol. You can use orchidee_ol_prod or orchidee_ol_debug depending on the compilation you activated. Read more here: wiki:Documentation/UserGuide/InstallingORCHIDEEBasic
{{{
mkdir RUN1; cd RUN1
ln -s /pathtoyourinstallation/modipsl/bin/orchidee_ol_prod .  (if use old driver)
ln -s /pathtoyourinstallation/modipsl/bin/orchideedriver_prod .  (if use new driver)
}}}

=== Input netcdf files === 
Input files are stored on the shared repository IGCM, here named by R_IN. Set R_IN depending on your machine and link the files below.  
* at ciclad/climserv: export R_IN=/projsu/igcmg/IGCM
* at obelix: export R_IN=/home/orchideeshare/igcmg/IGCM 
* at IDRIS and TGCC see ORCHIDEE training courses or http://forge.ipsl.fr/igcmg_doc/wiki/Doc/ComputingCenters/SharedFiles
* Note that if the shell in your terminal is csh or tcsh, use set instead of export
{{{
Link file from shared repository                                                             File name expected by ORCHIDEE

ln -s  ${R_IN}/SRF/METEO/CRU-NCEP/v5.3.2/twodeg/cruncep_twodeg_2000.nc                       forcing_file.nc
ln -s  ${R_IN}/SRF/PFTMAPS/CMIP6/ESA-LUH2v2/historical/15PFT.v2/PFTmap_2000.nc               PFTmap.nc 
ln -s  ${R_IN}/SRF/SOIL/soils_param_usdatop_coord.nc                                         soils_param.nc
ln -s  ${R_IN}/SRF/SOIL/soils_param_zobler_coord.nc                                          soilcolor.nc
ln -s  ${R_IN}/SRF/SOIL/soil_bulk_and_ph.nc                                                  soil_bulk_and_ph.nc 
ln -s  ${R_IN}/SRF/cartepente2d_15min.nc                                                     cartepente2d_15min.nc 
ln -s  ${R_IN}/SRF/reftemp.nc                                                                reftemp.nc
ln -s  ${R_IN}/SRF/ROUTING/routing.nc                                                        routing.nc 
ln -s  ${R_IN}/SRF/NITROGEN/N_FERTILISATION/NMIP/synthetic/historical/Nfer_pasture_2000.nc   nfert_pasture.nc
ln -s  ${R_IN}/SRF/NITROGEN/N_FERTILISATION/NMIP/synthetic/historical/Nfer_cropland_2000.nc  nfert_cropland.nc 
ln -s  ${R_IN}/SRF/NITROGEN/N_FERTILISATION/NMIP/manure/historical/Nmanure_pasture_2000.nc   nmanure_pasture.nc 
ln -s  ${R_IN}/SRF/NITROGEN/N_FERTILISATION/NMIP/manure/historical/Nmanure_cropland_2000.nc  nmanure_cropland.nc 
ln -s  ${R_IN}/SRF/NITROGEN/N_DEPOSITION/CCMI_ndep/historical/CCMI_ndep_nhx_2000.nc          ndep_nhx.nc
ln -s  ${R_IN}/SRF/NITROGEN/N_DEPOSITION/CCMI_ndep/historical/CCMI_ndep_noy_2000.nc          ndep_noy.nc 
ln -s  ${R_IN}/SRF/NITROGEN/BNF/bnf_1850.nc                                                  bnf.nc 
}}}

The files can also be download using wget, replace R_IN by https://vesg.ipsl.upmc.fr/thredds/catalog/igcmg/IGCM/catalog.html [[BR]]
In this test case, input files for year 2000 are used. You can replace 2000 by the year of your choice between 1901-2010

If using the new driver, then:
{{{
ln -s  ${R_IN}/SRF/METEO/CRU-NCEP/v5.3.2/twodeg/cruncep_twodeg_1999.nc forcing_yearm1.nc
ln -s  ${R_IN}/SRF/METEO/CRU-NCEP/v5.3.2/twodeg/cruncep_twodeg_2000.nc forcing_year.nc
ln -s  ${R_IN}/SRF/METEO/CRU-NCEP/v5.3.2/twodeg/cruncep_twodeg_2001.nc forcing_yearp1.nc
}}}

=== xml files for running with XIOS ===
''Note: If you do not compile with XIOS, you do not need to copy these files but you need to adapt run.def to activate output with IOIPSL, see further below.''[[BR]]

The xml files controls the output of the model if you use XIOS. XIOS is the default instead of IOIPSL since rev 3115 in the trunk. Moreover, since rev 3839, only XIOS/trunk revision 965 (XIOS2) or later can be used. 

* Copy all the xml files from the "modeles" directory ORCHIDEE/src_xml to your run directory: iodef.xml, context_orchidee.xml, context_input_orchidee.xml, field_def_orchidee.xml and file_def_orchidee.xml.

* Edit file_def_orchidee.xml to change every instance of "_AUTO_" (3 for each output file)
 * output_level="_AUTO_" into output_level="X" where X is an integer between 0-11
 * output_freq="_AUTO_" into output_freq="1mo" or output_freq="1d" par example
 * enabled="_AUTO_" into enabled=".TRUE." or enabled=".FALSE."
 * do any other change as you wish to adapt the output to your needs

* Edit field_def_orchidee.xml only if you changed the ORCHDEE source code.

=== Parameter files ===
Copy following parameter files from experiment set up OOL_SEC_STO2 into your run folder and modify all occurrences of AUTO as follow:
* modipsl/config/ORCHIDEE_OL/OOL_SEC_STO_FG2/PARAM/run.def 
{{{
INCLUDEDEF=orchidee.def
INCLUDEDEF=orchidee_pft.def

TIME_LENGTH = 1D
TIME_SKIP = 0
DRIVER_reset_time = n
RESTART_FILEIN = NONE
ATM_CO2 = 350.

# Add a small test region over France
LIMIT_WEST=-5
LIMIT_EAST=5
LIMIT_SOUTH=40
LIMIT_NORTH=55
}}} 

* If using the new driver, modipsl/config/ORCHIDEE_OL/OOL_SEC_STO_FG2nd/PARAM/run.def 
{{{
START_DATE = 2000-01-01 00:00:00
END_DATE = 2000-01-31 24:00:00

RESTART_FILEIN = NONE
ATM_CO2 = 350.

# Add a small test region over France
LIMIT_WEST=-5
LIMIT_EAST=5
LIMIT_SOUTH=40
LIMIT_NORTH=55
}}} 

* modipsl/config/ORCHIDEE_OL/OOL_SEC_STO_FG2/PARAM/orchidee.def
{{{
SECHIBA_restart_in = NONE
STOMATE_RESTART_FILEIN = NONE
XIOS_ORCHIDEE_OK = y
SECHIBA_HISTFILE2 = n
WRITE_STEP = 0
WRITE_STEP2 = 0 
STOMATE_HIST_DT = 0
STOMATE_IPCC_HIST_DT = 0
RIVER_DESC = n
VEGET_UPDATE = 0Y
STOMATE_OK_STOMATE = y 
NINPUT_UPDATE = 0Y
STOMATE_IMPOSE_CN = n
}}}
* modipsl/config/ORCHIDEE_OL/OOL_SEC_STO_FG2/PARAM/orchidee_pft.def_15pft.1ac
  * If use new driver, modipsl/config/ORCHIDEE_OL/OOL_SEC_STO_FG2nd/PARAM/orchidee_pft.def_15pft.1ac
  * rename the file as orchidee_pft.def, no changes in the file

* given the small region used in the test case, modify modipsl/config/ORCHIDEE_OL/OOL_SEC_STO_FG2nd/PARAM/orchidee.def for example to avoid routing error:
  * RIVER_ROUTING = n

By default, in this test case the simulation will be on the global domain, running for 1 day (case of using the old driver) or 1month (case of using the new driver), starting with no restart files. See comments if in run.def and orchidee.def files to understand the meaning of the parameters. You can for example run on regional domain using LIMIT_xx parameters to be set in run.def, see comments in the end of this file.
 
== Check you environment and launch the model ==
To run the model you first need to load the same netcdf library as the one used for the compilation. This depends on the machine you work at. If you use one of the predefined IPSL machines (irene, jeanzay, obelix or ciclad/climserv), source the file in the folder ORCHIDEE_OL/ARCH:
{{{
source modipsl/config/ORCHIDEE_OL/ARCH/arch.env
}}}
For other machines, make sure you use the same environment as the one used during compilation. 

Once you've get all input files, launch the model in the same directory :
{{{
./orchidee_ol_prod > out_orchidee_ol_prod 2>&1   (use old driver)
./orchideedriver_prod > out_orchideedriver_prod 2>&1   (use new driver)
}}}


== Other methods to set up a run directory ==
If you run with libIGCM, set up a normal job using the command ./../../../libIGMC/ins_job but add exit in the main Job after following:
{{{
  echo
  echo "#######################################"
  echo "#      DIR BEFORE RUN EXECUTION       #"
  echo "#######################################"
  echo
  ls -lrt

  exit
}}}
Launch the job and the go to the run directory where you'll find all input netcdf files and parameter files. You can work directly in this run directory to make simpler test cases. 

Note: at obelix, set RUN_DIR_PATH in the main job so the run directory will be accessible.   

 
Another way to do it from a run you've already finished with libIGCM is to look at the Script_Output_* file.  Inside this file libIGCM lists all the files that it copies to the run directory (look for the commands where the commands IGCM_sys_Cp and IGCM_sys_Get appear in the Script_Output_* file).  If you copy those files manually to a new directory, you should be able to launch the exact same simulation but you first need to change all occurrences of AUTO as in the above part of this page.