\documentclass{article}
\usepackage[english]{babel}
%\usepackage[latin1]{inputenc}
\usepackage{graphicx}
\usepackage{geometry}
\usepackage{hyperref}

\usepackage{listings}
\usepackage{xcolor}
%%%% \AtBeginDocument{\obeylines}
\lstset{
keepspaces=true,
columns=flexible,
frame=single,
basicstyle=\ttfamily,
language=bash,
morekeywords={use,reg,fill,shade,pal,lev,contour},
keywordstyle=\bfseries\color{orange!80!black},
%keywordstyle=\bfseries\color{gold},
%commentstyle=\itshape\color{blue!80!black},
commentstyle=\itshape\color{blue!80!black},
%moredelim=**[is][\color{teal}\bfseries]{ }{=},
%moredelim=[is][\color{teal}]{\$}{ }
%identifierstyle=\color{blue},
stringstyle=\color{blue!50!black},
showstringspaces=false
showtabs=false,
breaklines=false,
backgroundcolor=\color{gray!10},
rulecolor=\color{gray},
}

\usepackage{fontspec}
\setmonofont{Latin Modern Mono}



%\begin{lstlisting}[style=demostyle]
%\textbf{\textit{foobar}}
%\textit{\sffamily foobar}}

% Pour que le code puisse être récupéré sur le pdf en copier/coller sans erreur
% https://tex.stackexchange.com/questions/30284/how-to-make-listings-code-correct-copyable-from-pdf-and-with-hyperlink
%\makeatletter
%\def\lst@outputspace{{\ifx\lst@bkgcolor\empty\color{white}\else\lst@bkgcolor\fi\lst@visiblespace}}
%upquote=true

%\makeatother



\usepackage{a4wide}
%\textheight=23cm
%\oddsidemargin=0cm
%\textwidth=19cm

\begin{document}
%\newgeometry{top=10mm}
\def\afaire#1{{\bf Afaire : #1}}

