Changeset 11577 for NEMO/trunk/doc/latex/NEMO/subfiles/chap_ZDF.tex

Timestamp:

2019-09-19T19:01:38+02:00 (5 years ago)

Author:

nicolasmartin

Message:

New LaTeX commands \nam and \np to mention namelist content
(Partial commit to serve as a backup before other large edits)
In order to benefit of the syntax highlighting and to have a simpler syntax for
citing namelist block (\nam) and parameter (\np) with an optional variable assignment (\forcode{...}),
at this time the only viable solution I found is to require a double marker for
what it looks like the same item:

1. Marker with the real name: 'tra_adv' block or 'ln_flx' parameter
2. Marker with underscore character escaping: 'tra\_adv' block or 'ln\_flx' parameter

Despite many searches and attempts, I did not find a workaround to edit on-the-fly one or
the other marker.
In fact, the problem is on one side that the LaTeX index interprets '_' as a switch for lowering like
in math mode while on the other hand the backslash is considered for Pygments as a typo in Fortran
(red box).

For instance, \nam and \np have as of now the aforementioned 2 mandatory arguments in
the previous order (between braces) + an optional argument for \np when the parameter is defined
(between brackets at the first position):

• \nam: LaTeX code in the \nam{tra_adv}{tra\_adv} -> PDF ' in the &namtra_adv (namelist X.X) ' with syntax highlighting, the hyperlink and the index entry
• \np: LaTeX code \np[=.true.]{ln_flx}{ln\_flx} -> PDF ln_flux=.true. with syntax highlighting for the whole string and the entry in the 'parameters' index

File:

• NEMO/trunk/doc/latex/NEMO/subfiles/chap_ZDF.tex (modified) (50 diffs)

NEMO/trunk/doc/latex/NEMO/subfiles/chap_ZDF.tex

@@ -28 +28 @@
 At the surface they are prescribed from the surface forcing (see \autoref{chap:SBC}),
 while at the bottom they are set to zero for heat and salt,
-unless a geothermal flux forcing is prescribed as a bottom boundary condition (\ie\ \np{ln\_trabbc} defined,
+unless a geothermal flux forcing is prescribed as a bottom boundary condition (\ie\ \np{ln_trabbc}{ln\_trabbc} defined,
 see \autoref{subsec:TRA_bbc}), and specified through a bottom friction parameterisation for momentum
 (see \autoref{sec:ZDF_drg}).
@@ -42 +42 @@
 are computed and added to the general trend in the \mdl{dynzdf} and \mdl{trazdf} modules, respectively.
 %These trends can be computed using either a forward time stepping scheme
-%(namelist parameter \np{ln\_zdfexp}\forcode{=.true.}) or a backward time stepping scheme
-%(\np{ln\_zdfexp}\forcode{=.false.}) depending on the magnitude of the mixing coefficients,
+%(namelist parameter \np{ln_zdfexp}{ln\_zdfexp}\forcode{=.true.}) or a backward time stepping scheme
+%(\np{ln_zdfexp}{ln\_zdfexp}\forcode{=.false.}) depending on the magnitude of the mixing coefficients,
 %and thus of the formulation used (see \autoref{chap:TD}).
 
@@ -58 +58 @@
 %        Constant
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Constant (\forcode{ln_zdfcst})]{Constant (\protect\np{ln\_zdfcst})}
+\subsection[Constant (\forcode{ln_zdfcst})]{Constant (\protect\np{ln_zdfcst}{ln\_zdfcst})}
 \label{subsec:ZDF_cst}
 
 Options are defined through the \nam{zdf} namelist variables.
-When \np{ln\_zdfcst} is defined, the momentum and tracer vertical eddy coefficients are set to
+When \np{ln_zdfcst}{ln\_zdfcst} is defined, the momentum and tracer vertical eddy coefficients are set to
 constant values over the whole ocean.
 This is the crudest way to define the vertical ocean physics.
@@ -72 +72 @@
 \end{align*}
 
-These values are set through the \np{rn\_avm0} and \np{rn\_avt0} namelist parameters.
+These values are set through the \np{rn_avm0}{rn\_avm0} and \np{rn_avt0}{rn\_avt0} namelist parameters.
 In all cases, do not use values smaller that those associated with the molecular viscosity and diffusivity,
 that is $\sim10^{-6}~m^2.s^{-1}$ for momentum, $\sim10^{-7}~m^2.s^{-1}$ for temperature and
@@ -80 +80 @@
 %        Richardson Number Dependent
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Richardson number dependent (\forcode{ln_zdfric})]{Richardson number dependent (\protect\np{ln\_zdfric})}
+\subsection[Richardson number dependent (\forcode{ln_zdfric})]{Richardson number dependent (\protect\np{ln_zdfric}{ln\_zdfric})}
 \label{subsec:ZDF_ric}
 
@@ -92 +92 @@
 %--------------------------------------------------------------------------------------------------------------
 
-When \np{ln\_zdfric}\forcode{=.true.}, a local Richardson number dependent formulation for the vertical momentum and
-tracer eddy coefficients is set through the \nam{zdf\_ric} namelist variables.
+When \np{ln_zdfric}{ln\_zdfric}\forcode{=.true.}, a local Richardson number dependent formulation for the vertical momentum and
+tracer eddy coefficients is set through the \nam{zdf_ric}{zdf\_ric} namelist variables.
 The vertical mixing coefficients are diagnosed from the large scale variables computed by the model.
 \textit{In situ} measurements have been used to link vertical turbulent activity to large scale ocean structures.
@@ -114 +114 @@
 (see \autoref{subsec:ZDF_cst}), and $A_{ric}^{vT} = 10^{-4}~m^2.s^{-1}$ is the maximum value that
 can be reached by the coefficient when $Ri\leq 0$, $a=5$ and $n=2$.
