\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{January 10-12, 2023}


\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 https://lmdz.lmd.jussieu.fr/pub/Training/Tutorials/Tutorial_ORCHIDEE.pdf
\end{verbatim}
which should ease any copy/paste of command lines to issue.

\section{Prerequisites}

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, with the model installed in sequential mode (and compiled without ORCHIDEE).
Here however you will work with the model in parallel mode. Therefore we recommend to start by doing the optional "Tutorial\_Parallel" exercice that you can download here :
\begin{verbatim}
wget https://lmdz.lmd.jussieu.fr/pub/Training/Tutorials/Tutorial_Parallel.pdf
\end{verbatim}
%-------------------

You will now install the new configuration of LMDZ coupled with ORCHIDEE model, in parallel mode (the steps are similar to those in tutorial \#1 ):

Go to the "LMDZ" folder in your \verb+$home+ directory, where you have downloaded the script \verb+install_lmdz.sh+ ;
you can always download it again if needed :
\begin{verbatim}
cd ~/LMDZ
	# Only if you need to download again install_lmdz.sh :
wget https://lmdz.lmd.jussieu.fr/pub/install_lmdz.sh
chmod +x install_lmdz.sh
\end{verbatim}

Run the \verb+install_lmdz.sh+ script, with  \verb+-veg CMIP6+ option for ORCHIDEE, and also with  \verb+-name LMDZORpar+ and  \verb+-parallel mpi_omp+
(Note: the default resolution 32x32x39 will be used ; it is required to be able to perform the exercices with the BENCH) :
\begin{verbatim}
./install_lmdz.sh -name LMDZORpar -parallel mpi_omp -veget CMIP6
\end{verbatim}

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

The script  \verb+install_lmdz.sh+ has automatically run a simulation in the folder BENCH32x32x39, in \verb+~/LMDZ/LMDZORpar/modipsl/modeles/LMDZ+. In the \verb+config.def+ of this simulation
you will see \verb+VEGET=y+.
That means that the vegetation is activated, and the soil scheme is the one provided by the ORCHIDEE model.

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

We will now run the model using the simple ``bucket'' scheme. Prepare  a new simulation folder as follows (similarly to what you've practiced in Section 5 of Tutorial 1\\
https://lmdz.lmd.jussieu.fr/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 : bucket for the simple bucket scheme), 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_bucket
cd BENCH32x32x39_bucket
\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_ORCHIDEE+:
\begin{verbatim}
ln -s ../BENCH32x32x39_ORCHIDEE/gcm.e .
\end{verbatim}

\item Make sure \verb+VEGET=n+ in
\verb+config.def+.  
\end{itemize}

Now run the model, in parallel mode. \\
The easiest way is to run the script \verb+./bash.sh+, which automatically executes the model on 2MPIx2OMP processes, and sends the execution log in the "listing"file. \\ 
Alternatively, you may use the script \verb+bash_parallel.sh+, which requires 3 parameters : nb of MPI and of OMP processes, and the executable name, as follows :
\begin{verbatim}
./bench_parallel.sh 2 2 gcm.e 
# or, with the execution log in "listing" :
./bench_parallel.sh 2 2 gcm.e > listing 2>&1
\end{verbatim}


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

Prepare a new simulation folder (for example BENCH32x32x39\_bucketISW) as above

\begin{itemize}
\item 

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

\item again make sure \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}

\subsection[Bucket scheme] {Various prescribed values for the soil  thermal inertia}

You can prepare a new simulation folder as described  above
and run the model with various prescribed values of the soil thermal inertia. To prescribe it you need to 
modify the $physiq.def$ file to specify the value for \verb+inertie_sol+ (the default value is 2000. which corresponds to a moist soil, 900. for instance corresponds to a dry soil).
\\
\\
\vspace{.5cm}
Suggested variables to look at:
\begin{itemize}
\item turbulent fluxes for the austral summer (variables \verb+flat+ and \verb+sens+ in the LMDZ output files) 
\item Surface temperature ( \verb+tsol+ )
\end{itemize}

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

\subsection{LMDZOR(CMIP6) experiment with default options}

As mentioned above, when you installed the model with the \verb+-veget CMIP6+ option, it ran LMDZ using the ORCHIDEE vegetation scheme with its default options.

Go to the \verb+~/LMDZ/LMDZORpar/modipsl/modeles/LMDZ/BENCH32x32x39_ORCHIDEE+ directory and review its contents

\begin{itemize}

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

You can rename the initial condition files found in the folder, as you'll only use them in Section 3.4 :
\begin{verbatim}
mv sechiba_rest_in.nc sechiba_rest_in_spinup.nc
mv stomate_rest_in.nc stomate_rest_in_spinup.nc
\end{verbatim}

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

\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,  :
\begin{itemize}
\item copy the reference folder \verb+BENCH32x32x39_ORCHIDEE+ to \verb+BENCH32x32x39_ORCrsoil+
  \item enter the \verb+BENCH32x32x39_ORCrsoil+ folder
  \item change \verb+DO_RSOIL+ from "n" (default value) to "y"
  \item remove the old ORCHIDEE history files
\begin{verbatim}
rm sechiba_history.nc sechiba_out_2.nc sechiba_rest_out.nc 
rm stomate_history.nc stomate_rest_out.nc
\end{verbatim}
\item run the model with \verb+/bench.sh+,\\ 
or \verb+/bench_parallel.sh 2 2 gcm.e+ ,\\  
or \verb+./bench_parallel.sh 2 2 gcm.e > listing 2>&1+

\end{itemize}

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


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

\subsection{Experiment with realistic soil moisture}

Create a new experiment as in 3.3 , 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 the bench 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.nc+ \\
 and \\
	\verb+STOMATE_RESTART_FILEIN = NONE+ with \verb+STOMATE_RESTART_FILEIN = stomate_rest_in.nc+
  \item remove the old ORCHIDEE history files
\begin{verbatim}
rm sechiba_history.nc sechiba_out_2.nc sechiba_rest_out.nc 
rm stomate_history.nc stomate_rest_out.nc
\end{verbatim}
\item Run the model as usually with \verb+/bench.sh+ or \verb+./bench_parallel.sh 2 2 gcm.e+
\end{itemize}


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

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