\documentclass[a4paper]{article}

                                % Packages

\usepackage[utf8]{inputenc}
\usepackage{ifpdf}

\ifpdf
\else
\usepackage[active]{srcltx}
\fi

\usepackage{amsmath}

\usepackage[T1]{fontenc}
\usepackage{lmodern}

\usepackage{geometry}

\usepackage[np]{numprint}

\usepackage{hyperref}
\ifpdf
\hypersetup{pdftitle={Tutorial ORCHIDEE}, pdfauthor={LMDZ team},
  hypertexnames=false, pdfstartview=FitBH}
\fi

\author{LMDZ team}
\title{LMDZ tutorial: ORCHIDEE}
\date{December 16th, 2018}


\geometry{top=2cm,bottom=2cm,left=2.5cm,right=2.5cm}


                                %---------------

\begin{document}

\maketitle

This tutorial focuses on the interaction with the continental surface scheme ORCHIDEE in LMDZ.

This document can be downloaded as a pdf file:
\begin{verbatim}
wget http://www.lmd.jussieu.fr/~lmdz/pub/Training/Tutorials/Tutorial_ORCHIDEE.pdf
\end{verbatim}
which should ease any copy/paste of command lines to issue.

\section{Prerequisits}

You should be familiar with setting up simulations, as described in tutorials
\#1 and \#2.
\section{Preparing a simulation with Orchidee}
\begin{itemize}
\item
set \verb+veget=1+ in the script init.sh
and replace SIMU1 by SIMUORCH (for instance)
\item Run the script :
\begin{verbatim}
./init.sh
\end{verbatim}
  The script first compiles the model (\verb+gcm.e+) again and also compiles the program
  \verb+ce0l.e+, which creates initial state and boundary
  conditions. \verb+init.sh+ then downloads new NetCDF files which
  contain the surface orography, sea-surface temperature, and so on.
   \verb+init.sh+ then runs \verb+ce0l.e+ which
  creates files \verb+start.nc+, \verb+startphy.nc+ and
  \verb+limit.nc+ in a directory called \verb+INITIAL+. These files are then used to initialize
a new simulation in a directory called \verb+SIMUORCH+. You can check that these 3 files have
actually been  created in the directory \verb+SIMUORCH+. If not, please ask for our help.
If you already run init.sh in a previous step (without \verb+veget=1+ ), you already have these files in the directory called \verb+INITIAL+. The script will get the files requested to initialize ORCHIDEE.
 You will need to run a first simulation to create the ORCHIDEE initial
file.  To do so:
\begin{verbatim}
cd SIMU0
edit physiq.def and set ifl_pbltree=0 (the default value is 1 but cannot be activated with the Orchidee version which is distributed for the training)
./gcm.e > listing0                          
\end{verbatim}

This simulation should create a file called
\verb+sechiba_rest_out.nc+.  The ORCHIDEE initial file of your
simulation, \verb+sechiba_rest_in.nc+, should point to this file
(this is done automatically for the SIMUORCH experiment when
\verb+veget=1+.
\item If you have the files \verb+start.nc+, \verb+startphy.nc+ and
  \verb+limit.nc+ and  \verb+sechiba_rest_in.nc+ 
  in your SIMUORCH directory, you are almost done. 
\end{itemize}

\section{Exploring the sensitivity to the continental surface scheme}

\subsection[ORCHIDEE 2-layers]{Running with ORCHIDEE 2-layers}
\label{sec:orchid_2}

in the directory SIMU0  you already have a start file named \verb+sechiba_rest_in.nc+
(\verb+sechiba+ is the hydrological part of the soil/vegetation model
Orchidee).

In the directory SIMUORCH
 you can run \verb+gcm.e+ to do a simulation with Orchidee
activated. The number of days, set in \verb+run.def+, is
\verb+nday=1+. It can be increased and
change \verb+1day+ in \verb+3day+ in \verb+config.def+, in the line
'\verb+phys_out_filetimesteps+' (otherwise your output file
\verb+histmth.nc+ will be empty).

You can play with the \verb+sechiba+ output frequency by changing in
\verb+orchidee.def+ the variable \verb+WRITE_STEP+ (in seconds;
default: \verb+86400+ for daily output); \verb+0+ means no
\verb+sechiba+ output; \verb+-1+ means monthly output; \verb+N*86400+
means output written every N days).  A second output file
\verb+sechiba_out_2.nc+ is for high-frequency output, modulated by
\verb+WRITE_STEP2+ (default: 10800, for 3 hours)