-The last three values can be modified by setting the \np{rn\_avmri}, \np{rn\_alp} and
-\np{nn\_ric} namelist parameters, respectively.
+The last three values can be modified by setting the \np{rn_avmri}{rn\_avmri}, \np{rn_alp}{rn\_alp} and
+\np{nn_ric}{nn\_ric} namelist parameters, respectively.
 
 A simple mixing-layer model to transfer and dissipate the atmospheric forcings
-(wind-stress and buoyancy fluxes) can be activated setting the \np{ln\_mldw}\forcode{=.true.} in the namelist.
+(wind-stress and buoyancy fluxes) can be activated setting the \np{ln_mldw}{ln\_mldw}\forcode{=.true.} in the namelist.
 
 In this case, the local depth of turbulent wind-mixing or "Ekman depth" $h_{e}(x,y,t)$ is evaluated and
@@ -134 +134 @@
 \]
 is computed from the wind stress vector $|\tau|$ and the reference density $ \rho_o$.
-The final $h_{e}$ is further constrained by the adjustable bounds \np{rn\_mldmin} and \np{rn\_mldmax}.
+The final $h_{e}$ is further constrained by the adjustable bounds \np{rn_mldmin}{rn\_mldmin} and \np{rn_mldmax}{rn\_mldmax}.
 Once $h_{e}$ is computed, the vertical eddy coefficients within $h_{e}$ are set to
-the empirical values \np{rn\_wtmix} and \np{rn\_wvmix} \citep{lermusiaux_JMS01}.
+the empirical values \np{rn_wtmix}{rn\_wtmix} and \np{rn_wvmix}{rn\_wvmix} \citep{lermusiaux_JMS01}.
 
 % -------------------------------------------------------------------------------------------------------------
 %        TKE Turbulent Closure Scheme
 % -------------------------------------------------------------------------------------------------------------
-\subsection[TKE turbulent closure scheme (\forcode{ln_zdftke})]{TKE turbulent closure scheme (\protect\np{ln\_zdftke})}
+\subsection[TKE turbulent closure scheme (\forcode{ln_zdftke})]{TKE turbulent closure scheme (\protect\np{ln_zdftke}{ln\_zdftke})}
 \label{subsec:ZDF_tke}
 %--------------------------------------------namzdf_tke--------------------------------------------------
@@ -184 +184 @@
 The constants $C_k =  0.1$ and $C_\epsilon = \sqrt {2} /2$ $\approx 0.7$ are designed to deal with
 vertical mixing at any depth \citep{gaspar.gregoris.ea_JGR90}.
-They are set through namelist parameters \np{nn\_ediff} and \np{nn\_ediss}.
+They are set through namelist parameters \np{nn_ediff}{nn\_ediff} and \np{nn_ediss}{nn\_ediss}.
 $P_{rt}$ can be set to unity or, following \citet{blanke.delecluse_JPO93}, be a function of the local Richardson number, $R_i$:
 \begin{align*}
@@ -195 +195 @@
   \end{cases}
 \end{align*}
-The choice of $P_{rt}$ is controlled by the \np{nn\_pdl} namelist variable.
+The choice of $P_{rt}$ is controlled by the \np{nn_pdl}{nn\_pdl} namelist variable.
 
 At the sea surface, the value of $\bar{e}$ is prescribed from the wind stress field as
-$\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn\_ebb} namelist parameter.
+$\bar{e}_o = e_{bb} |\tau| / \rho_o$, with $e_{bb}$ the \np{rn_ebb}{rn\_ebb} namelist parameter.
 The default value of $e_{bb}$ is 3.75. \citep{gaspar.gregoris.ea_JGR90}), however a much larger value can be used when
 taking into account the surface wave breaking (see below Eq. \autoref{eq:ZDF_Esbc}).
@@ -204 +204 @@
 The time integration of the $\bar{e}$ equation may formally lead to negative values because
 the numerical scheme does not ensure its positivity.
-To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn\_emin} namelist parameter).
+To overcome this problem, a cut-off in the minimum value of $\bar{e}$ is used (\np{rn_emin}{rn\_emin} namelist parameter).
 Following \citet{gaspar.gregoris.ea_JGR90}, the cut-off value is set to $\sqrt{2}/2~10^{-6}~m^2.s^{-2}$.
 This allows the subsequent formulations to match that of \citet{gargett_JMR84} for the diffusion in
@@ -210 +210 @@
 In addition, a cut-off is applied on $K_m$ and $K_\rho$ to avoid numerical instabilities associated with
 too weak vertical diffusion.
-They must be specified at least larger than the molecular values, and are set through \np{rn\_avm0} and
-\np{rn\_avt0} (\nam{zdf} namelist, see \autoref{subsec:ZDF_cst}).
+They must be specified at least larger than the molecular values, and are set through \np{rn_avm0}{rn\_avm0} and
+\np{rn_avt0}{rn\_avt0} (\nam{zdf} namelist, see \autoref{subsec:ZDF_cst}).
 
 \subsubsection{Turbulent length scale}
@@ -217 +217 @@
 For computational efficiency, the original formulation of the turbulent length scales proposed by
 \citet{gaspar.gregoris.ea_JGR90} has been simplified.
-Four formulations are proposed, the choice of which is controlled by the \np{nn\_mxl} namelist parameter.
+Four formulations are proposed, the choice of which is controlled by the \np{nn_mxl}{nn\_mxl} namelist parameter.
 The first two are based on the following first order approximation \citep{blanke.delecluse_JPO93}:
 \begin{equation}
@@ -225 +225 @@
 which is valid in a stable stratified region with constant values of the Brunt-Vais\"{a}l\"{a} frequency.
 The resulting length scale is bounded by the distance to the surface or to the bottom
