= SPINUP_ANALYTIC =
This page gives you information how to modify the default way of adjusting the analytical spinup configuration. If you want a simulation w/o analytical spinup please see here how to activate/deactivate the analytical spinup: [https://forge.ipsl.fr/orchidee/wiki/Documentation/UserGuide/SpinupInJobBasic]


The description assumes you already know how to run the trunk version of ORCHIDEE. 

The same procedure has to be done when using the OOL_SEC_STO configuration, 
except that you have (1) to set the switch for the analytical spinup in COMP/stomate.card  to no, (2) comment out the variables CyclicBegin CyclicEnd in config.card, and (3) use the variable year instead of CyclicYear in stomate.card f 
If you want changing atmospheric CO2 concentration see here [https://forge.ipsl.fr/orchidee/wiki/Documentation/UserGuide/ChangeCO2]


== 1.1 create new experiment folder ==
{{{
cd ../../config/ORCHIDEE_OL/
cp -fr SPINUP_ANALYTIC/ MY_SPINUP_ANALYTIC/
cd MY_SPINUP_ANALYTIC/
}}}


== 1.2 tell libIGCM about the new input files (they are stored on the IMBALANCE-P disk on obelix) ==
for deposition file (path,etc) see here: [https://forge.ipsl.fr/orchidee/wiki/DevelopmentActivities/inputRoutine]

REMARK: The Trunk teams recommend to use the old Zobler soil texture; thus here the example for Zobler. 
add/exchange these files in list of "[InitialStateFiles]" in COMP/sechiba.card:
{{{
(/home/surface3/common/CNP_files/rev02/USDA_SoilSuborder.nc, USDA_SoilSuborder.nc), \
(/home/surface3/common/CNP_files/rev02/soils_param.nc, soils_param.nc), \
(/home/surface3/common/CNP_files/rev02/lithology.nc, lithology.nc)
}}}
REMARK: make sure there are no blanks behind the "\"!

add/exchange these files in list of "[BoundaryFiles]" in COMP/sechiba.card:
{{{
(/home/surface3/common/CNP_files/rev02/USDA_SoilSuborder.nc, USDA_SoilSuborder.nc), \
(/home/surface3/common/CNP_files/rev02/soils_param.nc, soils_param.nc), \
(/home/surface3/common/CNP_files/rev02/lithology.nc, lithology.nc), \
(/home/surface3/common/CNP_files/rev02/deposition.nc, deposition.nc),\
}}}

REMARK: In PARAM/run.def you have set the following two variables according to the names you set in COMP/stomate.card:
{{{
# SOILTYPE_CLASSIF :  Type of classification used for the map of soil types (default zobler)
SOILTYPE_CLASSIF = zobler
SOILALB_FILE     = soils_param.nc
SOILCLASS_FILE   = soils_param.nc

}}}


== You want account for inter-annual variability of deposition ? ==
You can loop over a couple for years of deposition to account for inter annual variability during a spinup using CyclicYear. 
This is done by adding deposition files in list of "[BoundaryFiles]"(!) file to COMP/sechiba(!).card:
{{{
[BoundaryFiles]
List=   (/home/surface3/common/CNP_files/deposition/deposition_${CyclicYear}.nc, deposition.nc)
}}}


== 1.3 adjust the libIGCM  ==

=== 1.3.1 disable XIOS (not needed anymore)

-- In case you do NOT want to use XIOS make sure you compile orchide with '''gmake without_xios'''. --

disable XIOS  in COMP/orchidee_ol.card
{{{
# Use XIOS as output library instead of IOIPSL
XIOS=n
}}}

make sure XIOS is set to "_AUTOBLOCKER_" (if you set it to "n", libIGCM will trigger a stop) in PARAM/run.def:
{{{
# Use XIOS for writing diagnostics file
XIOS_ORCHIDEE_OK = _AUTOBLOCKER_
}}}

disable XIOS in config.card:
{{{
#IOS= (xios, XIOS)
}}}
{{{
#IOS= (xios_server.exe, xios.x, 1MPI)
}}}

=== 1.3.2 other
When using XIOS, make sure the following line is in the list of "[ParametersFiles]":
{{{
        (${MODIPSL}/modeles/ORCHIDEE/src_xml/file_def_input_orchidee.xml, .)  ,\
}}}


Make sure the 11-layer hydrology &  scheme is used by settting it explicitly to "y" ; this is the default hydrological scheme in ORCHIDEE-CN-P (r4166). If it is on "_AUTO_" it will cause a stop of the orchidee executable. 
For activating the 11-layer hydrology see here [http://forge.ipsl.fr/orchidee/wiki/DevelopmentActivities/ORCHIDEE-CNP/activate11HYDRO].

add a set of parameters with their values from the ORCHIDEE-CAN components as well as for the nutrient components to the PARAM/run.def. Make sure you do not overwrite PARAM/run.def but add the additional parameters. 
{{{
cp /home/surface3/common/CNP_files/rev02/run.def PARAM/run.def
}}}

these flags are needed for the nutrient cycles in PARAM/run.def, 
so make sure they are in there and you set them according to your plans:
{{{
# to activate P cycle set =y
STOMATE_OK_PCYCLE=y
STOMATE_IMPOSE_NP=y
# to activate N cycle set =y
STOMATE_OK_NCYCLE=y
STOMATE_IMPOSE_CN=y
# make sure we dont fake
LD_FAKE_HEIGHT=n

# if you spinup the nitrogen and phosphorus; 
#the mineral N stocks can occasionally get over-depleted due to SOM accumulation;
# to avoid that; set this true 
SPINUP_CNP=y

# you can enable mass conservation and stoichiometry checks by =y
STOMATE_MASS_CONSERVATION=y
STOMATE_DSG_DEBUG=y

}}}
for setting the nutrient boundary conditions see here: [https://forge.ipsl.fr/orchidee/wiki/DevelopmentActivities/inputRoutine]

disable river routing if you run on non-global scale in run.def
{{{
# Activate river routing
RIVER_ROUTING = n
}}}

for more information on the manipulation of run.def: [http://forge.ipsl.fr/orchidee/wiki/Documentation/UserGuide/ManipulationDefFile]

== 1.4a activate analytic solution ==
in COMP/stomate.card:
{{{
[UserChoices]
# SPINUP_ANALYTIC=y/n : Activate the spinup analytic option to solve the carbon in soil balance
SPINUP_ANALYTIC=y
}}}

== 1.4b adjust the job as usual ==
modify config.card as usual (see here for more information howto set these parameters in general: [https://forge.ipsl.fr/orchidee/wiki/Documentation/UserGuide/SpinupInJobBasic])
I achieved an equilibrium for Europe using sets of 300-350 yr simulations (first step imposing NP concentration, second step prognostic NP concentrations restarting from step 1):
{{{
  #-- leap(gregorian), noleap, 360d                                                   
  CalendarType=noleap                                                                 
  #-- Start and End of Job                                                            
  #-- "YYYY-MM-DD"                                                                    
  DateBegin=1960-01-01
  DateEnd=2260-12-31
  # Forcing data between 1901 and 1920                                                
  CyclicBegin=1901
  CyclicEnd=1920

}}}
'''REMARK (curie only)''': If you want to run ORCHIDEE on spatial subdomain (here the example for a single grid box) you need to adjust the number before MPI line:
{{{
#OOL= (orchidee_ol, orchidee_ol, 32MPI)
OOL= (orchidee_ol, orchidee_ol, 1MPI)
}}}


modify run.def as usual (see wiki)
on obelix: set the directory where you want to have the output, do not use the default location which is /home/scratch01 as the automatic cleaning of the scratch drive does not work properly and can cause the model to crash. Ask Fabienne Maignan where you can store data on obelix in case you do not know. The output path ca be specified by adding to config.card:
{{{
ARCHIVE=/home/surface3/dgoll 
}}} 
REMARK: you need to add the same line to the Job_file (which will be generate in the next step)


== 1.5 create job ==
{{{
../../../libIGCM/ins_job
}}}

== 1.6 adjust job_file (optional) ==
=== 1.6.1. simulations sequential mode ===
Header to run a site scale simulation on obelix using a single execution unit (ppn):
{{{
######################
	## OBELIX      LSCE ##
	######################
	#PBS -N test
	#PBS -m a
	#PBS -j oe
	#PBS -q short
	#PBS -o Script_Output_test.000001
	#PBS -S /bin/ksh
	#PBS -v BATCH_NUM_PROC_TOT=1
	#PBS -l nodes=1:ppn=1
}}}


make sure in config.card you told libIGCM to run ORCHIDEE with one execution unit (1MPI):
{{{
OL= (orchidee_ol, orchidee_ol, 1MPI)
}}}

=== 1.6.2. simulations parallel mode ===
example for a global simulation and 64 processors
config.card you told libIGCM to run ORCHIDEE with one execution unit (63MPI and xios with 1MPI):
{{{
OL= (orchidee_ol, orchidee_ol, 64MPI)
IOS= (xios_server.exe, xios.x, 1MPI)
}}}

{{{
######################
	## OBELIX      LSCE ##
	######################
	#PBS -N test
	#PBS -m a
	#PBS -j oe
	#PBS -q longp
	#PBS -o Script_Output_test.000001
	#PBS -S /bin/ksh
	#PBS -v BATCH_NUM_PROC_TOT=64
	#PBS -l nodes=8:ppn=8
}}}

see here more info how to use parallel processors (info for all machines): 
[http://forge.ipsl.fr/orchidee/wiki/Documentation/UserGuide/TestCaseBatch]


=== 1.6.4. other options in Jobfile ===

to automatically have existing files deleted, set JobType=DEV
{{{
 	#D- Experience type : DEB(ug), DEV(elopment), RUN (default)
	JobType=DEV 
}}}
to avoid queuing take full advantage of your job time; the value depends on #PBS -q short and computation time of orchidee
{{{
#D- Number of execution in one job
	PeriodNb=60
}}}

on obelix: I strongly recommend to specify a directory for the RUN_DIR, if you do not specify you have to expect model crashes because the default location is full. exchange 'dgoll' with your ID and 'surface3'  with the disc you can use. Generate the folder RUN_DIR prior first use manually (mkdir command):
{{{
#D- Define running directory
#D- Default=${TMPDIR} ie temporary batch directory
#D-
#RUN_DIR_PATH=/workdir/or/scratchdir/of/this/machine
RUN_DIR_PATH=/home/surface3/dgoll/RUN_DIR
}}}
Also add the ARCHIVE path as you did in the config.card. The default path is on /home/scratch01 which can run full as the automatic cleaning of the scratch disc does not work all the time:
{{{
ARCHIVE=/home/surface3/dgoll
}}}


== REMARK: ==
 The default libIGCM copies all boundary files for ORCHIDEE instead of using links. This results in a reduction in computational efficiency as the copying of large files takes time. To use links instead of hard copy you can take a few simple steps. See description here [http://forge.ipsl.fr/orchidee/wiki/DevelopmentActivities/ORCHIDEE-CNP/LibIGCMmod01]


== 1.7 submit the job  ==
on obelix:
{{{
qsub Job_ID
}}}
on curie
{{{
ccc_msub Job_ID
}}}
== 1.8 restart / rerun a job after crash  ==
It is important that you stick to the libIGCM regulations. You /libIGCM/clean_Month to reset run.card or delete run.card if you want to start from scratch.
To avoid headaches, it is recommended to always delete all file which you want to redo , for example in the experiment output in IGCM_OUT, etc


== 2.0 problems which might occur ==
=== 2.1. executable causes a stop ===
In general, you should check the out_orchidee_ol and out_execution files for error messages.

==== known problems ====
if you can find in "out_orchidee_ol" a message that a LOGICAL has an inappropriate value, you must set in PARAM/run.def the LOGICAL to "y" or "n", for example:
{{{
# Activate the multi-layer diffusion scheme adapted from CWRR
# by default the Choisnel hydrology is used.
HYDROL_CWRR = n
}}}