source: trunk/LMDZ.MARS/doc/compilation.tex @ 2790

\chapter{Program organization and compilation script}
\label{sc:info}
\index{Programming organization and compilation}

\label{loc:contenu} 

Currently the model is split between two directories: {\bf LMDZ.COMMON}
and {\bf LMDZ.MARS}. The reason for this separation is that all that
concerns the dynamics (and which is common to all planets) is in
{\bf LMDZ.COMMON} whereas all that concerns the Martian physics is
in {\bf LMDZ.MARS}. For historical reasons, {\bf LMDZ.MARS} still
includes a dynamical core, but it is strongly recommended to use
the {\bf LMDZ.COMMON} (mandatory if you want to run in parallel).

\noindent Here is a brief description of the contents of directory
{\bf LMDZ.COMMON}:
\begin{verbatim}
 libf/  model FORTRAN Source code (.F or .F90)
         and  include files (.h) organised in sub-directories
        (dynamics (dyn3d), filters (filtrez), interface with
         physical packages (dynphy_lonlat), ...)

 arch/  set of architecture files used by the makelmdz_fcm script

 makelmdz_fcm  script to use to compile the GCM and related
                utilities
 bin/ directory where executables generated by the makelmdz_fcm
       script will be generated

 ioipsl/ directory with scripts usefull to download and build the
          IOIPSL library (not needed by the Martian GCM).
\end{verbatim}

\noindent And a brief description of the
{\bf LMDZ.MARS} directory contents:
\begin{verbatim}
 libf/ Model FORTRAN Source code (.F or .F90)
        and  include files (.h) organised in sub-directories
        (physics (phymars), dynamics (dyn3d), filters (filtrez)...)

 deftank/ A collection of examples of parameter files required 
                to run the GCM (run.def, callphys.def, ...)
  
 util/ A set of programs useful for post-processing GCM outputs.

 makegcm (Obsolete) script that should be used to compile the GCM as well
            as related utilities (newstart, start2archive, testphys1d)
\end{verbatim}

obtain
\section{Organization of the model source files}
\index{Organization of the model source files}

The model source files are stored in various sub directories
in directories {\tt LMDZ.COMMON/libf} and {\tt LMDZ.MARS/libf}.
These sub-directories correspond to the different parts of the model: \\
In {\tt LMDZ.COMMON} one will find directories relevant for the dynamical core:
\begin{description}
\item{\bf grid:} mainly made up of "dimensions.h" file,
which contains the parameters that define the model grid,
i.e. the number of points in longitude (iim), latitude (jjm) and altitude
(llm).

\item{\bf dyn3d:} contains the dynamical core's serial code.

\item{\bf dyn3dpar:} contains the dynamical core's parallel code.

\item{\bf dy3d\_common:} contains routine common to serial and parallel dynamical cores.

\item{\bf dynphy\_lonlat:} contains the physics/dynamics interfaces, including in subdirectory
{\tt dynphy\_lonlat/phymars} the interface to the Martian physics.

\item{\bf filtrez:} contains the longitudinal filter sources applied in the
polar latitudes where the Courant-Friedrich-Levy stability criterion would otherwise be violated.

\item{\bf misc:} contains miscelaneous routines, neither specific to dynamics or physics.

\item{\bf phy\_common:} contains routines common to all physics packages (Mars, Venus, ...)

\item{\bf aeronomars, phymars:} these are links to the directories of the Mars physics package in
{\tt LMDZ.MARS/libf}

\item{\bf aeronostd, chimtitan, muphytitan, phystd, phytitan, phyvenus:} links, which may be broken, to
other physics packages (Titan, Venus, Generic GCM).
\end{description}

\noindent In {\tt LMDZ.MARS/libf} are subdirectories relevent to the Mars physics package:
\begin{description}
\item{\bf dyn3d, grid, filtrez:} Obsolete versions of the serial dynamical core (the
dynamics package included in LMDZ.COMMON should be used instead).

\item{\bf phymars:} contains the Martian physics routines.

\item{\bf aeronomars:} contains the Martian chemistry and thermosphere routines.
\end{description}

\section{Programming}

The model is written in {\bf Fortran}.
\begin{itemize}
\item The program sources are written in {\bf ``file.F"} 
or {\bf ``file.F90''} files.
The extension .F is the standard extension for fixed-form Fortran and
the extension .F90 is for free-form Fortran.
These files must be preprocessed (by a{\bf C preprocessor}
such as (cpp)) before compilation (this behaviour is, for most
compilers, implicitly obtained but using a capital F in the extention
of the file names).

\item Constants are placed in COMMON declarations,
located in the common ``include'' files {\bf "file.h"} or in relevant modules.

\item In general, variables should be passed from subroutine to subroutine
as arguments (and never as COMMON blocks).

\item In some parts of the code, for ``historical'' reasons,
the following rule is sometimes used: in the subroutine,
the variables (ex: \verb+name+) passed as an argument by the calling program
are given the prefix \verb+p+ (ex: \verb+pname+)
 while the local variables are given the prefix \verb+z+ (ex: \verb+zname+).
As a result, several variables change their prefix (and thus their name)
when passing from a calling subroutine to a called subroutine. 
\end{itemize}

\section{Model organization}
Figure~\ref{fg:organi_phys} describes the main subroutines called by physiq.F. 
\index{Model organization}
\begin{figure}
\begin{flushleft}
\includegraphics[scale=0.70,angle=-90]{Fig/physique.pdf}
\caption{Organigram of subroutine function physiq.F}
\label{fg:organi_phys}
\end{flushleft}
\end{figure}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%  Compilation du modele
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Compiling the model}
\index{Compiling the model}

\label{sc:compil1}
Technically, the model is compiled using the Unix utility {\tt make}.
The {\tt makelmdz\_fcm} utility script recreates the {\tt makefile} file
when necessary, for example, when a source file has been added or removed
since the last compilation.

\noindent {\bf None of this is visible to the user.
To (re-)compile the model just run the command}
\begin{verbatim}
makelmdz_fcm
\end{verbatim}
with adequate options (e.g.
{\tt makelmdz\_fcm -arch local -d 62x48x32 -p mars gcm}), as
described in section~\ref{sc:compile}.


\paragraph{Help manual for the makelmdz\_fcm script}
Use the "-h" option to learn about possible options:
\begin{verbatim}
makelmdz_fcm -h
\end{verbatim}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% makegcm.help:  lu dans makegcm
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\input{input/makegcm_help.tex}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%