-(\np{nn\_mxl}\forcode{=0}) or by the local vertical scale factor (\np{nn\_mxl}\forcode{=1}).
+(\np{nn_mxl}{nn\_mxl}\forcode{=0}) or by the local vertical scale factor (\np{nn\_mxl}\forcode{=1}).
 \citet{blanke.delecluse_JPO93} notice that this simplification has two major drawbacks:
 it makes no sense for locally unstable stratification and the computation no longer uses all
 the information contained in the vertical density profile.
-To overcome these drawbacks, \citet{madec.delecluse.ea_NPM98} introduces the \np{nn\_mxl}\forcode{=2, 3} cases,
+To overcome these drawbacks, \citet{madec.delecluse.ea_NPM98} introduces the \np{nn_mxl}{nn\_mxl}\forcode{=2, 3} cases,
 which add an extra assumption concerning the vertical gradient of the computed length scale.
 So, the length scales are first evaluated as in \autoref{eq:ZDF_tke_mxl0_1} and then bounded such that:
@@ -267 +267 @@
 where $l^{(k)}$ is computed using \autoref{eq:ZDF_tke_mxl0_1}, \ie\ $l^{(k)} = \sqrt {2 {\bar e}^{(k)} / {N^2}^{(k)} }$.
 
-In the \np{nn\_mxl}\forcode{=2} case, the dissipation and mixing length scales take the same value:
-$ l_k=  l_\epsilon = \min \left(\ l_{up} \;,\;  l_{dwn}\ \right)$, while in the \np{nn\_mxl}\forcode{=3} case,
+In the \np{nn_mxl}{nn\_mxl}\forcode{=2} case, the dissipation and mixing length scales take the same value:
+$ l_k=  l_\epsilon = \min \left(\ l_{up} \;,\;  l_{dwn}\ \right)$, while in the \np{nn_mxl}{nn\_mxl}\forcode{=3} case,
 the dissipation and mixing turbulent length scales are give as in \citet{gaspar.gregoris.ea_JGR90}:
 \[
@@ -278 +278 @@
 \]
 
-At the ocean surface, a non zero length scale is set through the  \np{rn\_mxl0} namelist parameter.
+At the ocean surface, a non zero length scale is set through the  \np{rn_mxl0}{rn\_mxl0} namelist parameter.
 Usually the surface scale is given by $l_o = \kappa \,z_o$ where $\kappa = 0.4$ is von Karman's constant and
 $z_o$ the roughness parameter of the surface.
-Assuming $z_o=0.1$~m \citep{craig.banner_JPO94} leads to a 0.04~m, the default value of \np{rn\_mxl0}.
+Assuming $z_o=0.1$~m \citep{craig.banner_JPO94} leads to a 0.04~m, the default value of \np{rn_mxl0}{rn\_mxl0}.
 In the ocean interior a minimum length scale is set to recover the molecular viscosity when
 $\bar{e}$ reach its minimum value ($1.10^{-6}= C_k\, l_{min} \,\sqrt{\bar{e}_{min}}$ ).
@@ -312 +312 @@
 $\alpha_{CB} = 100$ the Craig and Banner's value.
 As the surface boundary condition on TKE is prescribed through $\bar{e}_o = e_{bb} |\tau| / \rho_o$,
-with $e_{bb}$ the \np{rn\_ebb} namelist parameter, setting \np{rn\_ebb}\forcode{ = 67.83} corresponds
+with $e_{bb}$ the \np{rn_ebb}{rn\_ebb} namelist parameter, setting \np{rn\_ebb}\forcode{ = 67.83} corresponds
 to $\alpha_{CB} = 100$.
-Further setting  \np{ln\_mxl0}\forcode{ =.true.},  applies \autoref{eq:ZDF_Lsbc} as the surface boundary condition on the length scale,
+Further setting  \np{ln_mxl0}{ln\_mxl0}\forcode{ =.true.},  applies \autoref{eq:ZDF_Lsbc} as the surface boundary condition on the length scale,
 with $\beta$ hard coded to the Stacey's value.
-Note that a minimal threshold of \np{rn\_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) is applied on the
+Note that a minimal threshold of \np{rn_emin0}{rn\_emin0}$=10^{-4}~m^2.s^{-2}$ (namelist parameters) is applied on the
 surface $\bar{e}$ value.
 
@@ -334 +334 @@
 The parameterization, tuned against large-eddy simulation, includes the whole effect of LC in
 an extra source term of TKE, $P_{LC}$.
-The presence of $P_{LC}$ in \autoref{eq:ZDF_tke_e}, the TKE equation, is controlled by setting \np{ln\_lc} to
-\forcode{.true.} in the \nam{zdf\_tke} namelist.
+The presence of $P_{LC}$ in \autoref{eq:ZDF_tke_e}, the TKE equation, is controlled by setting \np{ln_lc}{ln\_lc} to
+\forcode{.true.} in the \nam{zdf_tke}{zdf\_tke} namelist.
 
 By making an analogy with the characteristic convective velocity scale (\eg, \citet{dalessio.abdella.ea_JPO98}),
@@ -363 +363 @@
 where $c_{LC} = 0.15$ has been chosen by \citep{axell_JGR02} as a good compromise to fit LES data.
 The chosen value yields maximum vertical velocities $w_{LC}$ of the order of a few centimeters per second.
-The value of $c_{LC}$ is set through the \np{rn\_lc} namelist parameter,
+The value of $c_{LC}$ is set through the \np{rn_lc}{rn\_lc} namelist parameter,
 having in mind that it should stay between 0.15 and 0.54 \citep{axell_JGR02}.
 
@@ -385 +385 @@
 (\ie\ near-inertial oscillations and ocean swells and waves).
 
-When using this parameterization (\ie\ when \np{nn\_etau}\forcode{=1}),
+When using this parameterization (\ie\ when \np{nn_etau}{nn\_etau}\forcode{=1}),
 the TKE input to the ocean ($S$) imposed by the winds in the form of near-inertial oscillations,
 swell and waves is parameterized by \autoref{eq:ZDF_Esbc} the standard TKE surface boundary condition,
