source: trunk/MESOSCALE/DOC/SRC/user_manual_txt.tex @ 168

\chapter{What is the LMD Martian Mesoscale Model?}

\mk
\paragraph{Welcome !} The purpose of this introduction is to describe the Martian mesoscale model developed at the Laboratoire de M\'et\'eorologie Dynamique (LMD). This chapter comprises the excerpts from \textit{Spiga and Forget} [2009]\nocite{Spig:09} dedicated to the technical description of the LMD Martian Mesoscale Model. This serves as an introduction to the model, its design and capabilities. Further details can be found in the reference paper \textit{Spiga and Forget} [2009]\nocite{Spig:09} and subsequent papers about mesoscale applications: e.g., \textit{Spiga and Lewis} [2010]\nocite{Spig:10dust} and \textit{Spiga et al.} [2011]\nocite{Spig:11ti}. An introduction to Large-Eddy Simulations can be found in \textit{Spiga et al.} [2010]\nocite{Spig:10bl}. 

\paragraph{Important} Please cite the reference paper \textit{Spiga and Forget} [2009]\nocite{Spig:09} if you'd like to refer to the LMD Martian Mesoscale Model in one of your publication. If your paper makes use of simulations carried out with the LMD Martian Mesoscale Model, please consider including A. Spiga as a co-author of your work (and asking for help with writing the part related to mesoscale modeling). If you have any idea of specific simulations and wonder if it is ever possible to perform those with the LMD Martian Mesoscale Model, please do not hesitate to ask.

\mk
\section{Dynamical core}

\sk
The numerical integration of the atmospheric fluid dynamic equations is performed in meteorological models by the dynamical core. The LMD Martian Mesoscale Model dynamical core is based on the stable and carefully tested, fully parallellized, Advanced Research Weather Research and Forecasting model (hereinafter referred as ARW-WRF) [\textit{Skamarock et al.}, 2005, 2008\nocite{Skam:08}\nocite{Skam:05}], developed for terrestrial applications at NCEP/NCAR (version 2.2.1 - November 2007).

\sk
The ARW-WRF mesoscale model integrates the fully compressible non-hydrostatic Navier-Stokes equations in a specific area of interest on the planet. Since the mesoscale models can be employed to resolve meteorological motions less than few kilometers, a scale at which the vertical wind acceleration might become comparable to the acceleration of gravity, hydrostatic balance cannot be assumed, as is usually done in GCMs.

\sk
Mass, momentum, entropy, and tracer conservation are ensured by an explicitly conservative flux-form formulation of the fundamental equations, based on mass-coupled meteorological variables (winds, potential temperature, tracers). Alternatively, these variables are recast into a reference profile plus a perturbation to reduce truncation errors [\textit{Skamarock et al.}, 2008]\nocite{Skam:08}. Tracer transport can be computed by an additional forward-in-time scheme based on the Piecewise Parabolic Method [\textit{Carpenter et al.}, 1990]\nocite{Carp:90}, with positive definite and monotonic properties
[\textit{Skamarock et al.}, 2006]\nocite{Skam:06}.

