source: trunk/MESOSCALE_DEV/MANUAL/SRC/user_manual_txt.tex @ 219

\mk
\chapter{Preprocessing utilities}

\mk
In the previous chapter, we decribed the simulation settings
in the \ttt{namelist.input} file.
%
We saw that any modification of the parameters
labelled with \ttt{(p1)}, \ttt{(p2)} or \ttt{(p3)} 
implies the initial and boundary conditions
and/or the domain definition to be recomputed prior to running the model again.
%
As a result, you were probably unable to change many of the parameters 
of the Arsia Mons test case (proposed in section \ref{sc:arsia}) in which 
the initial and boundary conditions -- as well as the domain of 
simulation -- were predefined.

\mk
\marge In this chapter, we describe the installation and use of the preprocessing tools to 
define the domain of simulation, calculate an initial atmospheric state
and prepare the boundary conditions for the chosen simulation time.
%
This necessary step would eventually allow you to run your own simulations at the specific season and region
you are interested in, with a complete ability to modify any of the parameters in \ttt{namelist.input}.

\mk
\section{Installing the preprocessing utilities}

\mk
First and foremost, since the preprocessing utilities could generate 
(or involve) files of quite significant sizes, it is necessary
to define a directory where these files would be stored.
%
Such a directory (e.g. \ttt{/bigdisk/user}) must be linked as follows
%
\begin{verbatim}
ln -sf /bigdisk/user $LMDMOD/TMPDIR
\end{verbatim}

\mk
\marge A second prerequisite to the installation of the preprocessing tools is that the LMD Martian
Mesoscale Model was compiled at least once.
%
If this is not the case, please compile
the model with the \ttt{makemeso} command 
(see section \ref{sc:makemeso}).

\mk
\marge The compilation process created an
installation directory adapted to your
particular choice of compiler$+$machine.
%
The preprocessing tools will also
be installed in this directory.
%
Please type the following commands:
%
\begin{verbatim}
cd $LMDMOD/LMD_MM_MARS/g95_32_single/   ## or any install directory
ln -sf ../prepare_ini .
./prepare_ini
\end{verbatim}

\mk
\marge The script \ttt{prepare\_ini} plays with the preprocessing tools 
an equivalent role as the \ttt{copy\_model} with the model sources :
files are simply linked to their actual location in the \ttt{SRC} folder.
%
Once you have executed \ttt{prepare\_ini}, please check that
two folders were generated: \ttt{PREP\_MARS} and \ttt{WPS}. 

\mk
\marge In the \ttt{PREP\_MARS} directory, please compile
the programs \ttt{create\_readmeteo.exe} and \ttt{readmeteo.exe}, 
using the compiler mentionned in the name of the current
installation directory: 
%
\begin{verbatim}
echo $PWD
cd PREP_MARS/
./compile [or] ./compile_g95
ls -lt create_readmeteo.exe readmeteo.exe
cd ..
\end{verbatim}

\mk
\marge In the \ttt{WPS} directory, please compile
the programs \ttt{geogrid.exe} and \ttt{metgrid.exe}:
\begin{verbatim}
cd WPS/   
./configure   ## select your compiler + 'NO GRIB2' option
./compile
ls -lt geogrid.exe metgrid.exe
\end{verbatim}

\mk
\marge Apart from the executables you just compiled,
the preprocessing utilities include \ttt{real.exe}, 
which was compiled by the \ttt{makemeso} script
along with the mesoscale model executable \ttt{wrf.exe}.
%
\ttt{real.exe} should be copied or linked in the 
simulation directory (e.g. \ttt{TESTCASE} for the
Arsia Mons test case) to be at the same level than
\ttt{namelist.input}.

\begin{finger}
\item Even though the name of the executable writes 
e.g. \ttt{real\_x61\_y61\_z61\_d1\_t1\_p1.exe}, such program
is not related to the specific \ttt{makemeso} 
parameters -- contrary to the \ttt{wrf.exe} executable.
%
We just found that renaming the (possibly similar
if the model sources were not modified) 
\ttt{real.exe} was a practical way not to confuse
between executables compiled at different moments. 
\end{finger}