@@ -397 +397 @@
 the penetration, and $f_i$ is the ice concentration
 (no penetration if $f_i=1$, \ie\ if the ocean is entirely covered by sea-ice).
-The value of $f_r$, usually a few percents, is specified through \np{rn\_efr} namelist parameter.
-The vertical mixing length scale, $h_\tau$, can be set as a 10~m uniform value (\np{nn\_etau}\forcode{=0}) or
+The value of $f_r$, usually a few percents, is specified through \np{rn_efr}{rn\_efr} namelist parameter.
+The vertical mixing length scale, $h_\tau$, can be set as a 10~m uniform value (\np{nn_etau}{nn\_etau}\forcode{=0}) or
 a latitude dependent value (varying from 0.5~m at the Equator to a maximum value of 30~m at high latitudes
-(\np{nn\_etau}\forcode{=1}).
-
-Note that two other option exist, \np{nn\_etau}\forcode{=2, 3}.
+(\np{nn_etau}{nn\_etau}\forcode{=1}).
+
+Note that two other option exist, \np{nn_etau}{nn\_etau}\forcode{=2, 3}.
 They correspond to applying \autoref{eq:ZDF_Ehtau} only at the base of the mixed layer,
 or to using the high frequency part of the stress to evaluate the fraction of TKE that penetrates the ocean.
@@ -409 +409 @@
 
 % This should be explain better below what this rn_eice parameter is meant for:
-In presence of Sea Ice, the value of this mixing can be modulated by the \np{rn\_eice} namelist parameter.
+In presence of Sea Ice, the value of this mixing can be modulated by the \np{rn_eice}{rn\_eice} namelist parameter.
 This parameter varies from \forcode{0} for no effect to \forcode{4} to suppress the TKE input into the ocean when Sea Ice concentration
 is greater than 25\%.
@@ -424 +424 @@
 %        GLS Generic Length Scale Scheme
 % -------------------------------------------------------------------------------------------------------------
-\subsection[GLS: Generic Length Scale (\forcode{ln_zdfgls})]{GLS: Generic Length Scale (\protect\np{ln\_zdfgls})}
+\subsection[GLS: Generic Length Scale (\forcode{ln_zdfgls})]{GLS: Generic Length Scale (\protect\np{ln_zdfgls}{ln\_zdfgls})}
 \label{subsec:ZDF_gls}
 
@@ -483 +483 @@
 the choice of the turbulence model.
 Four different turbulent models are pre-defined (\autoref{tab:ZDF_GLS}).
-They are made available through the \np{nn\_clo} namelist parameter.
+They are made available through the \np{nn_clo}{nn\_clo} namelist parameter.
 
 %--------------------------------------------------TABLE--------------------------------------------------
@@ -494 +494 @@
     \hline
     \hline
-    \np{nn\_clo}     & \textbf{0} &   \textbf{1}  &   \textbf{2}   &    \textbf{3}   \\
+    \np{nn_clo}{nn\_clo}     & \textbf{0} &   \textbf{1}  &   \textbf{2}   &    \textbf{3}   \\
     \hline
     $( p , n , m )$         &   ( 0 , 1 , 1 )   & ( 3 , 1.5 , -1 )   & ( -1 , 0.5 , -1 )    &  ( 2 , 1 , -0.67 )  \\
@@ -508 +508 @@
   \caption[Set of predefined GLS parameters or equivalently predefined turbulence models available]{
     Set of predefined GLS parameters, or equivalently predefined turbulence models available with
-    \protect\np{ln\_zdfgls}\forcode{=.true.} and controlled by
-    the \protect\np{nn\_clos} namelist variable in \protect\nam{zdf\_gls}.}
+    \protect\np{ln_zdfgls}{ln\_zdfgls}\forcode{=.true.} and controlled by
+    the \protect\np{nn_clos}{nn\_clos} namelist variable in \protect\nam{zdf_gls}{zdf\_gls}.}
   \label{tab:ZDF_GLS}
 \end{table}
