= SPINUP_ANALYTIC =
This page gives you information how to modify the default way of adjusting the analytical spinup configuration. It 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 for the switch for the analytical spinup.

== 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) ==
modify the variable "ListNonDel" in COMP/stomate.card:
{{{
ListNonDel= (${R_IN}/SRF/reftemp.nc, .),\
(/home/surface3/common/CNP_files/revXX/lithology.nc, .), \
(/home/surface3/common/CNP_files/revXX/USDA_SoilSuborder.nc, .), \
(/home/users/dgoll/ORC_data/N_deposition/LMDzINCA_DEP_2000.nc, .), \
(/home/surface3/common/CNP_files/deposition/deposition_1850.nc,  deposition.nc)
}}}
REMARK: make sure there are no blanks behind the "\"!

add/exchange these files in list of "[InitialStateFiles]" in COMP/sechiba.card:
{{{
(/home/surface3/common/CNP_files/revXX/soils_param.nc, .), \
(/home/surface3/common/CNP_files/revXX/soils_param_usda_new.nc, .), \
(/home/surface3/common/CNP_files/deposition/deposition_1850.nc,  deposition.nc), \
}}}

REMARK: Although the file with N deposition is used in sechiba we must add the file to the stomate.card. 
This is needed to ensure it is copied when we restart from a simulation with impose_cn. In that case, the N deposition variable will not be present in the sechiba_restart_out.nc but the libIGCM assumes all sechiba variables are present.

WARNING (obelix): The double entry of deposition will cause a stop on obelix, as the "cp" option are set to not overwrite files.
The issue is not solved yet; but I asked Fabienne & Josefine how the cp option in libIGCM can be changed, so that you can overwrite files - or an alternative solution.)

== 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 done by adding deposition file to COMP/sechiba(!).card:
{{{
List=       (${R_IN}/SRF/routing.nc, .),     \
(/home/surface3/common/CNP_files/revXX/soils_param.nc, .), \
(/home/surface3/common/CNP_files/revXX/soils_param_usda_new.nc.nc, .), \
            (${R_IN}/SRF/cartepente2d_15min.nc, .), \
            (${R_IN}/SRF/floodplains.nc, .), \
            (${R_IN}/SRF/PFTmap_1850to2005_AR5_LUHa.rc2/PFTmap_IPCC_${year}.nc, PFTmap.nc), \
            (/ccc/work/cont003/dsm/p529vui/ORCHIDEE_trunk_CN/LMDzINCA_DEP_2000.nc, .),\
            (/ccc/work/cont003/dsm/p529goll/NP_deposition/final/deposition_${CyclicYear}.nc, deposition.nc)

}}}
as well as(!) in COMP/stomate.card:
{{{
ListNonDel= (${R_IN}/SRF/reftemp.nc, .),\
(/home/surface3/common/CNP_files/revXX/lithology.nc, .), \
(/home/users/dgoll/ORC_data/N_deposition/LMDzINCA_DEP_2000.nc, .), \
(/home/surface3/common/CNP_files/revXX/deposition_${CyclicYear}.nc, .)
}}}



== 1.3 adjust the libIGCM  ==

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)
}}}

set the IO frequency to avoid crashes in PARAM/run.def
{{{
# Writefrequency in seconds in sechiba_history.nc
# default = 86400.0
WRITE_STEP = 1800.0

# Writefrequency in days in stomate_history.nc
# default = 10.
STOMATE_HIST_DT = 1
}}}
Set the 11-layer hydrology &  scheme to 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.jussieu.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/revXX/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

Nammonium_FILE=LMDzINCA_DEP_2000.nc
Nnitrate_FILE=LMDzINCA_DEP_2000.nc
Nnitrate_VAR = NOY
Nammonium_VAR = NHX
Nfert_FILE=NONE
Nbnf_FILE=NONE
NINPUT_UPDATE=-1
}}}

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.jussieu.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.jussieu.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)
plus
if you want to archive, for example in the IMBALANCE-P storage; add to config.card:
{{{
ARCHIVE=/home/surface3/dgoll 
}}} 

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

== 1.6 adjust job_file (optional) ==

Header to run a site scale simulation on obelix
{{{
######################
	## 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
}}}

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
}}}

to have a temp directory you can access on obelix; exchange dgoll with your ID
{{{
#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/scratch01/dgoll/RUN_DIR
}}}
== 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
}}}