Index: NEMO/trunk/doc/latex/NEMO/subfiles/chap_STO.tex
===================================================================
--- NEMO/trunk/doc/latex/NEMO/subfiles/chap_STO.tex	(revision 11339)
+++ NEMO/trunk/doc/latex/NEMO/subfiles/chap_STO.tex	(revision 11340)
@@ -8,18 +8,25 @@
 \label{chap:STO}
 
-Authors: P.-A. Bouttier
+\minitoc
 
-\minitoc
+% \vfill
+% \begin{figure}[b]
+% \subsubsection*{Changes record}
+% \begin{tabular}{l||l|m{0.65\linewidth}}
+%    Release   & Author        & Modifications \\
+%    {\em 4.0.1} & {\em C. Levy} & {\em 4.0.1 update}  \\
+%    {\em 3.6} & {\em P.-A. Bouttier} & {\em initial version}  \\
+% \end{tabular}
+% \end{figure}
+
+Authors: \\
+C. Levy release 4.0.1 update \\
+P.-A. Bouttier release 3.6 inital version
 
 \newpage
 
-The stochastic parametrization module aims to explicitly simulate uncertainties in the model.
-More particularly, \cite{brankart_OM13} has shown that,
-because of the nonlinearity of the seawater equation of state, unresolved scales represent a major source of
-uncertainties in the computation of the large scale horizontal density gradient (from T/S large scale fields),
-and that the impact of these uncertainties can be simulated by
-random processes representing unresolved T/S fluctuations.
+As a result of the nonlinearity of the seawater equation of state, unresolved scales represent a major source of uncertainties in the computation of the large-scale horizontal density gradient from the large-scale temperature and salinity fields. Following  \cite{brankart_OM13}, the impact of these uncertainties can be simulated by random processes representing unresolved T/S fluctuations. The Stochastic Parametrization of EOS (STO) module implements this parametrization.
 
-The stochastic formulation of the equation of state can be written as:
+As detailed in \cite{brankart_OM13}, the stochastic formulation of the equation of state can be written as:
 \begin{equation}
   \label{eq:eos_sto}
@@ -27,5 +34,5 @@
 \end{equation}
 where $p_o(z)$ is the reference pressure depending on the depth and,
-$\Delta T_i$ and $\Delta S_i$ are a set of T/S perturbations defined as
+$\Delta T_i$ and $\Delta S_i$ (i=1,m) is a set of T/S perturbations defined as
 the scalar product of the respective local T/S gradients with random walks $\mathbf{\xi}$:
 \begin{equation}
@@ -33,5 +40,5 @@
   \Delta T_i = \mathbf{\xi}_i \cdot \nabla T \qquad \hbox{and} \qquad \Delta S_i = \mathbf{\xi}_i \cdot \nabla S
 \end{equation}
-$\mathbf{\xi}_i$ are produced by a first-order autoregressive processes (AR-1) with
+$\mathbf{\xi}_i$ are produced by a first-order autoregressive process (AR-1) with
 a parametrized decorrelation time scale, and horizontal and vertical standard deviations $\sigma_s$.
 $\mathbf{\xi}$ are uncorrelated over the horizontal and fully correlated along the vertical.
@@ -41,12 +48,11 @@
 \label{sec:STO_the_details}
 
-The starting point of our implementation of stochastic parameterizations in NEMO is to observe that
-many existing parameterizations are based on autoregressive processes,
+There are many existing parameterizations based on autoregressive processes,
 which are used as a basic source of randomness to transform a deterministic model into a probabilistic model.
-A generic approach is thus to add one single new module in NEMO,
-generating processes with appropriate statistics to simulate each kind of uncertainty in the model
+The generic approach here is to a new STO module,
+generating processes features with appropriate statistics to simulate these uncertainties in the model
 (see \cite{brankart.candille.ea_GMD15} for more details).
 
-In practice, at every model grid point,
+In practice, at each model grid point,
 independent Gaussian autoregressive processes~$\xi^{(i)},\,i=1,\ldots,m$ are first generated using
 the same basic equation:
@@ -101,41 +107,39 @@
 \noindent
 In this way, higher order processes can be easily generated recursively using the same piece of code implementing
-(\autoref{eq:autoreg}), and using succesively processes from order $0$ to~$n-1$ as~$w^{(i)}$.
-The parameters in (\autoref{eq:ord2}) are computed so that this recursive application of
-(\autoref{eq:autoreg}) leads to processes with the required standard deviation and correlation timescale,
+\autoref{eq:autoreg}, and using successive processes from order $0$ to~$n-1$ as~$w^{(i)}$.
+The parameters in \autoref{eq:ord2} are computed so that this recursive application of
+\autoref{eq:autoreg} leads to processes with the required standard deviation and correlation timescale,
 with the additional condition that the $n-1$ first derivatives of the autocorrelation function are equal to
-zero at~$t=0$, so that the resulting processes become smoother and smoother as $n$ is increased.
+zero at~$t=0$, so that the resulting processes become smoother and smoother as $n$ increases.
 
 Overall, this method provides quite a simple and generic way of generating a wide class of stochastic processes.
 However, this also means that new model parameters are needed to specify each of these stochastic processes.
-As in any parameterization of lacking physics, a very important issues then to tune these new parameters using
+As in any parameterization, the main issue is to tune the parameters using
 either first principles, model simulations, or real-world observations.
+The parameters are set by default as described in \cite{brankart_OM13}, which has been shown in the paper
+to give good results for a global low resolution (2°) NEMO configuration. where this parametrization produces a major effect on the average large-scale circulation, especilally in regions of intense mesoscale activity.
+The set of parameters will need further investigation to find appropriate values
+for any other configuration or resolution of the model.
 
 \section{Implementation details}
 \label{sec:STO_thech_details}
 