@@ -519 +519 @@
 $C_{\mu}$ and $C_{\mu'}$ are calculated from stability function proposed by \citet{galperin.kantha.ea_JAS88},
 or by \citet{kantha.clayson_JGR94} or one of the two functions suggested by \citet{canuto.howard.ea_JPO01}
-(\np{nn\_stab\_func}\forcode{=0, 3}, resp.).
+(\np{nn_stab_func}{nn\_stab\_func}\forcode{=0, 3}, resp.).
 The value of $C_{0\mu}$ depends on the choice of the stability function.
 
 The surface and bottom boundary condition on both $\bar{e}$ and $\psi$ can be calculated thanks to Dirichlet or
-Neumann condition through \np{nn\_bc\_surf} and \np{nn\_bc\_bot}, resp.
+Neumann condition through \np{nn_bc_surf}{nn\_bc\_surf} and \np{nn_bc_bot}{nn\_bc\_bot}, resp.
 As for TKE closure, the wave effect on the mixing is considered when
-\np{rn\_crban}\forcode{ > 0.} \citep{craig.banner_JPO94, mellor.blumberg_JPO04}.
-The \np{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and
-\np{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}.
+\np{rn_crban}{rn\_crban}\forcode{ > 0.} \citep{craig.banner_JPO94, mellor.blumberg_JPO04}.
+The \np{rn_crban}{rn\_crban} namelist parameter is $\alpha_{CB}$ in \autoref{eq:ZDF_Esbc} and
+\np{rn_charn}{rn\_charn} provides the value of $\beta$ in \autoref{eq:ZDF_Lsbc}.
 
 The $\psi$ equation is known to fail in stably stratified flows, and for this reason
@@ -536 +536 @@
 the entrainment depth predicted in stably stratified situations,
 and that its value has to be chosen in accordance with the algebraic model for the turbulent fluxes.
-The clipping is only activated if \np{ln\_length\_lim}\forcode{=.true.},
-and the $c_{lim}$ is set to the \np{rn\_clim\_galp} value.
+The clipping is only activated if \np{ln_length_lim}{ln\_length\_lim}\forcode{=.true.},
+and the $c_{lim}$ is set to the \np{rn_clim_galp}{rn\_clim\_galp} value.
 
 The time and space discretization of the GLS equations follows the same energetic consideration as for
@@ -548 +548 @@
 %        OSM OSMOSIS BL Scheme
 % -------------------------------------------------------------------------------------------------------------
-\subsection[OSM: OSMosis boundary layer scheme (\forcode{ln_zdfosm})]{OSM: OSMosis boundary layer scheme (\protect\np{ln\_zdfosm})}
+\subsection[OSM: OSMosis boundary layer scheme (\forcode{ln_zdfosm})]{OSM: OSMosis boundary layer scheme (\protect\np{ln_zdfosm}{ln\_zdfosm})}
 \label{subsec:ZDF_osm}
 %--------------------------------------------namzdf_osm---------------------------------------------------------
@@ -682 +682 @@
 %       Non-Penetrative Convective Adjustment
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Non-penetrative convective adjustment (\forcode{ln_tranpc})]{Non-penetrative convective adjustment (\protect\np{ln\_tranpc})}
+\subsection[Non-penetrative convective adjustment (\forcode{ln_tranpc})]{Non-penetrative convective adjustment (\protect\np{ln_tranpc}{ln\_tranpc})}
 \label{subsec:ZDF_npc}
 
@@ -707 +707 @@
 
 Options are defined through the \nam{zdf} namelist variables.
-The non-penetrative convective adjustment is used when \np{ln\_zdfnpc}\forcode{=.true.}.
-It is applied at each \np{nn\_npc} time step and mixes downwards instantaneously the statically unstable portion of
+The non-penetrative convective adjustment is used when \np{ln_zdfnpc}{ln\_zdfnpc}\forcode{=.true.}.
+It is applied at each \np{nn_npc}{nn\_npc} time step and mixes downwards instantaneously the statically unstable portion of
 the water column, but only until the density structure becomes neutrally stable
 (\ie\ until the mixed portion of the water column has \textit{exactly} the density of the water just below)
@@ -747 +747 @@
 %       Enhanced Vertical Diffusion
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Enhanced vertical diffusion (\forcode{ln_zdfevd})]{Enhanced vertical diffusion (\protect\np{ln\_zdfevd})}
+\subsection[Enhanced vertical diffusion (\forcode{ln_zdfevd})]{Enhanced vertical diffusion (\protect\np{ln_zdfevd}{ln\_zdfevd})}
 \label{subsec:ZDF_evd}
 
 Options are defined through the  \nam{zdf} namelist variables.
-The enhanced vertical diffusion parameterisation is used when \np{ln\_zdfevd}\forcode{=.true.}.
+The enhanced vertical diffusion parameterisation is used when \np{ln_zdfevd}{ln\_zdfevd}\forcode{=.true.}.
 In this case, the vertical eddy mixing coefficients are assigned very large values
 in regions where the stratification is unstable
 (\ie\ when $N^2$ the Brunt-Vais\"{a}l\"{a} frequency is negative) \citep{lazar_phd97, lazar.madec.ea_JPO99}.
-This is done either on tracers only (\np{nn\_evdm}\forcode{=0}) or
-on both momentum and tracers (\np{nn\_evdm}\forcode{=1}).
-
-In practice, where $N^2\leq 10^{-12}$, $A_T^{vT}$ and $A_T^{vS}$, and if \np{nn\_evdm}\forcode{=1},
+This is done either on tracers only (\np{nn_evdm}{nn\_evdm}\forcode{=0}) or
+on both momentum and tracers (\np{nn_evdm}{nn\_evdm}\forcode{=1}).
+
+In practice, where $N^2\leq 10^{-12}$, $A_T^{vT}$ and $A_T^{vS}$, and if \np{nn_evdm}{nn\_evdm}\forcode{=1},
 the four neighbouring $A_u^{vm} \;\mbox{and}\;A_v^{vm}$ values also, are set equal to
-the namelist parameter \np{rn\_avevd}.
+the namelist parameter \np{rn_avevd}{rn\_avevd}.
 A typical value for $rn\_avevd$ is between 1 and $100~m^2.s^{-1}$.
 This parameterisation of convective processes is less time consuming than
@@ -778 +778 @@
 
 The turbulent closure schemes presented in \autoref{subsec:ZDF_tke}, \autoref{subsec:ZDF_gls} and
-\autoref{subsec:ZDF_osm} (\ie\ \np{ln\_zdftke} or \np{ln\_zdfgls} or \np{ln\_zdfosm} defined) deal, in theory,
+\autoref{subsec:ZDF_osm} (\ie\ \np{ln_zdftke}{ln\_zdftke} or \np{ln_zdfgls}{ln\_zdfgls} or \np{ln_zdfosm}{ln\_zdfosm} defined) deal, in theory,
 with statically unstable density profiles.
 In such a case, the term corresponding to the destruction of turbulent kinetic energy through stratification in
@@ -790 +790 @@
 because the mixing length scale is bounded by the distance to the sea surface.
 It can thus be useful to combine the enhanced vertical diffusion with the turbulent closure scheme,
-\ie\ setting the \np{ln\_zdfnpc} namelist parameter to true and
-defining the turbulent closure (\np{ln\_zdftke} or \np{ln\_zdfgls} = \forcode{.true.}) all together.
+\ie\ setting the \np{ln_zdfnpc}{ln\_zdfnpc} namelist parameter to true and
+defining the turbulent closure (\np{ln_zdftke}{ln\_zdftke} or \np{ln_zdfgls}{ln\_zdfgls} = \forcode{.true.}) all together.
 
 The OSMOSIS turbulent closure scheme already includes enhanced vertical diffusion in the case of convection,
 %as governed by the variables $bvsqcon$ and $difcon$ found in \mdl{zdfkpp},
-therefore \np{ln\_zdfevd}\forcode{=.false.} should be used with the OSMOSIS scheme.
+therefore \np{ln_zdfevd}{ln\_zdfevd}\forcode{=.false.} should be used with the OSMOSIS scheme.
 % gm%  + one word on non local flux with KPP scheme trakpp.F90 module...
 
@@ -801 +801 @@
 % Double Diffusion Mixing
 % ================================================================
-\section[Double diffusion mixing (\forcode{ln_zdfddm})]{Double diffusion mixing (\protect\np{ln\_zdfddm})}
+\section[Double diffusion mixing (\forcode{ln_zdfddm})]{Double diffusion mixing (\protect\np{ln_zdfddm}{ln\_zdfddm})}
 \label{subsec:ZDF_ddm}
 
@@ -811 +811 @@
 
 This parameterisation has been introduced in \mdl{zdfddm} module and is controlled by the namelist parameter
-\np{ln\_zdfddm} in \nam{zdf}.
+\np{ln_zdfddm}{ln\_zdfddm} in \nam{zdf}.
 Double diffusion occurs when relatively warm, salty water overlies cooler, fresher water, or vice versa.
 The former condition leads to salt fingering and the latter to diffusive convection.
@@ -976 +976 @@
 %       Linear Bottom Friction
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Linear top/bottom friction (\forcode{ln_lin})]{Linear top/bottom friction (\protect\np{ln\_lin})}
+\subsection[Linear top/bottom friction (\forcode{ln_lin})]{Linear top/bottom friction (\protect\np{ln_lin}{ln\_lin})}
 \label{subsec:ZDF_drg_linear}
 
