%-------------------------------------------------------------------------------

% This file is part of Code_Saturne, a general-purpose CFD tool.
%
% Copyright (C) 1998-2020 EDF S.A.
%
% This program is free software; you can redistribute it and/or modify it under
% the terms of the GNU General Public License as published by the Free Software
% Foundation; either version 2 of the License, or (at your option) any later
% version.
%
% This program is distributed in the hope that it will be useful, but WITHOUT
% ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
% FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
% details.
%
% You should have received a copy of the GNU General Public License along with
% this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
% Street, Fifth Floor, Boston, MA 02110-1301, USA.

%-------------------------------------------------------------------------------

%==================================
%==================================
\section{Keyword list}
%==================================
%==================================
\label{sec:prg_motscles}

The keywords are classified under relevant headings. For each keyword of \CS Kernel,
the following informations are given:

\noindent
\makebox[2.5cm][l]{Variable name}\makebox[1.3cm][l]{Type}%
\makebox[5cm][l]{Allowed values}%
\makebox[4.cm][l]{[Default]}O/C\hspace{1cm}Level\\
\hspace*{2.5cm}Description\\
\hspace*{2.5cm}Potential dependences


\begin{list}{$\bullet$}{}
\item \textbf{Variable name}: Name of the variable containing the keyword.

\item \textbf{Type}: a (Array), i (Integer), r (Real number), c
      (Character string).

\item \textbf{Allowed values}: list or range of allowed values.

\item \textbf{Default}: value defined by the code before any user
      modification (every keyword has one). In some cases, a
      non-allowed value is given (generally $-999$ or $-10^{12}$), forcing the
      user to specify a value. If he does not do it, the code may:
\begin{list}{-}{}
\item automatically use a recommended value (for example, automatic
      choice of the variables for which chronological records will be
      generated).

\item stop, if the keyword is essential.
\end{list}

\item \textbf{O/C}: Optional/Compulsory
\begin{list}{-}{}
\item O: optional keyword, whose default value may be enough.

\item C: keyword which must imperatively be specified.
\end{list}

\item \textbf{Level}: L1, L2 or L3
\begin{list}{-}{}
\item L1 (level 1): the users will have to modify it in the framework of
      standard applications. The L1 keywords are written in bold.

\item L2 (level 2): the users may have to modify it in the framework of
      advanced applications. The L2 keywords are all optional.

\item L3 (level 3): the developers may have to modify it; it keeps its
      default value in any other case. The L3 keywords are all optional.
\end{list}

\item \textbf{Description}:  keyword description, with its potential
      dependences.

\end{list}

The L1 keywords can be modified through the Graphical Use Interface or
in the \texttt{cs\_user\_parameters.c} file. L2 and L3 keywords can only be modified through
the \texttt{cs\_user\_parameters.c} file, even if they do not appear in the version proposed
as example it the \texttt{SRC/REFERENCE/base} directory.\\
It is however recommended not to modify the keywords which do not belong to the L1
level.

The alphabetical keyword list is displayed in the index, in the end of
this report.

\minititre{Notes}
$\bullet\ $The notation ``d'' refers to a double precision real. For
           instance, 1.8d-2 means 0.018. \\
$\bullet\ $The notation ``{\tt grand}'' (which can be used in the code)
corresponds to $10^{12}$.

%==================================
\subsection{Input-output}
%==================================

\minititre{Notes}
\begin{list}{$\bullet$}{}
\item Two different files can not use the same unit number (in Fortran) nor the
      same name.
\end{list}

%==================================
\subsubsection{''Calculation'' files}
%==================================

\minititre{General}

\minititre{Thermochemistry}

For the calculation file related to the thermochemistry, please refer
to the dedicated \doxygenfile{group__userfile.html}{\texttt{Doxygen} documentation}.

%==================================
\subsection{Numerical options}
%==================================
\subsubsection{Calculation management}
%==================================

The following \doxygenfile{group__time__step__options.html}{\texttt{Doxygen} documentation}
provides information about the various calculation management options available
in \CS such as \texttt{ntmabs}, \texttt{ntcabs}, etc.

%==================================
\subsubsection{Scalar unknowns}
%==================================