\mk
\section{Running the preprocessing utilities}

\mk
When you run a simulation with \ttt{wrf.exe},
the program attempts to read the initial state 
in the files 
\ttt{wrfinput\_d01}, 
\ttt{wrfinput\_d02}, \ldots 
(one file per domain)
and the parent domain boundary conditions
in \ttt{wrfbdy\_d01}.
%
The whole chain of data conversion and
interpolation needed to generate those
files is summarized in the diagram next 
page.
%
Three distinct preprocessing steps are
necessary to generate the final files. 
%
As is described in the previous section,
some modifications in the \ttt{namelist.input} file
[e.g. start/end dates labelled with \ttt{(p1)}]
requires a complete reprocessing from step $1$ to step $3$
to successfully launch the simulation,
whereas other changes
[e.g. model top labelled with \ttt{(p3)}] 
only requires a quick reprocessing at step $3$, keeping
the files generated at the end of step $2$
the same.
 
\mk
\subsection{Input data}

\mk
\subsubsection{Static data}

\mk
All the static data 
(topography, thermal inertia, albedo)
needed to initialize the model
are included in the \ttt{\$LMDMOD/LMD\_MM\_MARS/WPS\_GEOG} directory.
%
By default, only coarse-resolution datasets\footnote{ 
%%%
Corresponding to the fields stored in the
file \ttt{surface.nc} known by LMD-MGCM users:
\url{http://web.lmd.jussieu.fr/~forget/datagcm/datafile/surface.nc}
%%%
} are available, but the directory also contains sources and scripts
to install finer resolution datasets:
\begin{citemize}
\item 32 and/or 64 pixel-per-degree (ppd) MOLA topography [\textit{Smith et al.}, 2001]\nocite{Smit:01mola},
\item 8 ppd MGS/Thermal Emission Spectrometer (TES) albedo [\textit{Christensen et al.}, 2001]\nocite{Chri:01},
\item 20 ppd TES thermal inertia [\textit{Putzig and Mellon}, 2007]\nocite{Putz:07} 
\end{citemize}
\pagebreak
\includepdf[pages=1,offset=25mm -20mm]{diagramme.pdf}

\mk
\marge The role of the \ttt{build\_static} script is to
automatically download these datasets from the web
(namely PDS archives) and convert them to an 
acceptable format for a future use by the 
preprocessing utilities:
%
\begin{verbatim}
cd $LMDMOD/LMD_MM_MARS
./build_static
\end{verbatim}
%
\begin{finger}
\item Please install the \ttt{octave}
free software\footnote{
%%%
Available at \url{http://www.gnu.org/software/octave}
%%%
} on your system to be able to use the
\ttt{build\_static} script.
%
Another solution is to browse into each of the
directories contained within \ttt{WPS\_GEOG}, download the
data with the shell scripts and execute the \ttt{.m} scripts with either
\ttt{octave} or the commercial software \ttt{matlab}
(just replace \ttt{\#} by \ttt{\%}).
%
\item If you do not manage to execute the \ttt{build\_static} script, 
converted ready-to-use datafiles are available upon request.
%
\item The building of the MOLA 64ppd topographical 
database can be quite long. Thus, such a process is
not performed by default by the \ttt{build\_static} script.
If the user would like to build this database,
please remove the \ttt{exit} command in the script, just above
the commands related to the MOLA 64ppd.
%
\item The resulting \ttt{WPS\_GEOG} can reach a size
of several hundreds of Mo. 
%
You might move such a folder in a place 
with more disk space available, but then be
sure to create in \ttt{\$LMDMOD/LMD\_MM\_MARS}
a link to the new location
of the directory.
\end{finger}

\mk
\subsubsection{Meteorological data}

\mk
The preprocessing tools generate initial and boundary conditions
from the \ttt{diagfi.nc} outputs of LMD-MGCM simulations.
%
If you would like to run a mesoscale simulation at a given
season, you need to first run a GCM simulation and output
the meteorological fields at the considered season.
%
For optimal forcing at the boundaries, we advise you
to write the meteorological fields to the 
\ttt{diagfi.nc} file at least each two hours.
%
Please also make sure that the following fields
are stored in the NETCDF \ttt{diagfi.nc} file:

\footnotesize
\codesource{contents_diagfi}

\normalsize
\begin{finger}
\item If the fields 
\ttt{emis}, 
\ttt{co2ice}, 
\ttt{q01}, 
\ttt{q02}, 
\ttt{tsoil} 
are missing in the \ttt{diagfi.nc} file, 
they are replaced by respective default 
values $0.95$, $0$, $0$, $0$, tsurf.
\end{finger}

\mk
\marge An example of input meteorological file 
\ttt{diagfi.nc} file can be downloaded
at \url{http://web.lmd.jussieu.fr/~aslmd/LMD_MM_MARS/diagfi.nc.tar.gz}.
%
Please deflate the archive and copy the \ttt{diagfi.nc} file
in \ttt{\$LMDMOD/TMPDIR/GCMINI}.
%
Such a file can then be used to define the initial
and boundary conditions, and we will go 
through the three preprocessing steps.

\mk
\subsection{Preprocessing steps} 

\mk
\subsubsection{Step 1: Converting GCM data}

\mk
\section{Running your own GCM simulations}

\begin{remarque}
To be completed
\end{remarque}

\mk
The programs in the \ttt{PREP\_MARS} directory
convert the data from the NETCDF \ttt{diagfi.nc}
file into separated binary datafiles for each
date contained in \ttt{diagfi.nc}, according to
the formatting needed by the 
preprocessing programs at step 2.
%
These programs can be executed by the following
commands: 
\begin{verbatim}
cd $LMDMOD/LMD_MM_MARS/your_install_dir/PREP\_MARS
echo 1 | ./create_readmeteo.exe     # drop the "echo 1 |" if you want control
./readmeteo.exe < readmeteo.def
\end{verbatim}
%
\marge If every went well with the conversion,
the directory \ttt{\$LMDMOD/TMPDIR/WPSFEED}
should contain files named \ttt{LMD:}.

\mk
\subsubsection{2: Interpolation on the regional domain}

\mk
In the \ttt{WPS} directory, the \ttt{geogrid.exe} program allows 
you to define the mesoscale simulation domain
to horizontally interpolate the topography, 
thermal inertia and albedo fields at the domain
resolution and to calculate useful fields
such as topographical slopes.%\pagebreak

\mk
\marge Please execute the commands:
%
\begin{verbatim}
cd $LMDMOD/LMD_MM_MARS/your_install_dir/WPS
ln -sf ../../TESTCASE/namelist.wps .   # test case
./geogrid.exe
\end{verbatim}
%
\marge The result of \ttt{geogrid.exe} 
-- and thus the definition of the mesoscale
domain -- can be checked in the NETCDF
file \ttt{geo\_em.d01.nc}.
%
A quick check can be performed using the command line
\begin{verbatim}
ncview geo_em.d01.nc
\end{verbatim} 
\marge if \ttt{ncview} is installed, or the \ttt{IDL}
script \ttt{out\_geo.pro}
\begin{verbatim}
idl
IDL> out_geo, field1='TOPO'
IDL> out_geo, field1='TI'
IDL> SPAWN, 'ghostview geo_em.d01_HGT_M.ps &'
IDL> SPAWN, 'ghostview geo_em.d01_THERMAL_INERTIA.ps &'
IDL> exit
\end{verbatim}
\marge if the demo version of \ttt{IDL} is installed.
%
Of course if your favorite graphical tool supports
the NETCDF standard, you might use it to check the
domain definition in \ttt{geo\_em.d01.nc}.

\mk
\marge If you are unhappy with the results or
you want to change 
the location of the mesoscale domain on the planet, 
the horizontal resolution,
the number of grid points \ldots,
please modify the parameter
file \ttt{namelist.wps} and execute again \ttt{geogrid.exe}.
%
Here are the contents of \ttt{namelist.wps}:
%
\codesource{namelist.wps_TEST} 

\begin{finger}
%
\item No input meteorological data 
are actually needed to execute \ttt{geogrid.exe}.
%
\item More details about the database and
more options of interpolation could be
found in the file \ttt{geogrid/GEOGRID.TBL}.
%
\item Defining several domains yields
distinct files 
\ttt{geo\_em.d01.nc},
\ttt{geo\_em.d02.nc},
\ttt{geo\_em.d03.nc}\ldots
\end{finger}

\mk
\marge Once the \ttt{geo\_em} file(s) are generated,
the \ttt{metgrid.exe} program performs
a similar horizontal interpolation 
of the meteorological fields to the mesoscale 
domain as the one performed by \ttt{geogrid.exe} 
for the surface data.
%
Then the program writes the results in
\ttt{met\_em} files and also collects
the static fields and domain parameters
included in the \ttt{geo\_em} file(s)
%
Please type the following commands:
\begin{verbatim}
cd $LMDMOD/LMD_MM_MARS/your_install_dir/WPS
./metgrid.exe
\end{verbatim}
%
\marge If every went well,
the directory \ttt{\$LMDMOD/TMPDIR/WRFFEED}
should contain the \ttt{met\_em.*} files.

\mk
\subsubsection{Step 3: Vertical interpolation on mesoscale levels}

\mk
\marge The last step is to execute \ttt{real.exe}
to perform the interpolation from the vertical
levels of the GCM to the vertical levels 
defined in the mesoscale model.
%
This program also prepares the final initial
state for the simulation in files called
\ttt{wrfinput} and the boundary conditions
in files called \ttt{wrfbdy}.

\mk
\marge To successfully execute \ttt{real.exe}, 
you need the \ttt{met\_em.*} files
and the \ttt{namelist.input} file
to be in the same directory as \ttt{real.exe}.
%
Parameters in \ttt{namelist.input} 
controlling the behavior of the vertical interpolation 
are those labelled with \ttt{(p3)} in the detailed
list introduced in the previous chapter.

\mk
\marge Please type the following commands
to prepare files for the Arsia Mons test case
(or your personal test case if you changed
the parameters in \ttt{namelist.wps}):
\begin{verbatim}
cd $LMDMOD/TESTCASE
ln -sf $LMDMOD/WRFFEED/met_em* .
./real.exe
\end{verbatim}

\mk
\marge The final message of the \ttt{real.exe}
should claim the success of the processes and you
are now ready to launch the integrations
of the LMD Martian Mesoscale Model again
with the \ttt{wrf.exe} command as in section
\ref{sc:arsia}.

\begin{finger}
\item When you modify either 
\ttt{namelist.wps} or \ttt{namelist.input},
make sure that the common parameters
are exactly similar in both files
(especially when running nested simulations)
otherwise either \ttt{real.exe} or \ttt{wrf.exe}
command will exit with an error message.
\end{finger}
%\pagebreak


\chapter{Starting simulations from scratch: a summary}

\mk
\section{Complete simulations with \ttt{runmeso}}

you'll notice you need to change namelist according to model compilation
in order to minimize errors and help the user.

\begin{remarque}
To be completed
\end{remarque}


\chapter{Advanced use}

\section{Grid nesting}\label{nests}

\section{Tracers}

\section{New physics}




\chapter{Outputs}

\mk
\section{Postprocessing utilities and graphics}\label{postproc}

\begin{remarque}
To be completed. Do-it-all \ttt{idl} scripts
would be described here !
\end{remarque}

\mk
\section{Modify the outputs}

\begin{remarque}
To be completed. 
Though the method is different,
we kept all the convenient aspects of \ttt{writediagfi}
\end{remarque}

\chapter{Frequently Asked Questions}


\begin{finger}
\item Which timestep should I choose to avoid crashes of the model ?
\item In the Martian simulations, why can't I define boundaries each 6 hours as on Earth ?
\item Help ! I get strange assembler errors or ILM errors while compiling !
\item Is it possible to run the model on a specific configuration that is not supported ?
\item Why do I have to define four less rows in the parent domain
when performing nested runs ?
\item I am kind of nostalgic of early/middle Mars. How could I run
mesoscale simulations at low/high obliquity ?
\item Why \ttt{real.exe} is crashing when the model top pressure is
lower than $2$~Pa ?
\item Can I use the two-way nesting ?
\end{finger}

\begin{remarque}
To be completed. 
\end{remarque}