@@ -995 +995 @@
 and assuming an ocean depth $H = 4000$~m, the resulting friction coefficient is $r = 4\;10^{-4}$~m\;s$^{-1}$.
 This is the default value used in \NEMO. It corresponds to a decay time scale of 115~days.
-It can be changed by specifying \np{rn\_Uc0} (namelist parameter).
+It can be changed by specifying \np{rn_Uc0}{rn\_Uc0} (namelist parameter).
 
  For the linear friction case the drag coefficient used in the general expression \autoref{eq:ZDF_bfr_bdef} is:
@@ -1002 +1002 @@
     c_b^T = - r
 \]
-When \np{ln\_lin} \forcode{= .true.}, the value of $r$ used is \np{rn\_Uc0}*\np{rn\_Cd0}.
-Setting \np{ln\_OFF} \forcode{= .true.} (and \forcode{ln_lin=.true.}) is equivalent to setting $r=0$ and leads to a free-slip boundary condition.
+When \np{ln_lin}{ln\_lin} \forcode{= .true.}, the value of $r$ used is \np{rn_Uc0}{rn\_Uc0}*\np{rn_Cd0}{rn\_Cd0}.
+Setting \np{ln_OFF}{ln\_OFF} \forcode{= .true.} (and \forcode{ln_lin=.true.}) is equivalent to setting $r=0$ and leads to a free-slip boundary condition.
 
 These values are assigned in \mdl{zdfdrg}.
 Note that there is support for local enhancement of these values via an externally defined 2D mask array
-(\np{ln\_boost}\forcode{=.true.}) given in the \ifile{bfr\_coef} input NetCDF file.
+(\np{ln_boost}{ln\_boost}\forcode{=.true.}) given in the \ifile{bfr\_coef} input NetCDF file.
 The mask values should vary from 0 to 1.
 Locations with a non-zero mask value will have the friction coefficient increased by
-$mask\_value$ * \np{rn\_boost} * \np{rn\_Cd0}.
+$mask\_value$ * \np{rn_boost}{rn\_boost} * \np{rn_Cd0}{rn\_Cd0}.
 
 % -------------------------------------------------------------------------------------------------------------
 %       Non-Linear Bottom Friction
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Non-linear top/bottom friction (\forcode{ln_non_lin})]{Non-linear top/bottom friction (\protect\np{ln\_non\_lin})}
+\subsection[Non-linear top/bottom friction (\forcode{ln_non_lin})]{Non-linear top/bottom friction (\protect\np{ln_non_lin}{ln\_non\_lin})}
 \label{subsec:ZDF_drg_nonlinear}
 
@@ -1030 +1030 @@
 $e_b = 2.5\;10^{-3}$m$^2$\;s$^{-2}$, while the FRAM experiment \citep{killworth_JPO92} uses $C_D = 1.4\;10^{-3}$ and
 $e_b =2.5\;\;10^{-3}$m$^2$\;s$^{-2}$.
-The CME choices have been set as default values (\np{rn\_Cd0} and \np{rn\_ke0} namelist parameters).
+The CME choices have been set as default values (\np{rn_Cd0}{rn\_Cd0} and \np{rn_ke0}{rn\_ke0} namelist parameters).
 
 As for the linear case, the friction is imposed in the code by adding the trend due to
@@ -1041 +1041 @@
 
 The coefficients that control the strength of the non-linear friction are initialised as namelist parameters:
-$C_D$= \np{rn\_Cd0}, and $e_b$ =\np{rn\_bfeb2}.
-Note that for applications which consider tides explicitly, a low or even zero value of \np{rn\_bfeb2} is recommended. A local enhancement of $C_D$ is again possible via an externally defined 2D mask array
-(\np{ln\_boost}\forcode{=.true.}).
+$C_D$= \np{rn_Cd0}{rn\_Cd0}, and $e_b$ =\np{rn_bfeb2}{rn\_bfeb2}.
+Note that for applications which consider tides explicitly, a low or even zero value of \np{rn_bfeb2}{rn\_bfeb2} is recommended. A local enhancement of $C_D$ is again possible via an externally defined 2D mask array
+(\np{ln_boost}{ln\_boost}\forcode{=.true.}).
 This works in the same way as for the linear friction case with non-zero masked locations increased by