You can change the complexity level of outputs by playing with the
\verb+SECHIBA_HISTLEVEL+ variable: higher \verb+SECHIBA_HISTLEVEL+
means more variables in output.  The variables corresponding to the
various output levels are coded in
\begin{verbatim}
modipsl/modeles/ORCHIDEE/src_sechiba/intersurf.f90
\end{verbatim}

\subsection[ORCHIDEE 11-layers]{Running with ORCHIDEE 11-layers}

Set \verb+HYDROL_CWRR+ to \verb+y+ in \verb+orchidee.def+ in order to use the multi-layer (11) hydrology in ORCHIDEE instead of the 2 layers scheme.

If it's the first time that you do a run with ORCHIDEE in your current
working directory (which is the case if you don't have a
\verb+sechiba_rest_in.nc+ file), the procedure is the same as
described in ~\ref{sec:orchid_2} for ORCHIDEE 2-layers.

If you have already done a run with ORCHIDEE -2 layers, you need to re-create
an initial state file adapted to the multi-layer hydrology: 
\begin{enumerate}
\item remove the file \verb+sechiba_rest_in.nc+ in SIMU0 
  directory,
%\item set \verb+SECHIBA_restart_in.nc+ to \verb+NONE+ in orchidee.def,
  and
\item remove  \verb+sechiba_rest_out.nc+ \verb+sechiba_out_2.nc+ \verb+sechiba_history.nc+ and all \verb+used_*+ files
\item relaunch the gcm.
\end{enumerate}

\subsection[Bucket]{Running with the simple bucket scheme}
\label{sec:bucket}

If \verb+VEGET=n+ (meaning that the vegetation is not activated) instead
of \verb+y+ in file \verb+config.def+, the soil scheme is a simple
bucket (even if you compiled with \verb+makegcm -v true+ as done by
\verb+install.sh+ when ran with \verb+veget=1+).

\subsection[Bucket scheme with imposed soil water
  content]{Running with bucket scheme with imposed soil water
  content}

Same as in~\ref{sec:bucket}, you should run with \verb+VEGET=n+ in
\verb+config.def+.  Evaporation is computed as the potential
evaporation multiplied by the aridity coefficient \verb+vbeta+, which
is a function of the soil water content \verb+qsol0+:
\begin{verbatim}
vbeta(i) = MIN(2.0*qsol/mx_eau_sol, 1.0)
\end{verbatim}
(here \verb+mx_eau_sol=150mm+ ). So, if \verb+qsol0+ is constant,
\verb+vbeta+ is constant as well.  You can fix \verb+qsol0+ to a
chosen value \verb+qsol0_val+ (in mm), by adding in \verb+physiq.def+
the line \verb+qsol0=qsol0_val+ ; try for example \verb+qsol0_val=5+
or \verb+10+, that result in \verb+vbeta+ values typical of
summertime.

You can compare the turbulent fluxes for the austral summer (variables
\verb+flat+ and \verb+sens+ in the LMZ output files) computed using
the different options.

