\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, 2020}


\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}
\label{prepar}
\begin{itemize}
\item go to \verb+LMDZ20201109.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

In the file \verb+config.def+, you can add the following line 
\verb+flag_flat=0 0 0 0 0 0+ in order to have the latent heat flux in your outputs.

\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[CMIP6]{Running with the ORCHIDEE version used for CMIP6}

\begin{itemize}
	\item{Install  a version of the model where ORCHIDEE-CMIP6 is implemented}
		Follow the indication given in the Tutorial 1 but download the file named \verb+install_lmdz_orc.sh+
		before running the install, you need to edit the file and replace \verb+veget=NONE+ with \verb+veget=CMIP6+
\item Description of some keys of ORCHIDEE relevant for the atmosphere land-surface interactions\\
	\begin{verbatim}
In orchide.def, the following keys allow to activate various recent options of ORCHIDEE:
ALB_BG_MODIS = y and ALB_BG_FILE = alb_bg.nc
allow to use the backgroung albedo optimized with MODIS.
ROUGH_DYN : accounts for  dynamic roughness heights
OK_FREEZE :  if y activates the complet soil freezing scheme
DEPTH_MAX_T=90 : set the maximum depth of the soil thermodynamics to 90m
OK_EXPLICITSNOW :  if y activates explict snow scheme 
(intermediate complexity scheme for the snow layer)
DO_RSOIL activates the resistance to bare soil evaporation
	\end{verbatim}

\end{itemize}

You can run a sensitivity experiment  with \verb+DO_RSOIL = y+ ( resistance to bare soil evaporation activated. You can then compare the latent heat flux: flat.

\section{Run the model with realistic soil moisture}
In the previous experiment, the soil variables have been initialized independently of the atmosphere above (i.e. the soil moisture content is not realistic). In order to get realistic soil moisture the land-surface and the atmosphere have to interact for one or two years (so called spin-up). You could do it yourself but it requires a long time on the PC. Initial conditions obtained after 2 years long runs have been preparated.To use them 
\begin{itemize}

	\item{prepare a new experiment as described in Tutorial 1.}
	\item{get specific files for the CMIP6 version of ORCHIDEE and impose the use of the ORCHIDEE module in config.def}
\begin{verbatim}
In the BENCH32x32x39 directory:
myget 3DBenchs/BENCHorch11.tar.gz
    tar xvzf BENCHorch11.tar.gz
    sed -e "s:VEGET=n:VEGET=y:" config.def > tmp
    mv -f tmp config.def
\end{verbatim}
	\item{use the initial conditions obtained after a 2 years spin-up}
\begin{enumerate}
\item in orchidee.def replace \verb+SECHIBA_restart_in=NONE+  with \verb+SECHIBA_restart_in=SECHIBA_restart_in.nc+ 
\item in orchidee.def replace \verb+STOMATE_RESTART_FILEIN = NONE+ with \verb+STOMATE_RESTART_FILEIN = stomate_rest_in.nc+
\end{enumerate}
		The sechiba file deals with the initial conditions for the hydrology (snow comprised) and the thermics of the soil, the stomate file deals with the properties of the vegetation.
\end{itemize}

You can compare the latent heat flux maps obtained with those obtained in the initial experiment
\end{document}