\sk
In the vertical dimension, the equations are projected, as suggested by \textit{Laprise} [1992]\nocite{Lapr:92}, on terrain-following mass-based coordinates (``eta levels"): $\eta = (\pi-\pi_t) / (\pi_s-\pi_t)$ where $\pi$ is the hydrostatic component of the pressure, $\pi_s$ the value at the surface and $\pi_t$ the (constant) upper boundary value. As shown in \textit{Laprise} [1992]\nocite{Lapr:92} and \textit{Janjic et al.} [2001]\nocite{Janj:01}, the choice of such vertical coordinates enables the integration of the ARW-WRF equations either in full non-hydrostatic mode or under the hydrostatic assumption. At the top of the domain, a free relaxation condition to zero vertical velocity is imposed (gravity wave absorbing layers can be defined as well).

\sk
In the horizontal dimension, the dynamical solver is available with three possible projections on the planetary sphere: Mercator (suitable for equatorial regions),  Lambert Conformal (for mid-latitudes),  and Polar Stereographic (for high-latitudes). Projections are defined by map scale factors, ensuring a regular computational grid whatever the map projection should be. Polar simulations are therefore devoid of any pole singularity, an usual drawback of the GCMs that requires the use of additional filtering. The spatial discretization is an Arakawa C-grid, where normal velocities are staggered one-half grid length from the thermodynamic variables [\textit{Arakawa}, 1966]\nocite{Arak:66}.

\sk
In the temporal dimension, a third-order Runge-Kutta integration scheme is employed for improved numerical accuracy and stability: the maximum stable Courant Friedrichs Lewy (CFL) numbers for advection are increased by a factor of two compared to the regular leapfrog integration scheme [\textit{Skamarock et al.}, 2008]. A time-splitting integration technique is implemented to prevent the meteorologically insignificant acoustic motions from triggering numerical instabilities [\textit{Klemp et al.}, 2007]\nocite{Klem:07}. Additional filters for acoustic external and internal modes damp residual instabilities possibly arising in the acoustic step integration.

\sk
In the ARW-WRF Runge-Kutta time-integration scheme, while pressure gradient and divergence terms are simply second order and centered, spatial discretizations of the advection terms for momentum, scalars and geopotential are 2nd through 6th order accurate [\textit{Wicker and Skamarock}, 2002]\nocite{Wick:02}. Martian simulations are performed with a 5th order discretized advection. One peculiarity of the odd-order advection discretization is the inherent inclusion of a dissipation term [\textit{Hundsdorfer et al.}, 1995]\nocite{Hund:95} with a coefficient proportional to the Courant number.

\sk
However, as was pointed out by \textit{Knievel et al.} [2007]\nocite{Knie:07}, this odd-ordered implicit scheme is not diffusive enough in low-wind or neutral/unstable stratification, and numerical noise in the wind fields might reach amplitudes comparable to the simulated winds. Such noise was found to be significant in the Martian case under near-surface afternoon superadiabatic conditions. The standard Martian simulations thus include the additional 6th order diffusion scheme developed by \textit{Knievel et al.}, with a removal parameter set for Martian applications to $20\%$ of the $2\,\Delta x$ noise in one timestep. While reducing the numerical noise near the surface to almost undiscernable amplitudes, the additional Knievel diffusion has little effect on the simulated meteorological fields.

\sk
Particular adaptations were required to use the ARW-WRF dynamical solver in the Martian environment. Physical constants, such as the acceleration of gravity and the planetary rotation rate, were converted to the Martian values. Vegetation and ocean-related variables were not used, and replaced with variables more suitable for the Martian applications (e.g., thermal inertia). Martian dates are given by the aerocentric solar longitude $L_s$, which indicates the position of Mars with respect to the Sun (0, 90, 180, 270 degrees are, respectively, the beginning of the northern hemisphere spring, summer, fall and winter). The terrestrial calendar was thus replaced with the LMD-GCM Martian calendar built on 669 Martian sols split in 12 ``aerocentric longitude"-based months (each of them is $L_s=30^{\circ}$ long, and thus encloses an irregular number of Martian sols due to the high eccentricity of the orbit), and one hour was defined as $1/24$ sol.

\mk
\section{Martian physics}

\sk
In any meteorological model, the 3D dynamical core is coupled with parameterization schemes (most often 1D) to compute at each grid point of the simulation domain the particular physics of the considered planetary environment: diabatic forcing of the atmospheric circulation (radiative transfer, soil thermal diffusion); sub-grid scale dynamical parameterizations (Planetary Boundary Layer [PBL] diffusion and mixing, convective adjustment); tracer sources and sinks (microphysical processes, chemistry, dust sedimentation and lifting). The LMD-MGCM complete physical parameterizations are interfaced with the adapted ARW-WRF dynamical core, described in the previous section, by a new ``driver" that is built on the same principles as the ARW-WRF terrestrial parameterization schemes, which are all switched off for the Martian applications. Thus, the LMD Martian Mesoscale Model shares the same comprehensive physical parameterizations as the LMD-MGCM, in order to simulate the Martian dust, CO$_2$, H$_2$O and photochemistry cycles [\textit{Forget et al.}, 1999; \textit{Montmessin et al.}, 2004; \textit{Lefevre et al.}, 2004].

\sk
\subsection{Physical parameterizations}

\sk
The radiative transfer in the model accounts for CO$_2$ gas infrared absorption/emission [\textit{Hourdin et al.}, 1992]\nocite{Hour:92} and visible and infrared dust absorption, emission and diffusion [\textit{Forget et al.}, 1998, 1999]\nocite{Forg:98grl}. Description of the CO$_2$ condensation processes in the model can be found in \textit{Forget et al.} [1998b]\nocite{Forg:98}. Thermal conduction in the soil is simulated by the 11-layer soil model developed by \textit{Hourdin et al.} [1993]\nocite{Hour:93} for Mars (soil density and soil specific heat capacity are set as constants). Turbulent closure is based on turbulent viscosity with coefficients calculated from the ``$2.5$-order" scheme by \textit{Mellor and Yamada} [1982]\nocite{Mell:82}, improved by \textit{Galperin et al.} [1988]\nocite{Galp:88}. In the case where vertical mixing is handled in the independent 1D physical packages, the native vertical mixing schemes in the ARW-WRF dynamical core are switched off, and the most appropriate choice for explicit horizontal diffusion is the built-in ARW-WRF scheme based on horizontal deformation [\textit{Smagorinsky}, 1963]\nocite{Smag:63}.

\sk
Recent improvements on the radiative transfer computations [\textit{Dufresne et al.}, 2005]\nocite{Dufr:05}, on the slope irradiance estimations [\textit{Spiga and Forget}, 2008]\nocite{Spig:08grl}, on the dust lifting and sedimentation [\textit{Forget et al.}, 1999b\nocite{Forg:99icm5}; \textit{Newmann et al.}, 2002]\nocite{Newm:02a}, on the water cycle and water ice clouds [\textit{Montmessin et al.}, 2004]\nocite{Mont:04}, and on the photochemical species [\textit{Lefevre et al.}, 2004]\nocite{Lefe:04}, particularly ozone [\textit{Lefevre et al.}, 2008]\nocite{Lefe:08}, are also natively included in the LMD Martian Mesoscale Model. The non-local thermodynamic equilibrium (NLTE) parameterizations for thermosphere applications [\textit{Gonz\'alez-Galindo et al.}, 2005\nocite{Gonz:05}] as well as estimations of the atmospheric exchanges with the Martian regolith [\textit{B\"ottger et al.}, 2005]\nocite{Bott:05}, are also available in the model.

%\sk
%Upcoming improvements of the LMD-MGCM physics [\textit{Forget et al.}, 2007]\nocite{Forg:07emsec}, following the recent measurements by instruments onboard Mars Express (MEx) and MRO, will be included in the LMD Martian Mesoscale Model too. Examples of future parameterizations that will be added in both models are the radiative effects of water ice clouds, which could significantly modify the atmospheric temperatures [\textit{Wilson et al.}, 2007]\nocite{Wils:07}, and the new dust radiative properties derived from recent measurements by the OMEGA instrument onboard MEx [\textit{M\"a\"att\"anen et al.}, 2008]\nocite{Maat:08} and the CRISM instrument onboard MRO [\textit{M.~J. Wolff and M. Vincendon}, personal communication, 2008].

\sk
Two physical parameterizations of the LMD-MGCM, specifically designed for synoptic-scale meteorological applications, are not used in the mesoscale applications.

\sk
Firstly, in the mesoscale domain, the topographical field is described with horizontal resolutions from tens of kilometers to hundreds of meters. The \textit{Lott and Miller} [1997]\nocite{Lott:97} subgrid-scale topographical drag parameterization and the \textit{Miller et al.} [1989]\nocite{Mill:89} gravity-wave drag scheme can thus be switched off, as the topographical influence on the atmospheric flow is computed by the dynamical core at the chosen mesoscale resolutions.

\sk
Secondly, in order to ensure numerical stability, and to account for subgrid-scale mixing processes insufficiently handled in the PBL scheme, it is usually necessary to modify any unstable layer with negative potential temperature gradients (an usual near-surface situation during Martian afternoons) into a neutral equivalent [\textit{Hourdin et al.}, 1993]. As pointed out by \textit{Rafkin} [2003b]\nocite{Rafk:03adj}, the use of such an artificial convective adjustment scheme might be questionable in Martian atmospheric models, should they be GCMs or mesoscale models. Since numerical stability is ensured in the LMD Martian Mesoscale Model by choosing the appropriate dynamical timestep with respect to the CFL condition, and using the aforementioned ARW-WRF nominal filters and diffusion schemes, the convective adjustment scheme used in the LMD-MGCM can thus be switched off in the LMD Martian Mesoscale Model. 

\mk
\subsection{Physical timestep}

\sk
Invoking physical packages often with respect to the dynamical computations was found to be necessary to accurately account for near-surface friction effects where the wind acceleration is particularly high, typically in regions of strong Martian topographically-driven circulation. In such areas, if the ratio between the physical timestep and the dynamical timestep is above $\sim 5$, the model predicts winds spuriously increasing with the chosen ratio and varying with the horizontal resolution. On the contrary, if this ratio is less than $\sim 5$, the simulated winds neither vary significantly with the chosen ratio nor with the horizontal resolution.

\sk
A ratio equal to 1 is chosen in the standard LMD Martian Mesoscale Model simulations. This choice is in conformity with the strategy adopted in the terrestrial ARW-WRF model. Besides, computing the physical parameterizations at the same frequency as the dynamical integration is profitable to some physical parameterizations, such as the formation of clouds (which is sensitive to rapid temperature change). Note that radiative transfer computations are usually carried out less often to save computational time.

\sk
When the ratio between the physical timestep and the dynamical timestep is superior to 1, two distinct strategies could be adopted. Interestingly, we found that splitting the physical tendency in equal parts and blending it with the dynamical tendency at each dynamical timestep computation is slightly more stable (understand: allows for higher dynamical timesteps) than applying the whole physical tendency when the physical parameterizations are computed, and letting the dynamical core naturally evolve until the next physics call. However, an analysis of the simulated meteorological fields in both cases does not reveal significant differences.

\mk
\section{Initial and boundary conditions}
\label{ssc:inibdy}

\mk
\subsection{Starting state and horizontal boundaries}

\sk
Mesoscale simulations can be performed in a limited domain anywhere on the planet. Thus, boundary conditions for the main meteorological fields (horizontal winds, temperature, tracers) have to be provided during the simulations, in addition to an atmospheric starting state. Idealized simulations usually require the use of periodic, symmetric or open boundary conditions, whereas real-case simulations need specified climatologies at the boundaries.

\sk
The specified boundary conditions and the atmospheric starting state are derived from previously performed $64\times48\times25$ (i.e., horizontal resolution of $5.625^{\circ}$ in longitude and $3.75^{\circ}$ in latitude, model top $\sim$~80~km~altitude) LMD-MGCM simulations which have reached equilibrium, typically after $\sim 10$ simulated years. GCM results are often used every Martian hour to constrain the mesoscale model at the domain boundaries. Temporal interpolations to each mesoscale timestep and spatial interpolations on the mesoscale domain are performed from the LMD-MGCM inputs. A relaxation zone of a given width (user-defined, usually 5 grid points) is implemented at the boundaries of the ARW-WRF domain to enable both the influence of the large-scale fields on the limited area, and the development of the specific mesoscale circulation inside the domain. The interpolations and the use of a relaxation zone prevent the prescribed meteorological fields at the lateral boundaries from having sharp gradients and from triggering spurious waves or numerical instabilities (the situation where the relaxation zone crosses steep topographical gradients should however be avoided).

\mk
\subsection{Nesting or single-domain strategy ?}
\label{ssc:nestingvalid}

\sk
The model includes one-way and two-way (or ``feedback") nesting capabilities. The nested simulations feature two kinds of domains where the meteorological fields are computed: the "parent" domain, with a large geographical extent, a coarse grid resolution, and specified boundary conditions, and the "nested" domains, centered in a particular zone of interest, with a finer grid resolution, and boundary conditions provided by its parent domain.

\sk
The nesting capabilities can be used only if deemed necessary, and single-domain simulations may be the primary type of run performed.

\sk
Firstly, employing the same physical parameterizations in the mesoscale model computations and in the GCM simulations defining the boundary and initial conditions, ensures a very consistent meteorological forcing at the boundaries of the mesoscale domain. This assumption was not denied by further examination of the performed simulations: mesoscale predictions are not unrealistically departing from the LMD-MGCM prescribed fields at the boundaries, and the mesoscale influence naturally adds to the synoptic (large-scale) tendency communicated at the boundaries. 

\sk
Secondly, the single-domain approach is appropriate as long as the variations of near-surface winds, pressure and temperature induced by ``passing" thermal tides through the east-west boundaries are not unrealistic. This criterion is specific to Martian mesoscale modeling and was described by \textit{Tyler et al.} [2002]. In the various simulations performed with the LMD Martian Mesoscale Model, a likely spurious influence of the passing thermal tides was only detected in the near-surface meteorological fields calculated at the $\sim 5$ near-boundaries grid points. The amplitudes of the departures were negligible ($\delta T \apprle 3$~K; $\delta u, \delta v \apprle 5\%$) and did not require the use of domains nested inside one semi-hemispheric parent domain [\textit{Tyler et al.}, 2002]. However, the analysis of the simulated fields at the near-boundaries grid points should be carried out with caution when choosing the single-domain approach. A practical solution to this drawback is to define a large domain, centered on the chosen area of interest, with a sufficient number of grid points ($75 \times 75$ being a minimal requirement).

\sk
Thirdly, \textit{Dimitrijevic and Laprise} [2005]\nocite{Dimi:05} showed, by the so-called ``Big Brother" approach, that the single-domain approach yields unbiased results when the boundary forcing involves a minimum of $\sim 8-10$ GCM grid points. Thus, given the resolution of the GCM fields used to constrain the LMD Martian Mesoscale Model, single-domain simulations with, for instance, a horizontal resolution of $20$~km shall be performed on at least $133 \times 88$ grid points. \textit{Antic et al.} [2006]\nocite{Anti:06} found that the ``$8-10$ grid points" limit can be lowered in situations of complex topography, because the dynamical influence of these mesoscale features is responsible for the larger part of the mesoscale circulation in the domain. Such situations are rather common on Mars, and the aforementioned ``minimal" grid can be of slightly smaller horizontal extent in areas such as Olympus Mons or Valles Marineris.

\sk
Thus the sizes of the simulation grids have to be chosen in order to ensure the applicability of the single-domain approach. The nesting technique is used only when defining a single domain with sufficient geographical extent would have required too many grid points to handle the computations within reasonable CPU time. For instance, with ``$64 \times 48$" GCM simulations as boundary conditions, the use of the single-domain strategy to model the Arsia Mons circulation at $5$ km resolution imposes a simulation grid of at least $531 \times 354$ points. The nesting technique is more suitable for this kind of simulation.

\mk
\subsection{Surface fields}

\sk
Surface static data intended for the mesoscale domain are extracted from maps derived from recent spacecraft measurements: 64 pixel-per-degree (ppd) MOLA topography [\textit{Smith et al.}, 2001]\nocite{Smit:01mola}, 8 ppd MGS/Thermal Emission Spectrometer (TES) albedo [\textit{Christensen et al.}, 2001]\nocite{Chri:01}, 20 ppd TES thermal inertia [\textit{Putzig and Mellon}, 2007]\nocite{Putz:07}. A smoother composite thermal inertia map derived from \textit{Palluconi and Kieffer} [1981]\nocite{Pall:81}, \textit{Mellon et al.} [2000]\nocite{Mell:00} and \textit{Vasavada et al.} [2000]\nocite{Vasa:00} can be alternatively used for better continuity with LMD-MGCM simulations. Except for CO$_2$ ice covered areas, emissivity is set to $0.95$. The roughness length $z_0$ is set to the constant value of $1$~cm, but further versions of the model will use spatially-varying $z_0$ [\textit{H\'ebrard et al.}, 2007]\nocite{Hebr:07}. Initial values for time-varying surface data, such as CO$_2$ and H$_2$O ice on the surface and soil temperatures, are derived from the GCM simulations. The latter initialization reduces the spin-up time for surface temperature to roughly one simulated sol.

\sk
The LMD Martian Mesoscale Model has the complete ability to simulate the dust cycle (lifting, sedimentation, transport). However, the high sensivity of the results to the assumptions made on threshold wind stress and injection rate [\textit{Basu et al.}, 2004]\nocite{Basu:04} leads us to postpone these issues to future studies. Instead, similarly to the reference LMD-MGCM simulations, dust opacities are prescribed in the mesoscale model from 1999-2001 TES measurements, thought to be representative of Martian atmospheric conditions outside of planet-encircling dust storm events [\textit{Montabone et al.}, 2006]\nocite{Mont:06luca}. In the vertical dimension, as described in \textit{Forget et al.} [1999], and in accordance with the general consensus of well-mixed dust in equilibrium with sedimentation and mixing processes [\textit{Conrath}, 1975]\nocite{Conr:75}, dust mixing ratio is kept constant from the surface up to a given elevation $z_{\textrm{\tiny{max}}}$ above which it rapidly declines. Both in the nominal GCM and mesoscale simulations, $z_{\textrm{\tiny{max}}}$ as a function of areocentric longitude and latitude is calculated from the ``MGS scenario" [\textit{Forget et al.}, 2003]\nocite{Forg:03}.

\mk
\subsection{Vertical interpolation}

\sk
In the process of initialization and definition of boundary conditions, the vertical interpolation of GCM meteorological fields to the terrain-following mesoscale levels must be treated with caution. While deriving the near-surface meteorological fields from GCM inputs, one may address the problem of underlying topographical structures at fine mesoscale horizontal resolution, e.g., a deep crater that is not resolved in the coarse GCM case.

\sk
A crude extrapolation of the near-surface GCM fields to the mesoscale levels is usually acceptable for terrestrial applications. On Mars, owing to the low density and heat capacity of the Martian atmosphere, the surface temperature is to first order controlled by radiative equilibrium, and thus it is left relatively unaffected by variations of topography [e.g. \textit{Nayvelt et al.}, 1997]\nocite{Nayv:97}. A practical consequence, which renders an extrapolation strategy particularly wrong on Mars, is that the near-surface temperature and wind fields vary much more with the distance from the surface than with the absolute altitude above the areoid (or equivalently with the pressure level). Initial tests carried out with the extrapolation strategy showed that differences between temperatures at the boundaries and temperatures computed within the mesoscale domain close to these boundaries often reach $20-30$~K near the surface. An interpolation based only on terrain-following principles solves this problem near the surface but was found to lead to numerical instabilities at higher altitudes during the mesoscale integrations.

\sk
Therefore, input meteorological data need to be recast on intermediate pressure levels $P'$ with a low level smooth transition from terrain-following levels (for the near-surface environment) to constant pressure levels (for the free atmosphere at higher altitude). We thus have $P'(x,y)=\alpha + \beta \, P_s(x,y)$, $P_s$ being the surface pressure at the resolution of the GCM simulations. To ensure a realistic low-level transition, the technique described in \textit{Millour et al.} [2008]\nocite{Mill:08ddd}, based on high-resolution GCM results, is employed to calculate the $P'$ levels. The mesoscale surface pressure field $p_s$ is an input parameter of the method, since the near-surface adiabatic cooling over mountains and warming within craters are taken into account. Note that $p_s(x,y)$ is calculated from $P_s(x,y)$ on the basis of the high-resolution topography of the mesoscale domain $z(x,y)$ by $$p_s(x,y) = P_s(x,y) \, e^{ \frac{g \, [Z(x,y)-z(x,y)]}{R \, T(x,y)} }$$ \noindent where $Z(x,y)$ is the topography at the resolution of the GCM simulations, $R$ the gas law constant, $g$ the acceleration of gravity, and $T(x,y)$ the temperature predicted by the GCM $1$~km above the surface (see \textit{Spiga et al.} [2007]\nocite{Spig:07omeg}). Without reinterpolating the data, the intermediate pressure $P'$ levels are then simply converted into their mesoscale counterparts $p'$ by substituting $p_s$ for $P_s$ in the formula $P'(x,y)=\alpha + \beta \, P_s(x,y)$. Finally, the built-in ARW-WRF vertical interpolation onto the final mesoscale terrain-following levels can be performed, as the problem of extrapolation is solved by the use of the intermediate pressure levels $p'$.

\sk
The initial atmospheric state obtained through this ``hybrid" method ensures low-amplitude adjustments of the meteorological fields by the mesoscale model at the beginning of the performed simulations (i.e., in the first thousands of seconds). Furthermore, the continuity between the large-scale forcing and the mesoscale computations near the limits of the domain, as well as the numerical stability of the simulations, appear as significantly improved compared to methods either based on extrapolation (especially in areas of uneven terrains) or terrain-following interpolation.

%\pagebreak
\includepdf[pages=1,offset=25mm -20mm]{meso.pdf}
\clearemptydoublepage

\chapter{First steps toward running the model}

\mk
This chapter is meant for first time users of the LMD Martian Mesoscale Model.
%
We describe how to install the model on your system, compile the program and run a test case.
%
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}

\mk
\subsection{General requirements}

\mk
In order to install the LMD Martian Mesoscale Model, please ensure that:
\begin{citemize}
\item your computer is connected to the internet;
\item your OS is Linux\footnote{
%%%%%%%%%%%%%%
The model was also successfully compiled on MacOSX; 
``howto" information is available upon request.
%%%%%%%%%%%%%%
} with a decent set of basic commmands (\ttt{sed}, \ttt{awk}, \ldots);
\item your Fortran compiler is the PGI commercial compiler \ttt{pgf90} or the GNU 
free compiler\footnote{
%%%%%%%%%%%%%%
Sources and binaries available on \url{http://www.g95.org}
%%%%%%%%%%%%%%
} \ttt{g95};
\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 have been compiled \emph{on your system}.
\end{citemize} 
%
\begin{finger}
\item You might also find useful -- though not mandatory -- to install on your system:
\begin{citemize}
\item the \ttt{ncview} utility\footnote{
%%%%%%
\url{http://meteora.ucsd.edu/~pierce/ncview\_home\_page.html}
%%%%%%
}, which is a nice tool to visualize the contents of a NETCDF file;
\item the \ttt{IDL} demo version\footnote{
%%%%%%
\url{http://www.ittvis.com/ProductServices/IDL.aspx}
%%%%%%
}, which is used by the plot utilities provided with the model.
\end{citemize} 
\end{finger}

\mk
\marge Three environment variables associated with the \ttt{NETCDF} libraries must be defined: 
\begin{verbatim}
declare -x NETCDF=/disk/user/netcdf  
declare -x NCDFLIB=$NETCDF/lib       
declare -x NCDFINC=$NETCDF/inc       
\end{verbatim}

\begin{finger}
\item All command lines in the document are proposed in \ttt{bash}.
\end{finger}

%%[csh] setenv NETCDF /disk/user/netcdf
%%[csh] setenv NCDFLIB $NETCDF/lib
%%[csh] setenv NCDFINC $NETCDF/inc

\mk
\marge You also need the environment variable \ttt{\$LMDMOD} to point 
at the directory where you will install the model (e.g. \ttt{/disk/user/MODELS}):
\begin{verbatim}
declare -x LMDMOD=/disk/user/MODELS  
\end{verbatim}
%[csh] setenv LMDMOD /disk/user/MODELS
%
\begin{finger}
\item Please check that $\sim 200$~Mo free disk space is available in \ttt{/disk}.
\end{finger}

\mk
\subsection{Parallel computations}

\mk
\marge Parallel computations with the Message Passing Interface (MPI) standard are supported by 
the ARW-WRF mesoscale model.
%
If you want to use this capability in the LMD Martian Mesoscale Model,
you would have the installation of MPICH2 as a additional prerequisite.

\mk
\marge Please download the current stable version of the sources
(e.g. \ttt{mpich2-1.0.8.tar.gz}) 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}
%
\begin{finger}
\item Even if you add the \ttt{\$LMDMOD/MPI/mpich2-1.0.8/bin}
directory to your \ttt{\$PATH} variable, defining the environment 
variable \ttt{\$WHERE\_MPI} is still required
to ensure a successful compilation of the model.
\end{finger}

\mk
\subsection{Compiling the terrestrial WRF model}

\mk
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}.

\mk
\marge 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 the \ttt{\$LMDMOD} folder.

\mk
\marge Then please extract the model sources and configure the compilation process:
\begin{verbatim}
cd $LMDMOD
tar xzvf WRFV2.2.TAR.gz
cd WRFV2
./configure
\end{verbatim}

\mk
\marge 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).

\mk
\marge The next step is 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.
\end{finger}%\pagebreak

\mk
\marge If the compilation was successful
(the file \ttt{log\_error} should be empty
or only reporting few warnings), you should find
in the \ttt{main} folder two executables
\ttt{ideal.exe} and \ttt{run.exe}
that would allow you to run the test
simulation:
\begin{verbatim}
cd test/em_hill2d_x
./ideal.exe
./wrf.exe
\end{verbatim}
%
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} data file
you might like to browse with a \ttt{NETCDF}-compliant software
such as \ttt{ncview}.
%
\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{Compiling the Martian model}

\mk
\subsection{Extracting and preparing the sources}

\mk
To start the installation of the Martian mesoscale model,
download the archive \ttt{LMD\_MM\_MARS.tar.gz}
(click on \url{http://www.lmd.jussieu.fr/~aslmd/LMD_MM_MARS/LMD_MM_MARS.tar.gz}
or use the \ttt{wget} command).
%
Copy the sources in the \ttt{\$LMDMOD} directory and extract the files:
\begin{verbatim}
cp LMD_MM_MARS.tar.gz $LMDMOD
cd $LMDMOD
tar xzvf LMD_MM_MARS.tar.gz
\end{verbatim}

\mk
\marge Execute the \ttt{prepare} script 
that would do some necessary preparatory tasks for you:
deflate the various compressed archives contained into \ttt{LMD\_MM\_MARS},
download the ARW-WRF sources from the web,
apply a (quite significant) ``Martian patch" to these sources
and build the final structure of your \ttt{LMD\_MM\_MARS} directory:
\begin{verbatim}
cd $LMDMOD/LMD_MM_MARS
./prepare
\end{verbatim}

\mk
\marge Please check the contents of the \ttt{LMD\_MM\_MARS} directory:
\begin{citemize}
\item seven \ttt{bash} scripts: 
\ttt{build\_static}, 
\ttt{copy\_model},
\ttt{makemeso}, 
\ttt{prepare},
\ttt{prepare\_ini},\linebreak 
\ttt{prepare\_post},
\ttt{save\_all}; 
\item the sources directory \ttt{SRC};
\item the static data directory \ttt{WPS\_GEOG};
\item the simulation utilities directory \ttt{SIMU}.
\end{citemize}
%
\marge and check that the \ttt{LMD\_MM\_MARS/SRC} directory contains:
\begin{citemize}
\item the model main sources in \ttt{WRFV2},
\item the preprocessing sources in \ttt{WPS} and \ttt{PREP\_MARS},
\item the postprocessing sources in \ttt{ARWpost},
\item three \ttt{tar.gz} archives and two information text files. %\ttt{saved} and \ttt{datesave}.
\end{citemize}

\mk
\subsection{Main compilation step}
\label{sc:makemeso}

\mk
In order to compile the model, execute the \ttt{makemeso} compilation script 
in the \ttt{LMD\_MM\_MARS}\linebreak directory 
%
\begin{verbatim}
cd $LMDMOD/LMD_MM_MARS
./makemeso
\end{verbatim}
%
\marge and answer to the questions about
\begin{asparaenum}[1.]%[\itshape Q1\upshape)]
\item compiler choice (and number of processors if using MPI)
\item number of grid points in longitude [61]
\item number of grid points in latitude [61]
\item number of vertical levels [61] 
\item number of tracers [1]
\item number of domains [1]
\end{asparaenum}

%\mk
\begin{finger}
\item On the first time you compile the model, you will probably wonder what to reply
to questions $2$ to $6$ \ldots type the answers given in brackets to compile an executable suitable 
for the test case given below.
\item Suppose you compiled a version of the model for a given set of parameters $1$ to $6$
to run a specific compilation. 
If you would like to run another simulation 
with at least one of parameters $1$ to $6$ 
subject to change, the model needs to be recompiled\footnote{This
necessary recompilation each time the number of grid points,
tracers and domains is modified is imposed by the LMD physics code.
The WRF dynamical core alone is much more flexible.} with \ttt{makemeso}.
\item When you use parallel computations, please bear in mind that with
$2$ (resp. $4$, $6$, $8$, $16$) processors the whole domain would be separated 
into $2$ (resp. $2$, $3$, $4$, $4$) tiles over
the latitude direction and $1$ (resp. $2$, $2$, $2$, $4$) tile over the longitude direction.
Thus make sure that the number of grid points minus $1$ in each direction 
could be divided by the aforementioned number of tiles over the considered
direction.
\item If you use grid nesting, note that no more than $4$ processors can be used.
\end{finger}

\mk
\marge The \ttt{makemeso} is an automated script which performs
the following serie of tasks:
%It is useful to detail and comment the  performed by the \ttt{makemeso} script: 
\begin{citemize}
\item determine if the machine is 32 or 64 bits;
\item ask the user about the compilation settings;
\item create a corresponding directory \ttt{\$LMDMOD/LMD\_MM\_MARS/DIRCOMP}; 
\begin{finger}
\item For example, a \ttt{DIRCOMP} directory named \ttt{g95\_32\_single} 
is created if the user requested
a \ttt{g95} compilation of the code for single-domain simulations
on a 32bits machine.
\end{finger}
\item generate with \ttt{copy\_model} a directory \ttt{DIRCOMP/WRFV2} containing links to \ttt{SRC/WRFV2} sources;
\begin{finger}
\item This method ensures that any change to the model sources would
be propagated to all the different \ttt{DIRCOMP} installation folders. 
\end{finger}
\item execute the WRF \ttt{configure} script with the correct option;
\item tweak the resulting \ttt{configure.wrf} file to include a link towards the Martian physics;
\item calculate the total number of horizontal grid points handled by the LMD physics;
\item duplicate LMD physical sources if nesting is activated;
\begin{finger}
\item The model presently supports 3 nests, but more nests
can be included by adaptating the following files: 
\begin{verbatim}
$LMDMOD/LMD_MM_MARS/SRC/WRFV2/call_meso_inifis3.inc
$LMDMOD/LMD_MM_MARS/SRC/WRFV2/call_meso_physiq3.inc
$LMDMOD/LMD_MM_MARS/SRC/WRFV2/mars_lmd/libf/duplicate3
$LMDMOD/LMD_MM_MARS/SRC/WRFV2/mars_lmd/libf/generate3
$LMDMOD/LMD_MM_MARS/SRC/WRFV2/mars_lmd/makegcm*  ## search for 'nest'
\end{verbatim}%\pagebreak
\end{finger}
\item compile the LMD physical packages with the appropriate \ttt{makegcm} command
and collect the compiled objects in the library \ttt{liblmd.a};
\begin{finger}
\item During this step that could be a bit long,
especially if you defined more than one domain,
the \ttt{makemeso} script provides you with the full path towards 
the text file \ttt{log\_compile\_phys} in which you can check for
compilation progress and possible errors.
%
In the end of the process, you will find an 
error message associated to the generation of the
final executable.
%
Please do not pay attention to this, as the compilation of the LMD
sources is meant to generate a library of
compiled objects called \ttt{liblmd.a} instead of a program.
\end{finger}
\item compile the modified Martian ARW-WRF solver, including
the \ttt{liblmd.a} library; 
\begin{finger}
\item When it is the first time the model is compiled, this 
step could be quite long.
%
The \ttt{makemeso} script provides you with a \ttt{log\_compile}
text file where the progress of the compilation can be checked
and a \ttt{log\_error} text file listing errors and warnings
during compilation. 
%
A list of warnings related to \ttt{grib}
utilities (not used in the Martian model) 
may appear and have no impact on the
final executables.
\item The compilation with \ttt{g95} might be unsuccessful 
due to some problems with files related to terrestrial microphysics.
%
Please type the following commands:
\begin{verbatim}
cd $LMDMOD/LMD_MM_MARS/SRC
tar xzvf g95.tar.gz
cp -f g95/WRFV2_g95_fix/* WRFV2/phys/
cd $LMDMOD/LMD_MM_MARS
\end{verbatim}
\marge then recompile the model with the \ttt{makemeso} command.
\end{finger}
\item change the name of the executables in agreements with the
settings provided by the user.
\begin{finger}
\item If you choose to answer to the \ttt{makemeso} questions using the
aforementioned parameters in brackets, you should have in the
\ttt{DIRCOMP} directory two executables:
\begin{verbatim}
real_x61_y61_z61_d1_t1_p1.exe
wrf_x61_y61_z61_d1_t1_p1.exe
\end{verbatim}
%
The directory also contains a text file
in which the answers to the questions are stored, which
allows you to re-run the script without the
``questions to the user" step:
\begin{verbatim}
./makemeso < makemeso_x61_y61_z61_d1_t1_p1
\end{verbatim}
\end{finger}
\end{citemize}

\mk
\section{Running a simple test case}
\label{sc:arsia}

\mk
We suppose that you had successfully compiled
the model at the end of the previous section
and you had used the answers in brackets 
to the \ttt{makemeso} questions.

\mk
\marge In order to test the compiled executables,
a ready-to-use test case 
(with pre-generated initial and boundary
conditions) is proposed
in the \ttt{LMD\_MM\_MARS\_TESTCASE.tar.gz}
archive you can download at 
\url{http://www.lmd.jussieu.fr/~aslmd/LMD_MM_MARS/LMD_MM_MARS_TESTCASE.tar.gz}.
%
This test case simulates the hydrostatic
atmospheric flow around Arsia Mons during half a sol
with constant thermal inertia, albedo
and dust opacity.

\begin{finger}
\item Though the simulation reproduces some reasonable
features of the mesoscale circulation around Arsia
Mons (e.g. slope winds), it should not be used
for scientific purpose, for the number of grid points
is unsufficient for single-domain simulation
and the integration time is below the necessary spin-up time.
\end{finger}
%\pagebreak

\marge To launch the test simulation, please type
the following commands, replacing the
\ttt{g95\_32\_single} directory with its corresponding
value on your system:
%
\begin{verbatim}
cp LMD_MM_MARS_TESTCASE.tar.gz $LMDMOD/LMD_MM_MARS/
tar xzvf LMD_MM_MARS_TESTCASE.tar.gz
cd TESTCASE
ln -sf ../g95_32_single/real_x61_y61_z61_d1_t1_p1.exe wrf.exe  
nohup wrf.exe > log_wrf &
\end{verbatim}

%tar xzvf wrfinput.tar.gz

\begin{finger}
\item If you compiled the model using MPICH2,
the command to launch a simulation is slightly different:
%
\begin{verbatim}
[simulation on 2 processors on 1 machine]
mpd &      # first-time only (or after a reboot)
           # NB: may request the creation of a file .mpd.conf
mpirun -np 8 wrf.exe < /dev/null &      # NB: mpirun is only a link to mpiexec  
tail -20 rsl.out.000?     # to check the outputs
\end{verbatim}
\begin{verbatim}
[simulation on 16 processors in 4 connected machines]
echo barry.lmd.jussieu.fr > ~/mpd.hosts
echo white.lmd.jussieu.fr >> ~/mpd.hosts
echo loves.lmd.jussieu.fr >> ~/mpd.hosts
echo tapas.lmd.jussieu.fr >> ~/mpd.hosts
ssh barry.lmd.jussieu.fr   # make sure that ssh to other machines 
                           # is possible without authentification
mpdboot -f ~/mpd.hosts -n 4
mpdtrace
mpirun -l -np 16 wrf.exe < /dev/null &   # NB: mpirun is only a link to mpiexec
tail -20 rsl.out.00??     # to check the outputs
\end{verbatim}
\end{finger}


\mk
\chapter{Setting the simulation parameters}

\mk
In this chapter, we describe how to set the various parameters
defining a given simulation.
%
As could be inferred from the content of the \ttt{TESTCASE} directory, 
two parameter files are needed to run the model:
\begin{enumerate}
\item The parameters related to the dynamical part of the model can be set
in the file \ttt{namelist.input} according to the ARW-WRF namelist formatting.
\item The parameters related to the physical part of the model can be set
in the file \ttt{callphys.def} according to the LMD-MGCM formatting.
\end{enumerate}

\mk
\section{Dynamical settings}

\mk
\ttt{namelist.input} controls the behavior of the dynamical core 
in the LMD Martian Mesoscale Model.
%
Compared to the file the ARW-WRF users are familiar with\footnote{
%%%
A description of this file can be found in \ttt{SRC/WRFV2/run/README.namelist}.
%%%
}, the \ttt{namelist.input} in the LMD Martian Mesoscale Model 
is much shorter.
%
The only mandatory parameters in this file
are information on time control\footnote{
%%%
More information on the adopted Martian calendar:
\url{http://www-mars.lmd.jussieu.fr/mars/time/solar_longitude.html}
%%%
} and domain definition.

\mk
\marge The minimal version of the \ttt{namelist.input}
file corresponds to standard simulations with the model.
%
It is however possible to modify optional parameters 
if needed, as is the case in the \ttt{namelist.input} 
associated to the Arsia Mons test case 
(e.g. the parameter \ttt{non\_hydrostatic} is set to false
to assume hydrostatic equilibrium, whereas standard
simulations are non-hydrostatic).

\mk
\marge A detailed description of the \ttt{namelist.input} file is given below\footnote{
%%%
You may find the corresponding file in \ttt{SIMU/namelist.input\_full}.
%%%
}.
%
Comments on each of the parameters are provided, 
with the following labels:
\begin{citemize}
\item \ttt{(*)} denotes parameters not to be modified,
\item \ttt{(r)} indicates parameters which modification implies a new recompilation of the model,
\item \ttt{(n)} describes parameters involved when nested domains are defined,
\item \ttt{(p1)}, \ttt{(p2)}, \ttt{(p3)} mention parameters which modification implies a new processing 
of initial and boundary conditions (see next chapter),
\item \ttt{(*d)} denotes dynamical parameters which modification implies
non-standard simulations -- please read \ttt{SRC/WRFV2/run/README.namelist} 
and use with caution.
\end{citemize}
%
If omitted, the optional parameters would be set to their default 
values indicated below.\pagebreak

\centers{\ttt{-- file: namelist.input\_full --}}\codesource{namelist.input_full}\centers{\ttt{-- end file: namelist.input\_full --}}

\begin{finger}
\item Please pay attention to rigorous syntax while
editing your personal \ttt{namelist.input} file
to avoid reading error.
\item To modify the default values (or even add
personal parameters) in the \ttt{namelist.input} file, 
edit the \ttt{SRC/WRFV2/Registry/Registry.EM} file.
%
You will then have to recompile the model with \ttt{makemeso} ; 
answer \ttt{y} to the last question.
\end{finger}

\mk
\marge In case you run simulations with \ttt{max\_dom}
nested domains, you have to set \ttt{max\_dom} parameters
wherever there is a ``," in the above list.
%
Here is an example of the resulting syntax of the
\ttt{time\_control}, \ttt{domains} and \ttt{bdy\_control}
categories in \ttt{namelist.input}:
%
\codesource{OMG_namelist.input}

\section{Physical settings}

\mk
\ttt{callphys.def} controls the behavior of the physical parameterizations
in the LMD Martian\linebreak Mesoscale Model.
%
The organization of this file is exactly similar 
to the corresponding file in the LMD Martian GCM, which
user manual can be found at 
\url{http://web.lmd.jussieu.fr/~forget/datagcm/user_manual.pdf}.

\mk
\marge Please find in what follows the contents of \ttt{callphys.def}:
%
\centers{\ttt{-- file: callphys.def --}}\codesource{callphys.def}\centers{\ttt{-- end file: callphys.def --}}

\mk
\begin{finger}
\item Note that in the given example
the convective adjustment,
the gravity wave parameterization,
and the NLTE schemes are turned off, as is
usually the case in typical Martian tropospheric 
mesoscale simulations.
\item \ttt{iradia} sets the frequency 
(in dynamical timesteps) at which
the radiative computations are performed.
\item Modifying \ttt{callphys.def} only implies
to recompile the model if the number of tracers is different.
\item If you run a simulation with, say, $3$ domains,
please ensure that you defined three files
\ttt{callphys.def}, \ttt{callphys\_d2.def} and \ttt{callphys\_d3.def}.
\end{finger}

\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
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}

\mk
\section{Running your own GCM simulations}

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

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

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


\chapter{Outputs}

\mk
\section{Postprocessing utilities and graphics}

\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}