-$mask\_value$ * \np{rn\_boost} * \np{rn\_Cd0}.
+$mask\_value$ * \np{rn_boost}{rn\_boost} * \np{rn_Cd0}{rn\_Cd0}.
 
 % -------------------------------------------------------------------------------------------------------------
 %       Bottom Friction Log-layer
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Log-layer top/bottom friction (\forcode{ln_loglayer})]{Log-layer top/bottom friction (\protect\np{ln\_loglayer})}
+\subsection[Log-layer top/bottom friction (\forcode{ln_loglayer})]{Log-layer top/bottom friction (\protect\np{ln_loglayer}{ln\_loglayer})}
 \label{subsec:ZDF_drg_loglayer}
 
 In the non-linear friction case, the drag coefficient, $C_D$, can be optionally enhanced using
 a "law of the wall" scaling. This assumes that the model vertical resolution can capture the logarithmic layer which typically occur for layers thinner than 1 m or so.
-If  \np{ln\_loglayer} \forcode{= .true.}, $C_D$ is no longer constant but is related to the distance to the wall (or equivalently to the half of the top/bottom layer thickness):
+If  \np{ln_loglayer}{ln\_loglayer} \forcode{= .true.}, $C_D$ is no longer constant but is related to the distance to the wall (or equivalently to the half of the top/bottom layer thickness):
 \[
   C_D = \left ( {\kappa \over {\mathrm log}\left ( 0.5 \; e_{3b} / rn\_{z0} \right ) } \right )^2
 \]
 
-\noindent where $\kappa$ is the von-Karman constant and \np{rn\_z0} is a roughness length provided via the namelist.
+\noindent where $\kappa$ is the von-Karman constant and \np{rn_z0}{rn\_z0} is a roughness length provided via the namelist.
 
 The drag coefficient is bounded such that it is kept greater or equal to
-the base \np{rn\_Cd0} value which occurs where layer thicknesses become large and presumably logarithmic layers are not resolved at all. For stability reason, it is also not allowed to exceed the value of an additional namelist parameter:
-\np{rn\_Cdmax}, \ie
+the base \np{rn_Cd0}{rn\_Cd0} value which occurs where layer thicknesses become large and presumably logarithmic layers are not resolved at all. For stability reason, it is also not allowed to exceed the value of an additional namelist parameter:
+\np{rn_Cdmax}{rn\_Cdmax}, \ie
 \[
   rn\_Cd0 \leq C_D \leq rn\_Cdmax
@@ -1070 +1070 @@
 
 \noindent The log-layer enhancement can also be applied to the top boundary friction if
-under ice-shelf cavities are activated (\np{ln\_isfcav}\forcode{=.true.}).
-%In this case, the relevant namelist parameters are \np{rn\_tfrz0}, \np{rn\_tfri2} and \np{rn\_tfri2\_max}.
+under ice-shelf cavities are activated (\np{ln_isfcav}{ln\_isfcav}\forcode{=.true.}).
+%In this case, the relevant namelist parameters are \np{rn_tfrz0}{rn\_tfrz0}, \np{rn_tfri2}{rn\_tfri2} and \np{rn_tfri2_max}{rn\_tfri2\_max}.
 
 % -------------------------------------------------------------------------------------------------------------
 %       Explicit bottom Friction
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Explicit top/bottom friction (\forcode{ln_drgimp=.false.})]{Explicit top/bottom friction (\protect\np{ln\_drgimp}\forcode{=.false.})}
+\subsection[Explicit top/bottom friction (\forcode{ln_drgimp=.false.})]{Explicit top/bottom friction (\protect\np{ln_drgimp}{ln\_drgimp}\forcode{=.false.})}
 \label{subsec:ZDF_drg_stability}
 
-Setting \np{ln\_drgimp} \forcode{= .false.} means that bottom friction is treated explicitly in time, which has the advantage of simplifying the interaction with the split-explicit free surface (see \autoref{subsec:ZDF_drg_ts}). The latter does indeed require the knowledge of bottom stresses in the course of the barotropic sub-iteration, which becomes less straightforward in the implicit case. In the explicit case, top/bottom stresses can be computed using \textit{before} velocities and inserted in the overall momentum tendency budget. This reads:
+Setting \np{ln_drgimp}{ln\_drgimp} \forcode{= .false.} means that bottom friction is treated explicitly in time, which has the advantage of simplifying the interaction with the split-explicit free surface (see \autoref{subsec:ZDF_drg_ts}). The latter does indeed require the knowledge of bottom stresses in the course of the barotropic sub-iteration, which becomes less straightforward in the implicit case. In the explicit case, top/bottom stresses can be computed using \textit{before} velocities and inserted in the overall momentum tendency budget. This reads:
 
 At the top (below an ice shelf cavity):
@@ -1137 +1137 @@
 %       Implicit Bottom Friction
 % -------------------------------------------------------------------------------------------------------------
-\subsection[Implicit top/bottom friction (\forcode{ln_drgimp=.true.})]{Implicit top/bottom friction (\protect\np{ln\_drgimp}\forcode{=.true.})}
+\subsection[Implicit top/bottom friction (\forcode{ln_drgimp=.true.})]{Implicit top/bottom friction (\protect\np{ln_drgimp}{ln\_drgimp}\forcode{=.true.})}
 \label{subsec:ZDF_drg_imp}
 
 An optional implicit form of bottom friction has been implemented to improve model stability.
 We recommend this option for shelf sea and coastal ocean applications. %, especially for split-explicit time splitting.
