\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: coupling with continental surface}
\date{December 14th, 2020}


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


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

\begin{document}

\maketitle

This tutorial focuses on the interaction between LMDZ and two different continental surface schemes: the simple "bucket" scheme, and the ORCHIDEE model in its CMIP6 version.

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.
%-------------------
The exercises with the bucket scheme (implying \verb+"VEGET=n"+ in \verb+config.def+) could be done in the model configuration you've worked with so far (which includes a version of ORCHIDEE older than CMIP6). However we recommend to do all the exercises of this tutorial in a newly installed configuration, with LMDZ coupled to ORCHIDEE in its CMIP6 version. 

In order to install the new configuration, you'll follow the same steps as in tutorial \#1, but you'll create a different directory than \verb+~/LMDZ+ and you'll use the \verb+install_lmdz_orc.sh+ script instead of \verb+install_lmdz.sh+ :

Go to your \verb+$home+ directory and create a new folder "LMDZOR" next to the "LMDZ" one.

\begin{verbatim}
cd
mkdir LMDZOR
cd LMDZOR
\end{verbatim}

Download the \verb+install_lmdz_orc_training.sh+ script, make sure that \verb+veget=CMIP6+, then run the script :

\begin{verbatim}
wget http://www.lmd.jussieu.fr/~lmdz/pub/install_lmdz_orc_training.sh
chmod +x install_lmdz_orc_training.sh
      (===> EDIT install_lmdz_orc.sh AND CHECK that "veget=CMIP6" (line 86; make this change yourself if needed)
./install_lmdz_orc_training.sh -d 32x32x39 -v 20201109.trunk
\end{verbatim}

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

The script  \verb+install_lmdz_orc_training.sh+ has automatically run a simulation in the folder BENCH32x32x39, in \verb+~/LMDZOR/LMDZ20201109.trunk/modipsl/modeles/LMDZ+. In the \verb+config.def+ of this simulation you will see \verb+VEGET=n+ .
That means that the vegetation is not activated, and the soil scheme is a simple
bucket (even if you compiled with \verb+makegcm -v true+ as done by default by the scripts
\verb+install_lmdz*.sh+ ; see flag \verb+veget=1+ therein).

Save this folder for comparison of results with the following experiments, by renaming it, for example:
\begin{verbatim}
cd ~/LMDZOR/LMDZ20201109.trunk/modipsl/modeles/LMDZ
mv BENCH32x32x39 BENCH32x32x39_bucket
\end{verbatim}

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

Prepare a new simulation folder as follows (similarly to what you've practiced in Section 5 of Tutorial 1\\
https://www.lmd.jussieu.fr/~lmdz/pub/Training/Tutorials/Tutorial\_1.pdf ):\\

\begin{itemize}
\item Use the file bench\_lmdz\_32x32x39.tar.gz to create a new folder BENCH32x32x39. 
Rename it right away, by adding a suffix indicating the experiment type 
(for ex : bucketISW for imposed soil water), then go in it.
Make sure that \verb+nday=1+ in \verb+run.def+.

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

\item To avoid recompiling the code, just create a link to the executable you have 
already compiled before, and used in \verb+BENCH32x32x39_bucket+:
\begin{verbatim}
ln -s ../BENCH32x32x39_bucket/gcm.e .
\end{verbatim}

\item Same as in ~\ref{sec:bucket}, you will run with \verb+VEGET=n+ in
\verb+config.def+.  

\item 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=5+
or \verb+10+, that result in \verb+vbeta+ values typical of
summertime.

\end{itemize}

Run the model as usually, with \verb+./gcm.e+   (or \verb+.gcm.e > listing+).\\

You can compare the turbulent fluxes for the austral summer 
(variables \verb+flat+ and \verb+sens+ in the LMDZ output files) 
computed without vs. with imposed soil water (Section 2.1 vs. 2.2).

%-------------------
\section{The ORCHIDEE land-surface model, CMIP6 version}

\subsection{Prepare a simulation folder to run LMDZ with ORCHIDEE-CMIP6}

\begin{itemize}
\item Create a new experiment using again \verb+bench_lmdz_32x32x39.tar.gz+ and the executable gcm.e already available (no recompilation needed):

\begin{verbatim}
tar -xf bench_lmdz_32x32x39.tar.gz 
mv BENCH32x32x39 BENCH32x32x39_ORC
cd BENCH32x32x39_ORC
ln -s ../BENCH32x32x39_bucket/gcm.e .
\end{verbatim}

% for older Orchidee versions like that installed by default by install_lmdz.sh
%\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}

\item Download a pack of files specific to ORCHIDEE-CMIP6 :
\begin{verbatim}
wget https://www.lmd.jussieu.fr/~lmdz/pub/3DBenchs/BENCHCMIP6.tar.gz 
tar -xvf BENCHCMIP6.tar.gz 
\end{verbatim}

\item Check the new \verb+config.def+ file : the "VEGET" flag is now "=y", which activates ORCHIDEE (if LMDZ was compiled with ORCHIDEE).

\item Check in \verb+orchide.def+ the following keys that allow activating various recent options of ORCHIDEE:\\
	\begin{verbatim}
Description of some keys of ORCHIDEE relevant for the atmosphere land-surface interactions

ALB_BG_MODIS = y and ALB_BG_FILE = alb_bg.nc
     allows using 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 explicit snow scheme 
(intermediate complexity scheme for the snow layer)
DO_RSOIL activates the resistance to bare soil evaporation
	\end{verbatim}
	
\item  Also note  in \verb+orchidee.def+ the flag \verb+HYDROL_CWRR+ set to \verb+y+  in order to use the multi-layer (11) hydrology in ORCHIDEE instead of an older 2-layer scheme.

\item Rename the initial condition files you downloaded, as you'll only use them in Section 3.5 :
\begin{verbatim}
mv sechiba_rest_in.nc sechiba_rest_in_spinup.nc
mv stomate_rest_in.nc stomate_rest_in_spinup.nc
\end{verbatim}

\end{itemize}

\verb+BENCH32x32x39_ORC+ is now your reference folder to run simulations with ORCHIDEE-CMIP6, with vegetation activated.
We recommend to start each of the following experiments by copying it under an informative name.

\subsection{LMDZOR(CMIP6) experiment with default options}
\label{sec:runDefault}
Copy the reference folder \verb+BENCH32x32x39_ORC+ as \verb+BENCH32x32x39_ORCv0+, and run the model with the defaut options above :
	\begin{verbatim}
cd ..
   (you must be back in  ~/LMDZOR/LMDZ20201109.trunk/modipsl/modeles/LMDZ ; 
   check with "pwd" command)
cp -pr BENCH32x32x39_ORC BENCH32x32x39_ORCv0
cd BENCH32x32x39_ORCv0
./gcm.e
	\end{verbatim}
	

\subsection{Output control}	

You can do this exercise separately, or combined with one of the following exercises.\\

The number of simulation days, set in \verb+run.def+, is \verb+nday=1+. 
It can be increased to \verb+5day+ , that is, equal to the value indicated for "histmth" file in \verb+config.def+, in the line
'\verb+phys_out_filetimesteps+' (if \verb+nday+ is smaller than this value, then the LMDZ 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{Sensitivity experiment with DO\_RSOIL}

Run a sensitivity experiment  with the resistance to bare soil evaporation activated.

In order to do that, repeat the procedure in 3.2, with 2 differences :
\begin{itemize}
  \item use for example the name \verb+BENCH32x32x39_ORCrsoil+ for the new experiment ;
  \item before running the model, change \verb+DO_RSOIL+ from "n" (default value) to "y"
\end{itemize}

Compare the latent heat flux "flat" to the one computed in the default experiment 3.2.


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

\subsection{Experiment with realistic soil moisture}

Create a new experiment as in 3.2 , using for example the name \verb+BENCH32x32x39_ORCinit+ for the new folder.

In the previous experiments, 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 prepared for this exercise, and are included in BENCHCMIP6 archive you already downloaded. 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.


\begin{itemize}
\item Change back the names of the initial condition files you downloaded and renamed in Section 3.1 :
\begin{verbatim}
mv sechiba_rest_in_spinup.nc sechiba_rest_in.nc
mv stomate_rest_in_spinup.nc stomate_rest_in.nc
\end{verbatim}
	
\item In orchidee.def replace : \\
	 \verb+SECHIBA_restart_in=NONE+  with \verb+SECHIBA_restart_in=sechiba_rest_in+ \\
 and \\
	\verb+STOMATE_RESTART_FILEIN = NONE+ with \verb+STOMATE_RESTART_FILEIN = stomate_rest_in.nc+

\item Run the model as usually with \verb+./gcm.e+
\end{itemize}


You can compare the maps of latent heat flux \verb+flat+  with those obtained in the "default" experiment 3.2.
%----------------------

%if you don't have a \verb+sechiba_rest_in.nc+ file in your simulation folder (it's the first time that you do a run with ORCHIDEE in your current
% working directory), ORCHIDEE will create the file ; in orchidee.def the STOMATE_RESTART_FILEIN  and SECHIBA_restart_in must be  \verb+NONE+.

% To re-run an experiment in the same directory, you first need to do some cleaning :
%\item remove  \verb+sechiba_rest_out.nc+ \verb+sechiba_out_2.nc+ \verb+sechiba_history.nc+ and all \verb+used_*+ files


\end{document}