\title{Hands on tutorial \#1: First steps with the model}
\date{\today}
\author{The LMDZ team}

\maketitle

This first tutorial focuses on installing and making basic first
runs using the LMDZ model.

This document can be downloaded as a pdf file at

\url{http://web.lmd.jussieu.fr/~hourdin/COURS/M2/MINI/Intro/Tutorial_1.pdf}

which should ease any copy/paste of command lines to issue.


\def\resol#1#2#3{#1$\times$#2-L#3} %


% ---------------------------------------------------------------
\section{Installing a first version}
% ---------------------------------------------------------------

\subsection{Prerequisites}

To run LMDZ, you will need a significant amount of memory, so first
ensure this is true. You can use the following command line
(that you can also, for convenience, put in your $\sim$/.bashrc file):
\begin{lstlisting}
ulimit -Ss unlimited
\end{lstlisting}


% ---------------------------------------------------------------
\subsection{Running the \lstinline{install_lmdz.sh} script}
% ---------------------------------------------------------------

We propose you to create a directory for LMDZ mini projects on your \lstinline{HOME} directory (but other choices are possible):\\
\begin{lstlisting}
mkdir -p ~/LMDZmini
cd ~/LMDZmini
\end{lstlisting}

The first step consists in cloning a git repository containing the model
and {\em blindly} running it :
\begin{lstlisting}
git clone https://gitlab.in2p3.fr/ipsl/projets/eduplanet/LMDZ
cd LMDZ/
./planet.sh bench
\end{lstlisting}
The model will be installed automatically in \lstinline{LMDZ}.

The script should then run smoothly (if it isn't the case,
immediately ask for some assistance).

You can take advantage of the installation time to open a second terminal
window and explore the downloaded directories and files.\newline

Run \lstinline{./planet.sh} as soon as possible. It takes some time du to the donwloads and of the compilation of the netCDF library.

\subsection{A first glance at the installed files and directory}

While installing, you can navigate through the files.

\lstinline{planet.sh} will first download
\footnote{Automatically from the LMDZ web site.}
\lstinline{install_lmdz.sh}, the main LMDZ installation script.

\lstinline{install_lmdz.sh} itself will :
\begin{itemize}
\item get files and archives (LMDZ, netCDF library, benches) with the \lstinline{wget} command from the LMDZ web site.
\item install (by default, which means without options) create the \lstinline{~/LMDZmini/LMDZseq} directory containing LMDZ.
\item install \lstinline{netcdf4_hdf5_seq}, which contains the NetCDF library.
\item  optionally creates a directory \lstinline{~/LMDZmini/LMDZ/pub} in which the downloaded files are stored in order to avoid downloading them twice if something went wrong\footnote{You do not have to do anything special for that.}.
\end{itemize}

\lstinline{LMDZseq} itself contains
\lstinline{modipsl}, which contains the model
In \lstinline{modipsl}, you will find directory \lstinline{modeles}, containing the 
\lstinline{LMDZ} directory.\footnote{The default behavior of the \lstinline{install_lmdz.sh} script is to install the model using the \lstinline{gfortran} compiler, which is fine on the laptops provided for this training course.
In any case, you can switch to another compiler using the \texttt{compiler} option of the \lstinline{install_lmdz.sh} script.
Several other features of the script can be modified or unactivated
just by editing few parameters in the file or specifying the appropriate
option (run \lstinline{./install_lmdz.sh -h} to learn about these). For example, you can disable the
NetCDF download and installation (first operation performed by \lstinline{install_lmdz.sh})
in case this library is already present on the computer you are using.}


Once the test bench simulation has been launched (the final step of the \lstinline{install_lmdz.sh}
script), you can visit the LMDZ tree on an other terminal.

\begin{lstlisting}
cd ~/LMDZmini/LMDZseq/modipsl/modeles/LMDZ
\end{lstlisting}
you will also find a  \lstinline{BENCH32x32x39/} directory from where
you will be able to run the model by launching
\begin{lstlisting}
cd ~/LMDZmini/LMDZseq/modipsl/modeles/LMDZ 
\end{lstlisting}
which willl list the outputs of the run (even if the simulation is still running:
it indeed takes a few minutes to complete the 3 day-long run on a single processor).
Check out the contents of this directory and use your favorite software (Grads,
Ferret,...) to browse the contents of the \lstinline{histday.nc} file.\newline

The source files of the dynamical core are in:\\
\begin{lstlisting}
~/LMDZmini/LMDZseq/modipsl/modeles/LMDZ/libf/dyn3d
\end{lstlisting}
including the main programm \lstinline{gcm.F90}.
Physics parameterizations are in:\\
\begin{lstlisting}
~/LMDZmini/LMDZseq/modipsl/modeles/LMDZ/libf/phylmd
\end{lstlisting}
physics parameterization driver: \lstinline{physiq_mod.F90}\\
The bench simulation is in 
\begin{lstlisting}
~/LMDZmini/LMDZseq/modipsl/modeles/LMDZ/BENCH32x32x39
\end{lstlisting}
You can start looking at the results in \lstinline{histday.nc}.
To know the variables available there :
\begin{lstlisting}
ncdump -h histday.nc  | grep long_name
\end{lstlisting}
Start to visualize outputs.

\subsection{Known issues}

Installing netCDF is one of the subtile things of the installations.
The choice by default was made that \lstinline{planet.sh} is compiling the netCDF library from sources.
This option is on average the most robust.

If you face problem with it, you can try to use the netCDF library installed on your machine by changing "\lstinline{-netcdf $local_d}" by "\lstinline{-netcdf 0}" in  \lstinline{planet.sh}.

% ---------------------------------------------------------------
\section{Exploring ``physics tendecies"}
% ---------------------------------------------------------------


Open \lstinline{histday.nc}.

\subsection{Le rayonnement}

On peut commencer par regarder les flux radiatifs descendants au sommet de l'atmosphere (swdntoa) ou au sol (swdnsfc) a differents instants.
On peut les moyenner aussi en temps et longitude (plot swdntoa[i=@ave,l=@ave]).

Les tendances associees au rayonnement sont:\\
- dtswr, K/s pour le SW,\\
- dtlwr, K/s pour le LW.\\ 
Quel est l'impact du rayonnement sur la temperature de l'atmosphere?


\subsection{La couche limite diffuse}

La turbulence de couche limite est prise en compte par une parametrisation des tourbillons diffusifs assurant un transport local dans la couche limite.\\ 
Les tendances en temperature et en humidite resultant de la turbulence de couche limite sont:\\
- dtvdf, K/s pour la temperature,\\
- dqvdf, kg/kg/s pour l'humidite.\\
Quel est l'impact de la turbulence sur la temperature et l'humidite de la couche limite?


\subsection{Les thermiques de couche limite}

Le transport non local au sein de la couche limite est pris en compte par une representation explicite des panaches thermiques.\\
Les tendances en temperature et en humidite resultant de l'effet des thermiques sont:\\
- dtthe, K/s pour la temperature\\
- dqthe, kg/kg/s pour l'humidite.\\
Quel est l'impact des thermiques sur la temperature et l'humidite de l'atmosphere?

\subsection{La convection profonde precipitante}

La convection profonde et les pluies associees sont prises en compte par une parametrisation de la convection nuageuse profonde pouvant atteindre le sommet de la troposphere.\\
Les tendances en temperature et en humidite resultant de la convection profonde sont:\\
- dtcon, K/s pour la temperature,\\
- dqcon, kg/kg/s pour l'humidite.\\
Quel est l'impact de la convection profonde sur la temperature et l'humidite de l'atmosphere?

\subsection{Les poches froides}

Le schema de convection profonde est couple a une parametrisation des poches froides qui se creent sous les systemes convectifs par l'evaporation des precipitations.\\
Les tendances en temperature et en humidite resultant de l'effet des poches froides sont:\\
- dtwak, K/s pour la temperature,\\
- dqwak, kg/kg/s pour l'humidite.\\
Quel est l'impact des poches froides sur la temperature et l'humidite de l'atmosphere?


\subsection{Condensation et evaporation de grande-echelle}

Les tendances associees a la condensation et l'evaporation ``grande-echelle" sont:\\
- dtlsc, K/s et dqlsc, kg/kg/s pour la condensation,\\
- dteva, K/s et dqeva, kg/kg/s pour l'evaporation. \\
Quel est l'impact de ces processus sur la temperature et l'humidite de l'atmosphere?\\
Rq: Pour avoir l'effet net, tracez dtlsc+dteva et dqlsc+dqeva.

\subsection{L'effet de l'orographie sous maille}

Les tendances associees a la prise en compte de l'orographie sont:\\
- dtoro, K/s et dqoro, kg/kg/s pour la trainee,\\
- dtlif, K/s et dqlif, kg/kg/s pour la portance.\\ 
Quel est l'impact de ces processus sur la temperature et l'humidite de l'atmosphere?

\subsection{Bilan}

Comparez l'evolution de la temperature et de l'humidite en un point donne entre la fin et le debut de la simulation avec la somme des tendances dues aux differentes parametrisations physiques.


% ---------------------------------------------------------------
\section{Running a sensitivity experiment}
% ---------------------------------------------------------------


In \lstinline{~/LMDZini/LMDZsec/modipsl/modeles/LMDZ}, create a new directory
\begin{lstlisting}
cd ~/LMDZmini/LMDZseq/modipsl/modeles/LMDZ
mkdir SIMU 
cd SIMU
\end{lstlisting}

Copy required files from \lstinline{BENCH32x32x39/} 
\begin{lstlisting}
cp ../BENCH32x32x39/start.nc .    # initial state of the dynamical core
cp ../BENCH32x32x39/startphy.nc . # initial state of physics parameterizations
cp ../BENCH32x32x39/limit.nc .    # boundary conditions (sea surface temp ...)
cp ../BENCH32x32x39/*.def .       # parameter files
cp ../BENCH32x32x39/gcm.e .       # model executable
\end{lstlisting}
Then run a new simulation
\begin{lstlisting}
./gcm.e
\end{lstlisting}
If you do not change anything before rerunning, the output files will be exactly the same as in the first simulations.

More interestingly, 
you may deactivate the "thermal plume model", the mass flux parameterization of boundary layer convection, by changing \lstinline{iflag_thermals=18} to \lstinline{iflag_thermals=0} in \lstinline{physics.def}.

You can open the two history files coming from the control and sensitivity experiments under \lstinline{ferret} with
\begin{lstlisting}
use ../BENCH32x32x39/histhf.nc
use histhf.nc
reg/x=0/y=22/k=30:39
set view ul
fill/lev=(-Inf)(-1.8,1.8,0.4)(Inf)/pal=blue_darkred Temp-temp[d=1]
contour/o/color=8 temp
set view ur
plot/l=7 theta[d=1],theta
\end{lstlisting}




% ---------------------------------------------------------------
\section{Installing the Single Column Model (1D configuration)}
% ---------------------------------------------------------------

You may run a 1D or "Single Column Model" configuration:
\begin{lstlisting}
./planet.sh SCM
\end{lstlisting}
will automatically install the SCM version of the model in \\
\lstinline{~/LMDZmini/LMDZseq/1D/EXEC/6AL79/ARMCU/REF}.
Ceux qui savent qu'ils vont travailler plutôt en 1D peuvent faire la suite avec un ou des cas 1D.
De la documentation est disponible dans \lstinline{~/LMDZmini/LMDZseq/1D/DOC}.

You can run the model by specifying from the begining a list of test cases :
\begin{lstlisting}
./planet.sh --grid 95 SCM[:case1,case2,...]
\end{lstlisting}
Cases should be taken among
\begin{lstlisting}
dry convection          : ayotte
cumulus continent       : arm_cu ARMCY/REF
marine cumulus          : rico RICO/REF rico2  bomex bomex2
strato cumulus          : fire sandufast sanduref sanduslow
ocean. deep convection  : toga twpice
cont.  deep convection  : amma
radiative/conv. eq.     : eq_rd_cv
other                   : hapex92_init dice_bucket gabls4
\end{lstlisting}



%--------------------------------------------------------------------------------------
\section{Installing various Earth climate configurations}
%--------------------------------------------------------------------------------------

\begin{lstlisting}
./planet.sh CONFIG 
\end{lstlisting}

with \lstinline{CONFIG} in 
\begin{description}
\item{\lstinline{clim: }} Running with imposed climatological SSTs \\
\item{\lstinline{slab: }} Running with a ``slab ocean", a two layer model developed by Francis Codron. \\
\item{\lstinline{aqua: }} Running an aquaplanet, with imposed Sea Surface Temperature (SST) all over the world that depends on latitude only.  \\
\item{\lstinline{terra:}} Running a terra planet in which surface temperature is computed with a simple thermal conduction with imposed thermal inertia. \\
\end{description}

The simulation will be run automatically  in a directory named \lstinline{CONFIG_IMxJMxLM} where
 \lstinline{IMxJMxLM} corresponds to the number of grid points in 3 directions.

A first simulation is run automatically on \lstinline{CONFIG_IMxJMxLM/SIMU1}.

A longer simulation can be run on several months or years, year by year, on \lstinline{CONFIG_IMxJMxLM/PROD0} by just running \lstinline{./enchaine.sh}.


%--------------------------------------------------------------------------------------
\section{Installing a configuration with idealized physics}
%--------------------------------------------------------------------------------------

The model can be run with a simplified physics, in which only 19 parameters are used
to describe the planet to be simulated.
\begin{lstlisting}
./planet.sh SimplePhysics 
\end{lstlisting}
installs a simulation on \lstinline{SimplePhysics_IMxJMxLM}



%--------------------------------------------------------------------------------------
\section{Changing the model grid}
%--------------------------------------------------------------------------------------

A zoom can be applied as well with a zooming factor of typically 2. This zooming factor is defined as the ratio of the smallest grid cell size in x and y to that of the regular grid.

The options to change the grid can be found by running 
\begin{lstlisting}
./planet.sh --help
\end{lstlisting}
which returns
\begin{lstlisting}
Use : ./planet.sh PLANET                                   Default : bench
                  [--grid|-g IMxJMxLM]                     Default : 32x32x
                  [--rad|-r oldrad/rrtm/ecrad]             Default : oldrad
                  [--nday|-n number_of_days]               Default : 3
                  [--parallel 0/1]                         Default : 0
                               - Concerning the zoom -
                  [--lon0|-x zoom_center_longitude]        Default : -120
                  [--lat0|-y zoom_center_latitude]         Default : 0
                  [--ext_lon|-dx zoom_extension_longitude] Default : 120
                  [--ext_lat|-dy zoom_extension_latitude]  Default : 60
                  [--fact_zoom|-f zoom_factor]             Default : 1
                  [--fact_zoomx|-fx zoom_factor_in_x]      Default : 1
                  [--fact_zoomx|-fx zoom_factor_in_y]      Default : 1

PLANET among
     bench  : bench for installation. 32x32x39. Coming with start files
     tuto   : the simplest one                        |
     clim   : Climatological SSTs                     |
     aqua   : aqua planet (SST function of latitude)  | From models/gcm
     terra  : global continent (simple soil)          |
     slab   : With a slab ocean                       |
     simple : 20 parameter physics
     dev    : teaching parameterization development
     SCM[:case1,case2,...] : 1D configurations, with optional cases specif.
\end{lstlisting}


%--------------------------------------------------------------------------------------
\section{Installing a parallel version for longer 3D simulations}
%--------------------------------------------------------------------------------------

\begin{lstlisting}
./planet.sh --parallel 1
\end{lstlisting}
This ill automatically install a parallel version of the model in\\
\lstinline{~/LMDZmini/LMDZpar/}

For running  the model, you can not use \lstinline{gcm.e} anymore, since you have to specify the number of CPU used for running the code. The parallelism relies on a combination of \lstinline{OpenMP} and \lstinline{MPI} approach.
When running the model manually on \lstinline{SIMU}, the number of processes used are specified in the \lstinline{run_local.sh} command
\begin{lstlisting}
./run_local.sh nMPI nOMP gcm.e
\end{lstlisting}
with typically \lstinline{nMPI=2} and \lstinline{nOMP=2} on a classical laptop with 4 physical CPUs.


\bigskip\bigskip
\appendix
{\LARGE \bf\flushleft Appendix}
%--------------------------------------------------------------------------------------
\section{Changing the outputs}
%--------------------------------------------------------------------------------------


The model outputs are controled in file \lstinline{config.def} by the following
lines (for instance in the standard bench):
\begin{lstlisting}
phys_out_filekeys=       y       y       y       n       n
phys_out_filenames=      histmth histday histhf  histins histLES
phys_out_filelevels=     10      5       4       3       4
phys_out_filetypes=      ave(X)  ave(X)  ave(X) inst(X) inst(X)
phys_out_filetimesteps=   5day   1day    6hr     6hr     6hr
\end{lstlisting}
Note the \lstinline{phys_out_filekeys} flags (y/n) which set which file is generated.
In the present case, you will obtain 3 files (apart from ORCHIDEE related outputs):
\lstinline{histmth.nc}, \lstinline{histday.nc} and \lstinline{histhf.nc}, containing respectively
0 days (should contain 1 record for the whole run, but the output frequency set for \lstinline{histmth.nc} above is \lstinline{5day}, whereas the run was only 3 days long), daily and 6-hour averages.

You can find out which variables have been written in a given file by running the command:
\begin{lstlisting}
ncdump -h histday.nc | grep long_name
\end{lstlisting}

To get a \lstinline{histmth.nc} with data, you would need to run the model over 5 days.
This means you would need to change the value of \lstinline{nday} in file \lstinline{run.def} to 5.
To run a new simulation, issue command \lstinline{./gcm.e}; if all goes well, it should end with the message \lstinline{"Everything is cool"}.

%Before relaunching the model, you can switch the ORCHIDEE model off
%by editing, in the bench directory, the \lstinline{config.def} parameters file
%and setting \lstinline{VEGET=n}.\\
%Also, you need to remove some output files (in case you relaunch in the
%same directory):
%\begin{lstlisting}
%rm sechiba_out_*.nc sechiba_rest_out.nc
%\end{lstlisting}

You may also re-run the simulation with a higher output frequency for
a few variables (e.g. atmospheric temperature at 2m above the surface:
\lstinline{t2m}, surface pressure: \lstinline{psol}, precipitation: \lstinline{precip}, etc.),
and other fields types (for instance instantaneous fields) by modifying \lstinline{config.def}:
\begin{lstlisting}
phys_out_filekeys=       y       y       n       y       n
phys_out_filenames=      histmth histday histhf  histins histLES
phys_out_filelevels=     10      5       4       3       4
phys_out_filetypes=      ave(X)  ave(X)  ave(X) inst(X) inst(X)
phys_out_filetimesteps=   5day   1day    6hr     6hr     6hr
flag_t2m=                10      10      5       3       5
flag_psol=               10      10      5       3       4
flag_precip=             10      10      4       3       5
\end{lstlisting}
Note that unlike other frequencies, 1TS (1 Time Step) is written in capital letters.\\
You can check in particular the \lstinline{histins.nc} file and explain the special results.


\end{document}