\section[New revision for ORCHIDEE]{Running with a more recent version for ORCHIDEE-11 (almost CMIP6-version}

go in the directory
\begin{verbatim}
modipsl/modeles/ORCHIDEE/
\end{verbatim}

if you have access to the web you can update the version with "svn update -r 4470 " to use the revision 4470 
otherwise  cp the file ORCHIDEE.tar which is in ~LMDZ/ORCHIDEE.tar 
\begin{verbatim}
modipsl/modeles/
\end{verbatim}
and do tar -xvf ORCHIDEE.tar 
go into ORCHIDEE and recompile 
\begin{verbatim}
./makeorchidee_fcm -j 8 -noxios -prod -parallel none -arch local > orchideelogrev >&1
\end{verbatim}
then go back in
\begin{verbatim}
modipsl/modeles/LMDZ
\end{verbatim}
edit the file compile.sh and remove the option:
\begin{verbatim}
 -cpp ORCHIDEE_NOZ0H from the ./makelmdz_fcm 
\end{verbatim}
 line. We need to do that in order to use the new interface between ORCHIDEE and LMDZ wich allows to compute 2 different roughness lengths for the moment and for the heat.
then re-compile the LMDZOR model: 
\begin{verbatim}
./compile.sh
\end{verbatim}
if the compilation fails ask for help.\\

Once the code is  successfully compiled, create a new directory for this experiment
\begin{verbatim}
in modipsl/modeles/LMDZ/TUTORIAL
mkdir SIMUNORCH
cd SIMUNORCH

ln -s ../SIMUORCH/start.nc .
ln -s ../SIMUORCH/startphy.nc .
ln -s ../SIMUORCH/limit.nc .
ln -s ../SIMU0/PFTmap.nc .
ln -s ../SIMU0/cartepente2d_15min.nc .
ln -s ../SIMU0/lai2D.nc .
ln -s ../SIMU0/soils_param.nc .
cp ../SIMUORCH/*.def .
ln -s ../SIMUORCH/gcm.e .
\end{verbatim}
In order to benefit from the albedo optimized from MODIS you need to use the file \verb+alb_bg.nc+ which is in
\begin{verbatim}
 ~/LMDZ/pub/3DInputData/Orchidee
\end{verbatim}
You can get it also with the following command:
\begin{verbatim}
wget http://www.lmd.jussieu.fr/~lmdz/pub/3DInputData/Orchidee/alb_bg.nc
\end{verbatim}
you can get an updated file for orchidee.def from the same directory
\begin{verbatim}
cp ~/LMDZ/pub/3DInputData/Orchidee/orchidee.def.new orchidee.def
or
wget http://www.lmd.jussieu.fr/~lmdz/pub/3DInputData/Orchidee/orchidee.def.new
mv orchidee.def.new orchidee.def
\end{verbatim}
Verify that  the file \verb+sechiba_rest_in.nc+  is not present in SIMUNORCH
  directory. \\
You need to edit  the orchidee.def (new) file
and (if not present) add the line:
\verb+XIOS_ORCHIDEE_OK+ to \verb+n+, this prevents the use of XIOS for the outputs.
Verify that
 \verb+HYDROL_CWRR+ is set to \verb+y+.  
Set \verb+SECHIBA_restart_in.nc+ to \verb+NONE+,
set \verb+SOILTYPE_CLASSIF+ to \verb+zobler+, and 
set \verb+SOILCLASS_FILE+ to \verb+soils_param.nc+ 
in order to use the zobler texture map. 
Set \verb+ALB_BG_MODIS = y+ and \verb+ALB_BG_FILE  = alb_bg.nc+ to use the backgroung albedo optimized with MODIS. 
In \verb+orchide.def+, the following keys allow to activate various recent options of ORCHIDEE:


\verb+ROUGH_DYN+ : accounts for a dynamic roughness height (if \verb+y+ activation of Su et al. parametrization)
\verb+OK_FREEZE+ :  if \verb+y+ Activates the complet soil freezing scheme
\verb+DEPTH_MAX_T=90+ : set the maximum depth of the soil thermodynamics to 90m
\verb+OK_EXPLICITSNOW+ :  if \verb+y+ activates explict snow scheme
\verb+DO_RSOIL+ activates the resistance to bare soil evaporation

You can do a control run (launch the gcm)  with \verb+DO_RSOIL = n+ and then run a sensitivity experiment with the resistance to bare soil evporation activated (\verb+DO_RSOIL = y+). You can then compare the latent heat flux: flat.

\end{document}
