\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 9th, 2019}


\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.
\section{Preparing a simulation with Orchidee}
\label{prepar}
\begin{itemize}
\item go to \verb+LMDZ20191106.trunk/modipsl/modeles/LMDZ+ and use the file called

\begin{verbatim}
bench_lmdz_32x32x39.tar.gz
\end{verbatim}

to create a new experiment:

\begin{verbatim}
mv BENCH32x32x39 BENCH32x32x39_old
tar -xf bench_lmdz_32x32x39.tar.gz 
cd BENCH32x32x39
\end{verbatim}

\item make sure that \verb+nday=1+ in \verb+run.def+
\item to avoid recompiling the code, just create a link to the executable you have 
already compiled before:
\begin{verbatim}
ln -s ../BENCH32x32x39_old/gcm.e .
\end{verbatim}

\item open the config.def files and modify the flag VEGET that activates ORCHIDEE (if compiled):
\begin{verbatim}
 VEGET=y
\end{verbatim}

\item open the physiq.def files and turn off the parameterization for the drag of induced by vertical obstacles penetrating the boundary layers like trees. It cannot cannot be activated with the version of Orchidee distributed.

\begin{verbatim}
ifl_pbltree=0
\end{verbatim}

\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).
\begin{itemize}
\item get the file that describes the vegetation types over the continents
\begin{verbatim}
wget http://www.lmd.jussieu.fr/~lmdz/pub/3DInputData/Orchidee/PFTmap_IPCC_2000.nc
\end{verbatim}
\item create a link 
\begin{verbatim}
ln -s PFTmap_IPCC_2000.nc PFTmap.nc
\end{verbatim}

\item you can now run \verb+gcm.e+ to do a simulation with Orchidee
activated. 

\end{itemize}

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+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}
create a new experiment:
Proceed as in section \label{prepar} and \label{sec:orchid_2}.

\begin{itemize}
\item  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
\item you will need  an initial state file for ORCHIDEE adapted to the multi-layer hydrology
, you can get with: 
\begin{verbatim}
wget http://www.lmd.jussieu.fr/~lmdz/pub/3DInputData/Orchidee/sechiba_rest_in.11_13PFT.nc \\
ln -s sechiba_rest_in.11_13PFT.nc  sechiba_rest_in.nc
\end{verbatim}
or creating it following the procedure "initializing ORCHIDEE-11"

\item get file that describes the soil textures
\begin{verbatim}
wget http://www.lmd.jussieu.fr/~lmdz/pub/3DInputData/Orchidee/soils_param.nc .
\end{verbatim}

\item you need to proceed as for ORC2  before running \verb+gcm.e+

\end{itemize}
%\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+).

You can create a new experiment to test this option

\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 LMDZ output files) computed using
the different options.

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

\begin{itemize}
\item{update orchidee version}
go into 
\begin{verbatim}
modipsl/modeles/ORCHIDEE/
\end{verbatim}
you can update the version with "svn update -r 5004 " to use the revision 5004.
You can need credentials ( login : sechiba)
%\begin{verbatim}
%modipsl/modeles/
%\end{verbatim}
%and do tar -xvf ORCHIDEE.tar 

\begin{verbatim}
./makeorchidee_fcm -j 8 -noxios -prod -parallel none -arch local > orchideelogrev >&1
\end{verbatim}
\item compile LMDZ 
\begin{verbatim}
in   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}
 This is necessary  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}
rm -rf \verb+bin/gcm.*+
\verb+./compile.sh+
\end{verbatim}

Once the code is  successfully compiled, create a new EXPERIMENT as indicated above. Modify config.def in order to activate ORCHIDEE (modify physiq.def). It is recommended to download an updated orchidee.def can get an orchidee.def similar 
\begin{verbatim}
wget http://www.lmd.jussieu.fr/~lmdz/pub/3DInputData/Orchidee/orchidee.def.CMIP6 
\end{verbatim}
\item \verb+cp ../bin/gcm_32x32x39_phylmd_seq_orch.e gcm.e+
\item you can download the file for the initial condition of sechiba\\
\verb+wget http://www.lmd.jussieu.fr/~lmdz/pub/3DInputData/Orchidee/sechiba_rest_in.11_15PFT.nc+
\verb+ln -s sechiba_rest_in.11_15PFT.nc  sechiba_rest_in.nc+
\item download the file describing the vegetation adapted for 15 PFT 
\begin{verbatim}
wget http://www.lmd.jussieu.fr/~lmdz/pub/3DInputData/Orchidee/PFTmap_15PFT.v1_2000.nc\\
ln -s PFTmap_15PFT.v1_2000.nc PFTmap.nc
\end{verbatim}
%11
%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}
\item Description of some keys of ORCHIDEE relevant for the atmosphere land-surface interactions\\
In \verb+orchide.def+, the following keys allow to activate various recent options of ORCHIDEE:\\
Set \verb+ALB_BG_MODIS = y+ and \verb+ALB_BG_FILE  = alb_bg.nc+ to use the backgroung albedo optimized with MODIS.
\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

\end{itemize}

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.

\section{Initialisation of Orchidee-11 (CMIP6)}
\begin{itemize}
\item Create a new experiment.
\item Do the modification to activate orchidee
\item Download files necessary for the initialization
\begin{verbatim}
wget http://www.lmd.jussieu.fr/~lmdz/pub/3DInputData/Orchidee/alb_bg.nc
wget http://www.lmd.jussieu.fr/~lmdz/pub/3DInputData/Orchidee/cartepente2d_15min.nc
wget http://www.lmd.jussieu.fr/~lmdz/pub/3DInputData/Orchidee/lai2D.nc
wget http://www.lmd.jussieu.fr/~lmdz/pub/3DInputData/Orchidee/soils_param.nc
wget http://www.lmd.jussieu.fr/~lmdz/pub/3DInputData/Orchidee/PFTmap_15PFT.v1_2000.nc
\end{verbatim}
you can get an updated file for orchidee.def from the same directory
\begin{verbatim}
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 the working directory
  directory. \\
You need to edit  the orchidee.def (new) file
and (if not present) add the line:
\verb+XIOS_ORCHIDEE_OK=n+, this prevents the use of XIOS for the outputs.
Verify that
 \verb+HYDROL_CWRR+ is set to \verb+y+.  

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{itemize}
\section{Initialisation of Orchidee-11 (CMIP6)}
\begin{itemize}
\item Create a new experiment.
\item Do the modification to activate orchidee
\item in orchidee.def  set \verb+SECHIBA_restart_in.nc+ to \verb+NONE+
and remove the file \verb+sechiba_rest_in.nc+ from the working directory
\end{itemize}
\end{document}