-%---------------------------------------namsbc--------------------------------------------------
 
-\nlst{namsto}
-%--------------------------------------------------------------------------------------------------------------
+The code implementing stochastic parametrisation is located in the src/OCE/STO directory.
+It contains three modules : 
+% \begin{description}
 
-The computer code implementing stochastic parametrisations can be found in the STO directory.
-It involves three modules : 
-\begin{description}
-\item[\mdl{stopar}:]
-  define the Stochastic parameters and their time evolution.
-\item[\mdl{storng}:]
-  a random number generator based on (and includes) the 64-bit KISS (Keep It Simple Stupid) random number generator
-  distributed by George Marsaglia
-  (see \href{https://groups.google.com/forum/#!searchin/comp.lang.fortran/64-bit$20KISS$20RNGs}{here})
-\item[\mdl{stopts}:]
-  stochastic parametrisation associated with the non-linearity of the equation of seawater,
-  implementing \autoref{eq:sto_pert} and specific piece of code in
-  the equation of state implementing \autoref{eq:eos_sto}.
-\end{description}
+\mdl{stopar} : define the Stochastic parameters and their time evolution
 
-The \mdl{stopar} module has 3 public routines to be called by the model (in our case, NEMO):
+\mdl{storng} : random number generator based on and including the 64-bit KISS (Keep It Simple Stupid) random number generator distributed by George Marsaglia
 
-The first routine (\rou{sto\_par}) is a direct implementation of (\autoref{eq:autoreg}),
+\mdl{stopts} : stochastic parametrisation associated with the non-linearity of the equation of
+ seawater, implementing \autoref{eq:sto_pert} so as specifics in the equation of state
+ implementing \autoref{eq:eos_sto}.
+% \end{description}
+
+The \mdl{stopar} module includes three public routines called in the model:
+
+(\rou{sto\_par}) is a direct implementation of \autoref{eq:autoreg},
 applied at each model grid point (in 2D or 3D), and called at each model time step ($k$) to
 update every autoregressive process ($i=1,\ldots,m$).
@@ -143,14 +147,36 @@
 to introduce a spatial correlation between the stochastic processes.
 
-The second routine (\rou{sto\_par\_init}) is an initialization routine mainly dedicated to
-the computation of parameters $a^{(i)}, b^{(i)}, c^{(i)}$ for each autoregressive process,
+(\rou{sto\_par\_init}) is the initialization routine computing
+the values $a^{(i)}, b^{(i)}, c^{(i)}$ for each autoregressive process,
 as a function of the statistical properties required by the model user
 (mean, standard deviation, time correlation, order of the process,\ldots). 
+This routine also includes the initialization (seeding) of the random number generator.
 
-Parameters for the processes can be specified through the following \ngn{namsto} namelist parameters:
+(\rou{sto\_rst\_write}) writes a restart file
+(which suffix name is given by \np{cn\_storst\_out} namelist parameter) containing the current value of
+all autoregressive processes to allow creating the file needed for a restart.
+This restart file also contains the current state of the random number generator.
+When \np{ln\_rststo} is set to \forcode{.true.}),
+the restart file (which suffix name is given by \np{cn\_storst\_in} namelist parameter) is read by
+the initialization routine (\rou{sto\_par\_init}).
+The simulation will continue exactly as if it was not interrupted only
+when \np{ln\_rstseed} is set to \forcode{.true.},
+\ie when the state of the random number generator is read in the restart file.\\
+
+
+Options and parameters \\
+
+The \np{ln\_sto\_eos} namelist variable activates stochastic parametrisation. By default it set to \forcode{.false.}) and not active.
+The set of parameters is available in \ngn{namsto} namelist:
+%---------------------------------------namsto--------------------------------------------------
+
+\nlst{namsto}
+%--------------------------------------------------------------------------------------------------------------
+
+The variables of stochastic paramtetrisation itself (based on the global 2° experiments as in \cite{brankart_OM13} are:
 \begin{description}
 \item[\np{nn\_sto\_eos}:]   number of independent random walks
-\item[\np{rn\_eos\_stdxy}:] random walk horz. standard deviation (in grid points)
-\item[\np{rn\_eos\_stdz}:]  random walk vert. standard deviation (in grid points)
+\item[\np{rn\_eos\_stdxy}:] random walk horizontal standard deviation (in grid points)
+\item[\np{rn\_eos\_stdz}:]  random walk vertical standard deviation (in grid points)
 \item[\np{rn\_eos\_tcor}:]  random walk time correlation (in timesteps)
 \item[\np{nn\_eos\_ord}:]   order of autoregressive processes
@@ -158,17 +184,6 @@
 \item[\np{rn\_eos\_lim}:]   limitation factor (default = 3.0)
 \end{description}
-This routine also includes the initialization (seeding) of the random number generator.
 
-The third routine (\rou{sto\_rst\_write}) writes a restart file
-(which suffix name is given by \np{cn\_storst\_out} namelist parameter) containing the current value of
-all autoregressive processes to allow restarting a simulation from where it has been interrupted.
-This file also contains the current state of the random number generator.
-When \np{ln\_rststo} is set to \forcode{.true.}),
-the restart file (which suffix name is given by \np{cn\_storst\_in} namelist parameter) is read by
-the initialization routine (\rou{sto\_par\_init}).
-The simulation will continue exactly as if it was not interrupted only
-when \np{ln\_rstseed} is set to \forcode{.true.},
-\ie when the state of the random number generator is read in the restart file.
-
+The first four parameters define the stochastic part of equation of state.
 \biblio
 
