\documentclass{article}
\usepackage[english]{babel}
\usepackage[latin1]{inputenc}

\usepackage{a4wide}
\begin{document}

\def\afaire#1{{\bf Afaire : #1}}
\title{Hands on tutorial : installing, compiling and executing the model}
\date{January 5th, 2023}
\author{The LMDZ team}

\maketitle

This first tutorial focuses on installing the model in sequential mode and making a simple bench run. We then install the model in parallel mode and run a simple test bench as well.
This ensures that you will be ready for the hands-on tutorials of the training session
starting on the 10th of January.

This document can be downloaded as a pdf file:
\begin{verbatim}
wget http://lmdz.lmd.jussieu.fr/pub/Training/Tutorials/Tutorial_simple.pdf
\end{verbatim}
which should ease any copy/paste of command lines to issue.

%\def\infol#1{#1}
%\def\infol#1{\verb+ #1 +}
\def\infol#1{{\bf #1}}
%\newcommand{\infol}[1]{\verb\+ #1 \+}

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


\section{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

\begin{verbatim}
ulimit -Ss unlimited
\end{verbatim}

but be advised we have encounterd cases where this did not work and you had to specify a numeric amount.




\section{Running the install\_lmdz.sh script for a sequential version of LMDZ}

The first step consists in downloading it from the LMD website
and {\em blindly} running it (after having first set the access permissions
to make it executable):
\begin{verbatim}
wget http://lmdz.lmd.jussieu.fr/pub/install_lmdz.sh
chmod +x install_lmdz.sh
./install_lmdz.sh -name LMDZTraining
\end{verbatim}

The "\verb|-name LMDZTraining|" option to the script just insures that the model will be installed in a 
directory called \verb|LMDZTraining| in the current directory.



Launching the script as indicated above will 
download the latest version of the source code, compile it and run a simple bench test case
at resolution \resol{32}{32}{39}. \newline
Compilation should take around five minutes.
The test bench is then downloaded and the
1 day long test simulation on a regular \resol{32}{32}{39} grid is run ;
messages about various downloads (via \infol{wget}) and/or compiler
informations are displayed.

The script should then run smoothly (if it isn't the case,
immediately ask for some assistance) and
end with messages such as:
\begin{verbatim}
##########################################################
Simulation finished in ...
You have compiled with:
./makelmdz...
You may re-run it with : cd  ...
or ./bench.sh
##########################################################
\end{verbatim}

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

\verb+install_lmdz.sh+ will check if some archives (LMDZ, NetCDF library, etc.) are
on the disk (in the \verb+~/LMDZ+ directory and subdirectories) and if not, will try to retrieve
them through the network using \verb+wget+ command.
It will create the \infol{LMDZTraining} directory ; inside, you will find subdirectories
\infol{modipsl}, which contains the model, and
\infol{netcdf-4.0.1}, which contains the NetCDF library.

In \infol{modipsl}, you will find directory \infol{modeles}, containing the 
\infol{LMDZ} directory.


Once the test bench simulation has been launched (the final step of the \infol{install\_lmdz.sh}
script), you will also find a  \infol{LMDZ/BENCH32x32x39/} directory from where
you will be able to list the outputs of the run (even if the simulation is still running:
it indeed takes a few minutes to complete the 1 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 \infol{histday.nc} file.\newline

\section{Running the install\_lmdz.sh script for a parallel version of LMDZ with ORCHIDEE}

We only need to change a few options when calling the \verb+install_lmdz.sh+ script to have LMDZ installed in parallel MPI+OMP mode (provided the corresponding libraries are 
installed on your computer) with the ORCHIDEE land-surface model. You should go back to the top directory where you copied the \verb+install_lmdz.sh+ script and launch it as

\begin{verbatim}
./install_lmdz.sh -name LMDZORpar -parallel mpi_omp -veget CMIP6 -netcdf 0
\end{verbatim}

where the options
\begin{itemize}
\item \verb+-parallel mpi_omp+ controls which parallel mode we choose to run
\item \verb+-veget CMIP6+ indicates that we want to run with the version of ORCHIDEE used in CMIP6
\item \verb+-netcdf 0+ indicates that we want to compile the model with the version of NetCDF installed on your machine. This should speed up the compilation provided the NetCDF
librairies are installed on your computer
\end{itemize}

If you're not sure whether NetCDF is indeed installed on your machine, you might try the following command:

\begin{verbatim}
./install_lmdz.sh -name LMDZORpar -parallel mpi_omp -veget CMIP6 \
                  -netcdf `pwd`/LMDZTraining/netcdf4_hdf5_seq 
\end{verbatim}

here, the "\verb+-netcdf `pwd`/LMDZTraining/netcdf4_hdf5_seq+" tells the script to compile the model with the version of NetCDF that was compiled in the first step of this tutorial
that can be found in the 
\infol{LMDZTraining/netcdf4\_hdf5\_seq} directory.

If everything goes to plan, you should get the same kind of messages as in the first part of this tutorial. If something does not work, don"t hesitate to ask for our help.
\end{document}
