\documentclass[a4paper,10pt]{article}
%\usepackage{graphicx}
\usepackage{natbib}  % si appel � bibtex
%\usepackage[francais]{babel}
%\usepackage[latin1]{inputenc}  % accents directs (�...), avec babel
%\usepackage{rotating}

\setlength{\hoffset}{-1.in}
\setlength{\oddsidemargin}{3.cm}
\setlength{\textwidth}{15.cm}
\setlength{\marginparsep}{0.mm}
\setlength{\marginparwidth}{0.mm}

\setlength{\voffset}{-1.in}
\setlength{\topmargin}{0.mm}
\setlength{\headheight}{0.mm}
\setlength{\headsep}{30.mm}
\setlength{\textheight}{24.cm}
\setlength{\footskip}{1.cm}

\setlength{\parindent}{0.mm}
\setlength{\parskip}{1 em}
\newcommand{\ten}[1]{$\times 10^{#1}$~} 
\renewcommand{\baselinestretch}{1.}

\begin{document}
\pagestyle{plain}

\begin{center}
{\bf \LARGE 
Documentation for LMDZ, Planets version

\vspace{1cm}
\Large
Running with only one column: \\
1D version of the Titan PCM
}

\vspace{1cm}
S\'ebastien Lebonnois \\ Updated by Lucie Rosset

\vspace{1cm}
Latest version: \today
\end{center}


\section{The \textsf{rcm1d} tool}

The physical part of the model can be used to run 1D simulations (one atmospheric column / globally averaged climate). The model is initialized the same way {gcm.F} does on 3D, but only on a single column, so that the physics may be tested without any dynamics.
In practice, the simulation is controlled from a main program called \textsf{rcm1d.F}, located in the \textsf{phytitan/dyn1d} directory, which, after initialization, calls the master subroutine of the physics \textsf{physiq\_mod.F90}

\section{Compilation}

The rcm1d tool can be compiled sequentially, or in parallel if you want to obtain outputs \textit{via} XIOS. However, \textbf{it must always be ran sequentially}. In case of parallel compilation, make sure to run it on a single core.

Compilation for 1D configuration for 55 pressure layers, with sequential execution  :
\begin{verbatim}
./makelmdz_fcm -cpp CPP_1D -d 55 -b 23x23 -s 1 -p titan -j 8 rcm1d
\end{verbatim}

Compilation for 1D configuration for 55 pressure layers with XIOS enabled :

\begin{verbatim}
./makelmdz_fcm -cpp CPP_1D -parallel mpi -io xios -d 55 -b 23x23 -s 1 -p titan -j 8 rcm1d
\end{verbatim}

You can find the executable \textsf{rcm1d.e} (the compiled model)
in the directory from which you ran the \textsf{makelmdz} command.

\section{Input files}

To run the 1D model, you need to retrieve the following files from the \textsf{deftank} and copy them into your working directory:

\begin{itemize}
    \item {\bf rcm1d.def}~: controls the 1D run parameters and initializations. See Section 5 for more details.
    \item {\bf callphys.def}~: controls the options in the physics, just like for the 3D GCM.
    \item {\bf z2sig.def}~: controls the vertical discretization (no change needed, in general), functions as with the 3D GCM.
    \item {\bf traceur.def}~: controls the tracer names (this file may not be present, as long as you run without tracers (option \textsf{tracer=.false.} in \textsc{callphys.def}). In case you decide to run with tracers, initial profiles must be provided (else, it will be set to zero.)
    \item {\bf run.def}~: this is actually file \textsf{run.def.1d} in the \textsf{deftank} directory, which must be renamed \textsf{run.def} to be read by the program. It is different from the 3D GCM's \textsf{run.def} input file, as it is only used to access \textsf{rcm1d.def}.
    \item {\bf profile.def, gases.def}
\end{itemize}

Using these files and an initial temperature vertical profile defined in the \textsf{profile.F} routine (with options available through \textsf{rcm1d.def}), the model is initialized and a first \textsf{startfi.nc} file is written, to be read again at the first call of \textsf{physiq}.

\section{Tracer profiles}

In case you decide to run with tracers, profiles must be provided to the model. In you working directory, each tracer defined in \textsf{traceur.def} must have a corresponding \textsf{profile$\_$$<$tracer name$>$} file, containing $n_{levels}+1$ values : the first one for the tracer value at the surface and then one per pressure layer.

For all chemical tracers, a profile for the extended photochemistry (up to 1300km) must also be provided : \textsf{profile$\_$$<$species$>$$\_$up}.

\textbf{BEWARE : mixing ratios must be in kg/kg}

\section{Specific \textsf{rcm1d.def} file}
 
This file is read by \textsf{rcm1d} during initialization.
It can be found in the \textsf{deftank} directory. 
Each line has a comment explaining what the parameter is. 

The number of timestep per day (third parameter) is the number of calls to the physics per day, since no dynamics is involved here.

It also includes parameters for the temperature profile definition.

\section{Outputs}

All aspects of the outputs (name, units, file, post-processing operations, etc.) are controlled by XIOS. In order to be able to access the outputs, the model must be computed in parallel. The sequential compilation and run (without XIOS) only provides the temperature profile at the last timestep.

To run the model with XIOS, the working directory must contain two dedicated XML files which are read at run-time, and provided in the \textsf{deftank} directory : \textsf{iodef.xml} and \textsf{context\_lmdz\_physics.xml}.

\end{document}