Several keywords refering to the scalar unknowns are
detailed in the following
\doxygenfile{structcs__thermal__model__t.html}{\texttt{Doxygen}
documentation}. The \doxygenfile{structcs__stokes__model__t.html}{\texttt{Doxygen} page}
of the Stokes model structure also contains some keywords such as \texttt{icpsyr},
\texttt{iclvfl} or \texttt{itbrrb}.
For other keywords, please refer to the following \texttt{Doxygen} pages refering to
\doxygenanchor{group__main__variables.html\#nscaus}{\texttt{nscaus}} and
\doxygenanchor{group__scalar__params.html\#iscacp}{\texttt{iscacp}}.

%==================================
\subsubsection{Definition of the equations}
%==================================

For informations about \texttt{istat}, \texttt{iconv}, \texttt{idiff}
or \texttt{idifft}, please refer to the following
\doxygenfile{structcs__var__cal__opt__t.html}{\texttt{Doxygen} documentation}.

Moreover, one can find details about the \texttt{idircl} keyword
\doxygenanchor{group__linear__solver.html\#idircl}{here} and about the
\texttt{ivisse} keyword \doxygenanchor{structcs__stokes__model__t.html\#ivisse}{there}.

%==================================
\subsubsection{Definition of the time advancement}
%==================================

\motcleb{idilat}{i}{1, 2, 3, 4}{1}{O}{L1}
{Algorithm to take into account the density variation in time\\
\hspace*{1.3cm}= 1: steady dilatable flow algorithm (default)\\
\hspace*{1.3cm}= 2: unsteady dilatable flow algorithm\\
\hspace*{1.3cm}= 3: low-Mach number algorithm\\
\hspace*{1.3cm}= 4: non conservative algorithm for fire simulation\\
always useful}

\motcleb{cdtvar}{ra}{strictly positive real number}{1}{O}{L1}
{multiplicative factor applied to the time step for each scalar\\
Hence, the time step used when solving the evolution equation for the
variable is the time step used for the dynamic equations (velocity/pressure)
multiplied by {\tt cdtvar}.\\
The size of the array {\tt cdtvar} is {\tt nvar}. For instance, the multiplicative
coefficient applied to the scalar 2 is {\tt cdtvar(isca(2))}). Yet, the value of
{\tt cdtvar} for the velocity components and the pressure is not used. Also,
although it is possible to change the value of {\tt cdtvar} for the turbulent
variables, it is highly not recommended\\
useful if and only if {\tt nscal} $\geqslant$ 1}

\motcle{varrdt}{r}{strictly positive real number}{0.1}{O}{L3}
{maximum allowed relative increase in the calculated time step value
between two successive time steps (to ensure stability, any decrease in the time step
is immediate and without limit)\\
useful if {\tt idtvar} $\ne$ 0}

For details about time stepping options, please refer to the
dedicated \doxygenfile{group__time__step__options.html}{\texttt{Doxygen}
documentation}.

\minititre{Non-constant time step}
The calculation of the time step uses a reference time step {\tt dtref} (at
the calculation beginning). Later, every time step, the time step value
is calculated by taking into account the different existing limits, in
the following order: \\
\hspace*{1.cm}$\bullet$ {\tt coumax}, {\tt foumax}: the more restrictive limit between
both is used (in the compressible module, the acoustic limitation is added),\\
\hspace*{1.cm}$\bullet$ {\tt varrdt}:  progressive increase and immediate
decrease in the time step,\\
\hspace*{1.cm}$\bullet$ {\tt iptlro}: limitation by the thermal time step,\\
\hspace*{1.cm}$\bullet$ {\tt dtmax} and {\tt dtmin}: clipping of the time step to
the maximum, then to the minimum limit.\\


%==================================
\subsubsection{Turbulence}
%==================================

The $k-\varepsilon$ (standard and linearized production) and $R_{ij}-\varepsilon$
(LRR and SSG) turbulence
models implemented in \CS are ``High-Reynolds'' models. It is therefore
necessary to make sure that the thickness of the first cell neighboring
the wall is larger than the thickness of the viscous sub-layer (at the
wall, $y^+>2.5$ is required as a minimum, and preferably between 30 and
100)\footnote{While creating the mesh, $y^+=\frac{yu*}{\nu}$ is
generally unknown. It can be roughly estimated as $\frac{yU}{10\nu}$, where
$U$ is the characteristic velocity, $\nu$ is the kinematic viscosity of the fluid
 and $y$ is the mid-height of the first cell near the wall.}. If the mesh does
 not respect this condition, the results may be biased
(particularly if thermal processes are involved). Using scalable wall-functions
(cf. keyword {\tt iwallf}) may help avoiding this problem.\\
The v2-f model is a ``Low-Reynolds'' model, it is therefore necessary to
make sure that the thickness of the first cell neighboring the wall is
smaller than the thickness of the viscous sub-layer ($y^+<1$).\\
The $k-\omega$ SST model provides correct results whatever the thickness of the first cell.
Yet, it requires the knowledge of the distance to the wall in every
cell of the calculation domain. The user may refer to the keyword
{\tt icdpar\index{icdpar}} for more details about the potential limitations.\\
The $k-\varepsilon$ model with linear production allows to correct the
known flaw of the standard $k-\varepsilon$ model which overestimates the
turbulence level in case of strong velocity gradients (stopping point).\\
With LES, the wall functions are usually not greatly adapted. It is generally more advisable
(if possible) to refine the mesh towards the wall so that the first cell is in the
viscous sub-layer, where the boundary conditions are simple natural no-slip conditions.\\
Concerning the LES model, the user may refer to the subroutine
\texttt{ussmag} for complements about the dynamic model. Its usage
and the interpretation of its results require particular attention.
In addition, the user must pay further attention when using the dynamic
model with the least squares method based on a partial extended
neighbourhood ({\tt imrgra}=3). Indeed, the results may be degraded if the user
does not implement his own way of averaging the dynamic constant in
\texttt{ussmag} (\textit{i.e.} if the user keeps the local average based
on the extended neighbourhood).\\

For further details, please refer to the following \texttt{Doxygen} documentation
dealing with \doxygenfile{group__turbulence.html}{turbulence options} and
\doxygenfile{group__csttur.html}{turbulence constants}.

%==================================
\subsubsection{Time scheme}
%==================================

By default, the standard time scheme is a first-order.
A second-order scheme is activated automatically with LES modelling.
On the other hand, when ``specific physics'' (gas combustion, pulverised coal,
compressible module) are activated, the second-order scheme is not allowed.

In the current version, the second-order time scheme is not compatible
with the estimators ({\tt iescal}), the velocity-pressure coupling
({\tt ipucou}), the modelling of hydrostatic pressure ({\tt icalhy} and
{\tt iphydr}) and the time- or space-variable time step ({\tt idtvar}).

Also, in the case of a rotation periodicity, a proper second-order is not
ensured for the velocity, but calculations remain possible.

It is recommended to keep the default values of the variables listed
below. Hence, in standard cases, the user does not need to specify these
options.

Please refer to the dedicated
\doxygenfile{group__time__stepping.html}{\texttt{Doxygen} documentation}
for detailed informations about the time stepping parameters.

%==================================
\subsubsection{Gradient reconstruction}
%==================================

The gradient reconstruction keywords such as \texttt{imrgra}, \texttt{nswrgr},
\texttt{epsrgr}, \texttt{imligr}, or \texttt{climgr} are members
of the \texttt{cs\_var\_cal\_opt\_t} structure for which informations can be
found in the following \doxygenfile{structcs__var__cal__opt__t.html}{\texttt{Doxygen}
documentation}.

Details on the \texttt{anomax} keyword can be found
\doxygenanchor{structcs__space__disc__t.html\#anomax}{here} as well.

%==================================
\subsubsection{Solution of the linear systems}
%==================================

See \doxygenfile{parameters.html}{the dedicated \texttt{Doxygen} documentation}
for most settings related to linear solver options.

More informations on these settings can also be found
\doxygenanchor{structcs__var__cal__opt__t.html\#epsilo}{here}.

%==================================
\subsubsection{Convective scheme}
%==================================

For informations on the keywords related to the convective scheme
(i.e. \texttt{blencv}, \texttt{ischcv}, \texttt{isstpc}) please
refer to the following \doxygenfile{structcs__var__cal__opt__t.html}{\texttt{Doxygen}
documentation}.

%==================================
\subsubsection{Pressure-continuity step}
%==================================

Several options related to the pressure-continuity step
are available and can be modified by the user. These options
can be found in the following
\doxygenfile{structcs__stokes__model__t.html}{\texttt{Doxygen} documentation}.
For details about the porosity keyword \texttt{iporos}, please refer to
the dedicated \doxygenanchor{group__additional__source__terms.html\#iporos}{\texttt{Doxygen}
documentation}.

%==================================
\subsubsection{Error estimators for Navier-Stokes}
%==================================

There are currently {\tt nestmx\index{nestmx}}=4 types of local estimators
provided at every time step, with two possible definitions for
each\footnote{Choice made by the user}. These scalars indicate the areas
(cells) in which some error types may be important. They are
stored using the \texttt{cs\_field} API (see
\texttt{field\_get\_val\_s(iestim(iestim), c\_estim)}).
For each estimator, the code writes the minimum and maximum values
in the log and generates post-processing outputs along with
the other variables.

The additional memory cost is about one real number per cell and per
estimator. The additional calculation cost is variable. For instance, on a
simple test case, the total estimator {\tt iestot} generates an additional cost
of 15 to 20 $\%$ on the CPU time\footnote{Indeed, all the first-order in
space differential terms have to be recalculated at the time $t^{\,n+1}$};
the cost of the three others may be neglected. If the user wants to
avoid the calculation of the estimators during the computation, it is
possible to run a calculation without estimators first, and then activate them on
a restart of one or two time steps.

It is recommended to use the estimators only for visual and qualitative
analysis. Also, their use is compatible neither with a second-order time scheme
nor with a calculation with a frozen velocity field.

{\tt \bf iest = iespre\index{iespre}: prediction} (default name: EsPre).
After the velocity prediction step (yielding $\vect{\widetilde{u}}$), the
estimator $\eta^{\,pred}_{\,i,k}(\vect{\widetilde{u}})$, local variable calculated
at every cell $\Omega_i$, is created from $\vect{\mathcal
R}^{\,pred}(\vect{\widetilde{u}})$, which represents the residual of the equation
solved during this step:
\begin{equation*}
\begin{array}{r c l}
\vect{\mathcal{R}}^{\,pred}(\vect{\widetilde{u}})&= & \rho^n
    \dfrac{\vect{\widetilde{u}}-\vect{u}^n}{\Delta t}
  + \gradt \left(\vect{\widetilde{u}} \right) \cdot \left(\rho  \vect{u}\right)^n
              - \divv \left((\mu+\mu_t)^n \gradt(\vect{\widetilde{u}}) \right)
              + \grad(P^n)     \\
              &- &\text{rest of the right-hand side}
                        (\vect{u}^n, P^n, \text{other variables}^n)
\end{array}
\end{equation*}

By definition:
$$ \eta^{\,pred}_{\,i,k}(\vect{\widetilde{u}})= {|\Omega_i|}^{\,(k-2)/2}\ ||\vect{\mathcal R}^{\,pred}(\vect{\widetilde{u}})||
_{{\mathbb{L}}^{2}(\Omega_i)}$$
%
\begin{itemize}
\item The first family, $k=1$, suppresses the
volume $|\Omega_i|$ which intrinsically appears with the norm
${{\mathbb{L}}^{2}(\Omega_i)}$.
\item The second family, $k=2$, exactly represents the norm
${{\mathbb{L}}^{2}(\Omega_i)}$. The size of the cell therefore
appears in its calculation and induces a weighting effect.
\end{itemize}
$ \eta^{\,pred}_{\,i,k}(\vect{\widetilde{u}})$  is ideally equal to zero when the
reconstruction methods are perfect and the associated system is
solved exactly.

{\tt \bf iest = iesder\index{iesder}: drift}  (default name: EsDer).
The estimator $\eta^{\,der}_{\,i,k}(\vect{u}^{\,n+1})$ is based on the
following quantity (intrinsic to the code):
\begin{equation}
\begin{array}{lll}
 \eta^{der}_{i,k}(\vect{u}^{n+1})
&=& {|\Omega_i|}^{\,(k-2)/2}
||\divs \left(\text{corrected mass flow after the pressure step}\right)
                                              -\ \Gamma||_{{L}^{2}(\Omega_i)} \\
&=& {|\Omega_i|}^{\,(1-k)/2}
|div (\text{corrected mass flow after the pressure step})-\ \Gamma|
\end{array}
\end{equation}
Ideally, it is equal to zero when the Poisson equation related to the pressure is
solved exactly.

{\tt \bf iest = iescor\index{iescor}: correction}  (default name: EsCor).
The estimator $ \eta^{\,corr}_{\,i,k}(\vect{u}^{\,n+1})$ comes directly
from the mass flow calculated with the updated velocity field:
\begin{eqnarray*}
            \eta^{\,corr}_{\,i,k}(\vect{u}^{\,n+1})=
|\Omega_i|^{\,\delta_{\,2,k}}\ |div (\rho^n \vect{u}^{n+1}) -\ \Gamma|
\end{eqnarray*}
The velocities $\vect{u}^{n+1}$ are taken at the cell centers,
the divergence is calculated after projection on the faces.\\
            $ \,\delta_{\,2,k}$ represents the Kronecker symbol.\\
\hspace*{0.5cm}$\bullet$ The first family, $k=1$, is the absolute raw
value of the divergence of the mass flow minus the mass source term.\\
\hspace*{0.5cm}$\bullet$ The second family, $k=2$, represents a physical
property and allows to evaluate the difference in $kg.s^{\,-1}$.\\
Ideally, it is equal to zero when the Poisson equation is solved exactly and
the projection from the mass flux at the faces to the velocity at the cell
centers is made in a set of  functions with null divergence.

{\tt \bf iest = iestot\index{iestot}: total} (default name: EsTot).
The estimator $ \eta^{tot}_{\,i,k}(\vect{u}^{n+1})$, local variable
calculated at every cell $\Omega_i$, is based on the quantity
$\vect{\mathcal R}^{tot}(\vect{u}^{\,n+1})$, which represents the
residual of the equation using the updated values of
$\vect{u}$ and $P$:
\begin{equation*}
\begin{array}{@{}r@{\,} c@{\,} l}
\vect{\mathcal{R}}^{tot}({\vect{u}^{n+1}})&= & \rho^n
    \dfrac{{\vect{u}^{n+1}}-\vect{u}^n}{\Delta t}
  + \gradt \left({\vect{u}^{n+1}} \right) \cdot {\left(\rho  \vect{u}\right)}^{n+1}
              - \divv \left((\mu+\mu_t)^n \gradt({\vect{u}^{n+1}}) \right)
              + \grad({P^{n+1}})     \\
              &- &\text{rest of the right-hand side}
                        ({\vect{u}^{n+1}}, {P^{n+1}}, \text{other variables}^n)
\end{array}
\end{equation*}
%
By definition:
$$ \eta^{tot}_{i,k}(\vect{u}^{n+1})= {|\Omega_i|}^{\,(k-2)/2}\ ||\vect{\mathcal R}^{tot}(\vect{u}^{\,n+1})||
_{\mathbb{L}^{2}(\Omega_i)}$$

The mass flux in the convective term is recalculated from $\vect{u}^{n+1}$
expressed at the cell centres (and not taken from the updated mass flow at the
faces).\\

As for the prediction estimator:
\begin{itemize}
\item The first family, $k=1$, suppresses the
volume $|\Omega_i|$ which intrinsicly appears  with the norm
${\mathbb{L}^{2}(\Omega_i)}$.
\item The second family, $k=2$, exactly represents the norm
${\mathbb{L}^{2}(\Omega_i)}$. The size of the cell therefore
appears in its calculation and induces a weighting effect.
\end{itemize}

The estimators are evaluated depending on the values of {\tt iescal}.

%==================================
\subsubsection{Calculation of the distance to the wall}
%==================================

The options related to the calculation of the distance to the wall are described in
the following \doxygenfile{group__num__wall__distance.html}{\texttt{Doxygen} documentation}.
Some options are used only in the case of the calculation of the non-dimensional distance
to the wall $y^+$ (LES model with van Driest damping). Most of the keywords are simple copies of the
keywords for the numerical options of the general equations, with a potentially
specific value in the case of the calculation of the distance to the wall.\\

%==================================
\subsubsection{Others}
%==================================

Informations concerning the remaining keywords can be reached
through the following \texttt{Doxygen} pages:

\begin{itemize}
\item \doxygenfile{structcs__stokes__model__t.html}{\texttt{iccvfg}
and \texttt{ipucou}}
\item \doxygenfile{structcs__piso__t.html}{\texttt{nterup}
and \texttt{epsup}}
\item \doxygenanchor{structcs__space__disc__t.html\#imvisf}{\texttt{imvisf}}
\item \doxygenfile{structcs__var__cal__opt__t.html}{\texttt{irclu},
\texttt{nswrsm} and \texttt{epsrsm}}
\item \doxygenanchor{group__optcal.html\#isuit1}{\texttt{isuit1}}
\end{itemize}

%====================================================================================
\subsection{Numerical, physical and modelling parameters}
%=============================================================================
\subsubsection{Numeric parameters}
%================================

These parameters correspond to numeric reference values in the code.
They can be used but shall not be modified (they are defined as \texttt{parameter}).

For a list of these physical parameters, please refer to the following
\doxygenfile{group__cstnum.html}{\texttt{Doxygen} documentation}.


%==================================
\subsubsection{Physical parameters}
%==================================

These parameters correspond to physical reference values in the code. They
can be used but shall not be modified (they are defined as {\tt parameter}).

For a list of these physical parameters, please refer to the following
\doxygenfile{group__cstphy.html}{\texttt{Doxygen} documentation}.

%==================================
\subsubsection{Physical variables}
%==================================

Most physical variables are listed in the following
\doxygenfile{group__cstphy.html}{\texttt{Doxygen} documentation}.

Other physical variables such as \texttt{diftl0}, \texttt{srrom},
\texttt{sigmas} or \texttt{rvarfl} are described in the following
\texttt{Doxygen} pages :
\begin{itemize}
\item \doxygenanchor{group__thermophysical.html\#diftl0}{\texttt{diftl0}},
\item \doxygenanchor{group__enthalpy.html\#srrom}{\texttt{srrom}},
\item \doxygenfile{group__scalar__params.html}{\texttt{sigmas},
\texttt{rvarfl}}.
\end{itemize}

%==================================
\subsection{ALE}
%==================================

For further details about the ALE calculation options,
please refer to the dedicated \texttt{Doxygen} pages
\doxygenfile{group__albase.html}{here} and
\doxygenfile{group__alstru.html}{there}. The following
\doxygenanchor{group__conv__scheme.html\#iflxmw}{\texttt{Doxygen}
documentation} might be useful as well.

%==================================
\subsection{Thermal radiative transfers: global settings}
%==================================

Most of radiative module keywords may be modified in the user subroutines
\texttt{cs\_user\_radiative\_*} (or, for some of them, through the
thermochemical data files).

For a detailed list of these keywords, please refer to the following
\doxygenfile{structcs__rad__transfer__params__t.html}{\texttt{Doxygen}
documentation}.

%==================================
\subsection{Electric module (Joule effect and electric arcs): specificities}
%==================================

The electric module is composed of a Joule effect module
(\texttt{ippmod(ieljou)\index{ieljou}}) and an electric arcs module
(\texttt{ippmod(ielarc)\index{ielarc}}).

The Joule effect module is designed to take into account the Joule effect
(for instance in glass furnaces) with real or complex potential in the
enthalpy equation. The Laplace forces are not taken into account in the
impulse momentum equation. Specific boundary conditions can be applied to
account for the coupled effect of transformers (offset) in glass furnaces.

The electric arcs module is designed to take into account the Joule effect
(only with real potential) in the enthalpy equation. The Laplace forces
are taken into account in the impulse momentum equation.

The different keywords used in the electric module are detailed in
the following \doxygenfile{structcs__elec__option__t.html}{\texttt{Doxygen}
documentation}.