-This option can be invoked by setting \np{ln\_drgimp} to \forcode{.true.} in the \nam{drg} namelist.
-%This option requires \np{ln\_zdfexp} to be \forcode{.false.} in the \nam{zdf} namelist.
+This option can be invoked by setting \np{ln_drgimp}{ln\_drgimp} to \forcode{.true.} in the \nam{drg} namelist.
+%This option requires \np{ln_zdfexp}{ln\_zdfexp} to be \forcode{.false.} in the \nam{zdf} namelist.
 
 This implementation is performed in \mdl{dynzdf} where the following boundary conditions are set while solving the fully implicit diffusion step:
@@ -1170 +1170 @@
 \label{subsec:ZDF_drg_ts}
 
-With split-explicit free surface, the sub-stepping of barotropic equations needs the knowledge of top/bottom stresses. An obvious way to satisfy this is to take them as constant over the course of the barotropic integration and equal to the value used to update the baroclinic momentum trend. Provided \np{ln\_drgimp}\forcode{= .false.} and a centred or \textit{leap-frog} like integration of barotropic equations is used (\ie\ \forcode{ln_bt_fw=.false.}, cf \autoref{subsec:DYN_spg_ts}), this does ensure that barotropic and baroclinic dynamics feel the same stresses during one leapfrog time step. However, if \np{ln\_drgimp}\forcode{= .true.},  stresses depend on the \textit{after} value of the velocities which themselves depend on the barotropic iteration result. This cyclic dependency makes difficult obtaining consistent stresses in 2d and 3d dynamics. Part of this mismatch is then removed when setting the final barotropic component of 3d velocities to the time splitting estimate. This last step can be seen as a necessary evil but should be minimized since it interferes with the adjustment to the boundary conditions.
+With split-explicit free surface, the sub-stepping of barotropic equations needs the knowledge of top/bottom stresses. An obvious way to satisfy this is to take them as constant over the course of the barotropic integration and equal to the value used to update the baroclinic momentum trend. Provided \np{ln_drgimp}{ln\_drgimp}\forcode{= .false.} and a centred or \textit{leap-frog} like integration of barotropic equations is used (\ie\ \forcode{ln_bt_fw=.false.}, cf \autoref{subsec:DYN_spg_ts}), this does ensure that barotropic and baroclinic dynamics feel the same stresses during one leapfrog time step. However, if \np{ln\_drgimp}\forcode{= .true.},  stresses depend on the \textit{after} value of the velocities which themselves depend on the barotropic iteration result. This cyclic dependency makes difficult obtaining consistent stresses in 2d and 3d dynamics. Part of this mismatch is then removed when setting the final barotropic component of 3d velocities to the time splitting estimate. This last step can be seen as a necessary evil but should be minimized since it interferes with the adjustment to the boundary conditions.
 
 The strategy to handle top/bottom stresses with split-explicit free surface in \NEMO\ is as follows:
@@ -1184 +1184 @@
 % Internal wave-driven mixing
 % ================================================================
-\section[Internal wave-driven mixing (\forcode{ln_zdfiwm})]{Internal wave-driven mixing (\protect\np{ln\_zdfiwm})}
+\section[Internal wave-driven mixing (\forcode{ln_zdfiwm})]{Internal wave-driven mixing (\protect\np{ln_zdfiwm}{ln\_zdfiwm})}
 \label{subsec:ZDF_tmx_new}
 
@@ -1206 +1206 @@
 where $R_f$ is the mixing efficiency and $\epsilon$ is a specified three dimensional distribution of
 the energy available for mixing.
-If the \np{ln\_mevar} namelist parameter is set to \forcode{.false.}, the mixing efficiency is taken as constant and
+If the \np{ln_mevar}{ln\_mevar} namelist parameter is set to \forcode{.false.}, the mixing efficiency is taken as constant and
 equal to 1/6 \citep{osborn_JPO80}.
 In the opposite (recommended) case, $R_f$ is instead a function of
@@ -1216 +1216 @@
 
 In addition to the mixing efficiency, the ratio of salt to heat diffusivities can chosen to vary
-as a function of $Re_b$ by setting the \np{ln\_tsdiff} parameter to \forcode{.true.}, a recommended choice.
+as a function of $Re_b$ by setting the \np{ln_tsdiff}{ln\_tsdiff} parameter to \forcode{.true.}, a recommended choice.
 This parameterization of differential mixing, due to \cite{jackson.rehmann_JPO14},
 is implemented as in \cite{de-lavergne.madec.ea_JPO16}.
@@ -1234 +1234 @@
   h_{wkb} = H \, \frac{ \int_{-H}^{z} N \, dz' } { \int_{-H}^{\eta} N \, dz'  } \; ,
 \]
-The $n_p$ parameter (given by \np{nn\_zpyc} in \nam{zdf\_iwm} namelist)
+The $n_p$ parameter (given by \np{nn_zpyc}{nn\_zpyc} in \nam{zdf_iwm}{zdf\_iwm} namelist)
 controls the stratification-dependence of the pycnocline-intensified dissipation.
 It can take values of $1$ (recommended) or $2$.
@@ -1248 +1248 @@
 % surface wave-induced mixing
 % ================================================================
-\section[Surface wave-induced mixing (\forcode{ln_zdfswm})]{Surface wave-induced mixing (\protect\np{ln\_zdfswm})}
+\section[Surface wave-induced mixing (\forcode{ln_zdfswm})]{Surface wave-induced mixing (\protect\np{ln_zdfswm}{ln\_zdfswm})}
 \label{subsec:ZDF_swm}
 
@@ -1281 +1281 @@
 % Adaptive-implicit vertical advection
 % ================================================================
-\section[Adaptive-implicit vertical advection (\forcode{ln_zad_Aimp})]{Adaptive-implicit vertical advection(\protect\np{ln\_zad\_Aimp})}
+\section[Adaptive-implicit vertical advection (\forcode{ln_zad_Aimp})]{Adaptive-implicit vertical advection(\protect\np{ln_zad_Aimp}{ln\_zad\_Aimp})}
 \label{subsec:ZDF_aimp}