source: trunk/MESOSCALE/DOC/SRC/installation.tex @ 206

\chapter{Installing the model}

\vk
This chapter is meant for first time users of the LMD Martian Mesoscale Model. We describe how to install the model on your system. Experience with either the terrestrial WRF mesoscale model or the LMD Martian GCM is not absolutely required,
although it would help you getting more easily through the installation process.

\mk
\section{Prerequisites}

\sk
\subsection{General requirements}

\sk
In order to install the LMD Martian Mesoscale Model, please ensure the following prerequisites:
\begin{citemize}
\item your computer is connected to the internet;
\item you have~\ttt{200 Mo} free disk space available;
\item your OS is Linux\footnote{The model was also successfully compiled on MacOSX; ``howto" information is available upon request but could have become obsolete on recent versions of Apple hardware and software. It is probably possible to compile the model on Windows using Cygwin but this has not implemented nor tested. You are kindly advised to install a Linux distribution on your computer (e.g. Ubuntu, Debian, Fedora, ...).} with a decent set of basic commmands (\ttt{sed}, \ttt{awk}, \ldots);
\item at least one of the following Fortran compilers is installed on your computer
\begin{itemize}
\item Portland Group commercial compiler \ttt{pgf90}
\item G95 free compiler\footnote{Sources and binaries available on \url{http://www.g95.org}} \ttt{g95} 
\item Intel commercial compiler \ttt{ifort} 
\end{itemize}
\item your C compiler is \ttt{gcc} and C development libraries are included;
\item \ttt{bash}, \ttt{m4} and \ttt{perl} are installed on your computer;
\item \ttt{netCDF} libraries\footnote{The outputs from model computations are in netCDF format. This is a convenient self-describing file format widely used in atmospheric science and data analysis. Further information and downloads can be found in \url{http://www.unidata.ucar.edu/software/netcdf}.} have been compiled \emph{on your system with the Fortran compiler suite you aimed to use to compile the model}. Three environment variables associated with the \ttt{NETCDF} libraries must be defined with the following commands\footnote{Note that all command lines proposed in this document are defined in \ttt{bash} script language}:
\begin{verbatim}
declare -x NETCDF=/disk/user/netcdf  
declare -x NCDFLIB=$NETCDF/lib       
declare -x NCDFINC=$NETCDF/include       
\end{verbatim}
\end{citemize} 

\sk
\begin{finger}
\item 
You might also find useful -- though not mandatory -- to install on your system the following software:
\begin{citemize}
\item \ttt{ncview}\footnote{ \url{http://meteora.ucsd.edu/~pierce/ncview\_home\_page.html} }: tool to visualize the contents of a netCDF file;
\item \ttt{nco}\footnote{ \url{ http://nco.sourceforge.net } }: tools to manipulate and modify netCDF files;
\item \ttt{epd}\footnote{ \url{ http://www.enthought.com/products/getepd.php }. A complete version is available free of charge for students and employees at degree-granting institutions. A limited version with essential librairies is available free of charge for any user. }: the python distribution suite packaged by Enthought, including many librairies for plotting, scientific computations, data analysis...
\end{citemize}
\end{finger}

\sk
Parallel computations with the Message Passing Interface (MPI) standard are supported by the LMD Martian Mesoscale Model. If you want to use this capability, you would have to add the installation of MPICH2 as a additional prerequisite. Once the installation is completed, it is required to define the environment variable \ttt{\$WHERE\_MPI} to point in your \ttt{mpich} \ttt{bin} directory, even if you added the \ttt{\$LMDMOD/MPI/mpich2-1.0.8/bin} directory to your \ttt{\$PATH} variable. 

\begin{finger}
\item \scriptsize Here is a brief ``how-to" to install MPICH2, although this surely does not replace reading carefully installation notes and choosing what installation suits best your system. Please download the current stable version of the sources (e.g. we choose here an old version \ttt{mpich2-1.0.8.tar.gz} to illustrate the commands) on the MPICH2 website \url{http://www.mcs.anl.gov/research/projects/mpich2} and install the MPICH2 utilities by the following commands:
\begin{verbatim}
mkdir $LMDMOD/MPI
mv mpich2-1.0.8.tar.gz $LMDMOD/MPI
cd $LMDMOD/MPI
tar xzvf mpich2-1.0.8.tar.gz
cd mpich2-1.0.8
./configure --prefix=$PWD --with-device=ch3:nemesis > conf.log 2> conferr.log &
# please wait...
make > mk.log 2> mkerr.log &
declare -x WHERE_MPI=$LMDMOD/MPI/mpich2-1.0.8/bin
\end{verbatim}
\normalsize
\end{finger}

\sk
\subsection{Compiling the terrestrial WRF model}

\sk The LMD Martian Mesoscale Model is based on the terrestrial NCEP/NCAR ARW-WRF Mesoscale Model. As a first step towards the compilation of the Martian version, we advise you to check that the terrestrial model compiles on your computer with either \ttt{g95} or \ttt{pgf90} or \ttt{ifort}. On the ARW-WRF website \url{http://www.mmm.ucar.edu/wrf/users/download/get\_source.html}, you will be allowed to freely download the model after a quick registration process (click on ``New users"). Make sure to download the version 2.2 of the WRF model and copy the \ttt{WRFV2.2.TAR.gz} archive to your current working directory. Then please extract the model sources and configure the compilation process:
\begin{verbatim}
tar xzvf WRFV2.2.TAR.gz
cd WRFV2
./configure
\end{verbatim}

\sk
The \ttt{configure} script analyzes your architecture and proposes you several possible compilation options. Make sure to choose the ``single-threaded, no nesting" option related to either \ttt{g95} (should be option $13$ on a $32$~bits Linux PC) or \ttt{pgf90} (should be option $1$ on a $32$~bits Linux PC) or \ttt{ifort}. The next step is then to compile the WRF model by choosing the kind of simulations you would like to run. A simple and direct test consists in trying to compile the idealized case of a 2D flow impinging on a small hill:
\begin{verbatim}
./compile em_hill2d_x > log_compile 2> log_error &
\end{verbatim}
%
\begin{finger} \item In case you encounter problems compiling the ARW-WRF model, please read documentation on the website \url{http://www.mmm.ucar.edu/wrf/users}, contact the WRF helpdesk or search the web for your error message. Our team will not be able to offer support for the LMD Martian Mesoscale Model if the ARW-WRF model does not compile and run on your system. \end{finger}

\sk
If the compilation is successful, the file \ttt{log\_error} should be empty or only reporting few warnings). In the \ttt{main} folder two executables \ttt{ideal.exe} and \ttt{run.exe} should be found and allow you to run the test simulation:
\begin{verbatim}
cd test/em_hill2d_x
./ideal.exe
./wrf.exe
\end{verbatim}

\sk
During the simulation, the time taken by the computer to perform integrations at each dynamical timestep  is displayed in the standard output. The simulation should end with a message \ttt{SUCCESS COMPLETE WRF}. The model results are stored in a \ttt{wrfout} netCDF data file you might like to browse with a \ttt{NETCDF}-compliant software such as \ttt{ncview}, or read with your favorite graphical software. 
%
\begin{finger} \item If you compiled the model with \ttt{g95}, \ttt{ideal.exe} will probably complain about an error reading the namelist. Please move the line \ttt{non\_hydrostatic} below the line \ttt{v\_sca\_adv\_order} in the \ttt{namelist.input} file to solve the problem. \end{finger}

\mk
\section{Main installation of the model sources}

\sk
\subsection{Method 1: You were given a \ttt{LMD\_MM\_MARS.tar.gz} archive}

\sk
Please set the environment variable \ttt{\$LMDMOD} to point at the directory where you will install the model and define the environment variable \ttt{\$MMM} as \ttt{\$LMDMOD/LMD\_MM\_MARS}. Copy the \ttt{LMD\_MM\_MARS.tar.gz} file in the \ttt{\$LMDMOD} directory and extract the files. Then execute the \ttt{prepare} script that would do some necessary installation tasks\footnote{Deflate the various compressed archives contained into \ttt{LMD\_MM\_MARS}, download the ARW-WRF sources from the web, apply a (significant) ``Martian patch" to these sources and build the structure of your \ttt{LMD\_MM\_MARS} directory} for you:
%
\begin{verbatim}       
declare -x LMDMOD=/disk/user/MODELS
declare -x MMM=$LMDMOD/LMD_MM_MARS
cp LMD_MM_MARS.tar.gz $LMDMOD
cd $LMDMOD
tar xzvf LMD_MM_MARS.tar.gz
cd $LMDMOD/LMD_MM_MARS
./prepare
\end{verbatim}

\sk
\subsection{Method 2: You were given a \ttt{svn} link \ttt{the\_link}}

\sk
\emph{You must have Subversion (\ttt{svn}) installed on your system to follow this method}. Please use the name of our server repository combined to an \ttt{svn checkout} command to get the model sources\footnote{At this stage, it is essential to have registered to the WRF website (see foreword) because our server contains some part of the ARW-WRF sources.}. Please also set the environment variable \ttt{\$LMDMOD} and \ttt{\$MMM}:

\begin{verbatim}
svn checkout the_link -N the_name_of_your_local_destination_folder
cd the_name_of_your_local_destination_folder
svn update LMDZ.MARS MESOSCALE
cd MESOSCALE
declare -x LMDMOD=$PWD
declare -x MMM=$LMDMOD/LMD_MM_MARS
\end{verbatim}

\sk
The first download of the model sources could be a bit long. Compared to method~$1$, this method~$2$ using \ttt{svn} would allow you to easily get the latest updates and bug fixes done on the LMD Martian Mesoscale Model by the development team\footnote{If you are not interested by this feature, please replace the command line featuring \ttt{svn checkout} by this command line \ttt{svn export the\_link/LMDZ.MARS the\_link/MESOSCALE} }:

\begin{verbatim}
cd the_name_of_your_local_destination_folder
svn update LMDZ.MARS MESOSCALE
svn info | more
\end{verbatim}

\mk
\section{Structure of the \ttt{LMD\_MM\_MARS} directory}

\sk
Please check the contents of the \ttt{LMD\_MM\_MARS} and the \ttt{LMD\_MM\_MARS/SRC} directories by the following command line:
\begin{verbatim}
ls $MMM
ls $MMM/SRC
\end{verbatim}

\sk
Contents of~\ttt{LMD\_MM\_MARS} directory:
\begin{citemize}
\item seven \ttt{bash} scripts: 
\begin{itemize}
\item \ttt{build\_static}, 
\item \ttt{copy\_model},
\item \ttt{makemeso}, 
\item \ttt{prepare},
\ttt{prepare\_ini},
\ttt{prepare\_offline}, 
\ttt{prepare\_post},
\item \ttt{save\_all}; 
\end{itemize}
\item the sources directory \ttt{SRC};
\item the static data directory \ttt{WPS\_GEOG};
\item the simulation utilities directory \ttt{SIMU}.
\end{citemize}

\sk
Contents of~\ttt{LMD\_MM\_MARS/SRC} directory:
\begin{citemize}
\item the main model sources in \ttt{WRFV2},
\item the preprocessing sources in \ttt{WPS} and \ttt{PREP\_MARS},
\item the postprocessing sources in \ttt{POSTPROC} and \ttt{ARWpost},
\item three \ttt{tar.gz} archives and two information text files.
\end{citemize}

\sk
Contents of~\ttt{LMD\_MM\_MARS/WPS\_GEOG} directory:
\begin{citemize}
\item three directories \ttt{albedo\_GCM}, \ttt{mola\_GCM}, \ttt{thermal\_GCM}, \ttt{res}
\item one data file \ttt{dust\_tes.nc}
\end{citemize}

\sk
The directory~\ttt{LMD\_MM\_MARS/SIMU} contains many files and directories not important at this stage. If you used method~$2$, you will probably notice that other directories than~\ttt{LMD\_MM\_MARS} are present in \ttt{\$LMDMOD}, but those are not important at this stage.

\clearemptydoublepage