%-----------------------------------------------------------------------
%
%     This file is part of the Code_Saturne Kernel, element of the
%     Code_Saturne CFD tool.
%
%     Copyright (C) 1998-2009 EDF S.A., France
%
%     contact: saturne-support@edf.fr
%
%     The Code_Saturne Kernel 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.
%
%     The Code_Saturne Kernel 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 the Code_Saturne Kernel; if not, write to the
%     Free Software Foundation, Inc.,
%     51 Franklin St, Fifth Floor,
%     Boston, MA  02110-1301  USA
%
%-----------------------------------------------------------------------
\nopagebreak
%==================================
%==================================
\section{Introduction}
%==================================
%==================================

\CS is a system designed to solve the Navier-Stokes
equations in the cases of 2D, 2D axisymmetric or 3D flows. Its main module is
designed for the simulation of flows which may be steady or
unsteady, laminar or turbulent, incompressible or potentially dilatable,
isothermal or not. Scalars and turbulent fluctuations of scalars can be taken into
account. The code includes specific modules, referred to as ``specific physics'',
for the treatment of Lagrangian particle tracking, semi-transparent radiative transfer,
gas combustion, pulverised coal combustion,
electricity effects (Joule effect and electric arcs) and compressible flows.
The code also includes an engineering module, Matisse, for the simulation of
nuclear waste surface storage.

\CS 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.
\CS 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.\footnote{You should have
received a copy of the GNU General Public License
along with \CS; if not, write to the
Free Software Foundation, Inc.,
51 Franklin St, Fifth Floor,
Boston, MA  02110-1301  USA}


\CS relies on a finite volume discretisation and allows the use of
various mesh types which may be hybrid (containing several kinds of
elements) and may have structural non-conformities (hanging nodes).


\CS is composed of three main elements and an optional GUI,
as shown on figure \ref{Fig_elements}:
\begin{itemize}
\item the Kernel module is the numerical solver
\item the Preprocessor module is in charge of mesh import,
mesh joining (arbitrary interfaces), and definition of periodicity
boundary conditions (translation and/or rotation)
\item the Partitioner is in charge of optimizing domain decomposition
for parallel computing (optional, but highly recommended for parallel
performance)\\
\end{itemize}

\begin{figure}[!h]
\centerline{
\includegraphics*[width=14cm]{cs_components}}
\caption{\CS elements}\label{Fig_elements}
\end{figure}

\indent\CS also relies on two libraries (by the same team, under LGPL licence),
which can also be used independently:
\begin{itemize}
\item BFT (Base Functions and Types) for the management of memory and input/output
as well as specific utilities (estimation of time and memory usage for instance)
\item FVM (Finite Volume Mesh) for the post-processing output and the management
of code coupling
\end{itemize}

The present document is a practical user's guide for \CS version \verscs.
It is the result of the joint effort of
all the members in the development team.

The aim of this document is to give practical information to the users of
\CS. It is therefore strictly oriented towards the usage of the code.
For more details about the algorithms and their numerical
implementation, please refer to the reports \cite{mechitoua98} and
\cite{boucker00}, and to the theoretical documentation \cite{theory},
which is newer and more detailed
(the latest updated version of this document
is available on-line with the version of \CS and accessible through the command
\texttt{cs\_info --guide theory}).

The present document first
presents all the necessary elements to run a calculation
with \CS version \verscs. It then lists all the variables of the code
which may be useful for more advanced utilisation.
The user subroutines of all the modules within the code are then documented.
Eventually, for each key word and user-modifiable parameter in the code,
their definition, allowed values, default values and conditions for use are given.
These key words and parameters are grouped under headings
based on their function. An alphabetical index list is also given at the end of
the document for easier consultation.



%==================================
%==================================
\section{Practical information about \CS}
%==================================
%==================================

%==================================
\subsection{System Environment for \CS}
%==================================

%==================================
\subsubsection{Preliminary settings}
%==================================
\label{prg_environementCS}

In order to use \CS, every user must add the following line (in their
\texttt{.profile}, or equivalent, depending on the environment):

\hspace*{1cm}\texttt{export PATH=\{prefix\}/bin:\$PATH}\\

or define the following alias (in their \texttt{.bashrc}, or
 equivalent, or \texttt{.alias} file, depending on the environment):

\hspace*{1cm}\texttt{alias cs='\{prefix\}/bin/cs'}\\

where \texttt{prefix} is the base directory where
\CS and its components have been installed\footnote{At EDF R\&D, \texttt{/home/saturne/Code\_Saturne/\verscs} is used}.

%==================================
\subsubsection{Standard directory hierarchy}
%==================================
\label{prg_architecture}%
The standard architecture for the simulation studies is:

\noindent
A study directory containing:
\begin{list}{$\bullet$}{}
\item A directory \texttt{MESH} containing the mesh(es)
      necessary for the study
\item A directory \texttt{POST} for the potential post-processing routines (not
used directly by the code)
\item One or several calculation directories
\end{list}

\noindent
Every calculation directory contains:
\begin{list}{$\bullet$}{}
\item A directory \texttt{SRC} for the potential user subroutines
      necessary for the calculation
\item A directory \texttt{DATA} for the calculation data (data
      file from the interface, input profiles, thermo-chemical data, ...)
\item A directory \texttt{SCRIPTS} for the launch script
\item A directory \texttt{RESU} for the results\\
To improve the calculation traceability, the files and directories
sent to \texttt{RESU} after a calculation are given a suffix
identifying the calculation start date and time by an eight-digit
number (two digits for each month, day, hour and minute; the result of a
calculation started at 14h03 on December 31$^{\text{st}}$ will therefore be indexed
12311403)
\end{list}

\noindent
In the standard cases, \texttt{RESU} contains a directory
\texttt{CHR.ENSIGHT.mmddhhmm} with the post-processing files in {\em EnSight} format,
a directory \texttt{RESTART.mmddhhmm} for the calculation
      restart files,
a directory  \texttt{HIST.mmddhhmm} for the files of chronological
      record of the results at specific locations (probes),\\
\texttt{listpre.mmddhhmm} and \texttt{listing.mmddhhmm} files reporting the
Preprocessor and the Kernel execution. For an easier follow-up of the modifications
in former calculations, the user-subroutines used in a calculation are stored in
a directory \texttt{SRC.mmddhhmm} in the directory \texttt{RESU}. The {\em Xml}
Interface data file, thermo-chemical data files and launch script are also
copied into the  directory \texttt{RESU} with the appropriate suffix (whatever
its name, the launch script appears in the directory \texttt{RESU} as
\texttt{runcase.mmddhhmm}). \texttt{compil.log.mmddhhmm} and
\texttt{summary.mmddhhmm} are respectively reports of the compilation phase and
general information on the calculation (which kind of machine, which user, which
version of the code, ...). Eventually, when the user subroutines produce
specific result files (extraction of 1D profiles for instance), a
directory \texttt{RES\_USERS.mmddhhmm} is created in the directory \texttt{RESU}
for these files\footnote{in order for the script to copy them properly, their
names have to be given in the variable \texttt{USER\_OUTPUT\_FILES}
of the launch script, see \S\ref{prg_runcase}}.


During calculations coupled with \syrthes (option specified in the launch
script of \CS or {\em via} the Interface) the same organisation is used for the
files related to \CS. For the files related
 to \syrthes, the location of the upstream files is specified in the
\texttt{syrthes.env} file. Yet, the launch script is built presuming that the
following organisation is applied:
\begin{list}{$\bullet$}{}
\item a directory \texttt{SRC\_SYR} for the potential \syrthes user subroutines
\item a directory \texttt{DATA\_SYR} containing the configuration file \texttt{syrthes.env}
(location of files specific to \syrthes). The file defining the \syrthes
calculation options (\texttt{syrthes.data}) and the potential restart files can
also be placed in this directory.
\end{list}

The \syrthes result files (geometry file, chronological result files, calculation
restart files and the historic file) are placed in a sub-directory
\texttt{RESU\_SYR.mmddhhmm} of the \texttt{RESU} directory, where
\texttt{mmddhhmm} corresponds to the calculation identification suffix.

\sloppy

\noindent
The \syrthes execution report file is placed in the \texttt{RESU} directory (same as
for the \CS review) under the name \texttt{listsyr.mmddhhmm} and the compilation
report file is under the name  \texttt{compil\_syrthes.log.mmddhhmm}.
For an easier follow-up of the modifications
in former calculations, the potential \syrthes user-subroutines used in a
calculation are stored in a directory \texttt{SRC\_SYR.mmddhhmm} in the
directory \texttt{RESU}.

\fussy


\begin{table}[!t]
\begin{tabular}{lll}
\multicolumn{3}{l}{Below are typical contents of a case directory CASE1 in a study STUDY} \\
\multicolumn{3}{l}{(\CS calculation coupled with \syrthes):}\\
\multicolumn{2}{l}{\texttt{STUDY/CASE1/DATA:}}&{\bf \CS data}\\
&        \texttt{SaturneGUI}                &Graphical User Interface launch script\\
&        \texttt{study.xml}                &Graphical User Interface parameter file\\
&        \texttt{THCH}                        &example of thermochemical files
                                         (used with the specific\\
&                                   & physics modules for gas combustion,
                                      pulverised coal \\
&                                   & or electric arcs)\\

\multicolumn{2}{l}{\texttt{STUDY/CASE1/DATA\_SYR:}}&{\bf \syrthes data}\\
&        \texttt{syrthes.data}                  &\syrthes data file \\
&        \texttt{syrthes.env}                &\syrthes configuration file\\
\multicolumn{2}{l}{\texttt{STUDY/CASE1/SRC:}}&{\bf \CS user subroutines }\\
&        \texttt{REFERENCE}                   &        examples of a user subroutines\\
&        \texttt{usclim.f90}                 &user subroutines used for the present the calculation\\
&        \texttt{usini1.f90} &\\
\multicolumn{2}{l}{\texttt{STUDY/CASE1/RESU:}}&{\bf results}\\
&        \texttt{CHR.ENSIGHT.08211921}              &directory containing the \CS
                                           post-processing results\\
&                                         &in the {\em EnSight} format for the
                                          calculation 08211921\\
&                                        &(contains both volume and boundary results;\\
&                                        &the contents of the directory are user
                                          modifiable)\\
&        \texttt{SRC.08211921}              &\CS user subroutines
                                        used for the\\
&                                      &calculation 08211921\\
&        \texttt{SRC\_SYR.08211921}   &\syrthes user subroutines
                                     used in the calculation 08211921\\
&        \texttt{HIST.08211921}        &directory containing the chronological
                                      records for \CS\\
&        \texttt{RES\_USERS.08211921}  &optional directory containing the
                                     user results files\\
&        \texttt{RESTART.08211921}       &directory containing the \CS restart files \\
&        \texttt{compile.log.08211921}  &compilation report\\
&     \texttt{study.xml.08211921}   &Graphical User Interface parameter file
                                    used for the\\
&                                   &calculation 08211921\\
&        \texttt{runcase.08211921}       &launch script used for the calculation 08211921\\
&                                   &(whatever the name given to the file in the
                                     \texttt{SCRIPT} directory,\\
&                                   & the file will be referred as
                                      ``\texttt{runcase.*}'' in the
                                       \texttt{RESU} directory)\\
&        \texttt{listpre.08211921}     &execution report for the Preprocessor module of
                                    \CS\\
&        \texttt{listing.08211921}     &execution report for the Kernel module of \CS\\
&        \texttt{listsyr.08211921}     &execution report for \syrthes\\
&        \texttt{summary.08211921}      &general information (machine, user, version, ...)\\
&     \texttt{RESU\_SYR.08211921:}  &{\bf \syrthes results (file names given in
the
                                      \texttt{syrthes.env} file)}\\
&        \hspace*{0.3cm}\texttt{geoms} &\syrthes \ solid geometry file\\
&        \hspace*{0.3cm}\texttt{histos1}&\syrthes chronological records at
                                      specified probes\\
&        \hspace*{0.3cm}\texttt{resus1}&\syrthes calculation restart file (1
                                                     time step)\\
&        \hspace*{0.3cm}\texttt{resusc1}&\syrthes chronological solid
                                      post-processing file (may be transformed \\
&                                    &into the {\em EnSight} format with the
                                     {\em syrthes2ensight} utility)\\
\multicolumn{2}{l}{\texttt{STUDY/CASE1/SCRIPTS:}}&{\bf launch script}\\
&        \texttt{runcase}                &launch script (compliant with all
                                     architectures on which \\
&                                   & \CS has been ported)\\
\end{tabular}
\end{table}

\clearpage


%==================================
\subsubsection{\CS Kernel library files}
%==================================
\label{prg_library}%
Information about the content of the \CS base directories is given below. It
is not of vital interest for the user, but given only as general
information. Indeed, the case preparer command \texttt{code\_saturne~create}
automatically extracts the necessary files and prepares the launch script
without the user having to go directly into the \CS base directories
(see \S\ref{prg_cscreate}).
The \texttt{code\_saturne~info} command gives direct
access to the most needed information (especially the user and programmer's
guides and the tutorial) without the user having to look for them in the \CS
directories.

The subdirectories \texttt{\{prefix\}/lib} and \texttt{\{prefix\}/bin }
contain the libraries and compiled executables respectively.

The data files (for instance thermochemical data) are located in the
directory \texttt{data}.

The user subroutines are available in the directory \texttt{users},
under subdirectories corresponding to each module:
\texttt{base} (general routines),
\texttt{cfbl} (compressible flows),
\texttt{cogz} (gas combustion),
\texttt{cplv} (pulverised coal combustion),
\texttt{ctwr} (cooling towers modelling),
\texttt{elec} (electric module),
\texttt{fuel} (heavy fuel oil combustion module),
\texttt{lagr} (Lagrangian module,
\texttt{mati} (Matisse module),
\texttt{pprt} (general specific physics routines) and
\texttt{rayt} (radiative heat transfer).
The case preparer command \texttt{code\_saturne~create} copies all these files
in the user directory \texttt{SRC/REFERENCE} during the case preparation.

The ``include'' files are available in the directory
\texttt{include}, under similar subdirectories corresponding to each module:
\texttt{base}, \texttt{cfbl}, \texttt{cogz}, \texttt{cplv}, \texttt{elec},
\texttt{fuel}, \texttt{lagr}, \texttt{mati}, \texttt{pprt} and \texttt{rayt}.

The directory \texttt{bin} contains an example of the launch script, the
compilation parameter files and various utility programs.

%==================================
\subsection{Setting up and running of a calculation}
%==================================

%==================================
\subsubsection{Step by step calculation}
%==================================

This paragraph summarises the different steps which are necessary to
prepare and run a standard case:

\begin{list}{$\bullet$}{}

\item Check the version of \CS set for use in the environment variables
(\texttt{code\_saturne~info --version}). If it does not correspond to
the desired version, update the \texttt{.profile} file to set the environment
variables correctly. Log out of the session and
log in again to take the modifications into account properly (cf.
\S\ref{prg_environementCS}).

\item Prepare the different directories using the \texttt{code\_saturne~create}
command (see \S\ref{prg_cscreate}) and, when needed, add the directories
\texttt{DATA\_SYR} and \texttt{SRC\_SYR} which are required to accomodate the
\syrthes files.

\item Place the mesh(es) in the directory \texttt{MESH}. Make sure they are
in a format compliant with \CS (see \S\ref{prg_maillages}). There can be
several meshes in case of mesh joining or coupling with
\syrthes\footnote{\syrthes uses meshes composed of 10-node tetrahedra (vertices
and centers of edges)}.

\item Go to the directory \texttt{DATA} and launch the
      Graphical User Interface using the command \texttt{./SaturneGUI} (see
\S\ref{prg_gui}).

\item Place the necessary user subroutines in the directory \texttt{SRC} (see
\S\ref{prg_ssprgutilis}). When not using the Interface, some subroutines are
compulsory.

\begin{list}{}{}

\item {\bf For the standard physics:}

    \begin{list}{}{}
        \item {\em compulsory without Graphical User Interface:}
        \begin{list}{-}{}
            \item \texttt{usini1} to specify the calculation parameters

            \item \texttt{usclim} to manage the boundary conditions
        \end{list}

        \item {\em  very useful:}
        \begin{list}{-}{}
            \item \texttt{usphyv} to manage the variable physical
                  properties (fluid density, viscosity ...)

            \item \texttt{usiniv} to manage the non-standard initialisations
        \end{list}
    \end{list}

  \item{\bf For the specific physics ``gas combustion'':}

(not accessible through the Graphical User Interface in version \verscs)
    \begin{list}{}{}
        \item {\em compulsory:}
        \begin{list}{-}{}
            \item \texttt{usini1} to specify the calculation parameters

            \item \texttt{usppmo} to select a specific physics module and
               combustion model

            \item \texttt{usebuc}, \texttt{usd3pc} or \texttt{uslwcc}
                  (depending on the selected combustion model) to manage the
                  boundary conditions of {\em all variables} ({\em i.e.} not only
              the ones related to the combustion model)
        \end{list}

        \item {\em very useful:}
        \begin{list}{-}{}
            \item  \texttt{usebu1}, \texttt{usd3p1} or \texttt{uslwc1}
                   (depending on the selected combustion model)
               to specify the calculation options
                   for the variables
                   corresponding to combustion model

            \item   \texttt{usebui}, \texttt{usd3pi} or \texttt{uslwci}
              (depending on the selected combustion model)
                   to manage the initialisation of the variables
                   corresponding to the combustion model
        \end{list}
    \end{list}

  \item{\bf For the specific physics ``coal combustion'':}

    \begin{list}{}{}
        \item {\em compulsory without Graphical User Interface:}
        \begin{list}{-}{}
            \item \texttt{usini1} to specify the calculation parameters

            \item \texttt{usppmo} to select the specific physics module

            \item \texttt{uscpcl} or \texttt{uscplc} (depending on the
                  specific physics module) to manage the
                  boundary conditions of {\em all variables} ({\em i.e.} not only
              the ones related to the specific physics module)
        \end{list}

        \item {\em very useful:}
        \begin{list}{-}{}
            \item  \texttt{uscpi1}
               to specify the calculation options
                   for the variables
                   corresponding to the specific physics module

            \item \texttt{uscpiv} to manage the initialisation of the
                   variables corresponding to the specific physics module
        \end{list}
    \end{list}

     \item{\bf For the specific physics ``electric module''
      (Joule effect and electric arcs):}

(not accessible through the Graphical User Interface in version \verscs)
    \begin{list}{}{}
       \item {\em compulsory:}
        \begin{list}{-}{}
            \item \texttt{usini1} to specify the calculation parameters

            \item \texttt{usppmo} to select the specific physics module

            \item \texttt{uselcl} to manage the boundary conditions of {\em all
              variables} ({\em i.e.} not only
              the ones related to the electric module)

            \item \texttt{useliv} to initialise the enthalpy in
                  case of Joule effect

            \item \texttt{uselph} to define the physical
                  properties in case of Joule effect
        \end{list}

        \item {\em very useful:}
        \begin{list}{-}{}
            \item  \texttt{useli1} to manage the options related
                   to the variables corresponding to the electric module

            \item   \texttt{useliv} to manage the initialisation of the
                   variables corresponding to the electric module
        \end{list}
    \end{list}

     \item{\bf For the specific physics ``heavy fuel oil combustion module'':}

(not accessible through the Graphical User Interface in version \verscs)
    \begin{list}{}{}
        \item {\em compulsory:}
        \begin{list}{-}{}
            \item \texttt{usini1} to specify the calculation parameters

            \item \texttt{usppmo} to select the specific physics module

            \item \texttt{usfucl} to manage the
                  boundary conditions of {\em all variables} ({\em i.e.} not only
              the ones related to the specific physics module)
        \end{list}

        \item {\em very useful:}
        \begin{list}{-}{}
            \item  \texttt{usfui1}
               to specify the calculation options
                   for the variables
                   corresponding to the specific physics module

            \item \texttt{usfuiv} to manage the initialisation of the
                   variables corresponding to the specific physics module
        \end{list}
    \end{list}


    \item{\bf For the Lagrangian module (dispersed phase):}

(the continuous phase is managed in the same way as for a case of standard
physics)\\
(the Lagrangian module is not accessible through the Graphical User Interface in
version \verscs)
    \begin{list}{}{}
        \item {\em compulsory:}
        \begin{list}{-}{}
            \item \texttt{uslag1} to manage the calculation conditions

            \item \texttt{uslag2} to manage the boundary conditions for the
             dispersed phase

        \end{list}

        \item {\em very useful:}
        \begin{list}{-}{}
                \item \texttt{uslabo} to manage potential specific treatments at the
             boundaries (rebound conditions, specific statistics, ...)
        \end{list}
    \end{list}

   \item {\bf For the compressible module:}

(not accessible through the Graphical User Interface in version \verscs)
    \begin{list}{}{}
        \item {\em compulsory:}
        \begin{list}{-}{}
            \item \texttt{uscfx1} and \texttt{uscfx2} to manage the
                  calculation parameters

            \item \texttt{uscfcl} to manage the boundary conditions

            \item \texttt{uscfth} to define the thermodynamics.
        \end{list}

        \item {\em very useful:}
        \begin{list}{-}{}
                \item \texttt{uscfxi} to manage non-standard initialisations of the variables
        \end{list}
    \end{list}

\end{list}


The comprehensive list of the user subroutines and their instructions
      for use are given in \S\ref{prg_ssprgutilis}.

\item If necessary, place in the directory \texttt{DATA} the different
      external data (input profiles, thermochemical data files, ...)

\item Prepare the launch script \texttt{runcase}, directly or through the
      Graphical Interface (see \S\ref{prg_runcase})

\item Run the calculation and analyse the results

\item Purge the temporary files (in the directory \texttt{RUN} defined
      in the launch script, see \S\ref{prg_runcase})
\end{list}


%==================================
\subsubsection{Temporary execution directory}
%==================================
\label{prg_temporarydirectory}%
During a calculation, \CS uses a temporary directory for the compilation and
the execution, the result files being only copied at the end in the directory
\texttt{RESU}. This temporary directory is defined in the variable \texttt{RUN}
of the launch script. This variable is set top a default value in the non-user
section of the launch script, depending on the architecture:\\
\texttt{RUN=\$HOME/tmp\_Saturne/\$STUDY/\$CASE.mmddhhmm} for stand-alone
workstations or for the Chatou cluster\\
\texttt{RUN=\$SCRATCHDIR/tmp\_Saturne/\$STUDY/\$CASE.mmddhhmm} for
Platine at the CCRT\\
where \texttt{\$STUDY} and \texttt{\$CASE} are the names of the study and the
case. The usual suffix with the date and time is added so that successive
calculations will not get mixed-up.

This default value might not always be the optimal choice. Indeed, on a
stand-alone machine, it might be useful to take advantage of large sized local
disks on a machine when the \texttt{\$HOME} account is on an NFS disk.

For this matter, the variable \texttt{CS\_TMP\_PREFIX} of the launch script (see
\S\ref{prg_runcase}) allows  the user to change this directory.
If the variable is empty, the default
\texttt{RUN} directory will be used. If it is not empty, the launch script will
set the \texttt{RUN} directory to
\texttt{\$CS\_TMP\_PREFIX/tmp\_Saturne/\$STUDY/\$CASE.mmddhhmm}.

\noindent
{\em WARNING: in most cases, the temporary directories are not deleted
after a calculation. They will  accumulate and may hinder the correct running of
the machine.\\
\centerline{\bf It is therefore essential to remove them regularly.}}


%==================================
\subsubsection{Execution modes}
%==================================
\label{prg_executionmodes}%
As explained before, \CS is composed of two main modules, the Preprocessor and the
Kernel, and an optional Partitioner. The Preprocessor reads the meshes and
performs the necessary joinings. The Partitioner optimizes domain decomposition
for parallel runs. The resulting data is transfered to the Kernel through specific
files, named \texttt{preprocessor\_output} and \texttt{domain\_number\_*}, where
\texttt{*} is the number of processors used. In a standard calculation, the files
are not copied from the temporary execution directory to the results directory,
as they have no interest for data analysis, and are considered ``internal''
files, whose format or contents is not guaranteed not to change between \CS versions.

Yet, the Preprocessor and Partitioner do not work in parallel and may require a
large amount of memory. Hence it is sometimes useful to run them
separately, on a machine or in batch queues with extended memory, and to run the
proper parallel calculation on another machine or in another batch
queue. The launch scripts therefore allows specifically choosing
which modules to run, using the variables \texttt{EXEC\_PREPROCESS},
\texttt{EXEC\_PARTITION}, and \texttt{EXEC\_KERNEL} (see \S\ref{prg_runcase}).

\sloppy

\hspace*{0.5cm} If \texttt{EXEC\_PREPROCESS=no}, the Partitioner and Kernel will
copy or link the file defined by the \texttt{PREPROCESSOR\_OUTPUT\_IN}
variable to \texttt{preprocessor\_output}.

\hspace*{0.5cm} If \texttt{EXEC\_PARTITION=no}, the Kernel will search for a
corresponding \texttt{domain\_number\_*} file in the directory defined by
\texttt{PARTITION\_OUTPUT\_IN}.

\hspace*{0.5cm} If \texttt{EXEC\_KERNEL=no}, the Preprocessor and Partitioner
output will be saved respectively to a
\texttt{\$RESU/preprocessor\_output.\$SUFFIX} file
and to a \texttt{\$RESU/PARTITION\_OUTPUT.\$SUFFIX} directory.
In this case, the number of processors for which partitioning is required
is given by the \texttt{PARTITION\_LIST} variable of the launch script
(multiple partitionings may be done in one run).

\fussy

%==================================
\subsubsection{Interactive modification of the target time step}
%==================================
\label{prg_ficstp}%
During a calculation, it is possible to change the limit time step number
(\texttt{ntmabs}) specified through the Interface or in \texttt{usini1}.
To do so, a file named \texttt{ficstp} must be placed in the temporary
execution directory (see \S\ref{prg_temporarydirectory}).
This file must contain a blank first line and
the second line indicating the value of the new limit number of time steps.\\
If this new limit has already been passed in the calculation, \CS will stop
properly at the end of the current time step (the results and restart files
will be written correctly).\\
This procedure allows the user to stop a calculation in a clean and interactive
way whenever they wish.


%==================================
\subsection{Case preparer}
%==================================
\label{prg_cscreate}%
The case preparer command \texttt{code\_saturne~create} automatically creates a
study directory according to the typical architecture and copies and
pre-fills an example of calculation launch script.

The syntax of \texttt{code\_saturne~create} is as follows:

\noindent
\texttt{code\_saturne~create --study STUDY CASE\_NAME1 CASE\_NAME2...}\\
creates a study directory \texttt{STUDY} with case subdirectories
\texttt{CASE\_NAME1} and \texttt{CASE\_NAME2}...
If no case name is given, a default case directory called \texttt{CASE1} is
created.

\noindent
\texttt{code\_saturne~create --case DEBIT3 --case DEBIT4}\\
executed in the directory \texttt{STUDY} adds the case directories
\texttt{DEBIT3} and \texttt{DEBIT4}.

An option \texttt{--nogui} is available for the use of \CS
without Graphic Interface (see \S\ref{prg_gui}). This option must
be either the first or the last argument and appear only once.

In the directory \texttt{DATA}, the \texttt{code\_saturne~create} command
places a subdirectory \texttt{THCH} containing examples of thermochemical data
files used for pulverised coal combustion,
gas combustion or electric arc. The file to be used for the calculation must be
copied directly in the \texttt{DATA} directory and its name must be referenced
in the launch script in the variable THERMOCHEMISTRY\_DATA. All other files in
the \texttt{DATA} or in the \texttt{THCH} will be ignored.\\
The \texttt{code\_saturne~create} command also places in the directory
\texttt{DATA} the launch script for the Graphical User Interface:
\texttt{SaturneGUI}.


In the directory \texttt{SRC}, the \texttt{code\_saturne~create} command creates a
subdirectory \texttt{REFERENCE} containing all the user subroutines,
classified by module type:  \texttt{base},
\texttt{cfbl}, \texttt{cogz}, \texttt{cplv}, \texttt{elec}, \texttt{fuel},
\texttt{lagr}, \texttt{pprt} and \texttt{rayt}.
Only the user subroutines placed directly under
the directory \texttt{SRC} will be considered. The others will be ignored.

In the directory \texttt{SCRIPTS}, the \texttt{code\_saturne~create} command copies and
pre-fills an example of the launch script: \texttt{runcase}.
The study, case and user name are filled
automatically in the launch script, as are the paths leading to the
different directories. Other parameters must be specified in the script
(see \S\ref{prg_runcase}),
especially the mesh file(s) to use, but everything can be specified
through the Graphical Interface.

\smallskip \noindent

%==================================
\subsection{Supported mesh and post-processing output formats
\label{sec:formats}}
%==================================

\CS supports multiple mesh formats, all of these having been requested
at some time by users or projects based on their meshing or post-processing
tools. All of these formats have advantages and disadvantages (in terms
of simplicity, functionality, longevity, and popularity) when compared to
each other. The following formats are currently supported by \CS:

\begin{list}{-}{}

\item \hyperref[fmtdesc:des]{\simail (NOPO)}
\item \hyperref[fmtdesc:unv]{\ideas universal}
\item \hyperref[fmtdesc:igghexa]{NUMECA IGG/Hexa}
\item \hyperref[fmtdesc:med]{\med}
\item \hyperref[fmtdesc:cgns]{CGNS}
\item \hyperref[fmtdesc:ensight6]{\ensight 6}
\item \hyperref[fmtdesc:ensightg]{\ensightg}
\item \hyperref[fmtdesc:neu]{\gambit neutral}
\item \hyperref[fmtdesc:gmsh]{\gmsh}
\item \hyperref[fmtdesc:ngeom]{pro-STAR/STAR4}
\item \hyperref[fmtdesc:ccm]{STAR-CCM+}
\end{list}

These formats are described in greater detail in the following sections.
Unless a specific option is used, the \pcs determines the mesh format directly
from the file suffix: %
{\em``\texttt{.case}''} for \ensight (6 or Gold),
{\em``\texttt{.ccm}''} for STAR-CCM+,
{\em``\texttt{.cgns}''} for CGNS,
{\em``\texttt{.des}''} for \simail,
{\em``\texttt{.med}''} for \med,
{\em``\texttt{.msh}''} for \gmsh,
{\em``\texttt{.neu}''} for \gambit neutral,
{\em``\texttt{.ngeom}''} for pro-STAR/STAR4,
{\em``\texttt{.unv}''} for I-deas universal.

Note that the preprocessor can read gzipped mesh files directly (for Formats
other than MED or CGNS, which use specific external libraries) on most machines.

%==================================
\subsubsection{Formats supported for input\label{sec:formats_in}}
%==================================

\subsubsubsection{NOPO/\simail (INRIA/SIMULOG)%
\label{fmtdesc:des}}

This format output by \simail is still heavily used at EDF. We do not
currently handle cylindrical or spherical coordinates, but it seems that
\simail always outputs meshes in Cartesian coordinates, even if points
have been defined in another system. Most ``classical'' element types
are usable, except for pyramids.

Note that depending on the architecture on which a file was
produced by \simail,\footnote{``little endian'' on Intel or AMD processors, or
``big endian'' on most others, and starting with \simail 7, 32-bit or 64-bit
 integer and floating-point numbers depending on architecture},
it may not be directly readable by \simail on a different machine, while
this is not a problem for the \pcs, which automatically detects the
byte ordering and the 32/64 bit variant and adjusts accordingly.

\smallskip \noindent
\begin{tabular}[top]{|p{4.5cm}%
                     |>{\PreserveBackslash\raggedright\hspace{0pt}}p{10.5cm}|}
\hline
Default extension: & {\tt .des}\\
\hline
File type:         & semi-portable ``Fortran'' binary (IEEE integer and
                     floating-point numbers on 4 or 8 bytes, depending on
                     32 or 64 bit \simail version, bytes also ordered based
                     on the architecture)\\
\hline
Surface elements:  & triangles, quadrangles
                     (+ volume element face references)\\
\hline
Volume elements:   & tetrahedra, prisms, hexahedra\\
\hline
Zone selection:    & element face references and volume sub-domains\\
                   & (interpreted as numbered colors)\\
\hline
Compatibility:     & all files of this type as long as the coordinate
                     system used is Cartesian and not cylindrical or
                     spherical\\
\hline
Documentation:     & Simail user documentation and release notes or
                     MODULEF documentation:
                     \url{http://www-rocq.inria.fr/modulef} \par
                     Especially: \par
                     \url{http://www-rocq.inria.fr/modulef/Doc/FR/Guide2-14/node49.html} \\
\hline
\end{tabular}

\subsubsubsection{\ideas universal file%
\label{fmtdesc:unv}}

This format was very popular in the 1990's and early 2000's, and though
the I-deas tool has not focused on the CFD (or even meshing) market since
many years, it is handled (at least in part) by many tools, and may
be considered as a major ``legacy'' format. It may contain many different
datasets, relative to CAD, meshing, materials, calculation results,
or part representation. Most of these datasets are ignored by \CS,
and only those relative to vertex, element, group, and coordinate system
definitions are handled.

This format's definition evolves with \ideas versions, albeit in a limited
manner: some datasets are declared obsolete, and are replaced by others,
but the definition of a given dataset type is never modified. Element and
Vertex definitions have not changed for many years, but group definitions
have gone through several dataset variants through the same period,
usually adding minor additional group types not relevant to meshing.
If one were to read a file generated with a more recent version of \ideas
for which this definitions would have changed with no update in the \pcs,
as the new dataset would be unknown, it would simply be ignored.

Note that this is a text format. Most element types are handled, except
for pyramids.

\smallskip \noindent
\begin{tabular}[top]{|p{4.5cm}%
                     |>{\PreserveBackslash\raggedright\hspace{0pt}}p{10.5cm}|}
\hline
Default extension: & {\tt .unv}\\
\hline
File type:         & text\\
\hline
Surface elements:  & triangles, quadrangles\\
\hline
Volume elements:   & tetrahedra, prisms, hexahedra\\
\hline
Zone selection:    & colors (systematic) and named groups\\
\hline
Compatibility:     & \ideas (\emph{Master Series} 5 to 9, \emph{NX Series} 10 to 12)
                     at least\\
\hline
Documentation:     & Online I-deas NX Series documentation\\
\hline
\end{tabular}

\subsubsubsection{\gambit neutral%
\label{fmtdesc:neu}}

This format may be produced by Ansys \fluent's GAMBIT meshing tool.
As this tool does not export meshes to other formats directly handled
by the \pcs (though \fluent itself may export files to the CGNS or
\ideas universal formats), it was deemed useful to enable the \pcs
to directly read files in \gambit neutral format.

Note that this is a text format. ``Classical'' element types are usable.

\smallskip \noindent
\begin{tabular}[top]{|p{4.5cm}%
                     |>{\PreserveBackslash\raggedright\hspace{0pt}}p{10.5cm}|}
\hline
Default extension: & {\tt .neu}\\
\hline
File type:         & text\\
\hline
Surface elements:  & triangles, quadrangles\\
\hline
Volume elements:   & tetrahedra, pyramids, prisms, hexahedra\\
\hline
Zone selection:    & boundary conditions for faces, element groups for cells\\
                   & (interpreted as named groups)\\
\hline
Documentation:     & GAMBIT on-line documentation\\
\hline
\end{tabular}

\subsubsubsection{pro-STAR%
\label{fmtdesc:ngeom}}

This polyhedral format from CD-Adapco seems to be usable both with the
\starcd and \starccmp tools, and the \textbf{pro-STAR} tool should be able to
generate it. The test meshes we have were generated by the
\textbf{Comet-Design} tool, which has since been replaced by other
CD-Adapco tools, especially \starcd V4 and \starccmp. The available
test cases are thus not extensive in terms of functionality (especially
when considering definition of descriptions), so support for this format
is lightly tested.

Currently, geometric entity numbers are converted to ``color'' numbers.
This tends to lead to a large number of colors.

\smallskip \noindent
\begin{tabular}[top]{|p{4.5cm}%
                     |>{\PreserveBackslash\raggedright\hspace{0pt}}p{10.5cm}|}
\hline
Default extension: & {\tt .ngeom}\\
\hline
File type:         & binary file using portable XDR encoding.\\
\hline
Surface elements:  & polygons\\
\hline
Volume elements:   & polyhedra\\
\hline
Zone selection:    & face and cell sets\\
                   & (interpreted as numbered colors)\\
\hline
Compatibility:     & all files of this type ? (tested on purely polyhedral meshes)\\
\hline
Documentation:     & documentation accompanying and source code provided by CD-adapco in
                     the context of a collaboration with UMIST (now
                     University of Manchester) and EDF R\&D/MFEE\\
\hline
\end{tabular}

\subsubsubsection{\starccmp%
\label{fmtdesc:ccm}}

This polyhedral format is the current CD-Adapco format, and is based on
CD-Adapco's libccmio, which is based on ADF (the low-level file format
used by CGNS prior to the shift to HDF-5). libccmio comes with a version
of ADF modified for performance, but also works with a standard version
from CGNS.

Currently, geometric entity numbers are converted to ``color'' numbers,
with the corresponding names printed to the \pcs log. Depending on whether
the names were generated automatically or set by the user, it would be
preferable to interpret such sets as named ``groups'' rather than numbered
``colors''.

The CCMIO library is distributed freely by CD-Adapco upon demand.

\smallskip \noindent
\begin{tabular}[top]{|p{4.5cm}%
                     |>{\PreserveBackslash\raggedright\hspace{0pt}}p{10.5cm}|}
\hline
Default extension: & {\tt .ccm}\\
\hline
File type:         & binary file using modified ADF library.\\
\hline
Surface elements:  & polygons\\
\hline
Volume elements:   & polyhedra\\
\hline
Zone selection:    & named face and cell sets\\
                   & (interpreted as numbered colors, with names appearing in log)\\
\hline
Compatibility:     & all files of this type ? (tested on purely polyhedral meshes)\\
\hline
Documentation:     & documentation and source code provided by CD-adapco\\
\hline
\end{tabular}

\subsubsubsection{\ensight 6%
\label{fmtdesc:ensight6}}

This format is used for output by the \harpoon meshing tool, developed
by Sharc Ltd (also the distributor of \ensight for the United Kingdom).
This format may represent all ``classical'' element types.

Designed for post processing, it does not explicitely handle the definition
of surface patches or volume zones, but allows the use of many \emph{parts}
(i.e. groups of elements) which use a common vertex list.
A possible convention (used at least by \harpoon) is to add surface
elements to the volume mesh, using one \emph{part} per group. The volume
mesh may also be separated into several \emph{parts} so as to identify
different zones. As \emph{part} names may contain up to 80 characters,
we do not transform them into groups (whose names could be unwieldy),
so we simply interpret their number as a color.

Also note that files produced by \harpoon may contain badly oriented
prisms, so the \pcs orientation correction option
(\texttt{--reorient})may need to be used. Meshes built by this tool also
contain hanging nodes, with non-conforming elements sharing some vertices.
The \texttt{--join --semi-conf} preprocessor option must thus be used.
This option is not set automatically, as the user may prefer to specify
which surfaces should be joined, and which ones should not (i.e. to
conserve thin walls).

\smallskip \noindent
\begin{tabular}[top]{|p{4.5cm}%
                     |>{\PreserveBackslash\raggedright\hspace{0pt}}p{10.5cm}|}
\hline
Default extension: & {\tt .case}\\
\hline
File type:         & text file (extension \emph{.case}), and text,
                     binary, or Fortran binary file with 
                     (\emph{.geo} extension), describing the  integers
                     describing integers and floats in the IEEE format,
                     using 32 bits\\
\hline
Surface elements:  & triangles, quadrangles\\
\hline
Volume elements:   & tetrahedra, pyramids, prisms, hexahedra\\
\hline
Zone selection:    & part numbers interpreted as color numbers\\
\hline
Compatibility:     & All files of this type\\
\hline
Documentation:     & online documentation, also available at:
                     \url{http://www.ensight.com/Downloads/}\\
\hline
\end{tabular}

\subsubsubsection{\gmsh%
\label{fmtdesc:gmsh}}

This format is used by the free \href{http://www.geuz.org/gmsh}{\gmsh}
tool. This tool has both meshing and post-processing functionality,
but \CS only imports meshes.

Note that some meshes produced by\gmsh man contain some badly oriented
elements, so the \pcs's \texttt{-reorient} option may be necessary.

The \pcs handles versions 1 and 2 of this array. In version 1,
two labels are associated with each element: the first defines the
element's physical entity  number, the second defines it' elementary
entity number. Using version 2, it is possible to associate an
arbitrary number of labels with each element, but files produced
by \gmsh use 2 labels, with the same meanings as with version 1.

We chose to convert physical entity numbers to colors. It is possible
to build a mesh using \gmsh without defining any  physical entities
(in which case all elements will have the same color, but the \gmsh
documentation clearly says that geometric entities are to be used
so as to group elementary entities having similar ``physical'' meanings.

So as to obtain distinct colors with a mesh generated by \gmsh, it
is thus necessary for the user to define physical entities.
This requires an extra step, but allows for fine-grained control
over the colors associated with the mesh, while using only elementary
entities could lead to a high number of colors.

\smallskip \noindent
\begin{tabular}[top]{|p{4.5cm}%
                     |>{\PreserveBackslash\raggedright\hspace{0pt}}p{10.5cm}|}
\hline
Default extension: & {\tt .msh}\\
\hline
File type:         & text or binary file\\
\hline
Surface elements:  & triangles, quadrangles\\
\hline
Volume elements:   & tetrahedra, pyramids, prisms, hexahedra\\
\hline
Zone selection:    & physical entity numbers interpreted as color numbers\\
\hline
Compatibility:     & all files of this type\\
\hline
Documentation:     & included documentation, also available at:
                     \href{http://www.geuz.org/gmsh}
                          {http://www.geuz.org/gmsh}\\
\hline
\end{tabular}

\subsubsubsection{IGG/Hexa (NUMECA)%
\label{fmtdesc:igghexa}}

This format is quite peculiar in the sense that it defines a hierarchical mesh
built exclusively of hexahedra, of quadrangular faces, and of edges, in which
edges may be split in 2, faces in 2 or 4, and cells in 2, 4, or 8. Two
neighboring elements are thus not always conforming. The \pcs only keeps the
finest mesh level, and uses the hierarchical information so as to
automatically build the appropriate conformal joining. CAD face
information is transformed into color numbers.

\noindent
\parbox[t]{.15\linewidth}{{\bf Remark}:}
\parbox[t]{.85\linewidth}{
  The reader is based on the IGG/Hexa format as it was defined at the end of
  2001. Since that time, the mesher seems to have been renamed $HEXPRESS^{TM}$, and
  we do not have any recent documentation or test file. For this reason,
  support for this format is not directly included in the main \pcs executable,
  but requires conversion using the \texttt{igghexa\_to\_med} tool.
}

\smallskip \noindent
\begin{tabular}[top]{|p{4.5cm}%
                     |>{\PreserveBackslash\raggedright\hspace{0pt}}p{10.5cm}|}
\hline
Default extension: & {\tt .hex}\\
\hline
File type:         & portable binary by default
                     (4-byte integers, 8-byte IEEE double-precision reals,
                     big-endian), or text\\
\hline
Surface elements:  & quadrangles\\
\hline
Volume elements:   & hexahedra\\
\hline
Zone selection:    & no volume selection, CAD surface numbers interpreted as
                     colors\\
\hline
Compatibility:     & unknown (at least files from late 2001 are readable)\\
\hline
Documentation:     & elements provided by NUMECA (\href{http://www.numeca.be}
                                                       {http://www.numeca.be})
                     in 2001.\\
\hline
\end{tabular}

%==================================
\subsubsection{Formats supported for input or output\label{cha:formats_inout}}
%==================================

\subsubsubsection{\ensightg%
\label{fmtdesc:ensightg}}

This format may represent all ``classical'' element types, as well as
arbitrary polygons and convex polyhedra.

This format evolves slightly from one \ensight version to another, keeping
backwards compatibility. For example, polygons could not be used in the
same \emph{part} as other element types prior to version 7.4, which removed
this restriction and added support for polyhedra. Version 7.6 added support
for material type definitions.

This format offers many possibilities not used by \CS, such as defining
values on part of a mesh only (using ``undefined'' marker values or
partial values), assigning materials to elements, defining rigid
motion, or defining per-processor mesh parts with ghost cells for
parallel runs. Note that some libraries allowing direct \ensightg support
do not necessarily support the whole format specification.
Especially, VTK does not support material types, and has only recently
added support for polyhedral elements in \ensightg files (interpreted
as convex point sets, and not true polyhedra, but at least usable).
Also, both \ensightg (8.2 and above) and VTK allow for automatic distribution,
reducing the usefulness of pre-distributed meshes with per-processor files.

This format may be used as an input format, similar to \ensight 6.
Compared to the latter, each \emph{part} has its own coordinates and vertex
connectivity, so as a convention, we consider that surface or
volume zones may only be considered to be part of the same mesh
if the file defines vertex IDs (which we consider to be
unique vertex labels). In this case, \emph{part} numbers
are interpreted as colors. Without vertex IDs, only one part is read,
and no colors are assigned.

\smallskip \noindent
\begin{tabular}[top]{|p{4.5cm}%
                     |>{\PreserveBackslash\raggedright\hspace{0pt}}p{10.5cm}|}
\hline
Default extension: & {directory {\tt{{\it \{case\_name\}}.ensight}},
                     containing a file with the \tt .case} extension\\
\hline
File type:         & multiple binary or text files\\
\hline
Surface elements:  & triangles, quadrangles, polygons\\
\hline
Volume elements:   & tetrahedra, pyramids, prisms, hexahedra, convex polyhedra\\
\hline
Zone selection:    & possibility of defining element materials (not used), or
                     interpret part number as color number if vertex IDs are
                     given\\
\hline
Compatibility:     & files readable by \ensight 7.4 to 9.0, as well as tools
                     based on the \href{http://www.vtk.org}{\vtk} library,
                     especially \paraview\ (\url{http://www.paraview.org})\\
\hline
Documentation:     & online documentation, also available at:
                     \url{http://www.ensight.com/Downloads/}\\
\hline
\end{tabular}

\subsubsubsection{\med 2.3 or \med 3.0}\hyperdef{sec}{med}{}
\label{fmtdesc:med}

Initially defined by EDF R\&D, this format (\emph{Modèle d'échanges de Données},
or \emph{Model for Exchange of Data}) has been defined and maintained through
a \med working group comprising members of EDF R\&D and CEA (the \CS team
being represented). This is the reference format for the
\href{http://www.opencascade.org/SALOME/Salome.html}{\emph SALOME} environment.
This format is quite complete, allowing the definition of all ``classical''
element types, in nodal or descending connectivity. Since \med 2.2 in 2003,
this format may handle polygonal faces and polyhedral cells,
as well as the definition of structured meshes.

This format, which requires a library also depending on the free HDF5 library,
allows both for reading and writing meshes with their attributes (``families'' of
color/attribute and group combinations), as well as handling calculation data,
with the possibility (unused by \CS) of defining variables only on a subset
(``profile'') of a mesh.

The \med library is available under a \href{http://www.gnu.org}{LGPL} licence,
and is even packaged in some Linux distributions
(at least Debian and Ubuntu). Versions 2.3.5 and older require HDF5 1.6,
version 2.3.6 may compile with either HDF5 1.6 or HDF5 1.8 (if the latter
has HDF5 1.6 compatibility enabled).

\smallskip \noindent
\begin{tabular}[top]{|p{4.5cm}%
                     |>{\PreserveBackslash\raggedright\hspace{0pt}}p{10.5cm}|}
\hline
Default extension: & {\tt .med}\\
\hline
File type:         & portable binary, based on the HDF5 library
                     (\url{http://www.hdfgroup.org/HDF5/index.html})\\
\hline
Surface elements:  & triangles, quadrangles, simple polygons\\
\hline
Volume elements:   & tetrahedra, pyramids, prisms, hexahedra, simple polyhedra\\
\hline
Zone selection:    & element families ({\it i.e.} colors and groups)\\
\hline
Compatibility:     & \med 2.3.5, \med 2.3.6, or \med 3.0.2 and above (only unstructured
                     nodal connectivity is supported)\\
\hline
Documentation:     & online documentation. Download link at \url{http://files.salome-platform.org/Salome/other/med-3.0.3.tar.gz}\\
\hline
\end{tabular}

\subsubsubsection{CGNS 2.5 or CGNS 3.1}\hyperdef{sec}{cgns}{}
\label{fmtdesc:cgns}

Promoted especially by NASA, Boeing, and ICEM~CFD (as well as ONERA in France),
this format(\emph{CFD General Notation System}) is quite well established in
the world of CFD. The concept is similar to that of \med, with a bigger
emphasis on normalization of variable names or calculation information, and
even richer possibilities. The opposite of \med, the first version of this format
was limited to multibloc structured meshes, unstructured meshes having been
added in CGNS 2.

Slightly older than \med, this library was free from the start, with a good
English documentation, and is thus much better known. It is more focused
on CFD, where \med is more generic. A certain number of tools accompany
the CGNS distribution, including a mesh visualizer (which does not handle
polygonale faces although the format defines them), and an interpolation
tool.

We should be able to read almost any mesh written in this format, though
meshes with overset interfaces may not be usable for a calculation.
Other (abutting) interfaces are not handled automatically (as there are
at least 3 or 4 ways of defining them, and some mesh tools do not export
them\footnote{For example, \icemcfd can join non-conforming meshes, but it
exports joining surfaces as simple boundary faces with user-defined boundary
conditions.}), so the user is simply informed of their existence in the
\pcs's log file, with a suggestion to use an appropriate conformal joining
option. Structured zones are converted to unstructured zones immediately after
being read.

Boundary condition information is interpreted as groups with the same
name. The format does not yet provide for selection of volume elements,
as only boundary conditions defined in the model (and can be assigned to
faces in the case of unstructured meshes, or vertices in any case).
Note that boundary conditions defined at vertices are not ignored by
the \pcs, but are assigned to the faces of which all vertices bear
the same condition.\footnote{If one of a face's vertices does not bear
a boundary condition, that condition is not transferred to the face.}

The \pcs also has the capability of building additional volume or surface groups,
based on the mesh sections to which cells or faces belong. This may be
activated using a sub-option of the mesh selection, and allows obtaining
zone selection information from meshes that do not have explicit
boundary condition information but that are subdivided in appropriate zones or
sections (which depends on the tool used to build the mesh).

When outputting to CGNS, an unstructured connectivity is used for the calculation
domain, with no face joining information or face boundary condition
information.\footnote{Older versions of the documentation specified that
a field must be defined on all elements of a zone, so that adding faces
on which to base boundary conditions to a volume mesh would have required
also defining volume fields on these faces. More recent versions of the
documentation make it clear that a field must be defined on all elements
of maximum dimension in a zone, not on all elements.} 

Though many tools support CGNS, that support is often quite dissapointing,
at least for unstructured meshes. Thus, some editors seem to use
different means to mark zones to associate with boundary conditions than
the ones recommended in the CGNS documentation, and some behaviors
are worse: for example, under \ensightg 8, whenever a mesh
contains multiple element types, variables are assigned to the wrong cells.
Regarding support of polygons (\emph{ngons} in the CGNS standard), even the
verification tools published alongside the CGNS library are unable
to handle them, and report errors in valid files containing such elements.
VisIt 1.11.1 reports an error when a mesh contains such faces, while
\ensightg 8 ignores them. CGNS 3 allows for polyhedra, but as this is a
recent developpement, it is not supported yet by \CS.

\smallskip \noindent
\begin{tabular}[top]{|p{4.5cm}%
                     |>{\PreserveBackslash\raggedright\hspace{0pt}}p{10.5cm}|}
\hline
Default extension: & {\tt .cgns}\\
\hline
File type:         & portable binary (uses the ADF library specific to CGNS, or HDF5)\\
\hline
Surface elements:  & triangles, quadrangles, simple polygons\\
\hline
Volume elements:   & tetrahedra, pyramids, prisms, hexahedra\\
\hline
Zone selection:    & Surface zone selection using boundary conditions, no volume zone
                     selection, but the \pcs allows creation of groups associated to
                     zones or sections in the mesh using mesh selection sub-options\\
\hline
Compatibility:     & CGNS 2.5 or 3.1 on output\\
\hline
Documentation:     & See CGNS site: \url{http://www.cgns.org}\\
\hline
\end{tabular}

%==================================
\subsubsection{Mesh meta-files}
%==================================

The \pcs allows use of text files (preferably with a {\tt .mesh} extension)
describing a set of meshes and their transformations, in place of (or
combined with) ``true'' mesh files. These meta-files are
described here:

Empty lines are ignored, and the \# character may be used to define
comments (the part of a line following this character is ignored).

One may request the reading of as many meshes as one needs, using
for each mesh a section such as:

\noindent
\verb+read_mesh:+ {\it filename}

or:

\noindent
\verb+read_mesh:+ {\it filename} {\tt <sub-options>}

If this section type appears more than once, the corresponding meshes
are automatically appended. If needed, a mesh meta-file may itself
declare another meta-file as a mesh file.
Possible sub-options associated with a file may be separated by commas,
semicolumns, or spaces, and are of the following form:

\noindent
\begin{tabular}[top]{ p{2.5cm}%
                     >{\PreserveBackslash\raggedright\hspace{0pt}}p{12.5cm} }
{\tt format=}   & {format name (identical to command-line options)}\\
{\tt num=}      & {mesh number (useful when a file contains multiple meshes)}\\
{\tt grp\_cel=} & {{\tt <section} or {\tt zone>}, useful only for files in
                    CGNS format}\\
{\tt grp\_fac=} & {{\tt <section} or {\tt zone>}, useful only for files in
                    CGNS format}\\
\end{tabular}

\smallskip
It is also possible to define a geometric transformation to apply to a mesh,
using a homogeneous coordinates transformation matrix (3 lines, 4 columns,
with the 3 first columns describing a rotation/scaling factor,
and the last column describing a translation. The corresponding section
is as follows (values may be spread over several lines):

\noindent
\verb+transformation_matrix:+ $t_{11}$ $t_{12}$ $t_{13}$ $t_{14}$
$t_{21}$ $t_{22}$ $t_{23}$ $t_{24}$ $t_{31}$ $t_{32}$ $t_{33}$ $t_{34}$\\

Note that the order in which multiple meshes are declared defines the
order in which they are read and appended, but the geometric transformation
is only applied at the end (this is a description file, not a command file).
If multiple transformations are needed, a hierarchy of mesh meta-files
may be used.

%==================================
\subsubsection{Meshing tools and associated formats}
%==================================

Most often, the choice of a mesh format is linked to the choice of
a meshing tool. Still, some tools allow exporting a mesh under several
formats handled by \CS. This is the case of \fluent and \icemcfd,
which can export meshes to both the \ideas universal and CGNS formats
(\fluent's \gambit is also able to export to \ideas universal format).

Traditionally, users exported files to the \ideas universal format,
but it does not handle pyramid elements, which are often used by these
tools to transition from hexahedral to tetrahedral cells in the case
of hybrid meshes. The user is encouraged to export to CGNS, which
does not have this limitation.

Tools related to the \salome platform should preferably use
\salome{}'s native \med format (export to \ideas universal is
also possible, but has some limitations).

The use of files of the ``Common Solver'' type\footnote{File type specifically
developed for the early prototype versions of \CS (\texttt{tlc}) extension}
is still possible but is deprecated. Such files are read directly from the
Kernel, without the \pcs.
The variable SOLCOM must
 be set to 1 in the launch scripts. Many potentialities of \CS are not
usable with this file format (mesh joining with hanging nodes, periodicity,
parallel computing, ...).
For all the other formats, the \pcs must be used (SOLCOM=0).

%==================================
\subsubsection{Meshing remarks}
%==================================
\label{prg_maillages}%

{\em WARNING: }
Some turbulence models ($k-\varepsilon$, $R_{ij}-\varepsilon$ SSG, ...) used in
\CS are ``High-Reynolds'' models. Therefore the size of the cells
neighboring the wall needs to be greater than the thickness of the viscous
sublayer (at the wall, $y^+>2.5$ is required, and $30<y^+<100$ is
preferable). If the mesh does not match this constraint, the results may
be false (particularly if thermal phenomena are involved). For more details
on these constraints, see the keyword \texttt{ITURB}.

%==================================
\subsection{Preprocessor command line options}
%==================================
\label{prg_optappelecs}%
The main options are:
\begin{list}{$\bullet$}{}
\item \texttt{--help}: gives a summary of the different command line options

\item \texttt{-m mesh1 mesh2}: used to specify the names of the different meshes
used. The launch script automatically calls the Preprocessor with the option
\texttt{-m \$MESH}, where \texttt{MESH} is the variable where the user has
specified the different meshes to be used.

\item \texttt{--join}: triggers the mesh joining functions. If nothing more is
specified, every area of contact between two meshes will be joined together. The
joining can be limited to certain selected faces. For instance, to join only
the faces of colors 6 and 7, the full option will be \mbox{\texttt{--join --color
6 7}}. These options are to be specified in the \texttt{COMMAND\_JOIN} variable in
the launch script, to be automatically passed to the command line.

\item \texttt{--perio}: triggers periodic boundary conditions. Two types of
periodic boundaries are possible: translation or rotation (see
\S\ref{prg_paralperio} for additional details). For the translation, the basic
option line is \texttt{--perio --trans tx ty tz}\\
where \texttt{tx}, \texttt{ty} and \texttt{tz} are the coordinates of the
translation vector. For the rotation, there are two possibilities. The
transformation can be defined with a rotation angle (in degrees, between -180
and 180), a direction  and an
invariant point\\
\texttt{--perio --rota --angle a --dir dx dy dz --invpt px py pz}\\
(with obvious notations), or by giving the rotation matrix and an invariant point\\
\texttt{--perio --rota --matrix m11 m12 m13 m21 m22 m23 m31 m32 m33 --invpt px py
pz}\\
A rotation and a translation can be combined, by giving both \texttt{--rota} and
\texttt{--trans} specifications. The translation will always be applied first,
whatever the order in which the rotation and the translation have been given.\\
The orientation of the transformations is not important since both the
transformation and its inverse will be used to connect faces. Yet, when
combining a translation and a rotation, the orientations given for both have to
be consistent.\\
It is possible (and usually recommended) to restrict the  search for periodic
connections between faces to a certain group of faces, by adding selection
arguments like \texttt{--color}. It is also possible to specify up to 3
independent periodicities, simply by repeating the \texttt{--perio} option. Below
is given a example of the option line for a triple periodicity (the \verb+\+
indicates the continuation of the command line):\\
\texttt{--perio --trans -10.2 0 0 --color 2} \verb+\+\\
\texttt{--perio --rota --angle 90 --dir 0 0 1 --invpt 0 0 0 --color 3 4} \verb+\+\\
\texttt{--perio --trans 0 1 0 --rota --matrix 1 0  0 0 0 -1 0 1 0 --invpt 0 0 -0.2}\\
This option is to be specified in the \texttt{COMMAND\_PERIO} variable in
the launch script, to be automatically passed to the command line.

\item \texttt{--reorient}: try to re-orient badly-oriented cells
if it is necessary to compensate for mesh-generation software
whose output does not conform to the format specifications.

\end{list}

%==================================
\subsection{Kernel command line options}
%==================================
\label{prg_optappelnoy}%
In the standard cases, the compilation of \CS and its execution are entirely
controlled by the launch script. The potential command line options are passed
through user modifiable variables at the beginning of the script. This way, the
user only has to fill these variables and doesn't need
to search deep in the script for the Kernel command line. Yet, below is given
the complete list of options, with the variables in which they should be
specified in the script.

\begin{list}{$\bullet$}{}
\item \texttt{--solcom}: this option indicates that the Kernel will read the
mesh directly, not using the Preprocessor output files. This is only possible
with ``Common Solver'' type of mesh files (see \S\ref{prg_maillages} for
restrictions).\\
This option is triggered by the \texttt{SOLCOM} variable in the launch
script. If \texttt{SOLCOM} is set to 1, the \texttt{-solcom} option is
automatically added to the Kernel command line. The variable
\texttt{ifoenv\index{ifoenv}} in the Fortran code will be set to 0 if the
\texttt{--solcom} option has been used, otherwise it will be set to 1.

\item \texttt{--mpi}: specifies that the calculation is running
with MPI communications. The number of processors used will be determined
automatically by the Kernel. If necessary, the launch script automatically
passes the \texttt{--mpi} option to the Kernel command line
(see \ref{prg_runcase}).

\item \texttt{-q} or \texttt{--quality}: triggers the verification mode.
The code runs without any Interface parameter file nor any user subroutine.
The mesh is read and elementary tests are performed:\\
\begin{list}{-}{}
\item the quality criteria of the mesh are calculated (non-orthogonality angles,
internal faces off-set, \ldots) and corresponding EnSight
post-processing parts are created.\\
\item test calculation of the gradient of $sin(x+2y+3z)$. The calculated
value is compared to the exact value, and an EnSight part for the
corresponding error is created. The gradient is calculated with each
option IMRGRA from $0$ to $4$.\\
\end{list}
The command \texttt{-q} is to be placed in the \texttt{ARG\_CS\_VERIF}
variable in the launch script to be added automatically to the Kernel
command line.\\

\item \texttt{--cwf}: triggers the cutting of boundary and internal faces which
have a warp angle larger than a certain limit\footnote{the warp angle is an
indicator of the non-coplanarity of the different vertices of the face}. The
concerned faces are divided into triangles. This option is to handle with care,
since the division of the faces increases the non-orthogonalities of the mesh,
but it is sometimes required (for the Lagrangian modeling, for instance, where
non-plane faces lead to noticeable particle loss). By default, the faces are
divided if their warp angle is larger than 0.01 degrees. This default value can
be changed by adding an optional angle value to the command. For instance, to
devide faces with a warp angle larger than 0.02 degrees, the full option will
be \mbox{\texttt{-cwf 0.02}}.\\
This option is to be specified in the \texttt{COMMAND\_CWF} variable in
the launch script, to be automatically passed to the command line.

\item \texttt{--benchmark}: triggers the benchmark mode, for a timing
of elementary operations on the machine. A secondary option
\texttt{--mpitrace} can be added. It is to be activated when the benchmark mode
is used in association with a MPI trace utility. It restricts the elementary
operations to those implying MPI communications and does only one of each
elementary operation, to avoid overfilling the MPI trace report.\\
This command is to be placed in the \texttt{ARG\_CS\_VERIF} variable
in the launch script to be added automatically to the Kernel command line.

\item \texttt{--log n}: specifies the destination of the output for a
single-processor calculation or for the processor of rank 0 in a parallel
calculation.\\
\hspace*{0.5cm}\texttt{n=0}: output directed towards the standard output\\
\hspace*{0.5cm}\texttt{n=1}: output redirected towards a file \texttt{listing}
(default behaviour)\\
This option can be specified in the \texttt{ARG\_CS\_OUTPUT} variable of the
launch script.

\item \texttt{--logp n}: specifies the destination of the output for the
processors of rank 1 to $N-1$ in a calculation in parallel on $N$ processors
({\em i.e.} the redirection of all but the first processor).\\
\hspace*{0.5cm}\texttt{n=-1}: no output for the processors of rank 1 to $N-1$
(default behaviour).\\
\hspace*{0.5cm}\texttt{n=0}: no redirection. Every processor will write to the
standard output. This might be useful in case a debugger is used, with separate
terminals for each processor.\\
\hspace*{0.5cm}\texttt{n=1}: one file for the output of each processor. The
output of the processors of rank 1 to $N-1$ are directed to the files
\texttt{listing\_n0002} to \texttt{listing\_n$N$}.
This option can be specified in the \texttt{ARG\_CS\_OUTPUT} variable of the
launch script.

\item \texttt{-p xxx} or \texttt{--param xxx}: specifies the name of the GUI
parameter file to use for the calculation.\\
The value of \texttt{xxx} is to be placed in the \texttt{PARAM} variable in the launch
script (the file will be looked for in the directory \texttt{DATA}).
The option \mbox{\texttt{-param \$PARAM}} is automatically added to the
Kernel command line.

\item \texttt{-h} or \texttt{--help}: to display a summary of the different
command line options.
\end{list}

%==================================
\subsection{Parameters in the launch script}
%==================================
\label{prg_runcase}%

The case preparer command \texttt{code\_saturne~create} places an example of launch script,
\texttt{runcase}, in the \texttt{SCRIPTS} directory. This script is quite general
and known to work on every architecture \CS has been tested on. The beginning
if the script contains the definition of certain parameters (environment
variables) necessary to set the calculation. The second part of the script
contains the commands for the preparation and execution of the calculation. No
user intervention should be necessary in this second part.\\
The Graphical User Interface allows to fill in the major
parameters of the script without having to edit the file.

Below is a list of the different variables and parameters that might be modified
for a calculation, in their order of apparition in the script:
\begin{list}{$\bullet$}{}
\item LSF headers: definition of the headers for an LSF batch system, as can be
found on the machines of the CCRT (Platine). The data expected are
the number of processors reserved (\texttt{\#BSUB -n}), the CPU time limit
(\texttt{\#BSUB -W}), the name of the standard output file (\texttt{\#BSUB -o}),
the name of the standard error file (\texttt{\#BSUB -e}) and the name of
the job (\texttt{\#BSUB -J}).

\item PBS headers: definition of the headers for a PBS batch system, as can be
found on the machines of the Chatou cluster. The data expected are the number of
nodes reserved (\texttt{nodes}), the number of processors per node
(\texttt{ppn}), the total CPU time (\texttt{walltime}), the memory reserved
(\texttt{mem}), and the name of the job (\texttt{\#PBS -N}).

\item Manchester headers: definition of the headers for the batch system
specific to the cluster of the University of Manchester

\item \texttt{SOLCOM}: a value of 1 will pass the \texttt{-solcom} option to the
Kernel (see \ref{prg_optappelnoy})
\end{list}

\begin{list}{$\bullet$}{}
\item \texttt{STUDY}: name of the study directory (automatically set by
\texttt{code\_saturne~create}, see \S\ref{prg_architecture})

\item \texttt{CASE}: name of the case directory (automatically set by
\texttt{code\_saturne~create}, see \S\ref{prg_architecture})

\item \texttt{PARAM}: name of the Interface parameter file, if necessary (see
\ref{prg_optappelnoy})

\item \texttt{MESH}: name(s) of the mesh(es) used for the calculation (see
\ref{prg_optappelecs} and \ref{prg_maillages}). The files will be looked for in
the directory \texttt{MESHDIR} (see below).

\item \texttt{COMMAND\_JOIN}: Preprocessor command line option for mesh joining (see
\ref{prg_optappelecs})

\item \texttt{COMMAND\_CWF}: Kernel command line option for the division of
faces with too large a warp angle (see \ref{prg_optappelnoy})

\item \texttt{COMMAND\_PERIO}: Preprocessor command line option for the definition
of periodic boundary conditions (see \ref{prg_optappelecs})

\item \texttt{THERMOCHEMISTRY\_DATA}: name of the thermochemical data file, if
necessary (the file is looked for in the directory \texttt{DATA}, see
\S\ref{prg_usppmo})

\item \texttt{NUMBER\_OF\_PROCESSORS}: number of processors (potentially virtual)
to be used for the calculation.\\
If the variable is left empty, the launch script
will fill it automatically: on a batch system, \texttt{NUMBER\_OF\_PROCESSORS}
will be equal to the number of processors reserved; in case of an
interactive calculation, it will be set to 1.\\
When using a batch system,
\texttt{NUMBER\_OF\_PROCESSORS} should ideally be equal to the number of
processors reserved, and can never be larger (one executable per
processor). With an interactive calculation (like a Linux PC),
\texttt{NUMBER\_OF\_PROCESSORS} can be larger than the total number of processors
available, although it is not recommended (loss of efficiency because several
executables share the same processor).\\
In case of
coupling with \syrthes, one processor is reserved for \syrthes, and the Kernel
of \CS will therefore automatically be set to run on
\texttt{NUMBER\_OF\_PROCESSORS-1} processors.

\item \texttt{PROCESSOR\_LIST}: list of nodes on which the calculation is to
be run. On batch systems, this list is set automatically by the batch
manager. For calculations on a stand-alone machine, the list is not used. Hence,
except for very specific test (mainly for developing purposes), it is
recommended to leave this variable empty.

\item \texttt{USER\_INPUT\_FILES}: list of the user data files to be
copied in the temporary execution directory before the calculation (input
profiles for instance). The files will
be looked for in the directory \texttt{DATA}. The thermochemical data files,
Interface parameter file and calculation restart files are specified in other
variables and do not need to appear here. When using the vortex method for LES
entry conditions, the corresponding data files have to be specified in
\texttt{USER\_INPUT\_FILES} (see \S\ref{prg_usvort})

\item \texttt{USER\_OUTPUT\_FILES}: list of user result files to be
copied in the directory \texttt{RESU} at the end of the calculation. A directory
\texttt{RES\_USERS.mmddhhmm} will be created in the directory \texttt{RESU} and
all the files will be stored in it. The files automatically created by the code
(listings, post-processing, automatic chronological records\footnote{when using
\texttt{ushist} for user-defined chronological records, the files created need
to be specified in \texttt{USER\_OUTPUT\_FILES}},
restart files) do not need to be specified in
\texttt{USER\_OUTPUT\_FILES}.

\item \texttt{CS\_TMP\_PREFIX}: alternate temporary directory for the
calculation (see \S\ref{prg_temporarydirectory})

\item \texttt{OPTIMIZATION}: optimisation level for compilation
 (LO, DBG, EF or PROF; see \S\ref{prg_library}). This optimisation
level will be applied to all the modules of \CS (BASE, CFBL, COGZ, CPLV, ELEC,
FUEL, LAGR, MATI, RAYT).
Leaving the variable empty stands for ``standard''
optimisation.

\item \texttt{CS\_LIB\_ADD}: additional commands for the link stage of the
compilation. This can be especially useful if the user subroutines call routines
provided by external libraries. To link with an external library ``foo'', the
variable would be for instance\\
\texttt{CS\_LIB\_ADD=``-L/opt/foo/lib -lfoo''}

\item \texttt{VALGRIND}: command to be placed before the \CS executable name on
the execution command line ({\em i.e.} the launch script will execute the
command \texttt{\$VALGRIND cs\_solver ...}). It is especially designed to use the
valgrind debugging and profiling tool. The usual value to use valgrind is
\texttt{VALGRIND=``valgrind --tool=memcheck''}

\item \texttt{ARG\_CS\_VERIF}: verification mode to be used for \CS (see
\ref{prg_optappelnoy}). An empty variable implies standard calculation mode
(IVERIF=0).

\item \texttt{ARG\_CS\_OUTPUT}: options for the redirection of the standard
output (see \ref{prg_optappelnoy})

\item \texttt{ECHOCOMM}: level for the \texttt{--echo-comm} option of the Kernel
command line (see \ref{prg_optappelnoy})

\item \texttt{ADAPTATION}: commands to trigger the automatic mesh
adaptation with the software Homard. This option is still under development and
restricted to developpers use.

\item \texttt{CASEDIR}: root directory of the calculation. This variable is
automatically set by \texttt{code\_saturne~create} and should not be changed.

\item \texttt{DATA}: DATA directory of the case (see \ref{prg_architecture}).
This variable is automatically set by \texttt{code\_saturne~create} and should not be
changed.

\item \texttt{RESU}: RESU directory of the case (see \ref{prg_architecture}).
This variable is automatically set by \texttt{code\_saturne~create} and should not be
changed.

\item \texttt{SRC}: SRC directory of the case (see \ref{prg_architecture}).
This variable is automatically set by \texttt{code\_saturne~create} and should not be
changed.

\item \texttt{SCRIPTS}: SCRIPTS directory of the case (see
\ref{prg_architecture}). This variable is automatically set by
\texttt{code\_saturne~create} and should not be changed.

\item \texttt{RESTART\_IN}: directory containing the files for calculation
restart.

\item \texttt{PREPROCESSOR\_OUTPUT\_IN}: \texttt{preprocessor\_ouput} file for a calculation in ``calculation'' mode (see \ref{prg_executionmodes})

\item \texttt{MESHDIR}: directory containing the mesh files (see
\ref{prg_architecture}). This variable is automatically set by
\texttt{code\_saturne~create} and should generally not be changed.

\item \texttt{DATA\_SYR}: directory for the \syrthes data. This directory has
to be created by the user. It is advised to keep the location proposed
in the launch script, which complies with the standard architecture
of \CS (see
\ref{prg_architecture}).

\item \texttt{SYRTHES\_ENV}: name of the environment file for \syrthes (usually
\texttt{syrthes.env}, as proposed in the launch script).

\item \texttt{SRC\_SYR}: directory for the \syrthes user subroutines.
This directory has to be created by the user. It is advised to keep the location
proposed in the launch script, which complies with the standard architecture
of \CS (see \ref{prg_architecture}).

\item \texttt{COUPLING\_MODE}: coupling mode between \CS and \syrthes 3.4, when
such coupling is activated (see \texttt{COMMAND\_SYRTHES}). Two options are
available:\\
\hspace*{0.5cm}\texttt{MPI}: for a coupling based on MPI messages (requires a
MPI library)\\
\hspace*{0.5cm}\texttt{sockets}: for a coupling based on sockets

\item \texttt{EXEC\_PREPROCESSOR}: execution mode for \CS preprocessor (see \ref{prg_executionmodes})

\item \texttt{EXEC\_PARTITION}: execution mode for \CS partitionner (see \ref{prg_executionmodes})

\item \texttt{EXEC\_KERNEL}: execution mode for \CS kernel (see \ref{prg_executionmodes})

\end{list}


%==================================
\subsection{Graphical User Interface}
%==================================
\label{prg_ihm}%
A Graphical User Interface is available with \CS.
This Interface creates or reads an XML file according to
a specific \CS syntax which is then interpreted by the code.

In version \verscs, the Graphical Interface manages calculation parameters,
standard initialisation values and boundary
conditions for standard physics, pulverised coal combustion and radiative
transfers. The other specific
physics are not yet managed by the Graphical
Interface. In these particular cases, user subroutines have to be completed.

The Interface is optional. Every data that can be specified through the
Interface can also still be specified in the user subroutines. In case of
conflict, all calculation parameters, initialisation value or boundary condition
set directly in the user subroutines will prevail over what is defined by the
Interface. However, it is no longer necessary to redefine everything in the
user subroutines. Only what was not set or could not be set using the Graphical
Interface should be specified.

{\em WARNING: }
There are some limitations to the changes that can be made between the Interface
and the user routines. In particular, it is not possible to specify a certain
number of solved variables in the Interface and change it in the user routines
(for example, it is not possible to specify the use of a $k-\varepsilon$ model
in the Interface and change it to $R_{ij}-\varepsilon$ in \texttt{usini1.f90}, or
to define additional scalars in \texttt{usini1} with respect to the
Interface). Also, all boundaries should be referenced in the Interface, even if
the associated conditions are intended to be modified in \texttt{usclim}, and
their nature (entry, outlet, wall\footnote{smooth and rough walls are considered
of the same nature}, symmetry) should not be changed.

For example, in order to set the boundary conditions of a calculation
corresponding to a channel flow with a given inlet velocity profile, one
should:\\
- set the boundary conditions corresponding to the wall and the output
using the Graphical Interface\\
- set a dummy boundary condition for the inlet (uniform velocity for instance)
- set the proper velocity profile at inlet in \texttt{usclim}. The wall and
output areas do not need to appear in \texttt{usclim}. The dummy velocity
entered in the Interface will not be taken into account.

The Graphical User Interface is launched with the \texttt{./SaturneGUI} command
in the directory \texttt{DATA}. The first step is
then to load an existing parameter file (in order to modify it) or to
open a new one. The headings to be filled for a standard calculation are the
followings:

\begin{list}{-}{}
\item Analysis environment: definition of the calculation directories
      (STUDY, CASE), mesh file(s), periodicity, coupling with \syrthes,
      stand-alone execution of the
      Preprocessor module (used by the Interface to get the colors of the boundary
      faces).

\item Thermophysical models: physical model, ALE mobile mesh features,
      turbulence model, thermal model,
      initialisation of the variables.

\item Physical properties: reference pressure, fluid characteristics, gravity.

\item Additional scalars: definition, physical characteristics and
      initialisation of the scalars (apart from the temperature, which
      is treated separately in the Interface).

\item Boundary conditions: definition of the boundary conditions for
      each variable. The colors of the boundary faces may be read
      directly from a ``listing'' file created by the Preprocessor. This
      file can be generated directly by the Interface under the heading\\
      ``Analysis environment $\rightarrow$ Solution Domain $\rightarrow$
        Stand-alone running''.

\item Analysis control: parameters concerning the time averages, time step,
      location of
      the probes where some variables will be monitored over time,
      definition of the frequency of the outputs in the calculation
      listing and in the chronological records and of the EnSight outputs.

\item Numerical parameters: advanced parameters for the numerical solution of
      the equations

\item Calculation management: management of the calculation restarts,
      updating of the launch script (temporary execution directory, parallel
      computing, user data or result files, ...), interactive launch of the
      calculation and user arrays definition.

\end{list}

The \CS tutorial \cite{tutorial} offers a step-by-step guidance to the setting
up of some simple calculations with the \CS Interface.

To launch \CS using an XML parameter file,
the name of the file must
be given to the variable \texttt{PARAM} in the launch script (see
\S\ref{prg_runcase}). When the launch
script is edited from the Interface (Calculation management $\rightarrow$
Prepare batch analysis), the PARAM section is filled automatically as are the
other parameters specified through the Interface.


\minititre{Note: option \texttt{--nogui} of the \texttt{code\_saturne~create} command}
When a calculation is using the Interface but, for some reason, some extra
parameters need to be specified in the subroutine \texttt{usini1}, the latter
must be placed in the directory \texttt{SRC}. But, while doing this, all the
parameters appearing in \texttt{usini1} will also be taken into account. In
order to prevent the user from having to respecify in \texttt{usini1} all that
he has already specified through the Interface, \texttt{code\_saturne~create} automatically
comments out the examples in \texttt{usini1} (\texttt{Cex} at the beginning of
each line) while copying it in the directory \texttt{REFERENCE}. Therefore, the user
only needs to uncomment the specific parts of \texttt{usini1} he wants to modify,
and the rest of the examples will be ignored.\\
On the contrary, if the Interface will not be used, then all the parameters in
\texttt{usini1} have to be specified. In that case, using the \texttt{--nogui}
option of \texttt{code\_saturne~create} will prevent it from commenting \texttt{usini1}
out, thus saving the user the tedious task of uncommenting all the lines (and
the risk of skipping some of them).


%==================================
\subsection{Face and cell mesh-defined properties and selection}
%==================================
\label{selection_criteria}

The mesh entities may be referenced by the user during the mesh
creation. These references may then be used to mark out some mesh entities
according to the need (specification of boundary conditions, pressure
drop zones, ...). The references are generally of one of the two
following types:
\begin{list}{$\bullet$}{}
\item color.
A color is an integer possibly associated with boundary faces and
volume elements by the mesh generator. Depending on the tool,
this concept may have different names, which \CS interprets
as colors. Most tools allow only one color per face or element.
      \begin{list}{-}{}
      \item I-deas uses a color number with a default of
            7 (green) for elements, be they volume elements or boundary
            ``surface coating'' elements. Color 11 (red) is used for
            for vertices, but vertex properties are ignored by \CS.
      \item SIMAIL uses the equivalent notions of ``reference''
            for element faces, and ``subdomain'' for volume elements.
            By default, element faces are assigned no reference (0),
            and volume elements domain 1.
      \item Gmsh uses ``physical property'' numbers.
      \item EnSight has no similar notion, but if several parts
            are present in an EnSight 6 file, or several parts
            are present \emph{and} vertex ids are given in an
            Ensight Gold file, the part number is interpreted as
            a color number by the Preprocessor.
      \item The Comet Design (pro-STAR/STAR4) and NUMECA Hex file
            formats have a CAD section id that is interpreted
            as a color number. In the latter case, this notion
            only applies to faces, so volume elements are given
            color.
      \item The MED format allow integer ``attributes'', though
            many tools working with this format ignore those
            and only handle groups.
      \end{list}
\item groups.
Named ``groups'' of mesh entities may also be used with many
mesh generators or formats. In some cases, a given cell or face may belong
to multiple groups (as some tools allow new groups to be defined
by boolean operations on existing groups).
In \CS, every group is assigned a group number (base on alphabetical
ordering of groups).
      \begin{list}{-}{}
      \item I-deas assigns a group number with each
            group, but by default, this number is just a counter.
            Only the group name is considered by \CS (so that elements
            belonging to two groups with identical names and different
            numbers are considered as belonging to the same group).
      \item CGNS allows both for named boundary conditions and mesh
            sections. If present, boundary condition names are
            interpreted as group names, and groups may also be defined
            based on element section or zone names using additional
            Preprocessor options (\texttt{-grp-cel} or
            \texttt{-grp-fac} followed by \texttt{section} or
            \texttt{zone}).
      \item Using the MED format, it is preferable to use ``groups''
            to colors, as many tools ignore the latter.
      \end{list}
\end{list}

Selection criteria may be defined in a similar fashion whether
using the GUI or in user subroutines.
Typically, a selection criteria is simply a string containing
the required color numbers or group names, possibly combined
using boolean expressions. Simple geometric criteria are also
possible.

A few examples are given below:

\verb+ENTRY+\\
\verb+1 or 7+\\
\verb+all[]+\\
\verb+3.1 >= z >= -2 or not (15 or entry)+\\
\verb+range[04, 13, attribute]+\\
\verb+sphere[0, 0, 0, 2] and (not no_group[])+

Strings such as group names containing whitespace
or having names similar to reserved operators may be protected
using ``escape characters''.\footnote{Note that for defining a
string in Fortran, double quotes are easier to use, as they do not
conflict with Fortran's single quotes delimiting a string.
In C, the converse is true. Also, in C, to define a string
such as \texttt{{$\backslash$}plane}, the string
\texttt{{$\backslash$}{$\backslash$}plane} must be
used, as the first $\backslash$ character is used by the
compiler itself. Using the GUI, either notation is easy.}
More complex examples of strings whith protected strings are given here:

\verb+"First entry" or Wall\ or\ sym+\\
\verb+entry or \plane or "noone's output"+

The following operators and syntaxes are allowed (fully capitalized
versions of keywords are also allowed, but mixed capitals/lowercase
versions are not):

\begin{tabular}[top]{p{6cm} l}
\multicolumn{2}{l}{\bf escape characters }\\
protect next character only: & \texttt{$\backslash$} \\
protect string:              & \texttt{{'}$string${'}} \quad \texttt{"$string$"}\\
\end{tabular}

\begin{tabular}[top]{p{6cm} l}
\multicolumn{2}{l}{\bf basic operators }\\
priority: & \texttt{(} \quad \texttt{)} \\
not:      &  \texttt{not} \quad \texttt{!} \quad \texttt{!=} \\
and:      &  \texttt{and} \quad \texttt{\&} \quad \texttt{\&\&} \\
or:       &  \texttt{or} \quad \texttt{|} \quad \texttt{||} \quad \texttt{,} \quad \texttt{;} \\
xor:      &  \texttt{xor} \quad \texttt{\^} \\
\end{tabular}

\begin{tabular}[top]{p{6cm} l}
\multicolumn{2}{l}{\bf general functions }\\
select all:                        &  \texttt{all[]}\\
entities having no group or color: &  \texttt{no\_group[]} \\
select a range of groups or colors: &  \texttt{range[$first$, $last$]} \\
                                    &  \texttt{range[$first$, $last$, group]} \\
                                    &  \texttt{range[$first$, $last$, attribute]} \\
\end{tabular}

For the range operator, $first$ and $last$ values are inclusive.
For attribute (color) numbers, natural integer value ordering is used,
while for group names, alphabetical ordering is used. Note also that in
the bizarre (not recommended) case in which a mesh would contain for
example both a color number 15 and a group named ``15'', using
\texttt{range[15, 15, group]} or \texttt{range[15, 15, attribute]}
could be used to distinguish the two.

Geometric functions are also available. The coordinates considered are
those of the cell or face centers. Normals are of course
usable only for face selections, not cell selections.

\begin{tabular}[top]{p{6cm} l}
\multicolumn{2}{l}{\bf geometric functions }\\
face normals:   &  \texttt{normal[$x$, $y$, $z$, $epsilon$]} \\
                &  \texttt{normal[$x$, $y$, $z$, epsilon = $epsilon$]} \\
plane, $ax + by + cz + d = 0$ form: &  \texttt{plane[$a$, $b$, $c$, $d$, $epsilon$]} \\
                &  \texttt{plane[$a$, $b$, $c$, $d$, epsilon = $epsilon$]} \\
                &  \texttt{plane[$a$, $b$, $c$, $d$, inside]} \\
                &  \texttt{plane[$a$, $b$, $c$, $d$, outside]} \\
plane, normal + point in plane form: &  \texttt{plane[$n_x$, $n_y$, $n_z$, $x$, $y$, $z$, $epsilon$]} \\
                &  \texttt{plane[$n_x$, $n_y$, $n_z$, $x$, $y$, $z$, epsilon = $epsilon$]} \\
                &  \texttt{plane[$n_x$, $n_y$, $n_z$, $x$, $y$, $z$, inside]} \\
                &  \texttt{plane[$n_x$, $n_y$, $n_z$, $x$, $y$, $z$, outside]} \\
box, extents form: &  \texttt{box[$x_{min}$, $y_{min}$, $z_{min}$,
                                  $x_{max}$, $y_{max}$, $z_{max}$]} \\
box, origin + axes form: &  \texttt{box[$x_0$, $y_0$, $z_0$,}\\
                         &  \texttt{\qquad $dx_1$, $dy_1$, $dz_1$,
                                        $dx_2$, $dy_2$, $dz_2$,
                                        $dx_3$, $dy_3$, $dz_3$]} \\
                &  \texttt{plane[$a$, $b$, $c$, $d$, epsilon = $epsilon$]} \\
                &  \texttt{plane[$a$, $b$, $c$, $d$, inside]} \\
                &  \texttt{plane[$a$, $b$, $c$, $d$, outside]} \\
cylinder:       &  \texttt{cylinder[$x_0$, $y_0$, $z_0$, $x_1$, $y_1$, $z_1$, $radius$]} \\
sphere:         &  \texttt{sphere[$x_c$, $y_c$, $z_c$, $radius$]} \\
inequalities:   &  \texttt{>}, \texttt{<}, \texttt{>=}, \texttt{<=} associated
                   with \texttt{x}, \texttt{y}, \texttt{z}  or
                   \texttt{X}, \texttt{Y}, \texttt{Z} keywords\\
                &   and coordinate value; \\
                &  \texttt{$x_{min}$ <= x < $x_{max}$} type syntax is allowed. \\
\end{tabular}

In the current version of \CS, all selection criteria used
are maintained in a list, so that re-interpreting a criterion already
encountered (such as at the previous time step) is avoided.
Lists of entities corresponding to a criteria containing no geometric
functions are also saved in a compact manner, so re-using a previously
used selection should be very fast. For criteria containing geometric
functions, the full list of corresponding entities is not maintained,
so each entity must be compared to the criterion at each time step.
Heavy use of many selection criteria containing geometric functions
may thus lead to reduced performance.

%==================================
\section{Preprocessing}
%==================================

The \pcs module of \CS reads the
mesh file(s) (under any supported format) and translates the necessary
information into a Kernel input file. Mesh joining and domain partitioning for parallel
calculations are done at this stage. In case of periodic boundary
conditions, the \pcs module also identifies the boundary faces that are
related through periodicity and generates the corresponding connectivity.

The executable of the \pcs module is \texttt{cs\_preprocess},
and the most useful options and sub-options are described briefly here.
To obtain a complete and up-to-date list of options and environment
variables, use the following command:
\texttt{cs\_preprocess~-h} or \texttt{cs\_preprocess~--help}. Many options,
such as this one, accept a short and a long version.

For the main options, the launch script \texttt{runcase} contains
corresponding variables, that are used to define options for the
\pcs. This way, the user only has to define these variables
and does not detailed knowledge of the \pcs command line.

Nonetheless, it may be useful to call the \pcs manually
in certain situations, especially for frequent verification when
building a mesh, so its use is described here. Verification
may also be done using the \texttt{code\_saturne~check\_mesh} command,
which takes a subset of the same command-line arguments.

The \pcs is controlled using command-line arguments, some of these
accepting sub-arguments. It is possible to complete the command-line
with a file, using the same syntax as the command-line, but also
allowing multiple lines and comments. A few environment variables
allow an expert user to modify some behaviors or to obtain
a trace of memory management.

%==================================
\subsection{\pcs options and sub-options\label{sec:optpcs_ssopt}}
%==================================

Main choices are done using command-line options. Sub-option arguments
must directly follow the one activating the corresponding option, and
the definition of sub-options ends with the first argument which does
not match the same sub-option. Some options may be applied multiple
times. For example, \texttt{-j} being the option which activates
face joining, \texttt{--fraction} the sub-option modifying the
default tolerance, and  \texttt{--color} a face selection sub-option:

\texttt{cs\_preprocess -m fluid.msh -j --fraction 0.2 --color 2 --color 3 -j}

\noindent means that we apply a joining to boundary faces of
color $2$ or $3$ of mesh \texttt{fluid.msh} with a tolerance of $0.2$,
then that we apply a second joining to all remaining boundary faces
(with default parameters), while:

\texttt{cs\_preprocess -m fluid.msh -j --fraction 0.2 -color 2 -j --color 3}

\noindent means that we apply a joining to boundary faces of
color $2$ of mesh \texttt{fluid.msh} with a tolerance of $0.2$,
then that we apply a second joining to boundary faces of color $3$
(with default values for other parameters).

\subsubsection{Option files\label{sec:optpcs:input}}

It is possible to complete the command-line with a file, using the same
syntax as the command-line, but allowing the addition of arbitrary line
jumps and comments. On a given line, anything that follows a\texttt{\#}
character until the end of the line is ignored in such a file.
The use of such a file is activated by the argument \texttt{-i}.
If for example a file \texttt{pp\_cmd} contains the following
lines:

\noindent
\begin{tabular}{l l}
\texttt{--ensight} & \texttt{\# activate EnSight output}\\
\texttt{--med}     & \texttt{\# activate MED output}\\
\end{tabular}

\noindent
\begin{tabular}{l l}
then command:     & \texttt{cs\_preprocess -i pp\_cmd -m mesh.unv}\\
is equivalent to: & \texttt{cs\_preprocess -m mesh.unv --ensight --med}\\
\end{tabular}

The use of option files may circumvent command-line length limits
(now rarely an issue), and allows easier manipulation and better
readability of complex option combinations.

\subsubsection{Mesh selection\label{sec:optpcs:mesh}}

Any use of the preprocessor requires one or several meshes (except for
\texttt{cs\_preprocess} and \texttt{cs\_preprocess~-h} which respectively
print the version number and list of options).
They are selected using the \texttt{--mesh} or \texttt{-m} option, followed
by th list of meshes to read. The file format is usually automatically
determined based on its extension (c.f. \ref{sec:formats_in}
page~\pageref{sec:formats_in}) but this option also allows a \texttt{--format}
sub-option, to force the format choice of selected files.

For formats allowing multiple meshes in a single file, the
\texttt{--num} sub-option followed by a strictly positive integer allows
selection of a specific mesh; by default, the first mesh is selected.

For meshes in CGNS format, we may in addition use the \texttt{--grp-cel}
or \texttt{--grp-fac} sub-options, followed by the \texttt{section}
or \texttt{zone} keywords, to define additional groups of cell or faces
based on the organization of the mesh in sections or zones. The sub-options
have no effect on meshes of other formats.

We may define as many mesh selections as we wish. Meshes are read and
automatically compounded (but not joined) in the order of their appearance.
For example:

\noindent
\texttt{cs\_preprocess -m file.1 file.2 --format ideas -m branch.cgns --grp-cel section}

\noindent
reads mesh files \texttt{file.1} and \texttt{file.2} as \ideas files,
and appends the first mesh from the \texttt{branch.cgns} file,
on which additional groups of cells corresponding to the CGNS section
names to which cells belong.

\subsubsection{Post-processing output\label{sec:optpcs:post}}

By default, the \pcs does not generate any post-processor output.
By adding \texttt{--ensight}, \texttt{--med}, or \texttt{--cgns} to
the command-line arguments, the output of the mesh to the indicated format
is provoked. It is possible to generate output to different formats
simultaneously. Note that we will obtain additional surface meshes
corresponding to the calculation domain boundary, to faces joined
or modified by joinings or periodicity, etc. Note also that
periodic faces are not considered to be part of the domain boundary.
\footnote{Periodicity is interpreted as a ``geometric'' condition
rather than a classical boundary condition.}

We consider 4 types of output: the volume mesh (output before possible
joinings), the boundary mesh, informational meshes (such as faces
stemming from or modified by a joining of periodicity, or
selected interior faces), and meshes outlining to zones with errors.
By default, all types of meshes are output. If one or several of
the three filtering sub-options is used , only the meshes of the
requested types will be output, as well as meshes corresponding to
zones with errors (non-filterable). The filtering sub-options
are: \texttt{--volume}, \texttt{--boundary}, and \texttt{--info}.

One may also optionally avoid outputting polygons or polyhedra
by adding the \texttt{--discard-poly} sub-option.
This allow working around bugs or limited polyhedron support
in visualization tools or limitations of the CGNS 2 format.
In this case, the post-processing output will be incomplete,
but at least readable.

In the case of \emph{EnSight Gold} output, we may use the
\texttt{--simple} sub-option to avoid splitting the output in
several \emph{parts} corresponding to different attributes
(colors and groups) borne by this mesh.

Still in the case of the \emph{EnSight Gold} output, we may
force the output in text mode using the \texttt{--text} sub-option,
or force binary output to ``big-endian'' variant using the
\texttt{--big-endian} sub-option. By default, the output is native
binary.

Finally, in the case of output in the \emph{MED} format, we may
force the conversion of attributes (colors) to groups using
the \texttt{--color-to-group} sub-option.

\subsubsection{Faces selection\label{sec:optpcs:select}}

Selection of faces occurs at several levels, especially for conforming
joining.

It is also possible to select a set of interior faces bearing attributes
(colors or groups) for verification purposes using the option
\texttt{--int-face}. The \pcs prints the number of interior faces
matching a selection criterion, and if in addition post-processing
output is activated, a surface mesh corresponding to the selected faces
will be generated.

\pcs selection criteria are more limited than those
used by th kernel, and are generated using the following sub-options:

\noindent
\begin{tabular}{l l}
\texttt{--color} $c_1$ $c_2$ ... $c_n$~ &
to select faces of the indicated color numbers\\
\texttt{--group} $g_1$ $g_2$ ... $g_n$~ &
to select faces of the groups named\\
\texttt{--invsel} &
to use the complement of the indicated colors and groups\\
\end{tabular}

The same selection sub-options are used for conforming joining, periodicity,
and interior faces verification. In the case of joining and periodicity,
the selection is automatically restricted to boundary faces, while
in the case of interior face verification, it is restricted to
interior faces bearing attributes.

For example, to select all interior faces of mesh \texttt{example.des}
which bear an attribute (color or group), but are not of color 2 and do not
belong to group ``inlet'', with output of an \emph{Ensight Gold} part
and with no kernel output (using \texttt{-sc}), we use the following
command line (the \verb=\= character marks line continuation):

\noindent
\begin{tabular}{l l l}
\texttt{cs\_preprocess} & \texttt{-m example.des -sc --ensight } \verb=\= \\
         & \texttt{--int-face --group entree --color 2 --invsel}\\
\end{tabular}

\subsubsection{Joining of non-conforming meshes\label{sec:optpcs:join}}

Conforming joining of possibly non-conforming meshes is one of the
\pcs's main functions. To activate it, use the \texttt{--join} or
\texttt{-j} command-line options, possibly followed by face selection
criteria and sub-options controlling associated tolerance parameters.

For a simple mesh, it is rarely useful to specify face selection
criteria, as joining is sufficiently automated to detect which faces
may actually be joined. For a more complex mesh, or a mesh with thin
walls which we want to avoid transforming into interior faces, it is
recommended to filter boundary faces that may be joined by using
face selection sub-arguments (see \S\ref{sec:formats_in}). This has the
additional advantage of reducing the number of faces to test for
in the intersection/overlap search, and thus reduced to time
required by the joining algorithm.

One may also modify tolerance criteria using 2 sub-options:

\noindent
\begin{tabular}[top]{p{3.0cm}%
                     >{\PreserveBackslash\raggedright\hspace{0pt}}p{12.0cm}}
\texttt{--fraction} $r$  &
assigns value $r$ (where $0 < r < 0,49$) to the maximum
intersection distance multiplier ($0,1$ by default). The maximum
intersection distance for a given vertex is based on the length of
the shortest incident edge, multiplied by $r$. The maximum intersection
at a given point along an edge is interpolated from that at its
vertices, as shown on the left of figure \ref{fig_join_tolerance}; \\
\texttt{--plane} $c$ &
assigns the minimum cosine between normals for two faces to be
considered coplanar ($0,8$ by default, which corresponds to almost 37°);
this parameter is used in the second stage of the algorithm, to
reconstruct conforming faces, as shown on the right of figure
\ref{fig_join_tolerance}.\\
\end{tabular}

\begin{figure}[hp]
\centerline{
\includegraphics*[width=14cm]{join_tolerance}}
\caption{Maximum intersection tolerance and faces normal angle
\label{fig_join_tolerance}}
\end{figure}

In practice, we are sometimes led to increase the maximum intersection
distance multiplier to $0.2$ or even $0.3$ when joining curved surfaces,
so that all intersection are detected. As this influences merging
of vertices and thus simplification of reconstructed faces, but also
deformation of ``lateral'' faces, it is recommended only to modify it
if necessary. As for the \texttt{--plane} sub-option, its use has
only been necessary on a few meshes up to now, and always in the
sense of reducing the tolerance (i.e. bringing the minimum cosine closer
to 1) so that face reconstruction does not try to generate faces
from initial faces on different surfaces.

As an example, to join faces with color $2$ of the mesh \texttt{mesh.des}
with an intersection distance multiplier of  $0.15$, then joining all
remaining joinable boundary faces with a default parameter of $0.1$,
we may use the following command:

\texttt{cs\_preprocess -m mesh.des -j --fraction 0.15 --color 2 -j}

In cases where any two faces to join always have at least one common vertex
(which is the case with meshes containing hanging nodes generated by
tools such as \harpoon), we may use the \texttt{--semi-conf}
sub-option, for a much faster edge intersection search than with
the usual algorithm.

\subsubsection{Periodicity\label{sec:optpcs:period}}

Handling of periodicity is based on an extension of conforming joining,
as shown on figure \ref{fig_join_periodic}. It is thus not necessary
that periodic faces be conforming (though it usually leads to better
mesh quality). All sub-options relative to conforming joining of
non-conforming faces also apply to periodicity. Note also that
once pre-processed, 2 periodic faces have the same orientation
(possibly adjusted by periodicity of rotation).

\begin{figure}[hp]
\centerline{
\includegraphics*[height=8cm]{join_periodic}}
\caption{Matching of periodic faces
\label{fig_join_periodic}}
\end{figure}

The sub-option for a translation-type periodicity is \texttt{--trans} followed
by the three translation vector components $(tx, ty, tz)$.
The sub-option for a rotation-type periodicity is \texttt{--rota}, 
which must be completed either by:

\noindent
\texttt{--angle} $\alpha$ \texttt{--dir} $dx$ $dy$ $dz$

\noindent
where $\alpha$ is the rotation angle in degrees and $(dx, dy, dz)$ defines
the rotation axis (using the trigonometric orientation), or by:

\noindent
\texttt{--matrix} $m11$ $m12$ $m13$ $m21$ $m22$ $m23$ $m31$ $m32$ $m33$

\noindent
where 
\begin{math}
  \left( \begin{smallmatrix}
     m_{11} & m_{12} & m_{13} \\ m_{21} & m_{22} & m_{23} \\ m_{31} & m_{32} & m_{33}
  \end{smallmatrix} \right)
\end{math}
 defines the rotation matrix.

In either case, we may define an invariant point different from $(0, 0, 0)$
by adding the rotation sub-option \texttt{--invpt} $px$ $py$ $pz$.
A translation and a rotation may be combined: in this case, the composite
transformation is always $R \circ T$, independently of the order in which
the translation and rotation are defined.

The orientation of the transformations has no importance (but in the
case of a composite transformation $R \circ T$, $R$ and $T$ must be
consistent).
As with joining, it is recommended to filter boundary faces to process
using a selection criterion. As many periodicities may be built as desired,
as long as boundary faces are present. One a periodicity is handled,
faces having periodic matches do not appear as boundary faces, but as
interior faces, and are thus not available anymore for other
periodicities.

We finish with the example of a periodicity of rotation of $90$ degrees around
an axis of direction $(0, 0, 1)$ passing through $(1, 0, 0)$,
for faces of group ``perio\_1'' and with a joining tolerance of $20\%$ (the
\verb=\= character marks line continuation):

\noindent
\begin{tabular}{l l l}
\texttt{--perio} & \texttt{--rota --angle 90 --dir 0 0 1 --invpt 1 0 0} \verb=\= \\
 & \texttt{--fraction 0.2 --group perio\_1}\\
\end{tabular}

\subsubsection{Element orientation correction\label{sec:optpcs:orient}}

We may active the possible element orientation correction using the
\texttt{--reorient} option.

Note that we cannot guarantee correction (or even detection) of a bad
orientation in all cases.
Not all local numbering possibilities of elements are tested,
as we focus on ``usual'' numbering permutations. Moreover,
the algorithms used may produce false positives or fail to find
a correct renumbering in the case of highly non convex elements.
In this case, nothing may be done short of modifying the mesh, as
without a convexity hypothesis, it is not always possible to choose
between two possible definitions starting from a point set.

With a post-processing option such as \texttt{--ensight},
visualizable meshes of corrected elements as well as remaining
badly oriented elements are generated.

\subsection{Environment variables\label{sec:envvpcs}}

Setting a few environment variables specific to the \pcs allows modifying
its default behavior. In general, if a given behavior is modifiable
through an environment variable rather than by a command-line option,
it has little interest for a non-developer, or its modification is
potentially hazardous. The environment variables used by the \pcs
are described here:

\envvar{CS\_PREPROCESS\_MEM\_LOG}

Allows defining a file name in which memory allocation, reallocation,
and freeing is logged.

\envvar{CS\_PREPROCESS\_MIN\_EDGE\_LEN}

Under the indicated length ($10^{-15}$ by default), an edge is considered
to be degenerate and its vertices will be merged after the transformation
to descending connectivity. Degenerate edges and faces will thus be
removed. Hence, the post-processed element does not change, but the
Kernel may handle a prism where the preprocessor input contained a
hexahedron with two identical vertex couples (and thus a face of zero
surface). If the \pcs does not print any information relative to this
type of correction, it means that it has not been necessary. To completely
deactivate this automatic correction, a negative value may be assigned
to this environment variable.

\envvar{CS\_PREPROCESS\_IGNORE\_IDEAS\_COO\_SYS}

If this variable is defined and is a strictly positive integer, coordinate
systems in \ideas universal format files will be ignored. The behavior
of the \pcs will thus be the same as that of versions 1.0 and 1.1.
Note that in any case, non Cartesian coordinate systems are not handled yet.

\envvar{CS\_PREPROCESS\_JOIN\_MAX\_SUB\_FACES}

Defines the number of new faces originating from an initial face ($100$
by default) above which we consider that the joining reconstruction has
probably entered an infinite loop and has thus failed.
This criterion is the last to intervene in the detection of errors and
only comes into play in pathological cases probably related to excessive
deformation of faces to join (and thus a too large tolerance factor).
It should not be necessary to increase it for a mesh really intended for
a calculation, as $100$ faces correspond to a refinement ratio of $10$
in each direction for joined cells, which is excessive from a numerical
standpoint.

\subsubsection{System environment variables\label{sec:envpcs:sys}}

Some system environment variables may also modify the behavior of
the \pcs. For example, if the \pcs was compiled with \med support
on an architecture allowing shared (dynamic) libraries, the
\texttt {LD\_PRELOAD} environment variable may be used to define a
``prioritary'' path to load \med or HDF5 libraries, and thus experiment
with another version of these libraries without recompiling the \pcs.
To determine which shared libraries are used by an executable file, use
the following command: \texttt{ldd~\{executable\_path\}}.

\subsection{Optional functionality\label{sec:pcs:lib_opt}}

Some functions of the \pcs are based on external libraries,
which may not always be available. It is thus possible to configure
and compile the \pcs so as not to use these libraries.
When running the \pcs, the supported options are printed.
The following optional libraries may be used:

\begin{itemize}

\item CGNS library. In its absence, \hyperref[fmtdesc:cgns]{CGNS}
      format support is deactivated.

\item \med-file library. In its absence, \hyperref[fmtdesc:med]{\med}
      format is simply deactivated.

\item Read compressed files using Zlib. With this option, it is
      possible to diretly read mesh files compressed with a
      \emph{gzip} type algorithm and bearing a \emph{.gz} extension.
      This is limited to formats not already based on an external
      library (i.e. it is not usable with CGNS or \med files),
      and has memory and CPU time overhead, but may be practical.
      Without this library, files must be uncompressed before use.

\end{itemize}

\subsection{General remarks}

Note that the \pcs is in general capable of reading all ``classical''
element types present in mesh files (triangles, quadrangles, tetrahedra,
pyramids, prisms, and hexahedra).
Quadratic or cubic elements are converted upon reading into their
linear counterparts. Vertices referenced by no element (isolated vertices
or centers of higher-degree elements) are discarded. Meshes are read
in the order defined by the user and are appended, vertex and element
indices being incremented appropriately.
\footnote{Possible entity labels are not maintained, as they would
probably not be unique when appending multiple meshes.}

At this stage, volume elements are sorted by type, and the fluid domain
post-processing output is generated if required. Conforming joining,
which may transform cells into general polyhedra only occurs
after this. This allows bypassing a limitation of most post-processing
tools, which do not handle polyhedral elements.
\emph{It is possible to require the simultaneous output with
multiple formats.}

In general, colors or groups assigned to vertices are ignored.
selections are thus based on faces or cells. with tools such
as \simail, faces of volume elements may be referenced directly, while
with \ideas or SALOME, a layer of surface elements bearing the required
colors and groups must be added. Internally, the \pcs always considers
that a layer of surface elements is added (i.e. when reading a \simail
mesh, additional faces are generated to bear cell face colors.
When building the descending connectivity, all faces with the
same topology are merged: the initial presence of two layers of identical
surface elements bearing different colors would thus lead to
a calculation mesh with faces bearing two colors.

\subsection{Files passed to the Kernel\label{sec:pcs:mode_comm}}

Data passed to the Kernel by the \pcs is transmitted using a
binary file, using ``big endian'' data representation, named
\texttt{preprocessor\_output}.

When using the \pcs for mesh verification, data for the Kernel
is usually not needed. In this case, the \texttt{-sc} option may be
used to simulate output, without creation of a {\tt preprocessor\_output}
file.

%==================================
\section{Partitioning for parallel runs\label{sec:parall}}
%==================================

Graph partitioning (using one of the optional \metis or
\scotch libraries) is done using a secondary executable,\\
\texttt{cs\_partition},
which reads the file produced by the \pcs and builds one or
several ``cell $\rightarrow$ domain'' distribution files, named
{\tt domain\_number\_\it{p}} for a partitioning on $p$ sub-domains.

This separation leads to extra work for the Kernel, which must
redistribute data read in the  {\tt preprocessor\_output} file
based on the associated partitioning, but avoids requiring
re-running the \pcs whenever running on a different number of
files. This useful mainly for large files (20 to 100 million
cells, for which running the \pcs may require several hours and
a machine with a very large memory capacity. Simple domain
partitioning requires much less time, and in general slightly
less memory than the \pcs.

Without partitioning (for example if neither \metis nor
\scotch is available, or the partitioner has not been run
for the required number of sub-domains), the Kernel will
use a built-in partitioning using a space-filling curve
(Z-curve) technique. This usually leads to partitionings
of lower quality than with graph partitioning, but parallel
performance remains reasonable.

\subsection{Options\label{sec:optcmd:parall}}

To list the partitioner's options, use the following command:
{\tt cs\_partition~-h} 

We provide the list of required partitionings an optionally additional
options. For example, to simulate a partitioning for calculations on
64 and 128 processes with no output, we may use the following command:

\texttt{cs\_partition 64 128 --no-write}

\subsubsection{Ignore periodicity\label{sec:optcmdpart:noperiod}}

By default, face periodicity relations are taken into account when building
the ``cell $\rightarrow$ cell'' connectivity graph used for partitioning.
This allows better partitioning optimization, but increases the probability
of having groups of cells at opposite sides of the domain in a same
sub-domain. This is not an issue for standard calculations, but may
degrade performance of search algorithms based on bounding boxes.
It is thus possible to ignore periodicity when partitioning a mesh
using the \texttt{--no-perio} option.

Note that nothing guarantees that a graph partitioner will not place
disjoint cells in the same sub-domain independently of this option,
but this behavior is rare.

\subsubsection{Partitioner choice\label{sec:optpart:partlib}}

If the Partitioner has been configured with both \metis and
\scotch libaries, using the \texttt{--metis} or \texttt{--scotch}
option allows choosing between either library. By default, \emph{metis} is
used if both choices are available.

\subsubsection{Simulation mode\label{sec:optpart:nowrite}}

Using the \texttt{--no-write} option, we can tell the partitioner
not to output a {\tt domain\_number\_\it{p}} file.
Partitioning is thus computed, but not saved.

\subsubsection{Environment variables\label{sec:optpart:envvar}}

\envvar{CS\_PARTITION\_MEM\_LOG}

Allows defining a file name in which memory allocations, reallocations,
and frees will be logged.

%==================================
\section{Main variables}
%==================================

This section presents a non-exhaustive list of the main variables which
may be encountered by the user. Most of them should not be modified by the
user. They are calculated automatically from the data. However it may be
useful to know what they represent.
Developpers can also refer to \cite{boucker00} and \cite{theory}.

These variables are listed in the alphabetical index at the end of this
document.

The type of each variable is given: integer [i], real number [r],
integer array [ia], real array [ra].

%==================================
\subsection{Array sizes}
%==================================
\label{prg_dimensions}

\variabsize{ndim}{Space dimension (ndim=3)}

\bigskip

\variabsize{ncel}{Number of real cells in the mesh}

\variabsize{ncelet}{Number of cells in the mesh, including the
ghost cells of the ``halos'' (see note 1)}

\variabsize{nfac}{Number of internal faces (see note 2)}

\variabsize{nfabor}{Number of boundary faces (see note 2)}

\variabsize{ncelbr}{Number of cells with at least one boundary
face (see note 2)}

\bigskip

\variabsize{lndfac}{Size of the array \texttt{nodfac}\index{nodfac} of
internal faces - nodes connectivity (see note 3)}

\variabsize{lndfbr}{Size of the array \texttt{nodfbr}\index{nodfbr} of
boundary faces - nodes connectivity (see note 3)}

\variabsize{nnod}{Number of vertices in the mesh}

\bigskip

\variabsize{nfml}{Number of referenced families of entities (boundary
faces, elements, ...)}

\variabsize{nprfml}{Number of properties per referenced entity family}

\bigskip

\variabsize{nphas}{Effective number of phases. \texttt{nphas} must be
inferior or equal to \texttt{nphsmx}. In the current version, \texttt{nphas}
is forced to 1 and should not be changed.}

\variabsize{nphsmx}{Maximum number of phases (default value:
1)\footnote{the data structure of \CS is ready for a multiphase description,
however no multiphase model has been implemented. Moreover, some options of the
code are not compatible with \texttt{nphas} different from 1.}}

\variabsize{nvar}{Number of solved variables (must be lower than
\texttt{nvrmax})}

\variabsize{nscamx}{Maximum number of scalars solutions of an
advection equation, apart from the variables of the turbulence model ($k$,
$\varepsilon$, $R_{ij}$, $\omega$, $\varphi$, $\overline{f}$). That is
to say the temperature and other scalars (passive or not, user-defined or not)}

\variabsize{nscal}{Effective number of scalars solutions of an
advection equation, apart from the variables of the turbulence model ($k$,
$\varepsilon$, $R_{ij}$, $\omega$, $\varphi$, $\overline{f}$). That is
to say the temperature and other scalars (passive or not, user-defined or
not). These scalars can be divided into two distinct groups: \texttt{nscaus}
user-defined scalars and \texttt{nscapp} scalars related to a ``specific
physics''. \texttt{nscal=nscaus+nscapp}, and \texttt{nscal}
must be inferior or equal to \texttt{nscamx}}

\variabsize{nscapp}{Effective number of scalars related to a
``specific physics''. These scalars are solutions of an advection
equation and distinct from the scalars of the turbulence model ($k$,
$\varepsilon$, $R_{ij}$, $\omega$, $\varphi$, $\overline{f}$). They are
automatically defined by the choice of the selected specific physics
model (gas combustion with Eddy Break-Up model, pulverised coal
combustion, ...). For example: mass fractions, enthalpy, ...}

\variabsize{nscaus}{Effective number of user-defined scalars. These
scalars are solutions of an advection equation and distinct from the
scalars of the turbulence model ($k$, $\varepsilon$, $R_{ij}$, $\omega$,
$\varphi$, $\overline{f}$) and from the \texttt{nscapp} scalars related to the
``specific physics''. For example: passive tracers, temperature (when no
specific physics model is selected), ...}

\variabsize{nestmx}{Maximum number of error estimators for
Navier-Stokes}

\bigskip

\variabsize{longia}{Size of the macro array of integer \texttt{ia}}

\variabsize{longra}{Size of the macro array of real \texttt{ra}}

\variabsize{npromx}{Maximum number of physical properties. They will
be stored in the arrays \texttt{propce}, \texttt{propfa} or \texttt{propfb}}

\variabsize{nproce}{Number of properties defined at the
cells. They will be stored in the array \texttt{propce}}

\variabsize{nprofa}{Number of properties defined at the internal
faces. They will be stored in the array \texttt{propfa}}

\variabsize{nprofb}{Number of properties defined at the boundary
faces. They will be stored in the array \texttt{propfb}}

\variabsize{nvisls}{Number of scalars with variable diffusivity}


\bigskip

\variabsize{nushmx}{Maximum number of user chronological files
(in the case where \texttt{ushist} is used)}

\variabsize{nbmomt}{Effective number of calculated time-averages.
NBMOMT must be inferior or equal to \texttt{nbmomx}}

\variabsize{nbmomx}{Maximum number of calculated time-averages (default
value: 50)}


\variabsize{ndgmox}{Maximum degree of the time-averages (default value:
5)}


\bigskip

\variabsize{nclacp}{Number of coal classes for the pulverised
coal combustion module. It is the total number of classes, {\it i.e.}
the sum of the number of classes for every represented coal. \texttt{nclacp} must
be inferior or equal to \texttt{nclcpm}}

\variabsize{nclcpm}{Maximum number of coal classes for the
pulverised coal combustion module}


\minititre{Note 1: ghost cells - ``halos''}
A cell (real cell) is an elementary mesh element of the spatial
discretisation of the calculation domain. The mesh is made of NCEL cells.\\
When using periodicity and parallelism, extra ``ghost'' cells
( called ``halo'' cells) are defined for temporary storage of some information
(on a given processor).
The total number of real and ghost cells is \texttt{ncelet}. \\
\hspace*{1cm} Indeed, when periodicity is enabled, the cells with
periodic faces do not have any real neighboring cell across these
particular faces. Their neighboring cell is elsewhere in the calculation
domain (its position is determined by the periodicity). In order to
temporarily store the information coming from this ``distant''
neighboring cell, a ghost cell (``halo'') is created. \\
\hspace*{1cm} The same kind of problem exists in the case of a
calculation on parallel machines: due to the decomposition of the
calculation domain, some cells no longer have access to all
their neighboring cells, some of them being treated by another processor. The
creation of ghost cells allows to temporarily store the information
coming from real neighboring cells treated by other processors.\\
The variables are generally arrays of size \texttt{ncelet} (number of real and
fictitious cells). The calculations (loops) are made on \texttt{ncel} cells (only
the real cells, the fictitious cells are only used to store information).

\minititre{Note 2: internal faces}
An internal face is an inferface shared by two cells (real or ghost
ones) of the mesh. A boundary face is a face which has only one real
neighboring cell. In the case of periodic calculations, a periodic face
is an internal face. In the case of parallel running calculations, the
faces situated at the boundary of a partition may be internal faces or
boundary faces (of the whole mesh);

\minititre{Note 3: faces-nodes connectivity}\label{prg_nodfac}
The faces - nodes connectivity is stored by
means of four integer arrays: \texttt{ipnfac} and \texttt{nodfac} for the
internal faces, \texttt{ipnfbr} and \texttt{nodfbr} for the boundary faces.
\texttt{nodfac} (size \texttt{lndfac})
contains the list of all the nodes of all the internal faces; first the nodes of
the first face, then the nodes of the second face, and so on.
\texttt{ipnfac} (size: \texttt{nfac+1}) gives the position \texttt{ipnfac(ifac)}
in \texttt{nodfac} of the first node of each internal face \texttt{ifac}.
Therefore, the reference numbers of all
the nodes of the internal face \texttt{ifac} are: \texttt{nodfac(ipnfac(ifac))},
\texttt{nodfac(ipnfac(ifac)+1)}, ..., \texttt{nodfac(ipnfac(ifac+1)-1)}.
In order for this last formula to be valid even for \texttt{ifac=nfac},
\texttt{ipnfac} is of size \texttt{nfac+1} and \texttt{ipnfac(nfac+1)}
is equal to \texttt{lndfac+1}.\\
The composition of the arrays \texttt{nodfbr} and \texttt{ipnfbr} is similar.

\minititre{Note 4: commons}
{\bf The user will not modify the existing ``commons''.} This would require the
recompilation of the complete version, operation which is not allowed in
standard use.

%==================================
\subsection{Geometric variables}
%==================================

The main geometric variables are available in most of the
subroutines and directly accessible through the following arrays.

\variab{cdgfac}{cdgfac(ndim,nfac)}{ra}{Coordinates of the
centers of the internal faces}

\variab{cdgfbo}{cdgfbo(ndim,nfabor)}{ra}{Coordinates of the centers of the
boundary face}


\variab{ifacel}{ifacel(2,nfac)}{ia}{Index-numbers of the two (only) neighboring
cells for each internal face}

\variab{ifabor}{ifabor(nfabor)}{ia}{Index-number of the (unique) neighboring
cell for each boundary face}


\variab{ipnfac}{ipnfac(nfac+1)}{ia}{Position of the first node of the each internal
face in the array \texttt{nodfac} (see note 3 in paragraph \ref{prg_dimensions}).}

\variab{ipnfbr}{ipnfbr(nfabor+1)}{ia}{Position of the first node of the each boundary
face in the array \texttt{nodfbr} (see note 3 in paragraph \ref{prg_dimensions}).}


\variab{nodfac}{nodfac(lndfac)}{ia} {Index-numbers of the nodes of each
internal face (see note 3 in paragraph \ref{prg_dimensions}).}

\variab{nodfbr}{nodfbr(lndfbr)}{ia}{Index-numbers of the nodes of each
boundary face (see note 3 in paragraph \ref{prg_dimensions}).}

\variab{surfac}{surfac(ndim,nfac)}{ra}{Surface vector of the internal
faces. Its norm is the surface of the face and it is oriented from \texttt{ifacel(1,.)}
to \texttt{ifacel(2,.)}.}

\variab{surfbo}{surfbo(ndim,nfabor)}{ra}{Surface vector of the boundary
faces. Its norm is the surface of the face and it is oriented outwards}

\variab{volume}{volume(ncelet)}{ra}{Volume of each cell}

\variab{xyzcen}{xyzcen(ndim,ncelet)}{ra}{Coordinates of the cell centers}

\variab{xyznod}{xyznod(ndim,nnod)}{ra}{Coordinates of the mesh vertices}

In addition, other geometric variables are accessible in sections of
the unidimensional macro-arrays IA (for integers) and RA (for real numbers)
which are passed as arguments
in every subroutine (apart from a few ones of very low level). The
index-number of the first element of these sections is stored in a ``common''
(in the file \texttt{pointe.h}), passed to most of the routines. Hence, the
surface of an internal face \texttt{ifac} is stored in
\texttt{ra(isrfan+ifac-1)}.
Or, the coordinate of vector $\vect{OF}$ (see below for
definition) in the II$^{th}$ direction for face \texttt{ifac} is stored in
\texttt{ra(idofij+(ifac-1)*ndim+ii-1)}\footnote{in Fortran, a multidimensional
array \texttt{a(3,2)} is in fact a unidimensional array containing the elements
\texttt{a(1,1)}, \texttt{a(2,1)}, \texttt{a(3,1)}, \texttt{a(1,2)},
\texttt{a(2,2)}
and \texttt{a(3,2)} in this order.}.

The main variables of this type are the following:

\variab{idijpf}{idijpf}{i}{In \texttt{ra}, pointer to
\texttt{dijpf(ndim,nfac)}, real array giving, for every internal face,
the three components of the vector  $\vect{I'J'}$, where I' and J' are
respectively the orthogonal projections of the neighboring cell centers I and J
on a straight line orthogonal to the face and passing through its center.}

\variab{idiipb}{idiipb}{i}{In \texttt{ra}, pointer to
\texttt{diipb(ndim,nfabor)}, real array giving, for every boundary
face, the three components of the vector $\vect{II'}$. I' is the
orthogonal projection of I, center of the neighboring cell, on the
straight line perpendicular to the face and passign through its center}

\variab{idist}{idist}{i}{In \texttt{ra}, pointer to \texttt{dist(nfac)}, real
array giving, for every internal face, the scalar product between the
vectors $\vect{IJ}$ and $\vect{n}$. I and J are respectively the centers
of the first and the second neighboring cell. The vector $\vect{n}$ is
the unit vector normal to the face and oriented from the first to the
second cell}

\variab{idistb}{idistb}{i}{In \texttt{ra}, pointer to \texttt{distbr(nfabor)},
real array giving, for every boundary face, the scalar product between
the vectors $\vect{IF}$ and $\vect{n}$. I is the center of the
neighboring cell. F is the face center. The vector $\vect{n}$ is the
unit vector normal to the face and oriented to the exterior of the
domain}

\variab{idofij}{idofij}{i}{In \texttt{ra}, pointer to \texttt{dofij(ndim,nfac)},
real array giving, for every internal face, the components of the
vector $\vect{OF}$. O is the intersection point between the face and
the straight line joining the centers of the two neighboring cells. F
is the face center}

\variab{iicelb}{iicelb}{i}{In \texttt{ia}, pointer to \texttt{icelbr(ncelbr)},
integer array giving the list of cells having at least one boundary face}

\variab{ipond}{ipond}{i}{In \texttt{ra}, pointer to \texttt{pond(nfac)},
real array giving
$\displaystyle\frac{\vect{FJ}.\vect{n}}{\vect{IJ}.\vect{n}}$, for every
internal face. With regard to the mesh quality, its ideal value is 0.5}

\variab{isrfan}{isrfan}{i}{In \texttt{ra}, pointer to \texttt{surfan(nfac)},
real array giving the norm of the surface vector of the internal faces}

\variab{isrfbn}{isrfbn}{i}{In \texttt{ra}, pointer to \texttt{surfbn(nfabor)},
real array giving the norm of the surface of the boundary faces}

%==================================
\subsection{Physical variables}
%==================================

The main physical variables are available in the majority of the
subroutines and brought together according to their type in the
multidimensional arrays listed below. In some paricular subroutines,
some variables may be given a more explicit name, in order to ease the
comprehension.

\variab{propce}{propce(ncelet,nproce)}{ra}{Properties defined at the
cell centers. For instance: density, viscosity, ...}

\variab{propfa}{propfa(nfac,nprofa)}{ra}{Properties defined at the
internal faces. For instance: mass flow across internal faces}

\variab{propfb}{propfb(nfabor,nprofb)}{ra}{Properties defined at the
boundary faces. For instance: mass flow across boundary faces, density
at boundary faces, ...}

\variab{rtp}{rtp(ncelet,nvar)}{ra}{Array storing the values of the solved
variables at the current time step}

\variab{rtpa}{rtpa(ncelet,nvar)}{ra}{Array storing the values of the solved
variables at the previous time step}

\bigskip

\underline{About \texttt{rtp} and \texttt{rtpa}}

The indexes allowing to mark out the different variables (from 1 to
\texttt{nvar}) are integers available in a ``common'' file called
\texttt{numvar.h}. Some solved variables (pressure, velocity, turbulence)
depend on the considered phase, and the index which refers to it is then a
array of size \texttt{nphsmx}, the maximum number of phases.

For example, \texttt{ipr(iphas)} refers to the variable ``pressure'' of
the phase \texttt{iphas} (with 1$\leqslant$iphas$\leqslant$nphas):
the pressure of the phase \texttt{iphas} in the cell \texttt{iel}
at the current time step is therefore \texttt{rtp(iel,ipr(iphas))}.

The list of integers referring to solved variables is given below. These
variable index-numbers are not only used for the \texttt{rtp} and
\texttt{rtpa} arrays, but also for some arrays of variable associated options
(for instance, \texttt{blencv(ik(iphas))} is the percentage of second-order
convective scheme for the turbulent energy of
the phase \texttt{iphas} when a corresponding turbulent model is used).

\begin{list}{$\bullet$}{}
\item \texttt{ipr(iphas)}\index{\texttt{ipr}}: pressure
\footnote{\texttt{ipr(iphas)} corresponds to a
reduced pressure, from which the standard hydrostatic pressure has be
deduced. The total pressure is stored in the PROPCE array}.
\item \texttt{iu(iphas)}\index{\texttt{iu}}: velocity along the X axis.
\item \texttt{iv(iphas)}\index{\texttt{iv}}: velocity along the Y axis.
\item \texttt{iw(iphas)}\index{\texttt{iw}}: velocity along the Z axis.
\item \texttt{ik(iphas)}\index{\texttt{ik}}: turbulent energy, in $k-\varepsilon$,
$k-\omega$ modeling or v2f ($\varphi$-model) modeling.
\item \texttt{ir11(iphas)}\index{\texttt{ir11}}: Reynolds stress R11, in
      $R_{ij}-\varepsilon$ or SSG modeling.
\item \texttt{ir22(iphas)}\index{\texttt{ir22}}: Reynolds stress R22, in
      $R_{ij}-\varepsilon$ or SSG modeling.
\item \texttt{ir33(iphas)}\index{\texttt{ir33}}: Reynolds stress R33, in
      $R_{ij}-\varepsilon$ modeling.
\item \texttt{ir12(iphas)}\index{\texttt{ir12}}: Reynolds stress R12, in
      $R_{ij}-\varepsilon$ modeling.
\item \texttt{ir13(iphas)}\index{\texttt{ir13}}: Reynolds stress R13, in
      $R_{ij}-\varepsilon$ modeling.
\item \texttt{ir23(iphas)}\index{\texttt{ir23}}: Reynolds stress R23, in
      $R_{ij}-\varepsilon$ modeling.
\item \texttt{iep(iphas)}\index{\texttt{iep}}: turbulent dissipation in $k-\varepsilon$,
$R_{ij}-\varepsilon$ or v2f ($\varphi$-model) modeling.
\item \texttt{iomg(iphas)}\index{\texttt{iomg}}: Specific dissipation rate $\omega$, in
$k-\omega$ SST modeling.
\item \texttt{iphi(iphas)}\index{\texttt{iphi}}: variable $\varphi=\overline{v^2}/k$ in v2f ($\varphi$-model).
\item \texttt{ifb(iphas)}\index{\texttt{ifb}}: variable $\overline{f}$ in v2f ($\varphi$-model).
\item \texttt{isca(j)}\index{\texttt{isca}}: scalar j(1$\leqslant$j$\leqslant$nscal).
\end{list}

\bigskip

Concerning the solved scalar variables (apart from the variables
pressure, $k$, $\varepsilon$, $R_{ij}$, $\omega$, $\varphi$,
$\overline{f}$), the following are highly important:
\begin{list}{-}{}
\item The designation ``scalar'' refers to scalar variables which are
      solution of an advection equation, apart from the variables of the
      turbulence model  ($k$, $\varepsilon$, $R_{ij}$, $\omega$,
      $\varphi$, $\overline{f}$): for instance the temperature, scalars
      which may be passive or not, ``user'' or not. The mean value of
      the square of the fluctuations of a ``scalar'' is a
      ``scalar'', too. The scalars may be divided into two groups:
      \texttt{nscaus} ``user'' scalars and \texttt{nscapp}
      ``specific physics'' scalars, with
      \texttt{nscal=nscaus+nscapp}. \texttt{nscal} must be inferior or
       equal to \texttt{nscamx}.
\item The phase related to the scalar \texttt{j} is
      \texttt{iphsca(j)}\index{\texttt{iphsca}}.
\item The \texttt{j}$^{\text{th}}$ user scalar is, in
      the whole list of the \texttt{nscal} scalars, the scalar number
      \texttt{j}. In the list of the \texttt{nvar} solved variables, it
      corresponds to the variable number \texttt{isca(j)},
      its value in the cell \texttt{iel} at the current time step is given by
      \texttt{rtp(iel,isca(j)}).
\item The \texttt{j}$^{\text{th}}$ scalar related to a specific physics is, in
      the whole list of the \texttt{nscal} scalars, the scalar number
      \texttt{iscapp(j)}. In the list of the \texttt{nvar} solved variables, it
      corresponds to the variable number
      \texttt{isca(iscapp(j)})\index{\texttt{iscapp}},
      its value in the cell \texttt{iel} at the current time step is given by
      \texttt{rtp(iel,isca(iscapp(j)))}.

\item The temperature (or the enthalpy) is the scalar number
      \texttt{iscalt(iphas)}\index{iscalt} in the list of the \texttt{nscal}
      scalars. It corresponds to the variable number \texttt{isca(iscalt(iphas))}
      and its value in the cell \texttt{iel} is
      \texttt{rtp(iel,isca(iscalt(iphas)))}. if there is no thermal scalar,
      \texttt{iscalt(iphas)} is equal to -1.
\item A ``user'' scalar number \texttt{j} may represent the average of the
      square of the fluctuations of a scalar \texttt{k} ({\em i.e.} the average
      $\overline{\varphi^\prime\varphi^\prime}$ for a fluctuating scalar
      $\varphi$ ). This can be made either {\em via} the
      interface or by indicating \texttt{iscavr(j)=k}\index{\texttt{iscavr}} in
      \texttt{usini1} (if the scalar in question is not a ``user''
      scalar, the selection is made automatically). For instance, if \texttt{j}
      and \texttt{k} are ``user'' scalars, the variable $\varphi$ corresponding
      to \texttt{k} is the variable number \texttt{isca(k)=isca(iscavr(j))},
      and its value in the cell \texttt{iel} is \\
      \texttt{rtp(iel,isca(k))=rtp(iel,isca(iscavr(j)))}. \\
The variable corresponding to the mean value of the square of the
      fluctuations\footnote{it is really
      $\overline{\varphi^\prime\varphi^\prime}$, and not
      $\displaystyle\sqrt{\overline{\varphi^\prime\varphi^\prime}}$} is
      the variable number \texttt{isca(j)} and its value in the cell \texttt{iel}
      is \texttt{rtp(iel,isca(j))}.
\end{list}

\bigskip

\underline{About \texttt{propce}, \texttt{propfa} and \texttt{propfb}}
In \CS, the physical properties\footnote{other variables are stored in the
arrays \texttt{propce}, \texttt{propfa} and \texttt{propfb}. They are not
``physical properties'' strictly speaking, but it is convenient to have them
in the same array as the proper physical properties} are stored in the
\texttt{propce}, \texttt{propfa} and \texttt{propfb} arrays.
Some properties, like the density, are only stored for cells and boundary
faces. Some, like the mass flux, are only stored at the interior and boundary
faces. To avoid having different index numbers for a physical property,
depending on the array it is used in, the following structure is used in \CS:

\begin{list}{-}{}

\item All the properties (used or not) have a unique and distinct index-number,
given automatically by the code and stored in an integer or an integer array
(its size may be the maximum number of phases, the maximum
number of scalars or the maximum number of variables).

\item The indexes referring  to the different properties stored in the
\texttt{prop{\bf xx}} arrays are given respectively by the following integer arrays:

\variab{ipproc}{ipproc(npromx)}{ia}{Rank \texttt{i} in \texttt{propce(.,i)} of the
properties defined at the cell centers}

\variab{ipprof}{ipprof(npromx)}{ia}{Rank \texttt{i} in \texttt{propfa(.,i)} of the
properties defined at the internal faces}

\variab{ipprob}{ipprob(npromx)}{ia}{Rank \texttt{i} in \texttt{propfb(.,i)} of the
properties defined at the boundary faces}

\end{list}

For instance, the index number corresponding to the density of the phase
\texttt{iphas} is \texttt{irom(iphas)}.\\
In the list of the properties defined at the cell center, the density of
the phase \texttt{iphas} is therefore the \texttt{ipproc(irom(iphas))}$^{\text{th}}$
property: its value at the center of the cell \texttt{iel} is given by \\
\texttt{prop{\bf ce}(iel,ippro{\bf c}(irom(iphas)))}.\\
In the same way, in the list of the properties defined at the boundary
faces, the density of the phase \texttt{iphas} is the
\texttt{ipprob(irom(iphas)))}$^{\text{th}}$ property: its value at the boundary
face is given by \\
\texttt{prop{\bf fb}(iel,ippro{\bf b}(irom(iphas)))}

The list of properties accessible in the PROPxx arrays is given below (this does
not include the properties linked to the specific physics modules):

\variab{irom}{irom(nphsmx)}{ia}{For each phase, property number
corresponding to the density ({\em i.e.} $\rho$ in $kg.m^{-3}$)\\
stored at the cells and the boundary faces}

\variab{iroma}{iroma(nphsmx)}{ia}{For each phase, property number
corresponding to the density ({\em i.e.} $\rho$ in $kg.m^{-3}$) at the
previous time step, in the case of a second-order extrapolation in time\\
stored at the cells and the boundary faces}

\variab{iviscl}{iviscl(nphsmx)}{ia}{For each phase, property number
corresponding to the fluid molecular dynamic viscosity ({\em i.e.} $\mu$ in
$kg.m^{-1}.s^{-1}$)\\
stored at the cells}

\variab{ivisla}{ivisla(nphsmx)}{ia}{For each phase, property number
corresponding to the fluid molecular dynamic viscosity ({\em i.e.} $\mu$
in $kg.m^{-1}.s^{-1}$) at the previous time step, in the case of a
second-order extrapolation in time\\
stored at the cells}

\variab{ivisct}{ivisct(nphsmx)}{ia}{For each phase, property number
corresponding to the fluid turbulent dynamic viscosity ({\em i.e.}
$\mu_t$ in $kg.m^{-1}.s^{-1}$)\\
stored at the cells}

\variab{ivista}{ivista(nphsmx)}{ia}{For each phase, property number
corresponding to the fluid turbulent dynamic viscosity ({\em i.e.}
$\mu_t$ in $kg.m^{-1}.s^{-1}$) at the previous time step, in the case of a
second-order extrapolation in time\\
stored at the cells}

\variab{icp}{icp(nphsmx)}{ia}{For each phase,  property number
corresponding to the specific heat, in case where it is variable
({\em i.e.} $C_p$ in $m^2.s^{-2}.K^{-1}$). See note below\\
stored at the cells}

\variab{icpa}{icpa(nphsmx)}{ia}{For each phase,  property number
corresponding to the specific heat, in case where it is variable
({\em i.e.} $C_p$ in $m^2.s^{-2}.K^{-1}$), at the previous time step,
in the case of a second-order extrapolation in time. See note below\\
stored at the cells}

\variab{itsnsa}{itsnsa(nphsmx)}{ia}{For each phase, in the case of a
calculation run with a second-order discretisation in time with
extrapolation of the source terms, property number corresponding to the
source term of Navier-Stokes at the previous time step ($kg.m^{-1}.s^{-2}$)\\
stored at the cells}

\variab{itstua}{itstua(nphsmx)}{ia}{For each phase, in the case of a
calculation run with a second-order discretisation in time with
extrapolation of the source terms, property number corresponding to the
source terms of the turbulence at the previous time step\\
stored at the cells}

\variab{itssca}{itssca(nphsmx)}{ia}{For each phase, in the case of a
calculation run with a second-order discretisation in time with
extrapolation of the source terms, property number corresponding to the
source terms of the equations solved for the scalars at the previous
time step ($kg.m^{-1}.s^{-2}$)\\
stored at the cells}

\variab{iestim}{iestim(nestmx,nphsmx)}{ia}{For each phase, property
number for the \texttt{nestmx} error estimators for Navier-Stokes. The estimators
currently available are \texttt{iestim(iespre\index{iespre},iphas)},\\
\texttt{iestim(iesder\index{iesder},iphas)},
\texttt{iestim(iescor\index{iescor},iphas)},
\texttt{iestim(iestot\index{iestot},iphas)}
stored at the cells}

\variab{ifluma}{ifluma(nvarmx)}{ia}{Property number corresponding to the
mass flow associated with each variable ({\em i.e.} for each face
of surface $S$, $\rho \vect{u} \,.\,\vect{S}$ in $kg.s^{-1}$). It
must be noticed that the mass flows are associated with the
variables and not with the phases. This allows to have a distinct
convective flow for each scalar.\\
stored at the internal faces and boundary faces}

\variab{ifluaa}{ifluaa(nvarmx)}{ia}{Property number corresponding to the
mass flow associated with each variable at
the previous time step, in the case of a second-order extrapolation in time\\
stored at the internal faces and boundary faces}

\variab{ivisls}{ivisls(nscamx)}{ia}{Property number corresponding to the
diffusivity of scalars for which it is variable ({\em i.e.}$\displaystyle
\frac{\lambda}{C_p}$ for the temperature, in $kg.m^{-1}.s^{-1}$). It must
be noticed that the diffusivity is associated with the scalars rather
than with the variables. See note below\\
stored at the cells}

\variab{ivissa}{ivissa(nscamx)}{ia}{Property number corresponding to the
diffusivity of scalars for which it is variable ({\em i.e.}$\displaystyle
\frac{\lambda}{C_p}$ for the temperature, in $kg.m^{-1}.s^{-1}$) at the
previous time step, in the case of a second-order extrapolation in time\\
stored at the cells}

\variab{ismago}{ismago(nphsmx)}{ia}{For each phase, property number
corresponding to the variable $C$ of the dynamic model, {\em i.e}
so that $\mu_t=\rho C\overline{\Delta}^2\sqrt{2S_{ij}S_{ij}}$ (with the
notations of \cite{benhamadouche01}). $C$ corresponds to $C_s^2$ in the
classical model of Smagorinsky\\
stored at the cells}

\variab{icour}{icour(nphsmx)}{ia}{For each phase, CFL number in each cell at the
present time step\\
stored at the cells}

\variab{ifour}{ifour(nphsmx)}{ia}{For each phase, Fourier number in each cell at
the present time step\\
stored at the cells}

\variab{iprtot}{iprtot(nphsmx)}{ia}{For each phase\footnote{Although the data
structure of \CS allows multi-phase variables,  the algorithm does not allow
more than one pressure}, total pressure in each cell\\
stored at the cells}

\variab{ivisma}{ivisma(1 or 3)}{ia}{When the ALE method for deformable meshes is
activated, \texttt{ivisma} corresponds to the ``mesh viscosity'', allowing to limit
the deformation in certain areas. This mesh viscosity can be isotropic or be
taken as a diagonal tensor (depending on the value of the parameter
\texttt{iortvm}\index{\texttt{iortvm}}.\\
stored at the cells}

\variab{icmome}{icmome(nbmomx)}{ia}{Property number corresponding to
the time averages defined by the user. More precisely, it is not the time
average that is stored, but a summation over time (the division by the cumulated
duration is done just before the results are written)\\
stored at the cells}

\variab{icdtmo}{icdtmo(nbmomx)}{ia}{Property number corresponding to the
cumulated duration associated with each time average defined by the
user, when this duration is not spatially uniform (see note below)\\
stored at the cells}


\minititre{Note: Variable physical properties}\label{provar}
Some physical properties such as specific heat or diffusivity are often
constant (choice made by the user).
In that case, in order to limit the necessary memory, these
properties are stored as a simple real number rather than in a domain-sized
array of reals.
\begin{list}{$\bullet$}{}
\item It is the case for the specific heat $C_p$.
\begin{list}{-}{}
\item If $C_p$ is constant for the phase \texttt{iphas}, it can be specified in
      the interface or by indicating \texttt{icp(iphas)=0} in \texttt{usini1},
      and the property will be stored in the real number \texttt{cp0(iphas)}.
\item If $C_p$ is variable, it can be specified in the interface or by
      indicating \texttt{icp(iphas)=1} in \texttt{usini1}. The code will then
      modify this value to make \texttt{icp(iphas)} refer to the effective
      property number corresponding to the specific heat of the phase
      \texttt{iphas}, in a way which is transparent for the user. For each cell
      \texttt{iel}, the value of $C_p$ is then given in \texttt{usphyv} and
      stored in the array \texttt{propce(iel,ipproc(icp(iphas)))}.
\end{list}
\item It is the same for the diffusivity $K$ of each scalar \texttt{iscal}.
\begin{list}{-}{}
\item If $k$ is constant, it can be specified in the interface or by
      indicating \texttt{ivisls(iscal)=0} in \texttt{usini1}, and the property
      will be stored in the real number \texttt{visls0(iscal)}.
\item If $k$ is variable, it can be specified in the interface or by
      indicating \texttt{ivisls(iscal)=1} in \texttt{usini1}. The code will then
      modify this value to make \texttt{ivisls(iscal)} refer to the effective
      property number corresponding to the diffusivity of the scalar
      \texttt{iscal}, in a way which is transparent for the user. For each cell
      \texttt{iel}, the value of $k$ is then given in \texttt{usphyv} and stored
      in the \texttt{propce(iel,ipproc(ivisls(iscal)))} array.
\end{list}
\end{list}


\minititre{Note: cumulated duration associated with the averages
defined by the user}\label{prg_moyennes}
The cumulated duration associated with the calculation of a time averages
defined by the user is often a spatially uniform value. In this case, it
is stored in a simple real number: for the mean value \texttt{imom}, it is the
real number \texttt{dtcmom(-idtmom(imom))}\index{\texttt{dtcmom}}%
\index{\texttt{idtmom}} (\texttt{idtmom(imom)} is negative in this case).\\
When this cumulated duration is not spatially uniform (for instance in the case
of a spatially variable time step), it is stored in \texttt{propce}. It must be
noted that the cumulated duration associated with the calculation of
the average \texttt{imom} is variable in space if \texttt{idtmom(imom)} is strictly
positive. The number of the associated property in \texttt{propce} is then
\texttt{icdtmo(idtmom(imom))}\index{\texttt{icdtmo}}. For instance, for the
average \texttt{imom}, the cumulated duration in the cell \texttt{iel} will be
\texttt{propce(iel,icdtmo(idtmom(imom)))}.\\
The user may have a look to the example given in \texttt{usproj} to know
how to calculate a time averages in a particular cases (printing of extreme
values, writing of results, ...).

\bigskip

Two other variables, \texttt{hbord} and \texttt{tbord}, should be noted here,
although they are relatively local (they appear only in the treatment of the
boundary conditions) and are used only by developers.

\variab{hbord}{hbord(nfabor)}{ra}{Array of the exchange coefficient for
temperature (or enthalpy) at the boundary faces. The table is allocated only if
\texttt{isvhb}\index{\texttt{isvhb}} is set to 1 in \texttt{tridim}, which is
done automatically, but only if the coupling with \syrthes or the 1D thermal
wall module are activated.}

\variab{tbord}{tbord(nfabor)}{ra}{Temperature (or enthalpy) at the boundary
faces\footnote{It is the physical temeprature at the boundary faces, not the
boundary condition for temperature. See \cite{theory} for more details on
boundary conditions}. The table is allocated only if
\texttt{isvtb}\index{\texttt{isvtb}} is set to 1 in \texttt{tridim}, which is
done automatically but only if the coupling with \syrthes or the 1D thermal
wall module are activated.}

Tables \texttt{hbord} and \texttt{tbord} are of size \texttt{nfabor},
although they concern only the wall boundary faces.



%%%ICI%%%%%%%%%%%%%%%

%==================================
\subsection{Variables related to the numerical methods}
%==================================

The main numerical variables and ``pointers''\footnote{As for the
geometrical variables, some variables may be accessed to directly in
sections of the unidimensional macro-arrays IA (for the integers) and RA
(for the real numbers) which are present as arguments in every
subroutine (apart from a few ones of very low level). The number of the
first position of these sections in IA and RA is indicated by an integer
stored in a ``common''. These integers are called ``pointers''} are
displayed below.

\minititre{Boundary conditions}

\variab{coefa}{coefa(nfabor,*)}{ra}{Boundary conditions: see note 2}

\variab{coefb}{coefb(nfabor,*)}{ra}{Boundary conditions: see note 2}

\variab{iclrtp}{iclrtp(nvarmx,2)}{ia}{For each variable \texttt{ivar}
(1$\leqslant$ivar$\leqslant$nvar$\leqslant$nvarmx), rank in \texttt{coefa} and
\texttt{coefb} of the boundary conditions. See note 2}

\variab{icoef}{icoef}{i}{Rank in \texttt{iclrtp} of the rank in \texttt{coefa}
and \texttt{coefb} of the ``standard'' boundary conditions. See note 2}

\variab{icoeff}{icoeff}{i}{Rank in \texttt{iclrtp} of the rank in \texttt{coefa}
and \texttt{coefb} of the ``flow'' type boundary conditions, reserved for
developers. See note 2}

\variab{ifmfbr}{ifmfbr(nfabor)}{ia}{Family number of the boundary
faces. See note 1}

\variab{iprfml}{iprfml(nfml,nprfml)}{ia}{Properties of the
families of referenced entities. See note 1}

\variab{iisymp}{iisymp}{i}{Integer giving the rank in \texttt{ia} of the first
element of the section allowing to mark out the ``wall'' (\texttt{itypfb=iparoi}
or \texttt{iparug})
or ``symmetry'' (\texttt{itypfb=isymet}) boundary faces in order to prevent the
mass flow (these faces are impermeable). For instance, for the phase
\texttt{iphas}, if the face \texttt{ifac} is a wall or symmetry face,
\texttt{ia(iismph+ifac-1)=0} (with \texttt{iismph=iisymp+nfabor*(iphas-1))}.\\
Otherwise \texttt{ia(iisymp+ifac-1)=1}. \\
In some subroutines, an array called \texttt{isympa(nfabor)}\index{\texttt{isympa}}
allows to simplify the coding with \texttt{isympa(ifac)=ia(iismph+ifac-1)}}

\variab{iitrif}{iitrif}{i}{In \texttt{ia}, pointer to \texttt{itrifb}}

\variab{iitypf}{iitypf}{i}{In \texttt{ia}, pointer to \texttt{itypfb}}

\variab{itrifb}{itrifb(nfabor,nphas)}{ia}{Indirection array allowing to
sort the boundary faces according to their boundary condition type \texttt{itypfb}}

\variab{itypfb}{itypfb(nfabor,nphas)}{ia}{Boundary condition type at the
boundary face \texttt{ifac} for the phase \texttt{iphas} (see user subroutine
\texttt{usclim})}

\variab{iuetbo}{iuetbo}{i}{In \texttt{ra}, pointer to \texttt{uetbor}, used to
store the friction velocity at the wall, in the case of a LES calculation with van
Driest-wall damping}

\minititre{Distance to the wall}

\variab{iifapa}{iifapa(nphsmx)}{ia}{For each phase, the pointer in \texttt{ia}
which  marks out the number of the wall face(type \texttt{itypfb=iparoi} or
\texttt{iparug}) which is closest  to the center of a given volume when necessary
($R_{ij}-\varepsilon$ with wall echo, LES with van Driest-wall damping,
or SST $k-\omega$ turbulence model) and when \texttt{icdpar=2}.
The number of the wall face (for the phase \texttt{iphas}) which is the closest to
the center of the cell \texttt{iel} is therefore \texttt{ia(iifapa(iphas)+iel-1)}. This calculation method is not compatible with parallelism and periodicity}

\variab{idipar}{idipar}{i}{For each phase, pointer in \texttt{ra} to the section
allowing to mark out the distance between the center of a given volume and the
closest wall, when it is necessary ($R_{ij}-\varepsilon$ with wall echo,
LES with van Driest-wall damping, or SST $k-\omega$ turbulence model)
and when \texttt{icdpar=1}. The distance between the center of the cell
\texttt{iel} and the closest wall is therefore \texttt{ra(idipar+iel-1)}}

\variab{iyppar}{iyppar}{i}{For each phase, pointer in \texttt{ra} to the section
allowing to mark out the adimensional distance $y^+$ between a given
volume and the closest wall, when it is necessary (LES with van
Driest-wall damping) and when \texttt{icdpar=1}. The adimensional distance $y^+$
between the center of the cell \texttt{iel} and the closest wall is therefore
\texttt{ra(iyppar+iel-1)}}

\minititre{Pressure drops}

\variab{iicepd}{iicepd(nphsmx)}{ia}{For each phase \texttt{iphas}, pointer in
\texttt{ia} to \\
\texttt{icepdc(ncepdc(iphas))}, array allowing to mark out the index-numbers of
the \\
\texttt{ncepdc(iphas)} cells in which a pressure drop is imposed. \\
The number of these cells is therefore given by
\texttt{icepdc(ii)=ia(iicepd(iphas)+ii-1)}, with
1$\leqslant$\texttt{ii}$\leqslant$\texttt{ncepdc(iphas)}. See the user subroutine
\texttt{uskpdc}}

\variab{icepdc}{icepdc(ncepdc(iphas))}{ia}{Number of the \texttt{ncepdc(iphas)}
cells in which a pressure drop is imposed. See \texttt{iicepd} and the user
subroutine \texttt{uskpdc}}

\variab{ickupd}{ickupd(nphsmx)}{ia}{For each phase \texttt{iphas}, pointer in
\texttt{ra} to \\
\texttt{ckupdc(ncepdc(iphas),6)}, array allowing to mark out the\\
coefficients of the pressure drop tensor of the
\texttt{ncepdc(iphas)} cells in which a pressure drop is imposed. See the user
subroutine \texttt{uskpdc}}

\variab{ckupdc}{ckupdc(ncepdc(iphas),6)}{ra}{Value of the
coefficients of the pressure drop tensor of the
\texttt{ncepdc(iphas)} cells in which a pressure drop is imposed.
See \texttt{ickpdc} and the user subroutine \texttt{uskpdc}}

\variab{ncepdc}{ncepdc(nphsmx)}{ia}{For each phase, number of cells in
which a pressure drop is imposed. See the user subroutine \texttt{uskpdc}}


\minititre{Mass sources}

\variab{iicesm}{iicesm(nphsmx)}{ia}{For each phase \texttt{iphas}, pointer in
\texttt{ia} to \\
\texttt{icetsm(ncetsm(iphas)}, array allowing to mark out the numbers of the \\
\texttt{ncetsm(iphas)} cells in which a source of mass is imposed. The number of
these cells is therefore given by \texttt{icetsm(ii)=ia(iicesm(iphas)+ii-1)}, with
1$\leqslant$\texttt{ii}$\leqslant$\texttt{ncetsm(iphas)}. See the user subroutine
\texttt{ustsma}}

\variab{iitpsm}{iitpsm(nphsmx)}{ia}{For each phase \texttt{iphas}, pointer in
\texttt{ia} to \texttt{itypsm} (type of mass source for each variable).
See \texttt{itypsm} and the user subroutine \texttt{ustsma}}

\variab{icetsm}{icetsm(ncetsm(iphas))}{ia}{Number of the \texttt{ncetsm(iphas)}
cells in which a mass source term is imposed. See \texttt{iicesm} and the user
subroutine \texttt{ustsma}}

\variab{ismace}{ismace(nphsmx)}{ia}{For each phase \texttt{iphas}, pointer in
\texttt{ra} to \texttt{smacel} (mass source term and if necessary injection value
for every variable apart from pressure). See \texttt{smacel} and the user subroutine
\texttt{ustsma}}

\variab{itypsm}{itypsm(ncetsm(iphas),nvar)}{ia}{Type of mass source term
for each variable (0 for an injection at ambient value, 1 for an
injection at imposed value). See the user subroutine \texttt{ustsma}}

\variab{ncetsm}{ncetsm(nphsmx)}{ia}{For each phase, number of cells with
mass sources. See the user subroutine \texttt{ustsma}}

\variab{smacel}{smacel(ncetsm(iphas),nvar)}{ra}{Value of the mass source
term for pressure. For the other variables, eventual imposed injection
value. See the user subroutine \texttt{ustsma}}

\minititre{Wall 1D thermal module}

\variab{nfpt1d}{nfpt1d}{i}{Number of boundary faces which are coupled
with a wall 1D thermal module. See the user subroutine \texttt{uspt1d}}

\variab{iifpt1}{iifpt1}{i} {In \texttt{ia}, pointer to \texttt{ifpt1d(nfpt1d)},
array allowing to mark out the numbers of the \texttt{nfpt1d} boundary faces
which are coupled with a wall 1D thermal module. The number of these boundary
faces is therefore given by \texttt{ifpt1d(ii)=ia(iifpt1+ii-1)}, with
1$\leqslant$\texttt{ii}$\leqslant$\texttt{nfpt1d}.
See the user subroutine \texttt{uspt1d}}

\variab{inppt1}{inppt1}{i}{In \texttt{ia}, pointer to \texttt{nppt1d(nfpt1d)},
array giving the number of discretisation cells in the 1D wall for the
\texttt{nfpt1d} boundary faces which are coupled with a wall 1D thermal module. The
number of cells for these boundary faces is therefore given by
\texttt{nppt1d(ii)=ia(inppt1+ii-1)}, with
1$\leqslant$\texttt{ii}$\leqslant$\texttt{nfpt1d}. See
the user subroutine \texttt{uspt1d}}

\variab{ieppt1}{ieppt1}{i}{In \texttt{ia}, pointer to \texttt{eppt1d(nfpt1d)},
array giving the thickness of the 1D wall for the \texttt{nfpt1d} boundary faces
which are coupled with a wall 1D thermal module. The wall thickness for these
boundary faces is therefore given by \texttt{eppt1d(ii)=ia(ieppt1+ii-1)}, with
1$\leqslant$\texttt{ii}$\leqslant$\texttt{nfpt1d}. See the user subroutine
\texttt{uspt1d}}

\minititre{Others}

\variab{dt}{dt(ncelet)}{ra}{Value of the time step}

\variab{ifmcel}{ifmcel(ncelet)}{ia}{Family number of the elements. See note 1}

\variab{is2kw}{is2kw(nphsmx)}{ia}{For each phase \texttt{iphas}, pointer in
\texttt{ra} to the section storing the square of the norm of the deformation
rate tensor. In the cell \texttt{iel}, for the phase \texttt{iphas},
$S^2=2S_{ij}S_{ij}$
is therefore given by \texttt{ra(is2kw(iphas)+iel-1)}. This array is defined only
when the phase \texttt{iphas} is treated with the SST $k-\omega$ turbulence model}

\variab{idvukw}{idvukw(nphsmx)}{ia}{For each phase \texttt{iphas}, pointer in
\texttt{ra} to the section storing the divergence of the velocity. In the
cell \texttt{iel}, for the phase \texttt{iphas}, $div(\vect{u})$ is therefore
given by \texttt{ra(idvukw(iphas)+iel-1)}. This array is defined only when the
phase \texttt{iphas} is treated with the SST $k-\omega$ turbulence model
(because in this case it may be calculated at the same time as $S^2$)}

\variab{ngrmmx}{ngrmmx}{i}{upper limit of the number of grid levels
in the case of a multigrid solving (see \texttt{ngrmax})}

\variab{ia}{ia(longia)}{ia}{Integer work array}

\variab{ra}{ra(longra)}{ra}{Real work array}


\minititre{Note: boundary conditions}
The boundary conditions in \CS boil down to determine a value for the
current variable $\phi$ at the boundary faces, that is to say $\phi_f$,
value expressed as a function of $\phi_{I'}$, value of $\phi$ in I',
projection of the center of the adjacent cell on the straight line
perpendicular to the boundary face and crossing its center:
$\phi_f=A_{\phi,f}+B_{\phi,f}\phi_{I'}$.  \\
For a face \texttt{ifac}, the pair of coefficients $A_{\phi,f},B_{\phi,f}$ is
stored in \texttt{coefa(ifac,iclvar)} and
\texttt{coefb(ifac,iclvar)}, where the integer \texttt{iclvar=iclrtp(ivar,ijcl)}
determines the rank in \texttt{coefa} and \texttt{coefb} of the set of boundary
conditions of the variable \texttt{ivar}. \\
The second index of the array \texttt{iclrtp} allows to have several sets of
boundary conditions for each variable. The ``standard'' boundary
conditions are determined by \texttt{ijcl=icoef}, where \texttt{icoef} is a
parameter which is fixed automatically by the code, and can be accessed to in the
``common'' file \texttt{numvar.h}. More specificic or advanced boundary
conditions can be accessed to with \texttt{ijcl=icoeff}. \\
In practice, for a variable \texttt{ivar} whose value $\phi_{I'}$ in a
boundary cell is known, the value at the corresponding boundary face
\texttt{ifac} is: \\
\mbox{$\phi_f$=\texttt{coefa(ifac,iclvar)+coefb(ifac,iclvar)} $\phi_{I'}$}
with \texttt{iclvar=iclrtp(ivar,icoef)}


%==================================
\subsection{User arrays}
%==================================
The code allows to define two user arrays, one integer array and one
real array. The default size of these arrays is zero, and may be changed
in \texttt{usini1}. The two arrays are then passed as arguments in every
user subroutine of the code. For instance, a local variable calculated during
the determination of the physical properties (user subroutine
\texttt{usphyv}) may be stored in these arrays and sent to the
post-processor at the end of the time step (user subroutine \texttt{usvpst}).

\variab{nituse}{nituse}{i}{Size of the user integer array}

\variab{nrtuse}{nrtuse}{i}{Size of the user real array}

\variab{ituser}{ituser(nituse)}{ia}{User integer array}

\variab{rtuser}{rtuser(nrtuse)}{ra}{User real array}

%==================================
\subsection{Developer arrays}
%==================================
The code allows to define two developer arrays (similar to the user
arrays \texttt{ituser} and \texttt{rtuser}), one integer array a one real array.
The default size of these arrays is zero, and may be changed in
\texttt{ustbus}. The two arrays are then passed as arguments in the rest
of the code. They are designed to be used during the transitory
development phases, in order to ease the tests (transfer of pieces of
informations without consequence on the arguments of the subroutines).

\variab{nideve}{nideve}{i}{Size of the developer integer array}

\variab{nrdeve}{nrdeve}{i}{Size of the developer real array}

\variab{idevel}{idevel(nideve)}{ia}{Complementary integer array, used
during development and test phases}

\variab{rdevel}{rdevel(nrdeve)}{ra}{Complementary real array, used
during development and test phases}

%==================================
\subsection{Parallelism and periodicity}
%==================================

Parallelism is based on domain partitioning: each processor is assigned
a part of the domain, and data for cells on parallel boundaries
is duplicated on neigboring processors in corresponding ``ghost'',
or ``halo'' cells (both terms are used interchangeably). Values in
these cells may be accessed just the same as values in regular cells.
Communication is only required when cell values are modified
using values from neighboring cells, as the values in the ``halo'' can
not be computed correctly (since the halo does not have access to all
its neighbors), so halo values must be updated by copying values from
the corresponding cells on the neighboring processor.

Compared to other tools using a similar system, a specificity of
\CS is the separation of the halo in two parts: a standard part,
containing cells shared through faces on parallel boundaries, and an
extended part, containing cells shared through vertices, which is
used mainly for least squares gradient reconstruction using an
extended neighborhood. Most updates need only operate on the standard
halo, requiring less data communication than those on the extended halos.

\begin{figure}[!h]
\centerline{
\includegraphics*[width=14cm]{halo}}
\caption{Parallel domain partitioning: halos}\label{Fig_haluile}
\end{figure}

Periodicity is handled using the same halo structures as parallelism,
with an additional treatment for vector and coordinate values: updating
coordinates requires applying the periodic transformation to the copied
values, and in the case of rotation, updating vector and tensor values
also requires appying the rotation transformation.
Ghost cells may be parallel, periodic, or both. The example of a pump
combining parallelism and periodicity is given figure \ref{Fig_parperio_pump}.
In this example, all periodic boundaries match with boundaries on
the same domain, so halos are either parallel or periodic.

\begin{figure}[!h]
\centerline{
\includegraphics*[width=5.5cm]{rota_perio_parall}}
\caption{Combined parallelism and periodicity}\label{Fig_parperio_pump}
\end{figure}

\label{prg_paralperio}
{\bf Activation}

Parallelism and periodicity are activated by means of the launch script
in the standard cases:
\begin{list}{$\bullet$}{}

\item On clusters with PBS batch systems, the launching of a parallel run
      requires to complete the \texttt{PBS} batch cards located in the
      beginning of \texttt{runcase}, and particularly to set the number of
      physical nodes (\texttt{nodes}) and the number of physical
      processors per node (\texttt{ppn}) wanted. This can be done through
      the Graphical Interface or by editing the \texttt{runcase} file directly.
      The number of processors used for the calculation will then be set
      automatically to the number of processors reserved and the 
      variable \texttt{NUMBER\_OF\_PROCESSORS} can be left empty
      (see also \S\ref{prg_runcase}).

\item On clusters with LSF batch systems (like the CCRT machines),
      the launching of a parallel run
      requires to complete the \texttt{LSF} batch cards located in the
      beginning of \texttt{runcase}, and particularly to set the
      number of processors (\texttt{\#BSUB -n}) wanted and the limit CPU
      time (\texttt{\#BSUB -W}). As for now, this can only be done
      by editing the \texttt{runcase} file directly.
      The number of processors used for the calculation will then be set
      automatically to the number of processors reserved and the 
      variable \texttt{NUMBER\_OF\_PROCESSORS} can be left empty
      (see also \S\ref{prg_runcase}).

\item On clusters with other batch systems, \texttt{runcase} file may have to
      be modified manually. Please do not hesitate to contact the \CS support
      (saturne-support@edf.fr) so that these modifications can be added to
      the standard launch script to make it more general.

\item Although on batch systems the \texttt{NUMBER\_OF\_PROCESSORS} variable
      in the script (indicating the number of processors used for the
      calculation) is filled automatically to the number of processors
      reserved, the user can still choose to specify another value for it.
      This might only happen in very specific conditions and is not advised,
      as it will probably not be compatible with the batch system. Indeed,
      batch systems forbid to launch a calculation on more processors than the
      number of processors reserved, and some batch systems also forbid to
      launch a calculation on less processors than the number of processors
      reserved (automatic timeout on the idle processors that will stop the
      whole calculation).


\item Periodicity is activated through the Graphical Interface or by completing
      the \texttt{COMMAND\_PERIO} of the launch script \texttt{runcase}.
      The transformation
      allowing to pass from a boundary to the other one must be defined
      (the direction does not matter) and the set of periodic faces
      should be (optional but strongly advised) marked out (for instance
      by means of a color).

\item Periodicity is compatible with parallelism.

\item Periodicity can also work when the periodic boundaries are meshed
      differently (periodicity of non-conforming faces), {\it apart} from
      the case of a 180 degree rotation periodicity with faces coupled
      on the rotation axis.

\item A parallel calculation may be stopped in the same manner as a
      sequential one using a \texttt{ficstp} file (see praragraph
      \ref{prg_ficstp}).

\item The standard pieces of information displayed in the listing
      (marked out with \texttt{'v  '} for the min/max values of the
      variables), \texttt{'c  '} for the data concerning the convergence
      and \texttt{'a  '} for the values before clipping) are global
      values for the whole domain and not related to each processor.

\end{list}

\vspace{0.5cm}
{\bf User subroutines}

The user can notice in a subroutine
\begin{list}{-}{}
\item that the presence of periodicity is tested with the variable
      \texttt{iperio} (=1 if periodicity is activated);
\item that the presence of rotation periodicities is tested with the variable
      \texttt{iperot} (number of rotation periodicities);
\item that running of a calculation in parallel is tested for with the
      variable \texttt{irangp} (\texttt{irangp} is worth -1 in the case of a
      non-parallel calculation and $p-1$ in the case of a parallel calculation,
      $p$ being the number of the current processor)
\end{list}
Attention must be paid to the coding of the user subroutines. If
conventionnal subroutines like \texttt{usini1} or \texttt{usclim}
usually do not cause any problem, some kind of developments are more
complicated. The most usual cases are dealt with below. \\ Examples are
given in the subroutine \texttt{usproj}.
\begin{list}{$\bullet$}{}
\item {\bf Access to information related to neighboring cells in
      parallel and periodic cases}.\\
When periodicity or parallelism are brought into use, some cells of the
      mesh become physically distant from their neighbors. Concerning
      parallelism, the calculation domain is split and distributed
      between the processors: a cell located at the ``boundary'' of a
      given processor may have neighbors on different processors. \\
In the same way, in case of periodicity, the neighboring cells of cells
      adjacent to a periodic face are generally distant. \\
When data concerning neighboring cells are required for the
      calculation, they must first be searched on the other processors
      or on the other edge of periodic frontiers. In order to ease the
      manipulation of these data, they are stored temporarily in virtual
      cells called ``halo'' cells, as can be seen in figure \ref{Fig_haluile}.
It is in particular the case when the following operations are made on a
      variable $A$:
\begin{list}{-}{}
\item calculation of the gradient of $A$ (use of \texttt{grdcel});
\item calculation of an internal face value from the values of $A$  in
      the neighboring cells (use of \texttt{ifacel}).
\end{list}
The variable $A$ needs to be exchanged before these operations can be
      made: to allow it, the subroutines \texttt{parcom} and
      \texttt{percom} need to be called {\underline {\bf in this order}}.

\item {\bf Global operations in parallel mode}.\\
In parallel mode, the user must pay attention during the realisation of
      global operations. The following list is not exhaustive:
        \begin{list}{-}{}
\item calculation of extreme values on the domain (for instance, minimum
      and maximum of some calculation values);
\item test of the existence of a certain value (for instance, do faces
      of a certain color exist ?);
\item verification of a condition on the domain (for instance, is a
      given flow value reached somewhere ?);
\item counting out of entities (for instance, how many cells have
      pressure drops ?);
\item global sum (for instance, calculation of a mass flow or the total
      mass of a pollutant).
      \end{list}
The user may refer to the different examples present in the user
      subroutine \texttt{usproj}. \\
Care should be taken with the fact that the boundaries between
      subdomains consist of {\bf internal} faces shared between
      two processors (these are indeed internal faces, even if they are
      located at a ``processor boundary''). They should not be counted twice
      (once per processor) during global operations using internal faces
      (for instance, counting the internal faces per processor and
      summing all the obtained numbers drives into overevaluing the
      number of internal faces of the initial mesh).

\item {\bf Writing; operations that should be made on one
      processor only in parallel mode}.\\
In parallel mode, the user must pay attention during the writing of
      pieces of information. Writing to the ``listing'' can be done
      simply by using the \texttt{nfecra} logical unit (each processor will write
      to its own ``listing'' file): use
      \texttt{write(nfecra,...}. \\
If the user wants an operation to be done by only one processor (for
      example, open or write a file), the associated instructions must
      be included inside a test on the value of \texttt{irangp} (generally it is
      the processor 0 which realises these actions, and we want the
      subroutine to work in non-parallel mode, too: \texttt{if
      (irangp.le.0) then ...}).
\end{list}


{\bf Some notes about periodicity}

Some particular points should be reminded:
\begin{list}{-}{}
\item rotation periodicity is incompatible with
  \begin{list}{-}{}
  \item semi-transparent radiation,
  \item reinforced velocity-pressure coupling (\texttt{ipucou=1)}.
  \end{list}
\item although it has not been the case so far, potential problems might be met
      in the case of rotation periodicity with the LRR $R_{ij}-\varepsilon$
      model. They would come from the way of taking into account the
      orthotropic viscosity (however, this term usually has a low influence).
\end{list}

%==================================
\subsection{Geometry and particule  arrays
      related to Lagrangian modeling}
%==================================

In this section is given a non-exhaustive list of the main variables
which may be seen by the user in the Lagrangian module. Most of them
should not be modified by the user. They are calculated automatically
from the data. However it may be useful to know their meaning.

\noindent
These variables are listed in the alphabetical index in the end of this
document.

\noindent
The type of each variable is given: integer [i], real number [r],
integer array [ia], real array [ra].

\minititre{Size of the Lagrangian arrays}

\variab{lndnod}{lndnod}{i}{Size of the array \texttt{icocel} concerning the
cells $\rightarrow$ faces connectivity (the faces $\rightarrow$ nodes connectivity
needs to be given to allow the construction of this connectivity. See note 3
of section \ref{prg_dimensions})}

\variab{nbpmax}{nbpmax}{i}{Maximum number of particles
simultaneously acceptable in the calculation domain}

\variab{nvp}{nvp}{i}{Number of variables describing the particles for
which a stochastic differential equation (SDE) is solved}

\variab{nvls}{nvls}{i}{Number of variables describing the supplementary
user particles for which a SDE is solved}

\variab{nvep}{nvep}{i}{Number of real state variables describing the particles}

\variab{nivep}{nivep}{i}{Number of integer state variables describing the particles}

\variab{ntersl}{ntersl}{i}{Number of source terms representing the backward
coupling of the dispersed phase on the continuous phase}

\variab{nvlsta}{nvlsta}{i}{Number of volumetric statistical variables }

\variab{nvlsts}{nvlsts}{i}{Number of supplementary user volumetric
statistical variables}

\variab{nvisbr}{nvisbr}{i}{Number of boundary statistical variables}

\variab{nusbor}{nusbor}{i}{Number of supplementary user boundary statistical
variables}

\variab{nvgaus}{nvgaus}{i}{Number of gaussian random variables}

\minititre{Note: continuous eulerian phase number}
The current version of Lagrangian module is planned to work with only one
eulerian phase. This phase carries inclusions, and source terms of
backward coupling are applied to it, if necessary. The number of this
phase is stored in the variable \texttt{ilphas}\index{\texttt{ilphas}}.
The standard value is \texttt{ilphas = 1}.

\minititre{Lagrangian arrays}

\variab{icocel}{icocel(lndnod)}{ia}{Cells $rightarrow$ internal/boundary faces
connectivity. The numbers of the boundary faces are marked out in \texttt{icocel}
with a negative sign}

\variab{itycel}{itycel(ncelet+1)}{ia}{Array containing the position of
the first face surrounding every cell in the array \texttt{icocel} (see subroutine
\texttt{lagdeb} for more details)}

\variablist{ettp}{ettp(nbpmax,nvp)}{ra}
{Variables forming the state vector related to the particles: either at
the current stage if the Lagrangian scheme is a second-order, or at the
current time step if the scheme is a first-order. These variables are
marked out by ``pointers'' whose value can vary between 1 and \texttt{nvp}:
\begin{list}{$\rightarrow$}{}
\item \texttt{jmp}: particle mass
\item \texttt{jdp}: particle diameter
\item \texttt{jxp}, \texttt{jyp}, \texttt{jzp}: particle coordinates
\item \texttt{jup}, \texttt{jvp}, \texttt{jwp}: particle velocity components
\item \texttt{juf}, \texttt{jvf}, \texttt{jwf}: locally undisturbed fluid flow
      velocity components
\item \texttt{jtp}, \texttt{jtf}: particle and locally undisturbed fluid flow
      temperature (\degresC)
\item \texttt{jcp}: particle specific heat
\item \texttt{jhp}: coal particle temperature (\degresC)
\item \texttt{jmch}: mass of reactive coal of the coal particle
\item \texttt{jmck}: mass of coke of the coal particle
\item \texttt{jvls(ii): ii\textit{th}} supplementary user variable
\end{list}
}

\variab{ettpa}{ettpa(nbpmax,nvp)}{ra}{Variables forming the state vector
related to the particles: either at the previous stage if the Lagrangian
scheme is a second-order, or at the previous time step if the Lagrangian
scheme is a first-order}

\variablist{itepa}{itepa(nbpmax,nivep)}{ia}{Integer state variables
related to the particles. They are marked out by the following ``pointers'':
\begin{list}{$\rightarrow$}{}
\item \texttt{jisor}: Number of the current cell containing the particle; this
      number is reactualised during the trajectography step
\item \texttt{jinch}: Number of the coal particle
\end{list}
}

\variablist{tepa}{tepa(nbpmax,nvep)}{ra}{Real state variables
related to the particles. They are marked out by the following ``pointers'':
\begin{list}{$\rightarrow$}{}
\item \texttt{jrtsp}: particle residence time
\item \texttt{jrpoi}: particle statistic weight
\item \texttt{jrdck}: coal particle shrinking core diameter
\item \texttt{jrd0p}: coal particle initial diameter
\item \texttt{jrr0p}: coal particle initial density
\end{list}
}

\variab{indep}{indep(nbpmax)}{ia}{Storage of the cell number of every
particle at the beginning of a Lagrangian iteration; this data is not
modified during the iteration}

\variab{vitpar}{vitpar(nbpmax,3)}{ra}{At the beginning of the
trajectography, \texttt{vitpar} contains the particle velocity vector components;
the modifications of the particle velocity following every
particle/boundary interaction are saved in this array; after the
trajectography and backward coupling steps, \texttt{ettp} is updated with
\texttt{vitpar}}

\variab{vitflu}{vitflu(nbpmax,3)}{ra}{At the beginning of the
trajectography, \texttt{vitflu} contains the locally undisturbed fluid flow
velocity vector components;
the modifications of the locally undisturbed fluid flow velocity
following every
particle/boundary interaction are saved in this array; after the
trajectography and backward coupling steps, \texttt{ettp} is updated with
\texttt{vitflu}}

\variab{gradpr}{gradpr(ncelet,3)}{ra}{Pressure gradient of the
continuous phase}

\variab{gradvf}{gradvf(ncelet,9)}{ra}{Gradient of the continuous phase
fluid velocity (useful if the complete model is activated: see \texttt{modcpl})}

\variab{cpgd1}{cpgd1(nbpmax)}{ra}{First devolatilisation term (light
volatile matters) of the coal particles (useful in the case of backward
coupling on the continuous phase)}

\variab{cpgd2}{cpgd2(nbpmax)}{ra}{Second devolatilisation term (heavy
volatile matters) of the coal particles (useful in the case of backward
coupling on the continuous phase)}

\variab{cpght}{cpght(nbpmax)}{ra}{Heterogeneous combustion term of the
coal particles (useful in the case of backward coupling on the
continuous phase)}

\variablist{statis}{statis(ncelet,nvlsta)}{ra}{Volumetric statistics
related to the dispersed phase; these statistics are the kind of results
expected with the Lagrangian module. It is from these statistics that we
obtain information concerning the particle cloud (the particle
trajectories should only be observed on ``pedagogical'' account); they
are marked out by the following ``pointers'':
\begin{list}{$\rightarrow$}{}
\item \texttt{ilvx,ilvy,ilvz}: mean dispersed phase velocity
\item \texttt{ilvx2,ilvy2,ilvz2}: dispersed phase velocity standard deviation
\item \texttt{ilfv}: dispersed phase volumetric concentration
\item \texttt{ilpd}: sum of the statistical weights
\item \texttt{iltp}: dispersed phase temperature (\degresC)
\item \texttt{ildp}: dispersed phase mean diameter
\item \texttt{ilmp}: dispersed phase mean mass
\item \texttt{ilhp}: temperature of the coal particle cloud (\degresC)
\item \texttt{ilmch}: mass of reactive coal of the coal particle cloud
\item \texttt{ilmck}: mass of coke of the coal particle cloud
\item \texttt{ilmdk}: shrinking core diameter of the coal particle cloud
\item \texttt{ilvu(ii): ii\textit{th}} supplementary user volumetric statistics
\end{list}
}

\variablist{parbor}{parbor(nfabor,nvisbr)}{ra}{Boundary statistics
related the dispersed phase; after every particle/boundary
interaction it is possible to save some data and to calculate averages;
the boundary statistics are marked out by the following ``pointers'':
\begin{list}{$\rightarrow$}{}
\item \texttt{inbr}: number of particle/boundary interactions
\item \texttt{iflm}: particle mass flow at the boundary faces
\item \texttt{iang}: mean interaction angle with the boundary faces (see example
      in \texttt{uslabo})
\item \texttt{ivit}: mean interaction velocity with the boundary faces
\item \texttt{ienc}: mass of coal deposit at the walls
\item \texttt{iusb(ii): ii\textit{th}} supplementary user boundary statistics
\end{list}}

\variablist{tslagr}{tslagr(ncelet,ntersl)}{ra}{Source terms
corresponding to the backward coupling of the dispersed phase on the
continuous phase. These source terms are marked out by the following
``pointers'':
\begin{list}{$\rightarrow$}{}
\item \texttt{itsvx}, \texttt{itsvy}, \texttt{itsvz}:
      explicit source terms for the continuous phase velocity
\item \texttt{itsli}: implicit source term for the continuous phase velocity and
      for the turbulent energy if the $k-\varepsilon$ model is used
\item \texttt{itske}: explicit source term for the turbulent dissipation and the
      turbulent energy if the $k-\varepsilon$ turbulence model is used for the
      continuous phase
\item \texttt{itsr11},... \texttt{itsr33}: source terms for the Reynolds stress
      and the turbulent dissipation if the $R_{ij}-\varepsilon$ turbulence model
      is used for the continuous phase
\item \texttt{itsmas}: mass source term
\item \texttt{itste}, \texttt{itsti}: explicit and implicit thermal source terms
      for the thermal scalar of the continuous phase
\item \texttt{itsmv1(icha)}, \texttt{itsmv2(icha)}: source terms respectively
      for the light and heavy volatile matters
\item \texttt{itsco}: source term for the carbon released during
      heterogeneous combustion
\item \texttt{itsf}: source term for the air variance (not used at the
      present time)
\end{list}}

\variab{croule}{croule(ncelet)}{ra}{Importance function for the
technique of variance reduction (cloning/fusion of particles)}

\variab{vagaus}{vagaus(nbpmax,nvgaus)}{ra}{Vectors of gaussian random
variables}

\variab{auxl}{auxl(nbpmax,3)}{ra}{Auxiliary work array}


%==================================
\subsection{Variables saved to allow calculation restarts}
%==================================

The directory \texttt{RESTART*} contains:
\begin{list}{-}{}
\item \texttt{suiava}: main restart file,
\item \texttt{suiavx}: auxiliary restart file (see \texttt{ileaux\index{ileaux}},
                       \texttt{iecaux\index{iecaux}}),
\item \texttt{rayava}: restart file for the radiation module,
\item \texttt{lagava}: main restart file for the Lagrangian module,
\item \texttt{lasava}: auxiliary restart file for the Lagrangian module (mainly
                       for the statistics),
\item \texttt{t1dava}: restart file for the 1D wall thermal module,
\item \texttt{vorava}: restart file for the vortex method (see
                       \texttt{ivrtex\index{ivrtex}}).
\end{list}

The main restart file contains the values in every cell of the mesh for
pressure, velocity, turbulence variables and scalars. Its content is sufficient
for a calculation restart, but the complete continuity of the solution at
restart is not ensured\footnote{in other words, a restart calculation of n time
steps following a calculation of m time steps will not yield strictly the same
resluts as a direct calculation on m+n time steps, whereas it is the case when
the auxiliary file is used}.

The auxiliary restart file completes the main restart file to ensure
solution continuity in the case of a calculation restart.
If the code cannot find one or several pieces of data required for the
calculation restart in the auxiliary restart file, default values are
then used. This allows in particular to run calculation restarts even if
the number of faces has been modified (for instance in case of
modification of the mesh merging or of periodicity
conditions\footnote{imposing a periodicity changes boundary faces into
internal faces}). More precisely, the auxiliary restart file contains
the following data:

\begin{list}{-}{}
\item type and value of the time step, turbulence model,
\item density value at the cells and boundary faces, if it is variable,
\item values at the cells of the other variable physical properties,
when they are extrapolated in time (molecular dynamic viscosity, turbulent or
subgrid scale viscosity, specific heat, scalar diffusivities); for the Joule
effect, the specific heat is stored automatically (in case the user should need
it at restart to calculate the temperature from the enthalpy before the new
specific heat has been estimated),
\item time step value at the cells, if it is variable,
\item mass flow value at the internal and boundary faces (at the last
time step, and also at the previous time step if required by the time scheme),
\item boundary conditions,
\item values at the cells of the source terms when they are extrapolated in time,
\item number of time-averages, and values at the cells of the associated
cumulated values,
\item for each cell, distance to the wall when it is required (and
index-number of the nearest boundary face, depending on \texttt{icdpar}%
\index{\texttt{icdpar}}),
\item values at the cells of the external forces in balance with a part
of the pressure (hydrostatic, in general),
\item for the D3P gas combustion model: massic enthalpies and temperatures at entry,
type of boundary zones and entry indicators,
\item for the EBU gas combustion model: temperature of the fresh gas, constant
mixing rate (for the models without mixing rate transport), types of boundary
zones, entry indicators, temperatures and mixing rates at entry,
\item for the LWC gas combustion model: the boundaries of the probability
density functions for enthalpy and mixing rate, types of boundary
zones, entry indicators, temperatures and mixing rates at entry,
\item for the pulverised coal combustion: coal density,  types of boundary
zones, variables \texttt{ientat}, \texttt{ientcp}, \texttt{timpat}, \texttt{x20}
(in case of coupling with the Lagrangian module, \texttt{iencp} and \texttt{x20}
are not saved),
\item for the electric module: the tuned potential difference \texttt{dpot}%
\index{\texttt{dpot}}
and, for the electric arc module, the tuning coefficient \texttt{coejou}%
\index{\texttt{coejou}}
(when the boundary conditions are tuned), the Joule source term for the enthalpy
(with the Joule effect is activated) and the Laplace forces (with the electric
arc module).
\end{list}

It should be noted that, if the auxiliary restart file is read, it is
possible to run calculation restarts with relaxation of the
density\footnote{such a relaxation only makes sense for a stationary
calculation}(when it is variable), because this variable is stored in the
restart file. On the other hand, it is generally not possible to do the
same with the other physical properties (they are stored in the restart
file only when they are extrapolated in time, or with the Joule effect for the
specific heat).

Apart from \texttt{vorava} which has a different structure and is
always in text format, all the restart files are binary
files. Nonetheless, they may be dumped by the \texttt{cs\_io\_dump}
tool provided with the Preprocessor.

In the case of parallel calculations, it should be noted that all the processors
will write their restart data in the same files. Hence, for instance, there will
always be one and only one \texttt{suiava} file, whatever the number of
processors used. The data in the file are written according to the initial full
domain index-numbers for the cells, faces and nodes. This allows in particular
to continue with {\it p} processors a calculation begun with {\it n} processors,
or to make the restart files independent of any vectorial renumbering that may
be carried out in each domain.

{\bf On the other hand}, if the numbering of the initial full domain mesh is
modified, the restart files will not be compatible. This may be the case if the
mesh is composed of different elements that are pasted by the Preprocessor module
and the order of the different elements has been changed in the Preprocessor command
line between two calculations.

{\em WARNING: if the mesh is composed of several files, the order
in which they appear in the launch script or in the Graphical Interface must not
be modified in case of a calculation restart\footnote{when uncertain, the user
can check the saved copy of the launch script in the \texttt{RESU} directory, or
the head of the \texttt{listpre} file, which repeats the command line passed to
the Preprocessor module}.}

{\em NOTE: when meshes are pasted by the Preprocessor module with potential hanging
nodes, two nodes closer than a certain (small) tolerance will be
merged. Hence, due to numerical round-up errors, two different machines may
yield different results. This might change the number of faces in the global
domain\footnote{the number of cells will not be modified, it is always the sum of the
number of cells of the different meshes} and make restart files
incompatible. Should that problem arise when making a calculation restart on a
different architecture, the solution is to discard the \texttt{suiavx} file and
use only the \texttt{suiava} file.}




%==================================
%==================================
\section{User subroutines}
%==================================
%==================================
\label{prg_ssprgutilis}
%==================================
\subsection{Preliminary comments}
%==================================
The user can run the calculations with or without an interface, with or
 without the user subroutine. Without interface, some user subroutines
 are needed. With interface, all the user subroutines are optional.

The parameters can be read in the interface and then in the user
subroutine. In the case that a parameter is specified in the interface
 and in the user subroutine, it is the value in the user subroutine that
 is taken into acount. It is for that reason that all the examples of
 user subroutines are placed in the \texttt{REFERENCE} directory by the
 case preparer \texttt{code\_saturne~create}.



%==================================
\subsection{Using selection criteria in user subroutines}
%==================================
\label{fvm_selector}

In order to use selection criteria (cf. \S\ref{selection_criteria}) in Fortran
user subroutines, a collection of utility subroutines is provided. The aim is to
define a subset of the mesh, for example:

\begin{list}{-}{}
\item boundary regions (cf. \texttt{usclim}, \texttt{uscpcl},
\texttt{usray2}, \texttt{uslag2},...),
\item volumic initialization (cf. \texttt{usiniv},...),
\item head-loss region (cf. \texttt{uskpdc}),
\item source terms region (cf. \texttt{ustsns}, \texttt{ustssc}),
\item advanced post-processing (cf. \texttt{usdpst}), \texttt{usproj}, ...),
\end{list}

This section explains how to define surface or volume sections,
in the form of lists \texttt{lstelt} of \texttt{nlelt} elements
(internal faces, boundary faces or cells).
For each type of element, the user calls the appropriate Fortran
subroutine: \texttt{getfbr}
for boundary faces, \texttt{getfac} for internal faces
and \texttt{getcel} for cells. All of these take
the three following arguments:
\begin{list}{-}{}
\item the character string which contains the selection
      criterion (see some examples below), 
\item the returned number of elements \texttt{nlelt}, 
\item the returned list of elements \texttt{lstelt}. 
\end{list}

Several examples of possible selections are given here:
\begin{list}{-}{}
\item \verb+call getfbr('Face_1, Face_2', nlelt, lstelt)+ to select
  boundary faces in groups Face\_1 or Face\_2,  
\item \verb+call getfac('4', nlelt, lstelt)+ to select internal
  faces of color 4,
\item \verb+call getfac('not(4)', nlelt, lstelt)+ to select internal
  faces which have a different color from 4,
\item \verb+call getfac('4 to 8', nlelt, lstelt)+ to internal faces
with color between 4 and 8 internal faces,
\item \verb+call getcel('1 or 2', nlelt, lstelt)+ to select cells
  with colors 1 or 2,
\item \verb+call getfbr('1 and y > 0', nlelt, lstelt)+ to select boundary
  faces of color 1 which have the coordinate $Y > 0$,
\item \verb+call getfac('normal[1, 0, 0, 0.0001]', nlelt, lstelt)+ to select
internal faces which have a normal direction to the vector (1,0,0),  
\item \verb+call getcel('all[]', nlelt, lstelt)+ to select all cells.
\end{list}

The user may then use a loop on the selected elements.
For instance, in the subroutine \texttt{usclim} used to impose
boundary  conditions, let us consider the boundary faces of color
number 2 and which have the coordinate $X <= 0.01$ (so
that \verb+call getfbr('2 and x <= 0.01', nlelt,lstelt)+);
we can do a loop (\verb+do ilelt = 1, nlelt+) and
obtain \verb+ifac = lstelt(ilelt)+.

\minititre{Note: legacy method using explicit families and properties}

The selection method for user subroutines by prior versions of \CS
is still available, though it may be removed in future versions.
This method was better adpated to working with colors than with groups,
and is explained here:

From \CS 's point of view, all the references to mesh entities (boundary faces
and volume elements) correspond to a number (color number or negative
of group number) associated with the entity. An entity may have several
references (for instance, one entity may have one color and belong to
several groups). In \CS, these references may be designated as
``properties''. \\
The mesh entities are gathered in equivalence classes on the base of
their properties. These equivalence classes are called ``families''. All
the entities of one family have the same properties. In order to know
the properties (in particular the color) of an entity (a boundary face
for example), the user must first determine the family to which it
belongs. \\
For instance, let's consider a mesh whose boundary faces have all been
given one color (for example using SIMAIL). The family of the boundary
face \texttt{ifac} is \texttt{ifml=ifmfbr(ifac)}. The first (and only)
property of this family is the color \texttt{icoul}, obtained for the face
\texttt{ifac} with \texttt{icoul=iprfml(ifml,1)}. In order to know the
property number corresponding to a group, the utility function
\texttt{numgrp(nomgrp, lngnom)} (with a name
\texttt{nomgrp} of the type \texttt{character*} and its lenght
\texttt{lngnom} of the type \texttt{integer}) may be used.



%==================================
\subsection{Initialisation of the main key words: \textmd{\texttt{usini1}}}
%==================================

\noindent
\textit{Subroutine only called during calculation initialisation.}

This subroutine is used to indicate the value of different calculation
basic parameters: constant and uniform physical values, parameters of
numerical schemes, input-output management ...\\

In the case of a calculation launched using the interface, it is only
used to modify high-level parameters which can not be managed by the
interface. In the case of a code utilisation without interface, this
subroutine is compulsory and all the headings must be completed.

For more details about the different parameters, please refer to the key
word list (\S\ref{prg_motscles}).

\texttt{usini1.f90} is in fact a gouping of 6 sperate subroutines:  \texttt{usipph},
 \texttt{usinsc}, \texttt{usipsc}, \texttt{usipgl},
\texttt{usipsu}and \texttt{usipes}. Each one controls the management of various
 specific parameters. The key words that dont' feature in the supplied example
can be provided by the user in  \texttt{SRC/REFERENCE/base}; in this case,
understanding of the comments is needed to add the key words in the appropriate
subroutine (the most widely used is \texttt{iphas}, it will assure that the value
has been well defined). The modifiable parameters in each of the subroutines of
\texttt{usini1.f90} are:

\begin{list}{$\bullet$}{}
\item \texttt{usipph}: \texttt{iturb} and \texttt{icp} (don't modify these
      parameters anywhere else)
\item \texttt{usinsc}: \texttt{nscaus} (don't modify these parameters anywhere
      else)
\item \texttt{usipsc}: \texttt{iscavr} and \texttt{ivisls} (don't modify these
      parameters anywhere else)
\item \texttt{usipgl}: \texttt{idtvar}, \texttt{ipucou}, \texttt{iphydr} and the
      parameters related to the error estimators(don't modify these parameters
      anywhere else).
\item \texttt{usipsu}: physical parameters of the calculation (thermal scalar, physical
      properties,...), numeric parameters (time steps, number of iterations, ...),
      definition of the time averages.
\item \texttt{usipes}: post processing output parameters (periodicity, variable names,
      probe positions,...)
\end{list}

For more details of the different parameters, see the list of key words  (\S\ref{prg_motscles}).
 The names of the key words can also be seen in the helps sections of the interface.

\minititre{Notes}
$\bullet\ $ Determined in the list of \texttt{nscaus} user scalars, representing
 the mean square fluctuations of another whilst informing the \texttt{iscavr}
array (warning, this was not the case in version 1.0). For
the other scalars, \texttt{iscavr} does not need to be completed (by default,
\texttt{iscavr(ii)}$\leqslant$0). For instance, if the scalar \texttt{jj}
represents the average of the square of the fluctuations of the scalar \texttt{kk},
the user must indicate \texttt{iscavr(jj)=kk}
(1$\leqslant$\texttt{kk}$\leqslant$\texttt{nscaus}).

\noindent
$\bullet\ $ When using the interface, only the
supplementary parameters (which can not be defined in the interface)
should appear in \texttt{usini1}. To spare the user the necessity to
delete the other parameters appearing as examples in the subroutine, the
utility program \texttt{code\_saturne~create} comments automatically all the
example lines of \texttt{usini1} with a code \texttt{!ex}. The user
needs then only to uncomment the lines which are useful in his
case. This function of
\texttt{code\_saturne~create} can be deactivated with
the option \texttt{--nogui} (useful if the user knows that he will not
use the interface).

%==================================
\subsection{Management of boundary conditions: \textmd{\texttt{usclim}}}
%==================================

\noindent
\textit{Subroutine called every time step.}

It is the second compulsory subroutine for every calculation launched
without interface(except in the specific physics case where the
corresponding boundary condition user subroutine must be used)  \\
When the interface is used, \texttt{usclim} is used to define complex
boundary conditions (input profiles, conditions varying in time, ...)
which could not be specified by means of the interface, and only these
need to be defined. In the case of a calculation launched without the
interface, all the boundary conditions must appear in \texttt{usclim}.\\
\texttt{usclim} is essentially constituted of loops on boundary
face subsets. Several sequences 
of \verb+call getfbr+ \verb+('criterion', nlelt, lstelt)+ (cf.
\S\ref{fvm_selector}) allow to differentiate 
the boundary faces according to their group(s), their
color(s) or geometric criteria. If needed, geometric and
physical variables are also available to the user, these allow him
to differentiate the boundary faces using other criteria.

For more details about the treatment of boundary conditions, the user
may refer to the theoretical and computer documentation \cite{theory} of
the subroutine \texttt{condli} (for the wall conditions, see
\texttt{clptur}) (to access to this document on a workstation, use
\mbox{\texttt{code\_saturne~info --guide theory}}).

From the user point of view, the boundary conditions are totally
determined by three arrays\footnote{except with Lagrangian}:
\texttt{itypfb(nfabor,nphas)}\index{\texttt{itypfb}},
\texttt{icodcl(nfabor,nvar)}\index{\texttt{icodcl}} and
\texttt{rcodcl(nfabor,nvar,3)}\index{\texttt{rcodcl}}.
\begin{list}{-}{}
\item \texttt{itypfb(ifac,iphas)} defines the type of the face \texttt{ifac}
      (input, wall, ...) for the phase \texttt{iphas}.
\item \texttt{icodcl(ifac,ivar)} defines the type of boundary
      condition for the variable \texttt{ivar} at the face \texttt{ifac}
      (Dirichlet, flux ...).
\item \texttt{rcodcl(ifac,ivar,.)} gives the numerical values associated with the
      type of boundary condition (value of the Dirichlet, of the flux ...).
\end{list}

In the case of standard boundary conditions (see
\S\ref{prg_clstandard}), it is enough to complete \texttt{itypfb(ifac,iphas)} and
some boxes of the array \texttt{rcodcl}, the array \texttt{icodcl} and most of the
boxes of \texttt{rcodcl} are completed automatically. For non-standard boundary
conditions (see \S\ref{prg_clnonstandard}), the arrays \texttt{icodcl} and
\texttt{rcodcl} must be totally completed.

%==================================
\subsubsection{Coding of standard boundary conditions}
%==================================
\label{prg_clstandard}%
The standard values taken by the indicator \texttt{itypfb} are:
\texttt{ientre\index{ientre}}, \texttt{iparoi\index{iparoi}},
\texttt{iparug\index{iparug}}, \texttt{isymet\index{isymet}},
\texttt{isolib\index{isolib}} and \texttt{iindef\index{iindef}}.

\begin{list}{$\bullet$}{}
\item If \texttt{itypfb=ientre}: inlet face.

\begin{list}{$\rightarrow$}{}
\item Zero-flux condition for pressure and Dirichlet condition for all
      other variables. The value of the Dirichlet must be given in
      \texttt{rcodcl(ifac,ivar,1)} for every value of \texttt{ivar}, apart from
      \texttt{ivar=ipr(iphas)}. The other values of \texttt{rcodcl} and
      \texttt{icodcl} are completed automatically.
\end{list}

\item If \texttt{itypfb=iparoi}: smooth solid wall face, impermeable and with friction.

\begin{list}{$\rightarrow$}{}
\item the eventual moving velocity of the wall tangent to the face is
      given by \texttt{rcodcl(ifac,ivar,1)} (\texttt{ivar} being
      \texttt{iu(iphas)}, \texttt{iv(iphas)} or \texttt{iw(iphas))}. The initial
      value of \texttt{rcodcl(ifac,ivar,1)} is zero for
      the three velocity components (and therefore needs to be specified
      only in the case of the existence of a slipping velocity). \\
{\em WARNING: the wall moving velocity must be in the boundary face
      plane. By security, the code uses only the projection of this
      velocity on the face. As a consequence, if the velocity specified
      by the user is not in the face plane, the wall moving velocity really
      taken into account will be different.}

\item Concerning the scalars, two kinds of boundary conditions can be
      defined:
\begin{list}{$\rightsquigarrow$}{}
\item Imposed value at the wall. The user must write\\
\hspace*{1cm}\texttt{icodcl(ifac,ivar)}=5\\
\hspace*{1cm}\texttt{rcodcl(ifac,ivar,1)}=imposed value\\
\item Imposed flux at the wall. The user must write\\
\hspace*{1cm}\texttt{icodcl(ifac,ivar)}=3\\
\hspace*{1cm}\texttt{rcodcl(ifac,ivar,3)}=flux imposed value (for the flux
      definition according to the variable, the user may refer to the
      case \texttt{icodcl}=3 of the paragraph \ref{prg_clnonstandard}).
\item If the user does not complete these arrays, the default condition
      is zero flux.
\end{list}
\end{list}

\item If \texttt{itypfb=iparug}: rough solid wall face, impermeable and with friction.

\begin{list}{$\rightarrow$}{}
\item the eventual moving velocity of the wall tangent to the face is
      given by \texttt{rcodcl(ifac,ivar,1)} (\texttt{ivar} being
      \texttt{iu(iphas)}, \texttt{iv(iphas)} or \texttt{iw(iphas)}). The initial
      value of \texttt{rcodcl(ifac,ivar,1)} is zero for
      the three velocity components (and therefore needs to be specified
      only in the case of the existence of a slipping velocity). \\
{\em WARNING: the wall moving velocity must be in the boundary face
      plane. By security, the code uses only the projection of this
      velocity on the face. As a consequence, if the velocity specified
      by the user is not in the face plane, the wall moving velocity really
      taken into account will be different.}
\item The dynamic roughness must be specified in \texttt{rcdocl(ifac,iu(iphas),3)}.
      The values of \texttt{rcdocl(ifac,iv(iphas),3)} and
      \texttt{rcdocl(ifac,iw(iphas),3)} are not used.
\item For scalars, two kinds of boundary conditions can be defined:
\begin{list}{$\rightsquigarrow$}{}
\item Imposed value at the wall. The user must write\\
\hspace*{1cm}\texttt{icodcl(ifac,ivar)}=6\\
\hspace*{1cm}\texttt{rcodcl(ifac,ivar,1)}=imposed value\\
\hspace*{1cm}\texttt{rcodcl(ifac,ivar,3)}=thermal roughness value\\
\item Imposed flux at the wall. The user must write\\
\hspace*{1cm}\texttt{icodcl(ifac,ivar)}=3\\
\hspace*{1cm}\texttt{rcodcl(ifac,ivar,3)}=flux imposed value (for the flux
      definition according to the variable, the user may refer to the
      case \texttt{icodcl}=3 of the paragraph \ref{prg_clnonstandard}).
\item If the user does not complete these arrays, the default condition
      is zero flux.
\end{list}
\end{list}



\item If \texttt{itypfb=isymet}: symmetry face (or wall without friction)
\begin{list}{$\rightarrow$}{}
\item Nothing to write in \texttt{icodcl} and  \texttt{rcodcl}.
\end{list}

\item If \texttt{itypfb=isolib}: free outlet face (or more precisely free 
      inlet/outlet with forced pressure)
\begin{list}{$\rightarrow$}{}
\item The pressure is always treated with a Dirichlet condition, calculated
      in order to have $\displaystyle \frac{d}{dn}\left(\frac{dP}{d\tau}\right)=0$.
      The pressure is given the value $P_0$ at the first face \texttt{isolib} met.
      The pressure drop is always linked to just one face, even if there are
      several outlets.
\item If the mass flow is coming in, the ``infinite'' velocity is retained
      and Dirichlet condition for the scalars and the turbulent quantities is used
      (or zero-flux condition if no Dirichlet value has been specified).
\item If the mass flow is going out, zero-flux condition for the velocity,
      the scalars and the turbulent quantities.
\item Nothing to write in \texttt{icodcl} or \texttt{rcodcl} for pressure or
      velocity. An optional Dirichlet condition can be specified for the scalars
      and turbulent quantities.
\end{list}

\item If \texttt{itypfb=iindef}: non-defined type face (non-standard case)
\begin{list}{$\rightarrow$}{}
\item The coding is done by completing every array \texttt{rcodcl} and
      \texttt{icodcl} (see \S\ref{prg_clnonstandard}).
\end{list}
\end{list}

\minititre{Notes}
$\bullet\ $ Whatever the value of the indicator \texttt{itypfb(ifac,iphas)}, if
the array \texttt{icodcl(ifac,ivar)} is modified by the user ({\em i.e.} filled
in by a value different from zero), the code will not use the default
conditions for the variable \texttt{ivar} at the face \texttt{ifac}, but will
take into account the values of \texttt{icodcl} and \texttt{rcodcl} given by the
user (these arrays must then be totally completed, like in the non-standard case). \\
For instance, for a symmetry face at which the scalar 1 is given a
Dirichlet condition equal to 23.8 (with an infinite exchange
coefficient):\\
\hspace*{2cm}\texttt{itypfb(ifac,iphas)=isymet}\\
\hspace*{2cm}\texttt{icodcl(ifac,isca(1))=1}\\
\hspace*{2cm}\texttt{rcodcl(ifac,isca(1),1)=23.8}\\
(\texttt{rcodcl(ifac,isca(1),2)=rinfin} is the default value, so it is
not necessary to specify it)\\
The boundary conditions for the other variables are still automatically
defined.

\noindent
$\bullet\ $The user may define new types of wall faces. He only needs to
choose a value $N$ and to specify completely the boundary conditions
corresponding to this new wall face type (see
\S\ref{prg_clnonstandard}). He must then specify
\texttt{itypfb(ifac,iphas)}=$N$. The value of $N$ must be between 1 and
\texttt{ntypmx\index{ntypmx}} (maximum number of boundary face types), and of
course different from the values \texttt{ientre}, \texttt{iparoi},
\texttt{iparug}, \texttt{isymet}, \texttt{isolib} and \texttt{iindef} (the value
of these variables is given in the file \texttt{paramx.h}). This allows to
easily isolate some boundary faces, in order to calculate balances.

%==================================
\subsubsection{Coding of non-standard boundary conditions}
%==================================
\label{prg_clnonstandard}%
In the case of a face not corresponding to a standard type, the user
must complete all of the arrays \texttt{itypfb}, \texttt{icodcl} and
\texttt{rcodcl}. \texttt{itypfb(ifac,iphas)} is then worth \texttt{iindef}
or another value defined by the user (see note in the end of paragraph
\ref{prg_clstandard}). The arrays \texttt{icodcl} and \texttt{rcodcl}
must be completed as follows:

\begin{list}{$\bullet$}{}
\item If \texttt{icodcl(ifac,ivar)}=1: Dirichlet condition at the face
      \texttt{ifac} for the variable \texttt{ivar}.

\begin{list}{$\rightarrow$}{}
\item \texttt{rcodcl(ifac,ivar,1)} is the value of the variable \texttt{ivar}
      at the face \texttt{ifac}.

\item \texttt{rcodcl(ifac,ivar,2)} is the value of the exchange coefficient
      between the outside and the fluid for the variable \texttt{ivar}. An
      infinite value (\texttt{rcodcl(ifac,ivar,2)=rinfin}) indicates a
      perfect transfer between the outside and the fluid (default case).

\item \texttt{rcodcl(ifac,ivar,3)} is not used.

\item \texttt{rcodcl(ifac,ivar,1)} is expressed in the unit of the variable
      \texttt{ivar}, {\em i.e.}:
\begin{list}{$\rightsquigarrow$}{}
\item $m/s$ for the velocity

\item $m^2/s^2$ for the Reynolds stress

\item $m^2/s^3$ for the dissipation

\item $Pa$ for the pressure

\item \degresC\ for the temperature

\item $J.kg^{-1}$ for the enthalpy

\item \degresC$^2$ for the temperature fluctuations

\item $J^2.kg^{-2}$ for the enthalpy fluctuations
\end{list}

\item \texttt{rcodcl(ifac,ivar,2)} is expressed in the following unit (defined so
      that by multiplying the exchange coefficient and the variable, the
      obtained flux has the same unit as the flux defined below for
      \texttt{icodcl=3)}:

\begin{list}{$\rightsquigarrow$}{}
\item $kg.m^{-2}.s^{-1}$ for the velocity

\item $kg.m^{-2}.s^{-1}$ for the Reynolds stress

\item $s.m^{-1}$ for the pressure

\item $W.m^{-2}.\mbox{\degresC}^{-1}$ for the temperature

\item $kg.m^{-2}.s^{-1}$ for the enthalpy
\end{list}

\end{list}

\item If \texttt{icodcl(ifac,ivar)=3}: flux condition at the face \texttt{ifac}
      for the variable \texttt{ivar}.

\begin{list}{$\rightarrow$}{}
\item \texttt{rcodcl(ifac,ivar,1)} and \texttt{rcodcl(ifac,ivar,2)} are not used.

\item \texttt{rcodcl(ifac,ivar,3)} is the flux value of \texttt{ivar} at the
      wall. This flux is negative if it is a source for the fluid. It corresponds to:
\begin{list}{$\rightsquigarrow$}{}
\item
$\displaystyle -C_p(\frac{\lambda_T}{C_p}+\frac{\mu_t}{\sigma_T})\grad T\cdot\vect{n}$ in the case of a temperature (in $W/m^2$).

$\displaystyle -(\lambda_h+\frac{\mu_t}{\sigma_h})\grad h\cdot\vect{n}$
     in the case of an enthalpy (in $W/m^2$).

$\displaystyle -(\lambda_\varphi+\frac{\mu_t}{\sigma_\varphi})\grad\varphi\cdot\vect{n}$ in the case of another scalar $\varphi$ (in $kg.m^{-2}.s^{-1}.[\varphi]$, where $[\varphi]$ is the unit of $\varphi$).

\item $-\Delta t\ \grad P\cdot\vect{n}$ in the case of the pressure (in $kg.m^{-2}.s^{-1}$).

\item $-(\mu+\mu_t)\grad U_i\cdot\vect{n}$ in the case of a velocity component (in $kg.m^{-1}.s^{-2}$).

\item $-\mu\grad R_{ij}\cdot\vect{n}$ in the case of a $R_{ij}$ tensor component (in $W/m^2$).
\end{list}

\end{list}

\item If \texttt{icodcl(ifac,ivar)}=4: symmetry condition, for the symmetry
      faces or wall faces without friction. This condition can only be
      used for the velocity components ($\vect{U}\cdot\vect{n}=0$) and
      the $R_{ij}$ tensor components (for the other variables, a zero-flux
      condition type is generally used).\\

\item If \texttt{icodcl(ifac,ivar)}=5: friction condition, for the smooth-wall faces
      with friction. This condition can not be applied to the pressure.
\begin{list}{$\rightsquigarrow$}{}
\item For the velocity and (if necessary) the turbulent variables, the
      values at the wall are calculated from theoretical profiles. In
      the case of a moving wall, the three components of the slipping
      velocity are given by (\texttt{rcodcl(ifac,iu(iphas),1)},
      \texttt{rcodcl(ifac,iv(iphas),1)}, and \texttt{rcodcl(ifac,iw(iphas),1)}).\\
{\em WARNING: the wall moving velocity must be in the boundary face
      plane. By security, the code uses only the projection of this
      velocity on the face. As a consequence, if the velocity specified
      by the user is not in the face plane, the wall moving velocity really
      taken into account will be different.}

\item For the other scalars, the condition \texttt{icodcl}=5 is similar to
      \texttt{icodcl=1}, but with a wall exchange coefficient calculated from a
      theoretical law. The values of \texttt{rcodcl(ifac,ivar,1)} and
      \texttt{rcodcl(ifac,ivar,2)} must therefore be specified: see \cite{theory}.
\end{list}

\item If \texttt{icodcl(ifac,ivar)}=6: friction condition, for the rough-wall faces
      with friction. This condition can not be applied to the pressure.
\begin{list}{$\rightsquigarrow$}{}
\item For the velocity and (if necessary) the turbulent variables, the
      values at the wall are calculated from theoretical profiles. In
      the case of a moving wall, the three components of the slipping
      velocity are given by (\texttt{rcodcl(ifac,iu(iphas),1)},
      \texttt{rcodcl(ifac,iv(iphas),1)}, and \texttt{rcodcl(ifac,iw(iphas),1)}).\\
{\em WARNING: the wall moving velocity must be in the boundary face
      plane. By security, the code uses only the projection of this
      velocity on the face. As a consequence, if the velocity specified
      by the user is not in the face plane, the wall moving velocity really
      taken into account will be different.}\\
      The dynamic roughness height is given by \texttt{rcodcl(ifac,iu(iphas),3)} only.

\item For the other scalars, the condition \texttt{icodcl}=6 is similar to
      \texttt{icodcl}=1, but with a wall exchange coefficient calculated from a
      theoretical law. The values of \texttt{rcodcl(ifac,ivar,1)} and
      \texttt{rcodcl(ifac,ivar,2)} must therefore be specified: see \cite{theory}.
      The thermal roughness height is then given by \texttt{rcodcl(ifac,ivar,3)}.
\end{list}

\item If \texttt{icodcl(ifac,ivar)}=9: free outlet condition for the
      velocity. This condition can only be applied to the velocity
      components.\\
If the mass flow at the face is going out, this condition is equivalent
      to a zero-flux condition.\\
If the mass flow at the face is coming in, the value zero is imposed to
      the velocity at the face (but not to the mass flow).\\
\texttt{rcodcl} is not used.

\end{list}

\minititre{Note}
$\bullet\ $A standard \texttt{isolib} outlet face amounts to a Dirichlet
condition (\texttt{icodcl}=1) for the pressure, a free outlet condition
(\texttt{icodcl}=9) for the velocity and a Dirichlet condition
(\texttt{icodcl}=1) if the user has specified a Dirichlet value or a zero-flux
condition (\texttt{icodcl}=3) for the other variables.\\

%==================================
\subsubsection{Checking of the boundary conditions}
%==================================

The code checks the main compatibilities between the boundary
conditions. In particular, the following rules must be respected: \\
$\bullet\ $On each face, the three components of the velocity
must belong to the same type. The same must be true for the different
components of the $R_{ij}$ tensor.\\
$\bullet\ $If the boundary conditions for the velocity belong to the
``slipping'' type (\texttt{icodcl}=4), the conditions for $R_{ij}$ must belong to
the ``symmetry'' type (\texttt{icodcl}=4), and vice versa.\\
$\bullet\ $If the boundary conditions for the velocity belong to the
``friction'' type (\texttt{icodcl}=5 or 6), the conditions for the turbulent variables
must belong to the ``friction'' type, too.\\
$\bullet\ $If the boundary condition for a scalar belongs to the
``friction'' type, the boundary condition for the velocity must belong to
the ``friction'' type, too.

In case of error, if post-processing output is activated (which is the default),
a special error output to the same mesh format occurs, so as to help
correcting boundary condition definitions.

%==================================
\subsubsection{Sorting of the boundary faces}
%==================================

In the code, it may be necessary to have access to all the boundary
faces of a given type. In order to ease this kind of search, an array of
sorted faces is automatically completed (and updated at every time step)
for each phase \texttt{iphas}: \texttt{itrifb(nfabor,iphas)\index{itrifb}}.\\
\texttt{ifac=itrifb(i,iphas)} is the number of the i$^{\text{th}}$  face of type
1.\\
\texttt{ifac=itrifb(i+n,iphas)} is the number of the i$^{\text{th}}$ face de type
2, if there are $n$ faces of type 1.\\
... etc.

Two auxiliary arrays of size \texttt{ntypmx} are also defined.\\
\texttt{idebty(ityp,iphas)\index{idebty}} is the number of the first box
corresponding to the
faces of type \texttt{ityp} in the array \texttt{itrifb}.\\
\texttt{ifinty(ityp,iphas)\index{ifinty}} is the number of the last box
corresponding to the
faces of type \texttt{ityp} in the array \texttt{itrifb}.

Therefore, a number \texttt{ifac0} between \texttt{idebty(ityp,iphas)} and
\texttt{ifinty(ityp,iphas)} corresponds to each face of type
\texttt{ityp=itypfb(ifac,iphas)}, so that \texttt{ifac=itrifb(ifac0,iphas)}.

If there is no face of type \texttt{ityp}, the code imposes \\
\texttt{ifinty(ityp,iphas)=idebty(ityp,iphas)-1},\\
which allows to bypass, for all the missing \texttt{ityp}, the loops like \\
\texttt{do ii=idebty(ityp,iphas),ifinty(ityp,iphas)}.

The values of all these indicators are displayed in the beginning of the
code execution listing.

%=============================================================
\subsection[Management of the boundary conditions with LES: \texttt{usvort}]
{Management of the boundary conditions with LES: \textmd{\texttt{usvort}}}
%===============================================================
\label{prg_usvort}%
This subroutine allows to generate the non-stationary inlet boundary
conditions for the LES by the vortex method. The method is based on
 the generation of vortices in the 2D inlet plane with help from
the pre-defined functions. The fluctuation normal to the inlet plane
is generated by a Langevin equation. It is in the subroutine \texttt{usvort}
 where the parametres of this method are given.

\noindent
\textit{subroutine called for each time step}

To allow the application of the vortex method, an indicator must be informed of
the method in the user subroutine \texttt{usini1}(ivrtex=1)

The subroutine \texttt{usvort} contains 3 seperate parts:

\begin{list}{-}{}
\item The 1st part defines the number of inlets concerned with the vortex
method (\texttt{nnentt\index{nnent}}) and the number of vortex for each inlet
(\texttt{nvort\index{nvort}}), where \texttt{ient} represents the number of inlets.
\item The 2nd part (\texttt{iappel=1}) defines the boundary faces at which the
      vortex method is applicable. The \texttt{irepvo\index{irepvo}} array is informed
      by \texttt{ient} which defines the number of inlets concerned with the vortex
(essentially, the vortex method can be applied with many independant inlets).
\item The 3rd section defines the main parameters of the method at each inlet.
      With the complexity of any given geometry, 4 cases are distinguished
      (the first 3 use the data file \texttt{ficvor} and in the final case only 1
      initial velocity and energy are imposed.):

\begin{list}{*}{}
\item \texttt{icas}=1, For the outlet of a rectangluar pipe; 1 boundary condition is defined
for each side of the rectangle taking into account their interaction
with the vortex.
\item \texttt{icas}=2, For the outlet of a circular pipe; the entry face is considered as a
 wall (as far as interaction with the vortex is concerned)
\item \texttt{icas}=3, For inlets of any geometry; no boundary conditions are defined at the
 inlet face (i.e no specific treatment on the interation between the
 vortex and the boundary)
\item \texttt{icas}=4, similar to \texttt{icas}=3 except the data file is not
 used (\texttt{ficvor}); the outflow
 parameters are estimated by the code from the global data (initial
 velocity, level of turbulence and dissipation), information which is
 supplied by the user.
\end{list}

When the geometry allows, cases 1 and 2 are used. Case 4 is only used
 if it is not possible to use the other 3.

In the first 3 cases, the 2 base vectors in the plane of each inlet
must be defined (vectors \texttt{dir1} and \texttt{dir2}). The 3rd vector is
automatically calculated by the code, defined as a product of \texttt{dir1} and
\texttt{dir2}. \texttt{dir1} and \texttt{dir2} must be chosen imperatively to
give (\texttt{cen}, \texttt{dir1}, \texttt{dir2}) an orthogonal reference of the
inlet plane and so \texttt{dir3} is oriented in the entry domain. If
\texttt{icas}=2, the \texttt{cen} position must be the center of gravity of the
rectangle or disc.

The reference points (\texttt{cen}, \texttt{dir1}, \texttt{dir2}, \texttt{dir3})
which define the values of the variable in the \texttt{ficvor} file.\\
In the case where \texttt{icas}=4, the vectors \texttt{dir1} and \texttt{dir2}
are generated by the code.

If \texttt{icas}=1, the boundary conditions at the rectangle's edges must be
defined. They are defined in the array
\texttt{iclvor\index{iclvor}}. \texttt{iclvor(ii,ient)} represents the standard boundary
conditions at the edge II(1$\leqslant$II$\leqslant$4) of the inlet
\texttt{ient}. The code for the boundary conditions is as follows:
\begin{list}{*}{}
\item \texttt{iclvor}=1 for a wall
\item \texttt{iclvor}=2 for symmetry
\item \texttt{iclvor}=3 for periodicity of translation (the face corresponding
      to periodicity will automatically be taken as 3)
\end{list}
The 4 edges are numbered relative to the directions \texttt{dir1} and
\texttt{dir2} as shown in figure \ref{Fig_vortex}:

\begin{figure}[hp]
\centerline{
\includegraphics*[width=8cm]{vortex}}
\caption{Numbering of the edges of a rectangular inlet(\texttt{icas}=1)
 treated by the vortex method}\label{Fig_vortex}
\end{figure}

If \texttt{icas}=1, the user must define \texttt{llx} and \texttt{lly} which give
the lengths of the rectangular pipe in the directions \texttt{dir1} and \texttt{dir2}.\\
If \texttt{icas}=2, \texttt{lld} represents the diameter of the circular pipe.
If \texttt{icas}=4, \texttt{udebit} ,\texttt{kdebit} and \texttt{edebit} are
defined for each inlet, these give respectively,
initial speed, turbulent energy level and the dissipation level. These can be used to
 obtain their magnitude using the correlations in the user routine \texttt{usclim} for
 fully developed flow in a pipe.

 The case independant parameters are defined as follows:
\begin{list}{*}{}
\item \texttt{itmpl} represents the indicator of the advancement in time of the
  vortex. If \texttt{itmpli}=1, the vortex will be regenerated after a fixed
  time of
  \texttt{tmplim} second (defined as \texttt{itmpli}=1).
  If \texttt{itmpli}=2, following the data indicated in \texttt{ficvor} file,
  the vortex will have a variable life span equal to
  $5 \displaystyle C_\mu \displaystyle \frac{k^{\frac{3}{2}}}{\varepsilon U}$ ,
  where $C_\mu=0,09$ and $k$, $\varepsilon$ and $U$  represent respectively, turbulent energy,
  turbulent dissipation and the convective velocity in the direction normal to the inlet plane.

\item \texttt{xsgmvo} represents the support functions used in the vortex
  method. They are representative of the eddy sizes entered in the vortex
  method.
  \texttt{isgmvo} is used to define their size: if \texttt{isgmvo}=1,
  \texttt{xsgmvo} will be constant across the inlet face and is defined in
  \texttt{usvort}, if \texttt{isgmvo}=2, \texttt{xsgmvo} will be variable and
  equal to the mixing length of the standard $k-\varepsilon$ model
  ($\displaystyle {C_\mu}^{\frac{3}{4}} \displaystyle \frac{k^{\frac{3}{2}}}{\varepsilon}$), if
  \texttt{isgmvo}=3, \texttt{xsgmvo} will be equal to the maximum of $L_t$ et
  $L_K$ where $L_t$ and $L_K$ are the $\displaystyle \frac{\partial U}{\partial y}$
  $\displaystyle \frac{\partial U}{\partial y}$
  Taylor and Kolmogrov co-efficients
  ($\displaystyle L_T=(5 \nu \frac{k}{\displaystyle \varepsilon})^{\frac{1}{2}}$,
  $\displaystyle L_K= 200 (\frac{\nu^3}{\varepsilon})^{\frac{1}{4}}$).

\item \texttt{idepvo} gives the vortex displacement method in the 2D inlet plane
  (the vortex method is a langrangian method in which the eddy centers are
  replaced by a set velocity). If \texttt{idepvo}=1, the velocity displacement
  referred to by \texttt{ud} which is the vortex following a random sampling
  (a sample number r, is taken for each vortex, at each time step and for each direction and
  the center of the vortex is replaced by the 2 principle directions,
  $r \mbox{ud} \Delta t$ where $\Delta t$ is the time step of the calcualtion).
  If \texttt{idepvo}=2, the vortex will be convected by itself (with the speed
  given by the time step before the vortex method)
\end{list}

A data file, \texttt{ficvor}, must be defined in the cases of
\texttt{icas}=1,2,3, for each inlet. The data file must contain the following
data in order ($x$, $y$, $U$, $\displaystyle \frac{\partial U}
{\partial y}$, $k$, $\varepsilon$). The number of lines of the file is given by
the integer \texttt{ndat}. $x$ and $y$ are the co-ordinates in the inlet plane
defined by the vectors \texttt{dir1} and \texttt{dir2}. $U$, $k$ and
$\varepsilon$ are respectively, the average speed normal to the inlet,
the turbulent energy and the turbulent dissipation.
$\displaystyle \frac{\partial U}{\partial y}
$ is the derivative in the direction normal to the
 inlet boundary in the cases, \texttt{icas}=1, \texttt{icas}=2.
 Where \texttt{icas}=3 and \texttt{icas}=4 this variable is not applied
 (it is given the value 0) so the Langevin equations, used to generate
 fluctuations normal to the inlet plane, is de-activated
 (the flucutations normal to the inlet is 0 on both these cases).
 Note that the application of
 many different test of the Langevin equation doesn't have a notable influence
 on the results and that, by contrast it simply increases the computing time per
 iteration and so it decreases the random sampling which slows down the pressure
 solver. The interpolation used in the vortex method is defined by the function
 \texttt{phidat}. An example is given at the end of \texttt{usvort} where the
 user can define the interpolation required. In the \texttt{phidat} function,
 \texttt{xx} and \texttt{yy} are the co-ordinates by which the value of
 \texttt{phidat} is calculated. \texttt{xdat} and \texttt{ydat} are the
 co-ordinates in the \texttt{ficvor} file. \texttt{vardat} is the
 value of the \texttt{phidat} function with the co-ordinates \texttt{xdat}
 and \texttt{ydat} (given in the \texttt{ficvor} file). Note that using an
 indicator \texttt{iii} accelerates the calculations (the user need not modify or delete).
 The user must also define the parameter \texttt{isuivo} which indicates if the
 vortex were started at 0 or if the file must be re-read (\texttt{ficmvo}).

\end{list}

{\bf \underline{WARNING}}
\begin{list}{$\bullet$}{}
\item Be sure that the \texttt{ficvor} file and  the interpolation in the user
  function \texttt{phidat} are compatible (in particular that all the entry
  region is covered by \texttt{ficvor})
\item If the user wants to use a 1D profile in the \texttt{dir2} direction,
 set $x$ =0 in the \texttt{ficvor} file and define the interpolation in
 \texttt{phidat}.
\end{list}


%==================================
\subsection{Management of the variable physical properties:
  \textmd{\texttt{usphyv}}}
%==================================

\noindent
\textit{Subroutine called every time step.}

If necessary, all the variation laws related to the fluid physical
parameters (density, viscosity, thermal diffusivity, ...) are written in this
subroutine.

The validity of the variation laws must be checked, particularly when
non-linear laws are defined (for instance, a third-degree polynomial law
may produce negative density values).

{\bf \underline{WARNING}}\label{prg_propvar}
\begin{list}{$\bullet$}{}
\item If one wishes to impose a density or viscosity variable in
      \texttt{usphyv}, it can be done either in the interface or in
      \texttt{usini1}(\texttt{irovar(iphas)}=1, \texttt{ivivar(iphas)}=1).
\item In order to impose a physical property ($\rho$, $\mu$,
      $\lambda$, $C_p$)\footnote{except for some specific physics} a reference
      value must be inputted to the interface or in \texttt{usini1}(in
      particular for $\rho$, the pressure will contain 1 part as $\rho_0 gz$)
\item By default, the $C_p$ coefficient of the phase \texttt{iphas} and the
      diffusivity of the scalars \texttt{iscal} ($\lambda/C_p$ for the
      temperature) are considered as constant in time and uniform in
      space, with the values \texttt{cp0(iphas)} and \texttt{visls0(iscal)}
      specified in the interface or in \texttt{usini1}.\\
To give a variable value to $C_p$, the user must specify it in the
      interface or give the value 1 to \texttt{icp(iphas)} in \texttt{usini1},
      and complete for each cell \texttt{iel} the array
      \texttt{propce(iel,ipccp)} in \texttt{usphyv}. Completing the array
      \texttt{propce(iel,ipccp)} while \texttt{icp(iphas)=0} induces array
      overwriting problems and produces wrong results.

\item In the same way, to have variable diffusivities for the scalars
      \texttt{iscal}, the user must specify it in the interface or give the value
      1 to \texttt{ivisls(iscal)} in \texttt{usini1}, and complete for each cell
      \texttt{iel} the array \texttt{propce(iel,ipcvsl)} in \texttt{usphyv}.
      Completing \texttt{propce(iel,ipcvsl)} while \texttt{ivisls(iscal)}=0
      induces memory overwriting problems and produces wrong results.\\

{\em Example}: If the scalars 1 and 3 have a constant and uniform
      viscosity, and if the scalars 2 and 4 have a variable viscosity,
      the following values must be imposed in \texttt{usini1}: \\
      \texttt{ivisls(1)}=0, \texttt{ivisls(2)}=1, \texttt{ivisls(3)}=0
      and \texttt{ivisls(4)}=1. \\
      The indicators \texttt{ivisls(2)} and \texttt{ivisls(4)} are then
      modified automatically by the code in order to reflect the rank
      corresponding to the diffusivity of each scalar in the list of physical
      properties\footnote{they are no longer worth 1 but stay positive
      so that \texttt{ivisls}$>$0 is synonymous with variable property}.
      The arrays \mbox{\texttt{propce(iel,ipcvsl)}} in \texttt{usphyv} must
      then be completed with \texttt{ipcvsl=ipproc(ivisls(2))} and
      \texttt{ipcvsl=ipproc(ivisls(4))}. \\

{\em Note}: The indicators \texttt{ivisls} must not be completed in the case of
      user scalars representing the average of the square of the
      fluctuations of another scalar, because the diffusivity of a user
      scalar \texttt{jj} representing the average of the square of the
      fluctuations of a user scalar \texttt{kk} comes directly from the
      diffusivity of this last scalar. In particular, the diffusivity
      of the scalar \texttt{jj} is variable if the diffusivity of \texttt{kk}
      is variable.
\end{list}

%==================================
\subsection{Non-default variables initialisation:
  \textmd{\texttt{usiniv}}}
%==================================

\noindent
\textit{Subroutine only called during calculation initialisation.}

At the calculation beginning, the variables are initialised
automatically by the code. Velocities and scalars are set to the value
0 (or \texttt{scamax} or \texttt{scamin} if 0 is outside the acceptable
scalar variation range), and the turbulent variables are estimated from
\texttt{uref} and \texttt{almax}. \\
For $k$ in $k-\varepsilon$, $R_{ij}-\varepsilon$, v2f or $k-\omega$
model:\\
{\texttt{rtp(iel,ikiph) = 1.5*(0.02*uref(iphas))**2}
(in $R_{ij}-\varepsilon$,  $R_{ij}=\frac{2}{3}k\delta_{ij}$)\\
For $\varepsilon$ in $k-\varepsilon$, $R_{ij}-\varepsilon$ or v2f model:\\
\texttt{rtp(iel,ieiph) = rtp(iel,ikiph)**1.5*cmu/almax(iphas)}\\
For $\omega$ in $k-\omega$ model:\\
\texttt{rtp(iel,iomgip) = rtp(iel,ikiph)**0.5/almax(iphas)}\\
For $\varphi$ and $\overline{f}$ in v2f model:\\
\texttt{rtp(iel,iphiph) = 2/3}\\
\texttt{rtp(iel,ifbiph) = 0}

The subroutine \texttt{usiniv} allows if necessary to initialise some
variables at values closer to their estimated final values, in order to
obtain a faster convergence.

This subroutine allows also to make non-standard initialisation of
physical parameters (density, viscosity, ...), to impose a local
value of the time step, or to modify some parameters (time step,
variable specific heat, ...) in the case of a calculation restart.

\minititre{Note: value of the time step}
\begin{list}{-}{}
\item In the case of a calculation with constant and uniform time step
      (\texttt{idtvar}=0), the value of the time step is \texttt{dtref},
      given in the parametric file of the interface or \texttt{usini1}, the
      calculation being whether a restart (\texttt{isuite}=1) or not (
      \texttt{isuite}=0).
\item In the case of a calculation with non-constant time step
      (\texttt{idtvar}=1 or 2) which is not a calculation restart
      (\texttt{isuite}=0), the
      value of \texttt{dtref} given in the parametric file of the interface or in
      \texttt{usini1} is used to initialise the time step.
\item In the case of a calculation with non-constant time step
      (\texttt{idtvar}=1 or 2) which is a restart (\texttt{isuite}=1) of a
      calculation whose time step type was different (for instance, restart
      using a variable time step of a calculation run using a constant time
      step), the value of \texttt{dtref} given in the parametric file of the
      interface or in \texttt{usini1} is used to initialise the time step.
\item In the case of a calculation with non-constant time step
      (\texttt{idtvar}=1 or 2) which is a restart (\texttt{isuite}=1) of a
      calculation whose time step type was the same (for instance, restart with
      \texttt{idtvar}=1 of a calculation run with \texttt{idtvar}=1), the time
      step is read from the restart file and the value of \texttt{dtref} given
      in the parametric file of the interface or in \texttt{usini1} is not used.
\end{list}
It follows that for a calculation with non-constant time step (\texttt{idtvar}=1
or 2) which is a restart (\texttt{isuite}=1) of a calculation in which
\texttt{idtvar} had the same value, \texttt{dtref} does not allow to modify the
time step. The user subroutine \texttt{usiniv} allows to modify the array
\texttt{dt} which contains the value of the time step read from the restart file
(array whose size is \texttt{ncelet}, defined at the cell centers whatever the
chosen time step type).

{\em WARNING: to initialise the variables in the framework of a
specific physics module} (\texttt{nscapp.gt.0}) {\em one of the subroutines
\texttt{usebui}, \texttt{usd3pi}, \texttt{uslwci} or \texttt{uscpiv}
should be used instead of \texttt{usiniv} (depending on the activated module).}

%==================================
\subsection{Non-standard management of the chronological record files:
  \textmd{\texttt{ushist}}}
%==================================
\label{prg_ushist}

\noindent
\textit{Subroutine called every time step}

The interface and the subroutine \texttt{usini1} allow to manage the
``automatic'' chronological record files in an autonomous way:
position of the probes, printing frequency and concerned variables. The
results are written in a different file for each variable. These files
are written in {\em xmgrace or {\em gnuplot}} format and contain the profiles corresponding to
every probe. This type of output format may not be well adapted if, for
instance, the number of probes is too high. The subroutine
\texttt{ushist} allows then to personalise the output format of the
chronological record files. The version given as example in the
directory works as follows:

\begin{list}{-}{}
\item Positionning of the probes (only at the first passage): the index
      \texttt{ii} varies between 1 and the number of probes. The coordinates
      \texttt{xx}, \texttt{yy} and \texttt{zz} of each probe are given.
      The subroutine \texttt{findpt}
      gives then the number \texttt{icapt(ii)\index{icapt}} of the cell center
      which is the closest to the defined probe.

\item Opening of the output files (only at the first pass): in the
      version given as example, the program opens a different file for
      all the \texttt{nvar} variables. \texttt{ficush(j)} contains the name of the
      J\raisebox{1ex}{\small th} file and \texttt{impush(j)} its unit number
      (\texttt{impush} is initialised by default so that the user has at his
      disposal specific unit numbers and does not run the risk to overwrite an
      already open file).

\item Writing to the files: in the version given as example, the program
      writes the time step number, the physical time step (based on the
      standard time step in the case of a variable time step) and the
      value of the selected variable at the different probes.

\item Closing of the files (only at the last time step).

\end{list}

{\em WARNING: The use of {\em\texttt{ushist}} neither erases nor replaces the
parameters given in the interface or in {\em\texttt{usini1}}. Therefore, in
the case of the use of {\em\texttt{ushist}}, and to avoid the creation
of useless files, the user should set {\em \texttt{ncapt}=0} in the interface or
in {\em \texttt{usini1}} to deactivate the automatic production of
chronological records}.\\
In addition, {\em \texttt{ushist}} generates supplementary result
files. The user shoud remember to add in the launch script the necessary
command to copy them in the directory \texttt{RESU} at the end of the
calculation. The interface allows the specification of the name of the copied
 user results files. For the calculations without interface, the variable must
 be inputted in USER\_OUTPUT\_FILES in the launch script.

%==================================
\subsection{User source terms in Navier-Stokes: \textmd{\texttt{ustsns}}}
%==================================

\noindent
\textit{Subroutine called every time step}

This subroutine is used to add user source terms to the Navier-Stokes
equations. For each phase \texttt{iphas}, it is called three times every time
step, once for each velocity component (\texttt{ivar} is successively worth
\texttt{iu(iphas)}, \texttt{iv(iphas)} and \texttt{iw(iphas)}).
At each passage, the user must complete if necessary the arrays \texttt{crvimp}
and \texttt{crvexp} expressing respectively the implicit and explicit part of
the source term. If no other source terms apart from \texttt{ivar=iu(iphas)} for
example, are required, \texttt{crvimp} and \texttt{crvexp} must be read over and
their 2 other components, \texttt{ivar=iv(ihpas)} and \texttt{ivar=iw(iphas)}
must be cancelled.

Let us assume that the user source terms modify the equation of a
variable $\varphi$ in the following way:
\begin{displaymath}
\rho\frac{\partial \varphi}{\partial t}+\ldots = \ldots + S_{impl}\times\varphi+S_{expl}
\end{displaymath}
$\varphi$ is here a velocity component, but the examples are also valid
for a turbulent variable ($k$, $\varepsilon$, $R_{ij}$, $\omega$,
$\varphi$ or $\overline{f}$) and for a scalar (or for the average of the
square of the fluctuations of a scalar), because the syntax of the
subroutines \texttt{ustske}, \texttt{ustsri}, \texttt{ustsv2},
\texttt{ustskw} and \texttt{ustssc} is similar.

In finite volume formulation, the solved system is then modified as
follows:
\begin{displaymath}
\left(\frac{\rho_i\Omega_i}{\Delta t_i}-\Omega_iS_{impl,i}\right)
\left(\varphi_i^{(n+1)}-\varphi_i^{(n)}\right)
+\ldots = \ldots + \Omega_iS_{impl,i}\varphi_i^{(n)} + \Omega_iS_{expl,i}
\end{displaymath}
The user needs therefore to provide the following values:\\
$\text{\texttt{crvimp}}_i=\Omega_iS_{impl,i}$\\
$\text{\texttt{crvexp}}_i=\Omega_iS_{expl,i}$

In practice, it is essential that the term
$\displaystyle \left(\frac{\rho_i\Omega_i}{\Delta
t_i}-\Omega_iS_{impl,i}\right)$ is positive. To ensure this property,
the equation really taken into account by the code is the following:
\begin{displaymath}
\left(\frac{\rho_i\Omega_i}{\Delta t_i}-
\text{Min}(\Omega_iS_{impl,i};0)\right)
\left(\varphi_i^{(n+1)}-\varphi_i^{(n)}\right)
+\ldots = \ldots + \Omega_iS_{impl,i}\varphi_i^{(n)} + \Omega_iS_{expl,i}
\end{displaymath}
To make the ``implicitation'' effective, the source term decomposition
between implicit and explicit parts will be done by the user who must
make sure $\text{\texttt{crvimp}}_i=\Omega_iS_{impl,i}$ is always negative
(otherwise the solved equation remains right, but there is no
``implicitation'').

{\em WARNING: When the second-order in time with extrapolation of the
source terms\footnote{indicator \texttt{isno2t} for the velocity,
\texttt{ISTO2T} for the turbulence and \texttt{isso2t} for the scalars}
is activated, it is no longer possible to test the sign of $S_{impl,i}$,
because of coherence reasons (for more details, the user may refer to
the theoretical and computer documentation \cite{theory} of the
subroutine \texttt{preduv}). The user must therefore make sure it is
always positive.}

\minititre{Particular case of a linearised source term}

In some cases, the added source term is not linear, but the user may
want to linearise it using a first-order Taylor development, in order to
make it partially implicit.\\
Let us consider an equation of the type:
\begin{displaymath}
\rho\frac{\partial\varphi}{\partial t}=F(\varphi)
\end{displaymath}

We want to make it implicit using the following method:
\begin{eqnarray*}
\frac{\rho_i\Omega_i}{\Delta t}\left(\varphi_i^{(n+1)}-\varphi_i^{(n)}\right) & = &
\Omega_i\left[F(\varphi_i^{(n)})+\left(\varphi_i^{(n+1)}-\varphi_i^{(n)}\right)
\frac{dF}{d\varphi}(\varphi_i^{(n)})\right]\\
& = & \Omega_i\frac{dF}{d\varphi}(\varphi_i^{(n)})\times\varphi_i^{(n+1)}
+\Omega_i\left[F(\varphi_i^{(n)})-\frac{dF}{d\varphi}(\varphi_i^{(n)})
\times\varphi_i^{(n)}\right]
\end{eqnarray*}

The user must therefore specify:\\
$\displaystyle\text{\texttt{crvimp}}_i=\Omega_i\frac{dF}{d\varphi}(\varphi_i^{(n)})$\\
$\displaystyle\text{\texttt{crvexp}}_i=
\Omega_i\left[F(\varphi_i^{(n)})-\frac{dF}{d\varphi}(\varphi_i^{(n)})\times\varphi_i^{(n)}\right]$

\underline{\em Example}:\\
If the equation is
$\displaystyle \rho\frac{\partial\varphi}{\partial t}=-K\varphi^2$,
the user must set:\\
$\text{\texttt{crvimp}}_i=-2K\Omega_i\varphi_i^{(n)}$\\
$\text{\texttt{crvexp}}_i=K\Omega_i[\varphi_i^{(n)}]^2$



%==================================
\subsection{User source terms for $k$ and $\varepsilon$:
  \textmd{\texttt{ustske}}}
%==================================

\noindent
\textit{Subroutine called every time step, in $k-\varepsilon$ and
in v2f.}

This subroutine is used to add source terms to the transport equations
related to the turbulent kinetics energy $k$ and to the turbulent
dissipation $\varepsilon$ (for each phase \texttt{iphas}).
This subroutine is called every time step, once for each phase (the
treatment of the two variables $k$ and $\varepsilon$ is made
simultaneously). The user is expected to provide the arrays \texttt{crkimp} and
\texttt{crkexp} for $k$ and \texttt{creimp} and \texttt{creexp} for
$\varepsilon$. These arrays are similar to the arrays \texttt{crvimp} and
\texttt{crvexp} given for the velocity in the user subroutine \texttt{ustsns}.
The way of making implicit the resulting source terms is the same as the one
presented in \texttt{ustsns}. For $\varphi$ and $\bar{f}$
in v2f, see \texttt{ustsv2}, \S\ref{prg_ustsv2}.



%==================================
\subsection{User source terms for $R_{ij}$ and $\varepsilon$: \textmd{\texttt{ustsri}}}
%==================================

\noindent
\textit{Subroutine called every time step, in $R_{ij}-\varepsilon$.}

This subroutine is used to add source terms to the transport equations
related to the Reynolds stress variables $R_{ij}$ and to the turbulent
dissipation $\varepsilon$ (for each phase \texttt{iphas}).
This subroutine is called 7 times every time step and for each phase
(once for each Reynolds stress component and once for the
dissipation). The user must provide the arrays \texttt{crvimp} and
\texttt{crvexp} for the variable \texttt{ivar} (referring successively to
\texttt{ir11(iphas)}, \texttt{ir22(iphas)}, \texttt{ir33(iphas)},
\texttt{ir12(iphas)}, \texttt{ir13(iphas)}, \texttt{ir23(iphas)} and
\texttt{iep(iphas)}). These arrays are similar to the arrays \texttt{crvimp}
and \texttt{crvexp} given for the velocity in the user subroutine
\texttt{ustsns}. The method for impliciting the resulting source terms is the
same as that presented in \texttt{ustsns}.

%==================================
\subsection{User source terms for $\varphi$ and $\overline{f}$:
  \textmd{\texttt{ustsv2}}}
%==================================
\label{prg_ustsv2}
\noindent
\textit{Subroutine called every time step, in v2f.}

This subroutine is used to add source terms to the transport equations
related to the variables $\varphi$ and $\overline{f}$ of the v2f
$\varphi$-model (for each phase \texttt{iphas}). This subroutine is called twice
every time step and for each phase (once for $\varphi$ and once for
$\overline{f}$). The user is expected to provide the arrays \texttt{crvimp} and
\texttt{crvexp} for \texttt{ivar} referring successively to \texttt{iphi(iphas)}
and \texttt{ifb(iphas)}. Concerning $\varphi$, these arrays are similar to the arrays
\texttt{crvimp} and \texttt{crvexp} given for the velocity in the user subroutine
\texttt{ustsns}. Concerning $\overline{f}$, the equation is slightly
different:
\begin{displaymath}
L^2 div(\grad(\overline{f})) = \overline{f} + \ldots + S_{impl}\times\overline{f}+S_{expl}
\end{displaymath}
In finite volume formulation, the solved system is written:
\begin{displaymath}
\int_{\partial\Omega_i}\grad(\overline{f})^{(n+1)}dS=\frac{1}{L_i^2}\left(
\Omega_i\overline{f}^{(n+1)}_i + \ldots +  \Omega_iS_{impl,i}\overline{f}_i^{(n+1)} +
\Omega_iS_{expl,i} \right)
\end{displaymath}
The user must then specify:\\
$\text{\texttt{crvimp}}_i=\Omega_iS_{impl,i}$\\
$\text{\texttt{crvexp}}_i=\Omega_iS_{expl,i}$

The way of making implicit the resulting source terms is the same as the
one presented in \texttt{ustsns}.

%==================================
\subsection{User source terms for $k$ and $\omega$: \textmd{\texttt{ustskw}}}
%==================================

\noindent
\textit{Subroutine called every time step, in $k-\omega$.}

This subroutine is used to add source terms to the transport equations
related to the turbulent kinetics energy $k$ and to the specific
dissipation rate $\omega$ (for each phase \texttt{iphas}). This subroutine is
called every time step, once for each phase (the treatment of the two
variables $k$ and $\omega$ is made simultaneously).The user is expected
to provide the arrays \texttt{crkimp} and \texttt{crkexp} for the variable
$k$ the arrays \texttt{crwimp} and \texttt{crwexp} for the variable $\omega$.
These arrays are similar to the arrays \texttt{crvimp} and \texttt{crvexp}
given for the velocity in the user subroutine \texttt{ustsns}. The way of
impliciting the resulting source terms is the same as the one presented in
\texttt{ustsns}.

%==================================
\subsection{User source terms for the user scalars: \textmd{\texttt{ustssc}}}
%==================================

\noindent
\textit{Subroutine called every time step.}

This subroutine is used to add source terms to the transport equations
related to the user scalars (passive or not, average of the square of
the fluctuations of a scalar, ...). In the same way as
\texttt{ustsns}, this subroutine is called every time step, once for
each user scalar. The user needs to provide the arrays \texttt{crvimp}
and \texttt{crvexp} related to each scalar. \texttt{cvimp} and \texttt{crvexp}
must be set to 0 for the scalars on which it is not wished for the user source
term term to be applied (the arrays are initially at 0 at each inlet in the subroutine.)

%==================================
\subsection{Management of the pressure drops: \textmd{\texttt{uskpdc}}}
%==================================

\noindent
\textit{Subroutine called every time step.}

This subroutine is called three times every time step and for each phase
\texttt{iphas}.

The tensor representing the pressure drops is supposed to be symmetric
and positive.

\begin{list}{$\bullet$}{}
\item During the first call, all the cells are checked to know the
      number of cells in which a pressure drop is present for the phase
      \texttt{iphas}. This number is called \texttt{ncepdp\index{ncepdp}} in
      \texttt{uskpdc} (and corresponds to
      \texttt{ncepdc(iphas)\index{ncepdc}}). It is used to lay out the arrays
      related to the pressure drops. If there is no pressure drop,
      \texttt{ncepdp} must be equal to zero (it is the default value, and the
      rest of the subroutine is then useless).

\item During the second call, all the cells are checked again to
      complete the array \texttt{icepdp\index{icepdp}} whose size is
      \texttt{ncepdp}. \mbox{\texttt{icepdc(ielpdc)}} is the number of the
      \texttt{ielpdc}\raisebox{1ex}{\small th} cell containing pressure drops (for
      the current phase).

\item During the third call, all the cells containing pressure drops
      (for the current phase) are checked in order to complete the array
      containing the components of the tensor of pressure drops
      \mbox{\texttt{ckupdc(ncepdp,6)}\index{ckupdc}}. This array is so that
      the equation related to the velocity may be written:
\begin{displaymath}
\rho\frac{\partial}{\partial t}\vect{u}=\ldots -\rho\tens{K}\ind{pdc}\cdot\vect{u}
\end{displaymath}
The tensor components are given in the following order (in the general
      reference frame): \texttt{k11}, \texttt{k22}, \texttt{k33}, \texttt{k12},
      \texttt{k13}, \texttt{k23} with \texttt{k12}, \texttt{k13} and \texttt{k23}
      being zero if the tensor is diagonal.

\end{list}


The three calls are made every time step, so that variable pressure drop
zones or values may be treated.

%==================================
\subsection{Management of the mass sources: \textmd{\texttt{ustsma}}}
%==================================

\noindent
\textit{Subroutine called every time step.}

This subroutine is used to add a density source term in some cells of
the domain. The mass conservation equation is then modified as follows:
\begin{displaymath}
\frac{\partial \rho}{\partial t} + div(\rho\vect{u})=\Gamma
\end{displaymath}

$\Gamma$ is the mass source term expressed in $kg.m^{-3}.s^{-1}$.

The presence of a mass source term modifies the evolution equation of
the other variables, too. Let $\varphi$ be a any solved variable apart
from the pressure (velocity component, turbulent energy, dissipation,
scalar, ...). Its evolution equation becomes:
\begin{displaymath}
\rho\frac{\partial \varphi}{\partial t} + \ldots = \ldots + \Gamma(\varphi_i-\varphi)
\end{displaymath}

$\varphi_i$ is the value of $\varphi$ associated with the mass entering
or leaving the domain. After discretisation, the equation may be written:
\begin{displaymath}
\rho\frac{\varphi^{(n+1)}-\varphi^{(n)}}{\Delta t} + \ldots
= \ldots + \Gamma(\varphi_i-\varphi^{(n+1)})
\end{displaymath}

For each variable $\varphi$, there are two possibilities:
\begin{list}{$\bullet$}{}
\item We can consider that the mass is added (or removed) with the
      ambient value of $\varphi$. In this case
      $\varphi_i=\varphi^{(n+1)}$ and the equation of $\varphi$ is not
      modified.
\item Or we can consider that the mass is added with an
      imposed value $\varphi_i$ (this solution is physically correct
      only when the mass is effectively added, $\Gamma>0$).
\end{list}

\bigskip

This subroutine is called three times every time step (for each phase).

\begin{list}{$\bullet$}{}
\item During the first call, all the cells are checked to know the
      number of cells containing a mass source term for the current
      phase \texttt{iphas}. This number is called \texttt{ncesmp\index{ncesmp}} in
      \texttt{ustsma} (and corresponds to
      \texttt{ncetsm(iphas)\index{ncetsm}}). It is used to lay out the arrays
      related to the mass sources. If there is no mass source,
      \texttt{ncesmp} must be equal to zero (it is the default value, and the
      rest of the subroutine is then useless).

\item During the second call, all the cells are checked again to
      complete the array \texttt{icetsm\index{icetsm}} whose dimension is
      \texttt{ncesmp}. \mbox{\texttt{icetsm(ieltsm)}} is the number of the
      \texttt{ieltsm}\raisebox{1ex}{\small th} cell containing a mass source (for
      the current phase).

\item During the third call, all the cells containing mass sources are
      checked in order to complete the arrays
      \mbox{\texttt{itypsm(ncesmp,nvar)}\index{itypsm}} and
      \mbox{\texttt{smacel(ncesmp,nvar)}\index{smacel}}:\\
- \texttt{itypsm(ieltsm,ivar)} is the flow type associated with the variable
      \texttt{ivar} in the \texttt{ielstm}\raisebox{1ex}{\small th} cell
      containing a mass source.\\
\hspace*{1cm}\texttt{itypsm}=0: $\varphi_i=\varphi^{(n+1)}$ condition\\
\hspace*{1cm}\texttt{itypsm}=1: imposed $\varphi_i$ condition\\
\hspace*{1cm}\texttt{itypsm} is not used for \texttt{ivar=ipr(iphas)}\\
- \texttt{(ieltsm,ipr(iphas))} is the value of the mass source term $\Gamma$, in
$kg.m^{-3}.s^{-1}$.\\
- \texttt{smacel(ieltsm,ivar)}, for \texttt{ivar} different from
\texttt{ipr(iphas)}, is the value
of $\varphi_i$ for the variable \texttt{ivar} in the
\texttt{ielstm}\raisebox{1ex}{\small th} cell containing a mass source.\\

\minititre{Notes}
$\bullet$ If \texttt{itypsm(ieltsm,ivar)=0}, \texttt{smacel(ieltsm,ivar)}
      is not used.\\
$\bullet$ If $\Gamma$=\texttt{smacel(ieltsm,ipr(iphas))}$<$0, mass is removed from
      the system, and \CS considers automatically a
      $\varphi_i=\varphi^{(n+1)}$ condition, whatever the values given
      to \texttt{itypsm(ieltsm,ivar)} and \texttt{smacel(ieltsm,ivar)}
      (the extraction of a variable is done at ambient value).
\end{list}



The three calls are made every time step, so that variable mass source
zones or values may be treated.\\

For the variance, do not take into account the scalar $\varphi_i$ in the environment
where $\varphi\ne\varphi_i$ generates a variance source.

%========================================
\subsection{Thermal module in a 1D wall}
%========================================

\noindent
\textit{subroutine called at every time step}

This subroutine takes into account the affected thermal inertia by a wall.
 Some boundary faces are treated as a solid wall with a given thickness, on
 which the code resolves an undimensional equation for the heat conduction.
 The coupling between the 1D module and the fluid works in a similar way to
 the coupling with the \syrthes. In construction, the user is not able to
 account for the heat transfer between different parts of the wall. A physical
 analysis of each problem, case by case is required to evaluate the relevance
 of its usage by way of a report of the simple conditions (temperature, zero-flux
 ) or a coupling with \syrthes.\\

The use of this code requires that theres is only 1 phase (\texttt{nphas=1})
and that the thermal scalar is defined as (\texttt{iscalt}$>0$).

{\em WARNING: The 1D thermal module is developped assuming the thermal scalar
 as a temperature. If the thermal scalar is an enthalpy, the code calls the
 subroutine \texttt{usthht} for each transfer of information between the fluid
 and the wall in order to convert the enthalpy to temperature and vice-versa.
 This function has not been tested and is firmly discouraged. If the thermal
 variable is the total (compressible) energy, the thermal module will not work.}

\bigskip

This procedure  is called twice,on initialisation and again at each time step.

\begin{list}{$\bullet$}{}
\item The 1st call (initialisation) all the boundary faces that will be treated
 as a coupled wall are marked out. This figure is written noted as
 \texttt{nfkpt1d}. It applies dimension to the arrays in the thermal module.
 \texttt{nfkpt1d} will be at 0 if there are no coupled faces (it is in fact the
 default value, the remainer of the subroutine is not used in this case).
 The parameter \texttt{isuit1} also need to be defined, this indicates if the
 temperature of the wall must be initialised or written in the file (stored in
 the variable \texttt{filmt1}).
\item The 2nd call (initialisation) again concern the wall faces, it completes
 the \texttt{ifpt1d} array of dimension \texttt{nfpt1d}.
 \mbox{\texttt{ifpt1d(ifbt1d)}} is the number
 \texttt{ifbt1d}\raisebox{1ex}{\small th} boundary faces coupled with the thermal module
 of a 1D wall. The directional parameters are then completed for a pseudo
 wall associated to each face
\begin{list}{-}{}
\item \texttt{nppt1d(nfpt1d)\index{nppt1d}}: number of cells in the 1D mesh associated
 to the pseudo wall.
\item \texttt{eppt1d(nfpt1d)\index{eppt1d}}: thickness of the pseudo wall.
\item \texttt{rgpt1d(nfpt1d)\index{rgpt1d}}: geometery of the pseudo wall mesh (refined
 as a fluid if \texttt{rgt1d} is smaller than 1)
\item \texttt{tppt1d(nfpt1d)\index{tppt1d}}: initialisation temperature of the wall
(uniform in thickness). In the course of the calculation, the array stores the
 temperature of the solid at the fluid/solid interface.
\end{list}

Other than for re-reading a file (\texttt{ficmt1}), \texttt{tppt1d} is not used.
\texttt{nppt1d}, \texttt{ifpt1d}, \texttt{rgpt1d} and \texttt{eppt1d} are
compared to data from the follow-up file and they must be identical.

{\em WARNING: The test in \texttt{ifpt1d} implicilty assumes that the array is completed
 in ascending order (i.e \texttt{ifpt1d(ii)}$>$\texttt{ifpt1d(jj)} if ii$>$jj.
 This will be the case if the coupled faces are defined starting from the unique loop on the
boundary faces (as in the example). If this is not the case, contact the development
 team to short circuit the test.}

\item The 3rd call (at each time step) is for the confirmation that all the arrays
 involving physical parameter and external boundary conditions have been completed.
\begin{list}{-}{}
\item \texttt{iclt1d(nfpt1d)\index{iclt1d}}:Typical boundary condition at the external
 (pseudo) wall: Dirichlet condition (\texttt{iclt1d}=1) or flux condition (\texttt{iclt1d}=3)
\item \texttt{tept1d(nfpt1d)\index{tept1d}}: External temperature of the pseudo wall in the
 Dirichlet case.
\item \texttt{hept1d(nfpt1d)\index{hept1d}}: External coefficient of transfer in the pseudo
 wall under Dirichlet conditions(en $W.m^{-2}.K^.$).
\item \texttt{fept1d(nfpt1d)\index{nfpt1d}}: External heat flux in the pseudo wall  under
 the flux conditions(en $W.m^{-2}$,negative value for energy entering the wall)
\item \texttt{xlmt1d(nfpt1d)\index{xlmt1d}}: Conductivity$\lambda$ of the wall uniform
in thickness, (in $W.m^{-1}.K^{-1}$).
\item \texttt{rcpt1d(nfpt1d)\index{rcpt1d}}: Volumetric heat capacity $\rho C_p$ of the
wall uniform in thickness in $J.m^{-3}.K^{-1}$)
\item \texttt{dtpt1d(nfpt1d)\index{dtpt1d}}: Physical time step ascociated with the solved
 1D equation of the pseudo wall(which can be different from the time step in the
 calculation)
\end{list}

\end{list}

The 3rd call, done at each time step, allows the imposition of boundary conditions
 and physical values in time.

%==================================
\subsection{ Initialization of the options of the variables related
   to the ale module: \textmd{\texttt{usalin}} and \textmd{\texttt{usstr1}} }
%==================================
\label{prg_usalin}%
\noindent
\textit{Subroutine called at the start.}


\minititre{Subroutine \texttt{usalin}}
This subroutine completes \texttt{usini1}.

\texttt{usalin} allows to set option for the ale module, and in
particular to active the ale module

\minititre{Subroutine \texttt{usstr1}}

\texttt{usstr1} allows to specify for the structure module the
following pieces of information:
\begin{list}{-}{}
  \item number of structure (\texttt{nbstru}).
  \item initial value of deplacement, velocity and acceleration
    (\texttt{xstr0}, \texttt{xstreq} and \texttt{vstr0}).
\end{list}

Below is a list of the different variables that might be modified:

\begin{list}{$\bullet$}{}

\item{\texttt{nbstru}} \\
{the number of structures}

\item{\texttt{idfstr(i)}} \\
{index of the structure, where I is the index of the face}

\item{\texttt{xstr0(i,k)}} \\
{initial position of a structure, where \texttt{i} is the dimension of space
and \texttt{k} the index of the structure}

\item{\texttt{xstreq(i,k)}} \\
{position of balance of a structure, where \texttt{i} is the dimension of space
and \texttt{k} the index of the structure}

\item{\texttt{vstr0(i,k)}} \\
{initial velicity of a structure, where \texttt{i} is the dimension of space
and \texttt{k} the index of the structure }
\end{list}

%==================================
\subsection{Management of the boundary conditions of velocity mesh related to the ale module: \textmd{\texttt{usalcl}}}
%==================================


\noindent
\textit{Subroutine called every time step.}

\minititre{Subroutine \texttt{usalcl}}
The use of \texttt{usalcl} is obligatory to run a calculation using
the ale module just as it is in \texttt{usini1}. The way of using it
is the same as the way of using \texttt{usclim} in the framework of
standard calculations, that is to say a loop on the boundary faces
marked out by their colour (or more generally by a property of their
family), where the type of boundary condition of velocity mesh for
each variable are defined.

The main numerical variables are described below.

\variab{ialtyb}{ialtyb(nfabor)}{ia}{In the ale module, the user
defines the velocity mesh from the colour of the boundary faces, or
more generally from their properties (colours, groups, ...), from the
boundary conditions defined in \texttt{usclim}, or even from their
coordinates. To do so, the array \texttt{ialtyb(nfabor)} gives for each face
\texttt{ifac} the velocity mesh boundary condition types marked out by the key
words \texttt{ivimpo\index{ivimpo}}, \texttt{igliss\index{igliss}},
\texttt{ibfixe\index{ibfixe}}

\begin{list}{$\bullet$}{}

\item If \texttt{ialtyb=ivimpo}: imposed velocity.

\begin{list}{$\rightarrow$}{}
\item In the case where all the nodes of a face have a imposed displacement,
 it is not necessary to fill the tables with boundary conditions
 velocity mesh for this face, they will be erased. In the other case,
 the value of the Dirichlet must be given in \texttt{rcodcl(ifac,ivar,1)} for
 every value of \texttt{ivar} (\texttt{iuma}, \texttt{ivma} and \texttt{iwma})
 The other boxes of \texttt{rcodcl} and \texttt{icodcl} are completed automatically.

 The tangential velocity mesh is taken like a tape speed under the
 boundary conditions of wall for the fluid, except if wall velocity
 was specified by the user in the interface or usclim (in which case
 it is this speed which is considered).
\end{list}

 \item if \texttt{ialtyb(nfac) = ibfixe}: fixed wall
\begin{list}{$\rightarrow$}{}
 \item the velocity is null.
\end{list}

 \item if \texttt{ialtyb(nfac) = igliss}:  sliding wall
\begin{list}{$\rightarrow$}{}
\item the tangential velocity is not used.
\end{list}

\end{list}

}


%==================================
\subsection{Management of the structure property: \textmd{\texttt{usstr2}}}
%==================================

\noindent
\textit{Subroutine called every time step.}

The use of \texttt{usstr2}
is obligatory to run a calculation using the ale module with a structure module.

For each structure, the system that will be solved is:

\begin{equation}
M.x^{''}+C.x^{''}+K.(x-x_{0} = 0
\end{equation}

where

\begin{list}{-}{}
 \item $M$ is the mass stucture (\texttt{xmstru}).
 \item $C$ is the dumping coefficient of the stucture (\texttt{xcstru}).
 \item $K$ is the spring constant or force constant of the stucture (\texttt{xkstru}).
 \item $x_{0}$ is the initial position
\end{list}

Below is a list of the different variables that might be modified:

\begin{list}{$\bullet$}{}

\item{\texttt{xmstru(i,j,k})} \\
{the mass stucture of the structure, where \texttt{i},\texttt{j} is
the array of mass structure and \texttt{k} the index of the structure.}

\item{\texttt{xcstru(i,j,k})}\\
{dumping coefficient of the stucture, where \texttt{i},\texttt{j} is the array of
dumping coefficient and \texttt{k} the index of the structure.}

\item{\texttt{xkstru(i,j,k)}}\\
{spring constant of the stucture, where \texttt{i},\texttt{j} is the array of spring
constant and \texttt{k} the index of the structure.}

\item{\texttt{forstr(i,k)}}\\
{force vector of the stucture, where \texttt{i} is the force vector and
\texttt{k} the index of the structure.}
\end{list}


%==================================
\subsection{Modification of the turbulent viscosity: \textmd{\texttt{usvist}}}
%==================================
\noindent
\textit{Subroutine called every time step.}

This subroutine is used to modify the calculation of the turbulent
viscosity of the phase \texttt{iphas}, {\em i.e.} $\mu_t$ in $kg.m^{-1}.s^{-1}$
(this piece of information, at the mesh cell centers, is conveyed by the
variable \texttt{propce(iel,ipcvst)}, with
\texttt{ipcvst =  ipproc(ivisct(iphas))}). The
subroutine is called at the beginning of every time step, after the
calculation of the physical parameters of the flow and of the
``conventional'' value of $\mu_t$ corresponding to the chosen turbulence
model (indicator \texttt{iturb(iphas)}).\\
{\em WARNING: The calculation of the turbulent viscosity being a
particularly sensible stage, a wrong use of {\em\texttt{usvist}} may
seriously distort the results.}

%==================================
%==================================
\subsection{Modification of the variable $C$ of the dynamic LES model:
  \textmd{\texttt{ussmag}}}
%==================================

\noindent
\textit{Subroutine called every time step in the case of LES with the
dynamic model.}

This subroutine is used to modify the calculation of the variable $C$ of
the LES sub-grid scale dynamic model.

Let us first remind that the LES approach introduces the notion of
filtering between large eddies and small motions. The solved variables
are said to be filtered in an ``implicit'' way. Sub-grid scale models
(``dynamic'' models) introduce in addition an explicit filtering.

The notations used for the definition of the variable $C$ used in the
dynamic models of \CS are specified below. These notations are the ones
assumed in the document \cite{benhamadouche01}, to which the user may
refer for more details.

The value of $a$ filtered by the explicit filter (of width
$\widetilde{\overline{\Delta}}$) is called $\widetilde{a}$ and the value
of $a$ filtered by the implicit filter (of width $\overline{\Delta}$) is
called $\overline{a}$.
We define:
\begin{equation}
\begin{array}{ll}
\overline{S}_{ij}=\frac{1}{2}(\frac{\partial \overline{u}_i}{\partial x_j}
                  +\frac{\partial \overline{u}_j}{\partial x_i})  &
||\overline{S}||=\sqrt{2 \overline{S}_{ij}\overline{S}_{ij}}\\
\alpha_{ij}=-2\widetilde{\overline{\Delta}}^2
             ||\widetilde{\overline{S}}||
             \widetilde{\overline{S}}_{ij}&
\beta_{ij}=-2\overline{\Delta}^2
             ||\overline{S}||
               \overline{S}_{ij}\\
L_{ij}=\widetilde{\overline{u}_i\overline{u}_j}-
 \widetilde{\overline{u}}_i\widetilde{\overline{u}}_j&
M_{ij}=\alpha_{ij}-\widetilde{\beta}_{ij}\\
\end{array}
\end{equation}


In the framework of LES, the total viscosity (molecular + sub-grid) in
$kg.m^{-1}.s^{-1}$ may be written in \CS:
\begin{equation}
\begin{array}{llll}
\mu_{\text{total}}&=&\mu+\mu_{\text{sub-grid}} &
    \text{\ \ if\ \ }\mu_{\text{sub-grid}}>0\\
                   &=&\mu                          &
    \text{\ \ otherwise }\\
\text{with\ }\mu_{\text{sub-grid}}&=&\rho C \overline{\Delta}^2 ||\overline{S}||
\end{array}
\end{equation}

$\overline{\Delta}$ is the width of the implicit filter, defined at the
cell $\Omega_i$ by \\
$\overline{\Delta}=XLESFL(IPHAS)*(ALES(IPHAS)*|\Omega_i|)^{BLES(IPHAS)}$
\index{xlesfl}\index{ales}\index{bles}.

In the case of the Smagorinsky model (\texttt{iturb(iphas)=40}), $C$ is a
constant which is worth $C_s^2$. $C_s^2$ is the so-called Smagorinsky
constant and is stored the variable \texttt{$csmago$\index{csmago}}.

In the case of the dynamic model (\texttt{iturb(iphas)=41}), $C$ is variable in
time and in space. It is determined by
$\displaystyle C=\frac{M_{ij}L{ij}}{M_{kl}M_{kl}}$.

In practice, in order to increase the stability, the code does not use the
value of $C$ obtained in each cell, but an average with the values
obtained in the neighboring cells (this average uses the extended
neighborhood and corresponds to the explicit filter). By default, the
value calculated by the code is
\begin{displaymath}
C=\frac{\widetilde{M_{ij}L{ij}}}{\widetilde{M_{kl}M_{kl}}}
\end{displaymath}

The subroutine \texttt{ussmag} allows to modify this value. It is for
example possible to calculate the local average after having calculated the
ratio
\begin{displaymath}
C=\widetilde{\left[\frac{M_{ij}L{ij}}{M_{kl}M_{kl}}\right]}
\end{displaymath}

{\em WARNING: The subroutine {\em\texttt{ussmag}} can be activated only when
the dynamic model is used.}

%==================================
\subsection{Temperature-enthalpy and enthalpy-temperature conversions: \textmd{\texttt{usthht}}}
%==================================

\noindent
\textit{Subroutine optionally called.}

This subroutine is used to encapsulate a simple enthalpy-temperature
conversion law and its inverse.
This subroutine is called in \texttt{usray4}, user subroutine from the
radiation module.

%==================================
\subsection{Modification of the mesh geometry: \textmd{\texttt{usmodg}}}
%==================================

\noindent
\textit{Subroutine called only during the calculation initialisation.}

This subroutine may be used to modify ``manually'' the mesh vertices
coordinates, \textit{i.e.} the array:
\begin{list}{$\bullet$}{}
\item \mbox{\texttt{xyznod(3,nnod)}} (vertex coordinates)
\end{list}

{\em WARNING: Caution must be exercised when using this subroutine
along with periodicity. Indeed, the periodicity parameters are not
updated accordingly, meaning that the periodicity may be unadapted
after one changes the mesh vertex coordinates. It is particularly
true when one rescales the mesh.}\\

%==================================
\subsection{Management of the post-processing intermediate outputs: \textmd{\texttt{usnpst}}}
%==================================

\noindent
\textit{Subroutine called every time step(even if the user hasn't moved it to the SRC directroy).}

This subroutine is used to determine when post-processing outputs will be
generated. By default, it tests if the current time step number (\texttt{ntcabs}) is a
multiple of the chosen output frequency (\texttt{ntchr}). If it is the case, the
indicator \texttt{iipost} turns to 1, which triggers the writing of an
intermediate output. If the frequency is given a negative value, the
test is not done.

For instance, a user who wants to generate post-processing outputs (also
called ``chronological outputs'') at
the time step number 36 and around the physical time $t$=12 seconds may
use the following test:\\

\begin{tabular}{ll}
\mbox{\texttt{iipost = 0}}
                    & No output by default. \\
\mbox{\texttt{if (ntcabs.eq.36) then}}
                    & If the current time step is the 36$^{\text{th}}$,\\
\mbox{\texttt{~~~iipost=1}}
                    & ~~~generate an output. \\
\mbox{\texttt{endif}}
                    & End of the test on the time step number. \\
\mbox{\texttt{if (abs(ttcabs-12.d0).le.0.01d0) then}}
                    & If the physical time is 12s +/- 0.01s,\\
\mbox{\texttt{~~~iipost=1}}
                    & ~~~generate an output. \\
\mbox{\texttt{endif}}
                    & End of the test on the physical time. \\
\end{tabular}

In any case, a post-processing output is generated after the last time
step, \texttt{usnpst} being used or not.

\newpage
%==================================
\subsection{Definition of post-processing and mesh zones:
  \textmd{\texttt{usdpst}}}
%==================================

\noindent
\textit{Subroutine called at the calculation beginning..}

This subroutine allows for the definition of  surface or volume
sections, in the form of lists of \texttt{nlfac} internal faces
(\texttt{lstfac}) and \texttt{nlfab} boundary faces (\texttt{lstfab}),
or of \texttt{nlcel} cells (\texttt{lstcel}), in order to generate
chronological outputs in {\em EnSight}, {\em MED} or {\em CGNS} format.

One or several ``writers'' can be associated with each visualization
mesh, or ``part'' created. The arguments of the function \texttt{pstcwr}
defining a ``writer'' are as follows:

\begin{list}{$\bullet$}{}
       \item \texttt{nomcas}: basic name of the associated case.\\ {\em
             WARNING}: depending on the chosen format, this name may
             be shortened (maximum number of characters: 32 for {\em MED},
             19 for {\em EnSight}) or modified automatically (whitespaces or
             forbidden characters will be replaced by '\_')
       \item \texttt{nomrep}: name of the output directory
       \item \texttt{nomfmt}: choice of the output format:
        \begin{list}{$\rightarrow$}{}
               \item {\em EnSight Gold} ({\em EnSight} also accepted)
               \item {\em MED\_fichier} ({\em MED} also accepted)
               \item {\em CGNS}
               \item {\em text} (mesh output, no variables output, for debug only).
         \end{list}
The options are not case-sensitive, so {\em ensight} or {\em cgns} are valid, too.
       \item \texttt{optfmt}: character string containing a list of
             options related to the format, separated by commas; for the
             {\em EnSight Gold} format, these options are:
        \begin{list}{$\rightarrow$}{}
               \item {\em binary} for a binary format version (by default)
               \item {\em text} for a text format version
               \item {\em discard\_polygons} to prevent from exporting faces with more
 than four edges (which may not be recognized by some post-processing tools); such
 faces will therefore not appear in the post-processing mesh.
               \item {\em discard\_polyhedra} to prevent from exporting elements which
 are neither tetrahedra, prisms, pyramids nor hexahedra (which may not be recognized by
 some post-processing tools); such elements will therefore not appear in
 the post-processing mesh.
               \item {\em divide\_polygons}  to divide faces with more than four edges
 into triangles, so that any post-processing tool can recognize them
               \item {\em divide\_polyhedra} to divide elements which are neither
 tetrahedra, prisms, pyramids nor hexahedra into simpler elements (tetrahedra and
 pyramids), so that any post-processing tool can recognize them
               \item {\em split\_tensor} to export the components of a tensor
 variable as a series of independent variables (a variable is recognised as a
 tensor if its dimension is 6 or 9); not implemented yet.
         \end{list}
       \item \texttt{indmod}: indicates if the post-processing (i.e. visualization) meshes
             (or ``parts'') are:
        \begin{list}{$\rightarrow$}{}
               \item 0 fixed (usual case)
               \item 1 deformable (the vertex positions may vary over time)
               \item 2 modifiable:  (the lists of cells or faces
                     defining these ``parts'' can be changed over time)
         \end{list}
       \item \texttt{ntchrl}: default output frequency associated with
             this ``writer'' (the output may be forced or prevented at
             every time step using the subroutine \texttt{usnpst})
\end{list}

In order to allow the user to add an output format to
the main output format, or to add a mesh to the default
output, the lists of standard and user meshes and ``writers'' are not
separated. Negative numbers are reserved for the non-user items. For
instance,the mesh numbers -1 and -2 correspond respectively to the global
mesh and to boundary faces, generated by default, and the ``writer'' -1
corresponds to the usual post-processing case defined {\em via}
\texttt{usini1} or {\em via} the interface.

The user chooses the numbers corresponding to the post-processing
meshes and ``writers'' he wants to create. These numbers must be positive
integers. It is possible to assocate a user mesh with the standard
post-processing case (-1), or to ask for outputs regarding the boundary
faces (-2) associated with a user ``writer''.

For safety, the output frequency and the possibility to modify the
post-processing meshes are associated with the ``writers'' rather than
with with the ``parts''. This logic avoids unwanted generation of
inconstitent post-processing outputs. For instance EnSight would not
be able to read a case in which one field is output to a given part
every 10 time steps while another field is output to the same part
every 200 time steps.

The possibility to modify a mesh over time is limited by the more restrictive
``writer'' which is associated with it. For instance, if the ``writer''
1 allows the modification of the mesh topology (argument \texttt{indmod
= 2} in the call to \texttt{pstcwr}) and the ``writer'' 2 allows no
modification (\texttt{indmod = 0}), a user post-processing mesh
associated with the ``writers'' 1 and 2 will not be modifiable, but a
mesh associated only with the ``writer'' 1 will be modifiable. The
modification is done by means of the user subroutine \texttt{usmpst},
which is called only for the currently modifiable meshes.

It is possible to output variables which are normally automatically
output on the main volume or boundary meshes to a user mesh which is a subset
of one of these by assigning the corresponding category to the user
mesh. By default, a meshe's category is identical to its number, so
the category associated with the main volume output is -1, and that
associated with the main boundary output is -2. A category may be assigned
using the \texttt{pstcat} subroutine.

It is also possible to define an alias of a post-processing mesh. An
alias shares all the attributes of a ``part'' (without duplication),
except its number. This may be used to output different variables on a
same ``part'' with 2 different writers: the choice of output variables
is based on the ``part'', so if $P_a$ is associated with writer $W_a$,
all that is needed is to define an alias $P_b$ to $P_a$ and associate
it with writer $W_b$ to allow a different output variable selection with
each writer. An alias may be created using the \texttt{pstalm} subroutine.

Modification of a part or it's alias over time is always limited by the
most restrictive "writer" to which it's meshes have been asscoiated (parts of
the structures being shared in memory). It is possible to define as many
alias' as are required for a "part", but an alias cannot be defined for another alias.

It is not possible to mix cells and faces in the same ``part'' (most of
the post-processing tools being perturbed by such a case)\footnote{in thr
future, it will probably be possible to automatically add faces bearing
group or attribute characteristics to a cell mesh, but those faces will
only be written for formats supporting this (such as MED 2.3),
and will only bear attributes, not variable fields}. If the user
defines lists of faces and cells simultaneously, only the higher dimension
entities (the cells) will be taken into account.

For a better understanding, the user may refer to the example given in
{\texttt{usdpst}}. We can note that the whitespaces in the beginning or in
the end of the character strings given as arguments of the functions
called are suppressed automatically.

The variables to post-process on the defined ``parts'' will be specified
in the subroutine \texttt{usvpst}.  ``

{\em WARNING In the parallel case, some ``parts'' may not contain any
local elements on a given processor. This is not a problem at all, as
long as the ``part'' is defined for all processors (empty or not).
It would in fact not be a good idea at all to define a ``part'' only
if it contains local elements, global operations on the ``part'' would
become impossible, leading to probable deadlocks or crashes.}

%==================================
\subsection{Modification of the mesh zones to post-process:
  \textmd{\texttt{usmpst}}}
%==================================

\noindent
\textit{Subroutine called only for each modifiable ``part'', at every
active time step of an associated ``writer''.}

For the user ``parts'' defined {\em via} the user subroutine
\texttt{usdpst} and associated only with ``writers'' allowing the ``part''
modification over time ({\em i.e.} created with the
parameter \texttt{indmod} = 2), this subroutine is used to modify the
lists of cells, internal and boundary faces defining this ``part'' (or
post-processing mesh).

At first, the corresponding lists contain the previously defined
values. If these lists are modified for a given post-processing mesh, the
argument \texttt{imodif} must be given the value 1.If this argument
 maintains it's initial value of 0, the code will not consider this
 "part" to have been modified away from that call and it will offer
 to bring it upto date. It is in fact at the end of an optimisation
 so there is no need to modify these "parts" within the definate and
 modifiable assembly (if in doubt, let imodif=1).

Note that the \texttt{itypps} flag can be used to determine
whether the current post-processing mesh contains cells
(\texttt{itypps(1)} = 1), internal faces (\texttt{itypps(2)} = 1), or
boundary faces (\texttt{itypps(2)} = 1) globally (as the number of local cells
 or faces of a processor could be 0, it doesn't provide sufficient
 information).
 If at any time, a given part contains no element of any type, all the
 values of itypes will be 0 and that number cannot be put in the part
(\texttt {nummai}) to determine if it will affect the cells or
faces\footnote{It is not expressly forbidden to associate cells with the
``part'' at a certain timestep and faces at another, but this has not been tested}.

The user may refer to the example, in which cells are selected according
to a given criterion: \\
- For a volume ``part'', cells for which the velocity exceeds a certain
value. \\
- For a surface ``part'', interior faces which are between a cell in
which the velocity exceeds a certain value and a cell in which the
velocity is lower than this value (and boundary faces neighboring a
cell in which the velocity exceeds this value). This surface
post-processing mesh corresponds therefore to an approximation of a
velocity isosurface.

%==================================
\subsection{Definition of the variables to post-process:
  \textmd{\texttt{usvpst}}}
%==================================

\noindent
\textit{Subroutine called for each ``part'', at every active time step of an
associated ``writer'' (see \texttt{usdpst}).}

For the parts defined in \texttt{usdpst}, the subroutine \texttt{usvpst}
is used to specify the variables to post-process.

The output of a given variable is generated by means of a call to
\texttt{psteva}, whose arguments are:

\begin{list}{$\bullet$}{}
       \item \texttt{nummai}: current ``part'' number (input
             argument in \texttt{usvpst}).
       \item \texttt{namevr}: name to give to the variable.
       \item \texttt{idimt}: dimension of the variable (3 for a vector, 1 for
             a scalar).
       \item \texttt{ientla}: indicates if the stored arrays are
             ``interlaced'' or not:
        \begin{list}{$\rightarrow$}{}
               \item 0: not interlaced, in the form ${\{x_1, x_2, ..., x_n,
                         y_1, y_2, ..., y_n, z_1, z_2, ..., z_n\}}$ \\
                         (case of all variables defined in \texttt{rtp}).
               \item 1: interlaced, in the form ${\{x_1, y_1, z_1, x_2, y_2, z_2, ..., x_n, y_n, z_n\}}$ \\
                         (case of the geometric parameters, like
                     \texttt{xyzcen}, \texttt{surfbo}, ...).
         \end{list}
              For a scalar variable, this argument does not matter.
       \item \texttt{ivarpr}: indicates if the variable is defined on the
             ``parent'' mesh or locally:
        \begin{list}{$\rightarrow$}{}
               \item 0: variable generated by the user in the given work
                     arrays \texttt{tracel}, \texttt{trafac}, and
                     \texttt{trafbr} (whose size is respectively the
                     number of cells, internal faces and boundary faces
                     of the ``part'', $\times 3$). The arrays
                     \texttt{lstcel}, \texttt{lstfac}, and
                     \texttt{lstfbr} can be used to get the numbers
                     corresponding to the cells, internal faces and
                     boundary faces associated with the ``part'' and to
                     generate the appropriate post-processing variable.
               \item 1: variable already defined in the main mesh
                     (``parent'' mesh of the ``parts''), for example the
 variables in the rtp array. Instructions in the report which list\texttt
{lstcel}, \texttt{lstfac}, and \texttt{lstfbr}will be treated directly by
 the sub routine, avoiding unused copies and simplifying hte code
         \end{list}
       \item \texttt{ntcabs}: absolute current time step number. If a
             negative value is given (usually -1), the variable will be
             regarded  as time-independent (and we will have to make sure this
             call is only made once).
       \item \texttt{ttcabs}: current physical time value. It is not taken
             into account if \texttt{ntcabs} $< 0$.
       \item \texttt{tracel}: array containing the values of the
             variable at the cells. If \texttt{ivarpr} $= 1$, this
             argument will be replaced by the position of the beginning
             of the array on which the variable in defined, for instance
             \texttt{rtp(1, iu(1))} for the velocity of the phase 1.
       \item \texttt{trafac}: equivalent of \texttt{tracel} for the
             internal faces.
       \item \texttt{trafbr}: equivalent of \texttt{tracel} for the
             boundary faces.
\end{list}

The user may refer to the example, which presents the different ways of
generating an output of a variable.

{\em WARNING: Apart from the time-independent variables, it is not
recommended not to generate the same variables at every call
(corresponding to an active time step) for a given mesh, because the
post-processing tool may have difficulties to deal with such a case. To
generate outputs of different variables on the same mesh with different
frequancies, it is recommended to create an alias of this mesh and to
associate it with a different ``writer'' in the subroutine \texttt{usdpst}.}

%==================================
\subsection{Modification of the variables at the end of a time step: \textmd{\texttt{usproj}}}
%==================================

\noindent
\textit{Subroutine called every time step.}

This subroutine is called at the end of every time step. It is used to
print of modify any variable at the end of every time step.

Several examples are given:
\begin{list}{-}{}
\item Calculation of a thermal balance at  the boundaries and in the
      domain (including the mass source terms)

\item Modification of the temperature in a given area starting from a
      given time

\item Extraction of a 1D profile

\item Printing of a moment

\item Utilisation of utility
      subroutines useful in the case of a parallel calculation
      (calculation of a sum on the processors, of a maximum, ...)
\end{list}

{\em WARNING: As all the variables (solved variables, physical
properties, geometric parameters) can be modified in this subroutine, a
wrong use may distort totally the calculation.}

The thermal balance example is particularly interesting.
\begin{list}{-}{}
\item It can be easily adapted to another scalar (only three simple
      modifications to do, as indicated in the subroutine).
\item It shows how to make a sum on all the subdomains in the framework
      of a parallel calculation (see the calls to the subroutines
      \texttt{par*}).
\item It shows the precautions to take before doing some operations in
      the framework of periodic or parallel calculations (in particular
      when we want to calculate the gradient of a variable or to have
      access to values at the cells neighboring a face).
\item Finally it must not be forgotten that the solving with
      temperature as a solved variable is questionable when the specific
      heat is not constant.
\end{list}

%==================================
\subsection{Radiative thermal transfers in semi-transparent gray media}
%==================================

%==================================
\subsubsection{Initialisation of the radiation main key words: \textmd{\texttt{usray1}}}
%==================================

\noindent
\textit{Subroutine called only during calculation initialisation.}

This subroutine is one of the two which must be completed by the user for all
calculations including radiative thermal transfers. This subroutine is
composed of three headings. The first one is dedicated to the activation
of the radiation module, only in the case of classic physics. \\
{\em WARNING: when a calculation is run using a specific physics module,
this first heading must not be completed. The radiation module is then
activated or not according to the parameter file related to the considered
specific physics.} \\

\noindent
In the second heading the basic parameters of the radiation module are indicated.\\
Finally, the third heading deals with the selection of the
post-processing graphic outputs. The variables to treat are splitted
into two categories: the volumetric variables and those related to the
boundary faces.\\

\noindent
For more details about the different parameters, the user may refer to the
key word list (\S\ref{prg_motscles}).


%==================================
\subsubsection{Management of the radiation boundary conditions:
   \textmd{\texttt{usray2}}}
%==================================

\noindent
\textit{Subroutine called every time step.}

This is the second subroutine is necessary for every calculation
including radiative thermal transfers. It is used to give all the
necessary parameters concerning, in the one case, the wall temperature
calculation, and in the other, the coupling between the termal
scalar (temperature or enthalpy) and the radiation module at the
calculation domain boundaries. It must be noted that the boundary conditions
concerning the thermal scalar which may have been defined in the
subroutine \texttt{usclim} will be modified by the radiation module
according to the data given in \texttt{usray2} (cf. \S\ref{fvm_selector}).\\
A zone number must be given to each boundary face \footnote{this must be less
 than the maximum allowable by the code, \texttt{nozrdm}. This is fixed at 2000
 in \texttt{radiat.h} and cannot be modified.}and, specifically for
the walls, a boundary condition type and an initialisation temperature
(in Kelvin). The initialisation temperature is only used to make the
solving implicit at the first time step. The zone number allows to assign
an arbitrary integer to a set of boundary faces having the same
radiation boundary condition type. This gathering is used by the
calculation, and in the listing to print some physical values (mean
temperature, net radiative flux ...). An independent graphic output in
{\em EnSight} format is associated with each zone and allows the display on
the boundary faces of the variables selected in the third heading of the
subroutine \texttt{usray1}.\\
A boundary condition type stored in the array ISOTHP is associated with
each boundary face. There are five different types:

\begin{list}{$\bullet$}{}

\item \texttt{\textbf{itpimp}}: wall face with imposed temperature,

\item \texttt{\textbf{ipgrno}}: for a gray or black wall face, calculation of the
      temperature by means of a flux balance,

\item \texttt{\textbf{iprefl}}: for a reflecting wall face, calculation of the
      temperature by means of a flux balance.
 This is fixed at 2000 in \texttt{radiat.h} and cannot be modified.

\item \texttt{\textbf{ifgrno}}: gray or black wall face to which a conduction
      flux is imposed,

\item \texttt{\textbf{ifrefl}}: reflecting wall face to which a conduction
      flux is imposed, which is equivalent to impose this flux directly
      to the fluid.

\end{list}

\noindent
Depending on the selected boundary condition type at every wall face,
the code needs to be given some supplementary pieces of information:

\begin{list}{$\bullet$}{}

\item \texttt{\textbf{itpimp}}: the array \texttt{tintp} must be completed
      with the imposed temperature value and the array \texttt{epsp} must
      be completed with the emissivity value (strictly positive).

\item \texttt{\textbf{ipgrno}}: must be given: an initialisation temperature in
      the array \texttt{tintp}, the wall emissivity (strictly positive, in
      \texttt{epsp}), thickness (in \texttt{epap}), thermal conductivity
      (in \texttt{xlamp}) and an external temperature (in \texttt{textp})
      in order to calculate a conduction flux across the wall.

\item \texttt{\textbf{iprefl}}: must be given: an initialisation temperature (in
      \texttt{tintp}), the wall thickness (in \texttt{epap}) and thermal conductivity (in
      \texttt{xlamp}) and an external temperature (in \texttt{textp}).

\item \texttt{\textbf{ifgrno}}: must be given: an initialisation temperature (in
      \texttt{tintp}), the wall emissivity (in \texttt{epsp}) and the conduction
      flux (in $W/m^2$ whatever the thermal scalar, enthalpy or temperature) in
      the array \texttt{rcodcl}. The value of \texttt{rcodcl} is positive when the
      conduction flux is directed from the inside of the fluid domain to the
      outside (for instance, when the fluid heats the walls). If the
      conduction flux is null, the wall is adiabatic.

\item \texttt{\textbf{ifrefl}}: must be given: an initialisation temperature (in
      \texttt{tintp}) and the conduction flux (in $W/m^2$ whatever the thermal
      scalar) in the array \texttt{rcodcl}. The value of \texttt{rcodcl} is
      positive when the conduction flux is directed from the inside of the
      fluid domain to the outside (for instance, when the fluid heats the
      walls). If the conduction flux is null, the wall is adiabatic. The flux
      received by \texttt{rcodcl} is directly imposed as boundary condition for
      the fluid.

\end{list}

\noindent
{\em WARNING: it is obligatory to set a zone number to every boundary
face, even those which are not wall faces. These zones will be used during the
printing in the listing. It is recommended to gather together the
boundary faces of the same type, in order to ease the reading of the
listing.}\\

%==================================
\subsubsection{Absorption coefficient of the medium, boundary conditions
   for the luminance and calcualtion of the net radiative flux:
   \textmd{\texttt{usray3}}}
%==================================

\noindent
\textit{Subroutine called every time step.}

This subroutine is composed of three parts. In the first one, the user
must provide the absorption coefficient of the medium in the array CK,
for each cell of the fluid mesh. By default, the absorption coefficient
of the medium is 0, which corresponds to a transparent medium.\\

{\em WARNING: when a specific physics is activated, it is forbidden to
give a value to the absorption coefficient in this subroutine. In this
case, it is calculated automatically, or given by the user {\em via} a
thermo-chemical parameter file (dp\_C3P or dp\_C3PSJ for gas combustion,
and dp\_FCP for pulverised coal combustion).}\\

\noindent
The two following parts of this subroutine concern a more advanced use
of the radiation module. It is about imposing boundary conditions to the
equation of radiative transfer and net radiative flux calculation, in
coherence with the luminance at the boundary faces, when the user wants
to give it a particular value. In most cases, the given examples do not
need to be modified.

%==================================
\subsubsection{Encapsulation of the temperature-enthalpy conversion:
  \textmd{\texttt{usray4}}}
%==================================

\noindent
\textit{Subroutine called every time step.}

This subroutine is used to call the subroutine \texttt{usthht}. The user
can implement his own conversion formulas into it. \\
This subroutine is useless when the thermal scalar is the temperature.\\
\noindent

{\em WARNING: when a specific physics is activated, it is forbidden to use this
subroutine. In this case, {\em \texttt{usray4}} is replaced by {\em
\texttt{ppray4}}, which is not a user subroutine.}\\


\noindent
The value of the argument \texttt{mode} allows to know in which direction the
conversion will be made:
\begin{list}{$\bullet$}{}

\item \texttt{\textbf{mode = 1}}: the fluid enthalpy in the cell must be
      converted into temperature (in Kelvin),

\item \texttt{\textbf{mode = -1}}: the wall temperature (\texttt{text}
      or \texttt{tparoi}, in Kelvin) must be converted into enthalpy.

\end{list}
%
{\em WARNING: the value of \texttt{mode} is passed as argument and must not be
modified by the user.}\\



%==================================
\subsection{Utilisation of a specific physics: \textmd{\texttt{usppmo}}}
%==================================
\label{prg_usppmo}%
\noindent
\textit{Subroutine called only during calculation initialisation.}

This is one of the three subroutines which must be obligatory completed
by the user in order to use a specific physics module.
At the moment, \CS allows to use two ``pulverised coal'' modules
(Lagrangian coupling or not), two ``gas combustion'' modules, two
``electric'' modules and one ``compressible'' module. To activate one of
these modules, the user needs to complete one (and only one) of the
indicators \texttt{ippmod(i.....)\index{ippmod}} in the subroutine
\texttt{usppmo}. By default, all the indicators \texttt{ippmod(i.....)} are
initialised at -1, which means that no specific physics is activated.

\begin{list}{$\bullet$}{}
       \item Diffusion flame in the framework of ``3 points'' rapid complete
             chemistry: indicator {\bf \tt ippmod(icod3p\index{icod3p})}
        \begin{list}{$\rightarrow$}{}
               \item \texttt{ippmod(icod3p)} = 0 adiabatic conditions
               \item \texttt{ippmod(icod3p)} = 1 permeatic conditions (enthalpy
                     transport)
               \item \texttt{ippmod(icod3p)} =-1 module not activated
         \end{list}
        \item Eddy Break Up pre-mixed flame: indicator {\bf \tt
             ippmod(icoebu\index{icoebu})}
         \begin{list}{$\rightarrow$}{}
                \item \texttt{ippmod(icoebu\index{icoebu})} = 0 adiabatic
                      conditions at constant richness
                \item \texttt{ippmod(icoebu)} = 1 permeatic conditions at
                      constant richness
                \item \texttt{ippmod(icoebu)} = 2 adiabatic conditions at
                      variable richness
                \item \texttt{ippmod(icoebu)} = 3 permeatic conditions at
                      variable richness
                \item \texttt{ippmod(icoebu)} =-1 module not activated
         \end{list}
        \item Libby-Williams pre-mixed flame: indicator {\bf \tt ippmod(icolwc\index{icolwc})}
         \begin{list}{$\rightarrow$}{}
               \item \texttt{ippmod(icolwc)}=0 two peak model with adiabiatic conditions.
               \item \texttt{ippmod(icolwc)}=1 two peak model with permeatic conditions.
               \item \texttt{ippmod(icolwc)}=2 three peak model with adiabiatic conditions.
               \item \texttt{ippmod(icolwc)}=3 three peak model with permeatic conditions.
               \item \texttt{ippmod(icolwc)}=4 four peak model with adiabiatic conditions.
               \item \texttt{ippmod(icolwc)}=5 four peak model with permeatic condintions.
               \item \texttt{ippmod(icolwc)}=-1 module not activated.
          \end{list}
        \item Multi-coals and multi-classes pulverised coal combustion:
              indicator {\bf \tt ippmod(icp3pl\index{icp3pl})}
              The number of different coals must be inferior or equal to
              \texttt{ncharm\index{ncharm}} = 3. The number of particle size
             classes \texttt{nclpch\index{nclpch}(icha)} for the coal
             \texttt{icha}, must
             be inferior or equal to \texttt{ncpcmx\index{ncpcmx}} = 10.
         \begin{list}{$\rightarrow$}{}
                \item \texttt{ippmod(icp3pl)} = 0 imbalance between the
                      temperature of the continuous and the solid phases
                \item \texttt{ippmod(icp3pl)} = 1 otherwise
                \item \texttt{ippmod(icp3pl)} =-1 module not activated
         \end{list}
        \item Lagrangian modeling of multi-coals and
             multi-classes pulverised coal combustion:
                 indicator {\bf \tt ippmod(icpl3c\index{icpl3c})}
              The number of different coals must be inferior or equal to
              \texttt{ncharm\index{ncharm}} = 3. The number of particle size
             classes \texttt{nclpch\index{nclpch}(icha)} for the coal
             \texttt{icha}, must be inferior or equal to
             \texttt{ncpcmx\index{ncpcmx}} = 10.
         \begin{list}{$\rightarrow$}{}
                \item \texttt{ippmod(icpl3c)} = 1 coupling with the Lagrangian
                      module, with transport of $H_2$
                \item \texttt{ippmod(icpl3c)} =-1 module not activated
         \end{list}
       \item Electric arc module (Joule effect and Laplace forces):
             indicator {\bf \tt ippmod(ielarc\index{ielarc})}
        \begin{list}{$\rightarrow$}{}
               \item \texttt{ippmod(ielarc)} = 1 determination of the magnetic field by
                     means of the Ampere's theorem (not available)
               \item \texttt{ippmod(ielarc)} = 2 determination of the magnetic
                     field by means of the vector potential
               \item \texttt{ippmod(ielarc)} =-1 module not activated
         \end{list}
       \item Joule effect module (Laplace forces not taken into account):
             indicator {\bf \tt ippmod(ieljou\index{ieljou})}
        \begin{list}{$\rightarrow$}{}
               \item \texttt{ippmod(ieljou)} = 1 use of a real potential
               \item \texttt{ippmod(ieljou)} = 2 use of a complex potential
               \item \texttt{ippmod(ieljou)} = 3 use of real potential and specific boundary conditions for transformers.
               \item \texttt{ippmod(ieljou)} = 4 use of complex potential and specific boundary conditions for transformers.
               \item \texttt{ippmod(ieljou)} =-1 module not activated
         \end{list}
       \item Compressible module: indicator {\bf \tt
             ippmod(icompf\index{icompf})}
        \begin{list}{$\rightarrow$}{}
               \item \texttt{ippmod(icompf)} = 0 module activated
               \item \texttt{ippmod(icompf)} =-1 module not activated
         \end{list}

\end{list}

{\em WARNING: Only one specific physics module can be activated at the
same time.}

In the framework of the gas combustion modeling, the user may impose
his own enthalpy-temperature tabulation (conversion law). He needs then
to give the
value zero to the indicator \texttt{indjon\index{indjon}} (the default value
being 1). For more details, the user may refer to the following note
(thermo-chemical files).

\minititre{Note: the thermo-chemical files}
The user must not forget to place in the directory DATA the
thermo-chemical file \texttt{dp\_FCP}, \texttt{dp\_C3P}, \texttt{dp\_C3PSJ} or
\texttt{dp\_ELE} (depending on the specific physics module he activated)
and to specify the name of this file in the variable
THERMOCHEMISTRY\_DATA in the launch script
(for instance: THERMOCHEMISTRY\_DATA''dp\_C3P''). Some example files
are placed in the directory \texttt{DATA/THCH} at the creation of the
study case. Their content is described below.

\begin{list}{$\bullet$}{}
       \item Example of file for the gas combustion:
        \begin{list}{$\rightarrow$}{}
               \item if the enthalpy-temperature conversion data base
                     JANAF is used: \texttt{dp\_C3P} (see
                     array\ref{tab_dpC3P}).

\begin{table}[htbp]
\begin{center}
\small{
\begin{tabular}{|c|c|c|c|} \hline
 Lines  &Examples of values &        Variables             & Observations                                     \\ \hline
  1     &         5         &  \texttt{ngaze\index{ngaze}} & Number of current species                        \\ \hline
  2     &        10         &   \texttt{npo\index{npo}}    & Number of points for the                         \\
        &                   &                              & enthalpy-temperature tabulation                  \\ \hline
  3     &       300.        &  \texttt{tmin\index{tmin}}   & Temperature inferior limit                       \\
        &                   &                              & for the tabulation                               \\ \hline
  4     &      3000.        &  \texttt{tmax\index{tmax}}   & Temperature superior limit                       \\
        &                   &                              & for the tabulation                               \\ \hline
  5     &                   &                              & Empty line                                       \\ \hline
  6     & CH4 O2 CO2 H2O N2 &  \texttt{nomcoe\index{nomcoe}}(\texttt{ngaze}) & List of the current species                      \\ \hline
  7     &.35 .35 .35 .35 .35&  \texttt{kabse\index{kabse}}(\texttt{ngaze})   & Absorption coefficient                           \\
        &                   &                              & of  the current species                          \\ \hline
  8     &         4         &  \texttt{nato\index{nato}}   & Number of elemental species                      \\ \hline
  9     &.012  1  0  1  0  0& \texttt{wmolat\index{wmolat}}(\texttt{nato}),  & Molar mass of the elemental                      \\
 10     &.001  4  0  0  2  0&                              & species (first column)                           \\
 11     &.016  0  2  2  1  0&\texttt{atgaze\index{atgaze}}(\texttt{ngaze},\texttt{nato})& Composition of the current species             \\
 12     &.014  0  0  0  0  2&                              & as a function of the elemental species           \\
        &                   &                              & (\texttt{ngaze} following columns)                        \\ \hline
 13     &         3         &  \texttt{ngazg\index{ngazg}} & Number of global species                         \\
        &                   &                              & Here, \texttt{ngazg} = 3 (Fuel, Oxidiser and Products)    \\ \hline
 14     &  1. 0. 0. 0. 0.   &                              & Composition of the global species as a           \\
 15     &  0. 1. 0. 0. 3.76 &\texttt{compog\index{compog}}(\texttt{ngaze},\texttt{ngazg})& fonction of the current species of the line 6 \\
 16     &  0. 0. 1. 2. 7.52 &                              & In the order: Fuel (line 15),                    \\
        &                   &                              & Oxidiser (line 16) and Product (line 17)         \\ \hline
 17     &         1         &  \texttt{nrgaz\index{nrgaz}} & Number of global reactions                       \\
        &                   &                              & Here \texttt{nrgaz} = 1 (always equal to 1                \\
        &                   &                              & in this version)                                 \\ \hline
 18     &                   & \texttt{igfuel\index{igfuel}}(\texttt{nrgaz}), & Numbers of the global species concerned by       \\
        & 1 2 -1 -9.52 10.52&  \texttt{igoxy\index{igoxy}}(\texttt{nrgaz}),  & the stoichiometric ratio                         \\
        &                   &                              & (first 2 integers)                               \\
        &                   &\texttt{stoeg\index{stoeg}}(\texttt{ngazg},\texttt{nrgaz})& Stoichiometry in reaction global species.       \\
        &                   &                               & Negative for the reactants (here                \\
        &                   &                               & ``Fuel'' and ``Oxidiser'') and positive for      \\
        &                   &                               & the products (here ``Products'')                \\ \hline
\end{tabular}
}
\caption{Example of file for the gas combustion when JANAF is used: \texttt{dp\_C3P}}\label{tab_dpC3P}
\end{center}
\end{table}

               \item if the user provides his own enthalpy-temperature tabulation
                     (there must be three chemical species and only
                     one reaction): \texttt{dp\_C3PSJ} (see
                     array \ref{tab_dpC3PSJ}). This file replaces \texttt{dp\_C3P}.

\begin{table}[htbp]
\begin{center}
\small{
\begin{tabular}{|c|c|c|c|} \hline
 Lines  &            Examples of values     &        Variables            & Observations                                \\ \hline
   1    &                    6              &   \texttt{npo}              & Number of tabulation points                 \\ \hline
   2    &  50. -0.32E+07 -0.22E+06 -0.13E+08&                             &                                             \\
   3    & 250. -0.68E+06 -0.44E+05 -0.13E+08&\texttt{th\index{th}}(\texttt{npo}),           & Temperature(first column),                  \\
   4    & 450.  0.21E+07  0.14E+06 -0.13E+08& \texttt{ehgazg\index{ehgazg}}(1,\texttt{npo}),& mass enthalpy of fuel, oxidiser             \\
   5    & 650.  0.50E+07  0.33E+06 -0.12E+08& \texttt{ehgazg}(2,\texttt{npo}),              & and products (columns 2,3 and 4)            \\
   6    & 850.  0.80E+07  0.54E+06 -0.12E+08& \texttt{ehgazg}(3,\texttt{npo})               & from line 2 to line \texttt{npo}+1                   \\
   7    &1050.  0.11E+08  0.76E+06 -0.11E+08&                             &                                             \\ \hline
   8    & .00219       .1387        .159    &\texttt{wmolg(1)\index{wmolg}},       & Molar mass of fuel,                         \\
        &                                   &                    \texttt{wmolg(2)},& oxidiser                                    \\
        &                                   &                    \texttt{wmolg(3)} & and products                                \\ \hline
   9    &                .11111             &          \texttt{fs(1)\index{fs(1)}} & Mixing rate at the stoichiometry            \\
        &                                   &                             & (relating to Fuel and Oxidiser)             \\ \hline
  10    &    0.4      0.5       0.87        &\texttt{ckabsg\index{ckabsg}(1)},     & Absorption coefficient of fuel,             \\
        &                                   &                  \texttt{ckabsg(2)}, & oxidiser                                    \\
        &                                   &                  \texttt{ckabsg(3)}  & and products                                \\ \hline
  11    &    1.       2.                    & \texttt{xco2\index{xco2}},   \texttt{xh2o\index{xh2o}}& Molar coefficents of $CO_2$         \\
        &                                   &                             & and $H_2O$ in the products                  \\
        &                                   &                             & (radiation using Modak)                     \\ \hline
\end{tabular}
}
\caption{Example of file for the gas combustion when the user provides
 his own enthalpy-temperature tabulation
                     (there must be three species and only one
                     reaction): \texttt{dp\_C3PSJ} (this file replaces
 \texttt{dp\_C3P})}\label{tab_dpC3PSJ}
\end{center}
\end{table}
        \end{list}

       \item Example of file for the pulverised coal combustion:
             \texttt{dp\_FCP} (see array \ref{tab_dpFCP}).

\begin{table}[htbp]
\begin{center}
\tiny{
\begin{tabular}{|c|c|c|c|} \hline
 Lines  &      Examples of values        &        Variables              & Observations                                         \\ \hline
   1    &          THERMOCHIMIE          &                               & Comment line                                         \\ \hline
   2    &               8                & \texttt{ncoel\index{ncoel}}   & Number of current species                            \\ \hline
   3    &               8                &  \texttt{npo\index{npo}}      & Number of points for the                             \\
        &                                &                               & enthalpy-temperature tabulation                      \\ \hline
   4    &      ESPECES COURANTES         &                               & Comment line                                         \\ \hline
   5    & CH4 C2H4 CO O2 CO2 H2O N2 C(S) & \texttt{nomcoel\index{nomcoel}}(\texttt{ncoel}) & List of the                                          \\
        &                                &                               & current species                                      \\ \hline
   6    &               300.             &  \texttt{tmin\index{tmin}}    & Temperature inferior limit (Kelvin)                  \\
        &                                &                               & for the enthalpy-temperature tabulation              \\ \hline
   7    &              2400.             &  \texttt{tmax\index{tmax}}    & Temperature superior limit (Kelvin)                  \\
        &                                &                               & for the enthalpy-temperature tabulation              \\ \hline
   8    &               4                &  \texttt{nato\index{nato}}    & Number of elemental species                          \\ \hline
   9    &  .012  1  2  1  0  1  0  0  1  &                               & Molar mass of the elemental species                  \\
  10    &  .001  4  4  0  0  0  2  0  0  &\texttt{wmolat\index{wmolat}}(\texttt{nato}),    & (first column)                                       \\
  11    &  .016  0  0  1  2  2  1  0  0  &\texttt{atcoel\index{atcoel}}(\texttt{ncoel,nato})& and composition of the current species              \\
  12    &  .014  0  0  0  0  0  0  2  0  &                               & as a function of the elemental species               \\ \hline
  13    &          RAYONNEMENT           &                               & Comment line                                         \\ \hline
  14    &               0.1              & \texttt{ckabs1\index{ckabs1}}  & Constant absorption coefficient                      \\
        &                                &                               & for the gas mixture                                  \\ \hline
  15    &   CARACTERISTIQUES CHARBONS    &                               & Comment line                                         \\ \hline
  16    &               2                & \texttt{ncharb\index{ncharb}} & Number of coal types                                 \\ \hline
  17    &         1            1         & \texttt{nclpch\index{nclpch}}(\texttt{ncharb}) & Number of classes for each coal                      \\
        &                                &                               & (each column corresponding to                        \\
        &                                &                               & one coal type )                                      \\ \hline
  18    &    50.E-6        50.E-6        & \texttt{diam20\index{diam20}}(\texttt{nclacp})  & Initial diameter of each class (m)                   \\
        &                                &                               & \texttt{nclacp\index{nclacp}} is the total number of classes. \\
        &                                &                               & All the diameters are written on the same line       \\
        &                                &                               & (sucessively for each coal, we give the              \\
        &                                &                               & diameter corresponding to each class)                \\ \hline
  19    &    74.8          60.5          & \texttt{cch\index{cch}}(\texttt{ncharb})& Composition in C (mass.-\%, dry) of each coal        \\ \hline
  20    &     5.1           4.14         & \texttt{hch\index{hch}}(\texttt{ncharb})& Composition in H (mass.-\%, dry) of each coal        \\ \hline
  21    &    12.01          5.55         & \texttt{och\index{och}}(\texttt{ncharb})& Composition in O (mass.-\%, dry) of each coal        \\ \hline
  22    & 0  31524000.    0  31524000.   & \texttt{ipci\index{ipci}}(\texttt{ncharb})      & Value of the PCI ($Jkg^{-1}$) for each coal,         \\
        &                                & \texttt{pcich\index{pcich}}(\texttt{ncharb})    & the first integer indicating if this value refers    \\
        &                                &                               & to pure (0) or dry coal (1)                          \\ \hline
  23    &   1800.      1800.             & \texttt{cp2ch\index{cp2ch}}(\texttt{ncharb})& Heat-storage capacity at constant pressure        \\
        &                                &                               & ($Jkg^{-1}K^{-1}$) for each coal                     \\ \hline
  24    &   1200.      1200.             & \texttt{rho0ch\index{rho0ch}}(\texttt{ncharb})   & Initial density ($kgm^{-3}$) of each                 \\ \hline
  25    &          Coke                  &                               & Comment line                                         \\ \hline
  26    &      0.         0.             & \texttt{cck\index{cck}}(\texttt{ncharb}) & Composition in C (mass.-\%, dry) of the coke         \\
        &                                &                               & for each coal                                        \\ \hline
  27    &      0.         0.             & \texttt{hck\index{hck}}(\texttt{ncharb}) & Composition in H (mass.-\%, dry) of the coke         \\
        &                                &                               & for each coal                                        \\ \hline
  28    &      0.         0.             & \texttt{ock\index{ock}}(\texttt{ncharb}) & Composition in O (mass.\%, dry) of the coke          \\
        &                                &                               & for each coal                                        \\ \hline
  29    &      0.         0.             & \texttt{pcick\index{pcick}}(\texttt{ncharb})& PCI of the dry coke ($Jkg^{-1}$) for each coal       \\ \hline
  30    &          Cendres               &                               & Comment line                                         \\ \hline
  31    &      6.3        6.3            & \texttt{xashch\index{xashch}}(\texttt{ncharb})& Ash mass fraction (mass.-\%, dry) in each coal       \\ \hline
  32    &      0.         0.             & \texttt{h0ashc\index{h0ashc}}(\texttt{ncharb})  & Ash formation enthalpy ($Jkg^{-1}$)                  \\
        &                                &                               & for each coal                                        \\ \hline
  33    &      0.         0.             & \texttt{cpashc\index{cpashc}}(\texttt{ncharb})   & CP of the ashes ($Jkg^{-1}K^{-1}$) for each coal     \\ \hline
  34    &  D\'evolatilisation (Kobayashi)  &                             & Comment line                                         \\ \hline
  35    &  1  0.37      0  0.37          & \texttt{iy1ch\index{iy1ch}}(\texttt{ncharb}),   & For each coal, pairs (\texttt{iy1ch}, \texttt{y1ch}).                  \\
        &                                & \texttt{y1ch\index{y1ch}}(\texttt{ncharb})     & The real \texttt{y1ch} is the adimensional stoich. coefficient\\
        &                                &                               & If the integer \texttt{iy1ch} is worth 1,                     \\
        &                                &                               & the provided value of \texttt{y1ch} is adopted and            \\
        &                                &                               & the composition of the light volatile matters        \\
        &                                &                               & is calculated automatically.                         \\
        &                                &                               & If the integer \texttt{iy1ch} is worth 0,                     \\
        &                                &                               & the provided value of \texttt{y1ch} is ignored:               \\
        &                                &                               & \texttt{y1ch} is calculated automatically (the light          \\
        &                                &                               & volatiles are then composed of {$CH_{4}$}, {$CO$}).  \\ \hline
  36    &  1  0.74      1  0.74          & \texttt{iy2ch\index{iy2ch}}(\texttt{ncharb}),   & For each coal, pairs (\texttt{iy2ch}, \texttt{y2ch}).                  \\
        &                                & \texttt{y2ch\index{y2ch}}(\texttt{ncharb})     & The real \texttt{y2ch} is the adimensional stoich. coefficient\\
        &                                &                               & If the integer \texttt{iy2ch} is worth 1,                     \\
        &                                &                               & the provided value of \texttt{y2ch} is adopted and            \\
        &                                &                               & the composition of the heavy volatile matters        \\
        &                                &                               & is calculated automatically.                         \\
        &                                &                               & If the integer \texttt{iy2ch} is worth 0,                     \\
        &                                &                               & the provided value of \texttt{y2ch} is ignored:               \\
        &                                &                               & \texttt{y2ch} is calculated automatically (the heavy          \\
        &                                &                               & volatiles are then composed of {$C_{2}H_{4}$}, {$CO$}).\\ \hline
  37    &  370000.      410000.          & \texttt{a1ch\index{a1ch}}(\texttt{ncharb})& Devolatilisation pre-exponential factor A1 ($s^{-1}$)\\
        &                                &                               & for each coal (light volatile matters)               \\ \hline
  38    &  1.3E13       1.52E13          & \texttt{a2ch\index{a2ch}}(\texttt{ncharb})& Devolatilisation pre-exponential factor A2 ($s^{-1}$)\\
        &                                &                               & for each coal (heavy volatile matters)               \\ \hline
  39    &   74000.       80000.          & \texttt{e1ch\index{e1ch}}(\texttt{ncharb})& Devolatilisation activation energy E1 ($Jmol^{-1}$)  \\
        &                                &                               & for each coal (light volatile matters)               \\ \hline
  40    &  250000.      310000.          & \texttt{e2ch\index{e2ch}}(\texttt{ncharb})& Energie d'activation E2 ($Jmol^{-1}$) de d\'evolatilisation\\
        &                                &                               & for each coal (heavy volatile matters)               \\ \hline
  41    &  Combustion h\'et\'erog\`ene   &                               & Ligne de commentaire                                 \\ \hline
  42    &      17.88        17.88        & \texttt{ahetch\index{ahetch}}(\texttt{ncharb})   & Char burnout pre-exponential constant                \\
        &                                &                               & ($kgm^{-2}s^{-1}atm^{-1}$) for each coal             \\ \hline
  43    &      16.55        16.55        & \texttt{ehetch\index{ehetch}}(\texttt{ncharb})   & Char burnout activation energy ($kcalmol{-1}$)       \\
        &                                &                               & for each coal                                        \\ \hline
  44    &       1            1           & \texttt{iochet\index{iochet}}(\texttt{ncharb})   & Char burnout reaction order for each coal            \\
        &                                &                               & 0.5 if \texttt{iochet} = 0 and 1 if \texttt{iochet} = 1                \\ \hline
\end{tabular}
}
\caption{Example of file for the pulverised coal combustion:
 \texttt{dp\_FCP}}\label{tab_dpFCP}
\end{center}
\end{table}


       \item Example of file for the electric arc: \texttt{dp\_ELE} (see
             array \ref{tab_dpELE}).

\begin{table}[htbp]
\begin{center}
\small{
\begin{tabular}{|c|l|c|c|} \hline
 Li nes & Examples of values               & Variables & Observations                                       \\ \hline
  1     &\# Fichier ASCII format libre ... &           & Free comment                                       \\ \hline
  2     &\# Les lignes de commentaires ... &           & Free comment                                       \\ \hline
  3     &\#                            ... &           & Free comment                                       \\ \hline
  4     &\#   Proprietes de l'Argon    ... &           & Free comment                                       \\ \hline
  5     &\#                            ... &           & Free comment                                       \\ \hline
  6     &\# Nb d'especes NGAZG et Nb   ... &           & Free comment                                       \\ \hline
  7     &\# NGAZG NPO                  ... &           & Free comment                                       \\ \hline
  8     &    1   238         &    \texttt{ngazg\index{ngazg}}   & Number of species                         \\
        &                    &    \texttt{npo\index{npo}}       & Number of given temperature points for    \\
        &                    &                         & the tabulated physical properties                  \\
        &                    &                         & (\texttt{npo} $\leqslant$ \texttt{npot} set in \texttt{ppthch.h})             \\
        &                    &                         & So there will be \texttt{ngazg} blocks of \texttt{npo} lines each    \\ \hline
  9     &\#                            ... &           & Free comment                                       \\ \hline
 10     &\#  Proprietes                ... &           & Free comment                                       \\ \hline
 11     &\#  ~~~~T~~~~~~~~~~~H         ... &           & Free comment                                       \\ \hline
 12     &\#  Temperature  Enthalpie    ... &           & Free comment                                       \\ \hline
 13     &\#                            ... &           & Free comment                                       \\ \hline
 14     &\#  ~~~~~K~~~~~~~~~J/kg       ... &           & Free comment                                       \\ \hline
 15     &\#                            ... &           & Free comment                                       \\ \hline
 16     &    ~~~300.~~~~~~14000.       ... &           & Tabulation in line of the physical properties      \\
        &                                  &           & as a function of the temperature in Kelvin         \\
        &                                  &           & for each of the \texttt{ngazg} species             \\
        &                    &    \texttt{h}                    & Enthalpy in J/kg                                   \\
        &                    &    \texttt{roel}                 & Density in kg/m3                                   \\
        &                    &    \texttt{cpel}                 & Specific heat in J/(kg K)                          \\
        &                    &    \texttt{sigel}                & Electric conductivity in Ohm/m                     \\
        &                    &    \texttt{visel}                & Dynamic viscosity in kg/(m s)                      \\
        &                    &    \texttt{xlabel}               & Thermal conductivity in W/(m K)                    \\
        &                    &    \texttt{xkabel\index{xkabel}} & Absorption coefficient (radiation)                 \\   \hline
\end{tabular}
}
\caption{Example of file for the electric arc module:
 \texttt{dp\_ELE}}\label{tab_dpELE}
\end{center}
\end{table}

\end{list}

\clearpage
%==================================
\subsection{Management of the boundary conditions related to pulverised
  coal and gas combustion: \textmd{\texttt{usebuc, usd3pc, uslwcc,
  uscpcl and uscplc}} }
%==================================

\noindent
\textit{Subroutines called every time step.}

In this paragraph, ``specific physics'' refers to gas combustion or
to pulverised coal combustion.

As are \texttt{usini1} and \texttt{usppmo}, the use of \texttt{usebuc},
\texttt {usd3pc}, \texttt{uslwcc}, \texttt{uscpcl} or \texttt{uscplc} is
obligatory to run a calculation concerning a specific physics
modeling. The way of using them is the same as the way of using
\texttt{usclim} in the framework of standard calculations, that is to
say several loops on the boundary faces lists (cf. \S\ref{fvm_selector})
marked out by their colors, groups, or  geometrical criterion, where
the type of face, the type of boundary condition for each variable and
eventually the value of each variable are defined.

{\em WARNING: In the case of a specific physics modeling, all the
boundary conditions for every variable must be defined here, even for
the eventual user scalars: {\em \texttt{usclim}} is not used at all.}\\

In the case of a specific physics modeling, a zone number \texttt{izone}
\footnote{\texttt{izone} must be less than the maximum number of boundary
zone allowable by the code, \texttt{nozppm}. This is fixed at 2000 in
 \texttt{pppvar.h};not to be modified} (for
instance the color \texttt{icoul}) is associated with every boundary face, in
order to gather together all the boundary faces of the same type. In
comparison to \texttt{usclim}, the main change from the user point of
view concerns the faces whose boundary conditions belong to the type
\texttt{itypfb=ientre\index{ientre}}:

\begin{list}{$\bullet$}{}
       \item for the EBU pre-mixed flame module:
             \begin{list}{$\rightarrow$}{}
                    \item the user can choose between the ``burned gas
                          inlet'' type (marked out by the burned gas indicator
                          \texttt{ientgb\index{ientgb}(izone\index{izone})}=1) and the
                          ``fresh gas inlet'' type (marked out by
                          the fresh gas indicator
                          \texttt{ientgf\index{ientgf}(izone)}=1)
                    \item for each inlet type (fresh or burned
                          gas), a mass flow or a velocity must be imposed:

                          \begin{list}{-}{}
                                 \item to impose the mass flow,
                                     \begin{list}{-}{}
                                       \item the user gives to
                                             the indicator
                                             \texttt{iqimp\index{iqimp}(izone)}
                                             the value 1,
                                       \item  the
                                             mass flow value is set in
                                             \texttt{qimp\index{qimp}(izone)}
                                             (positive value, in $kgs^{-1}$)
                                       \item finally he imposes the
                                             velocity vector direction
                                             by giving the components of
                                             a direction vector in
                                             \texttt{rcodcl\index{rcodcl}(ifac,iu\index{iu}(iphas))}, \texttt{rcodcl(ifac,iv\index{iv}(iphas))} and \texttt{rcodcl(ifac,iw\index{iw}(iphas))}
                                     \end{list}

{\em WARNING:
\begin{list}{-}{}
\item the variable \texttt{qimp(izone)} refers to the mass flow across the whole
      zone \texttt{izone} and not across a boundary face (specifically for the axisymetric calculations, the inlet suface of the mesh must be broken up)
\item the variable \texttt{qimp(izone)} deals with the inflow across the area \texttt{izoz} and only across this zone;it is recomended to pay attention to the boundary conditions.
\item the velocity direction vector is neither necessarily normed, nor
      necessarily incoming.
\end{list}}

                                 \item to impose a velocity, the user
                                       must give to the indicator
                                       \texttt{iqimp(izone)} the value 0 and set
                                       the three velocity components (in
                                       $m.s^{-1}$) in
                                       \texttt{rcodcl(ifac,iu(iphas))},
                                       \texttt{rcodcl(ifac,iv(iphas))} and
                                       \texttt{rcodcl(ifac,iw(iphas))}
                          \end{list}
                    \item finally he specifies for each gas inlet type
                          the mixing rate \texttt{fment\index{fment}(izone)} and
                          the temperature \texttt{tkent\index{tkent}(izone)} in Kelvin
             \end{list}

       \item for the ``3 points'' diffusion flame module:
             \begin{list}{$\rightarrow$}{}
                    \item the user can choose between the ``oxydiser
                          inlet'' type marked out by
                          \texttt{ientox\index{ientox}(izone)}=1 and the ``fuel
                          inlet'' type marked out by
                          \texttt{ientfu\index{ientfu}(izone)}=1
                    \item concerning the input mass flow or the input
                          velocity, the method is the same as for the
                          EBU pre-mixed flame module
                    \item finally, the user sets the temperatures
                          \texttt{tinoxy\index{tinoxy}} for each oxydiser inlet
                          and \texttt{tinfue\index{tinfue}}, for each fuel inlet

{\em Note: In the standard version, only the cases with only one
                          oxydising inlet type and one fuel inlet type
                          can be treated. In particular, there must be
                          only one input temperature for the oxidiser
                          (\texttt{tinoxy}) and one input temperature for the
                          fuel (\texttt{tinfuel}).}
             \end{list}

       \item for the pulverised coal module:
             \begin{list}{$\rightarrow$}{}
                    \item the inlet faces can belong to the ``primary
                          air and pulverised coal inlet'' type, marked
                          out by \texttt{ientcp\index{ientcp}(izone)}=1, or to
                          the ``secondary or tertiary air inlet'' type,
                          marked out by \texttt{ientat\index{ientat}(izone)}=1
                    \item in a way which is similar to the process
                          described in the framework of the EBU module,
                          the user chooses for every inlet face to
                          impose the mass flow or not (\texttt{iqimp(izone)}=1 or
                          0). If the mass flow is imposed, the user
                          must set the air mass flow value
                          \texttt{qimpat\index{qimpat}(izone)}, its direction in
                          \texttt{rcodcl(ifac,iu(iphas))}, \texttt{rcodcl(ifac,iv(iphas))}
                          and \\ \texttt{rcodcl(ifac,iw(iphas))} and the incoming
                          air temperature \texttt{timpat\index{timpat}(izone)} in
                          Kelvin. If the velocity is imposed, he has to
                          set  \texttt{rcodcl(ifac,iu(iphas))}, \\
                          \texttt{rcodcl(ifac,iv(iphas))} and \texttt{rcodcl(ifac,iw(iphas))}.

                    \item if the inlet belongs to the ``primary air and
                          pluverised coal'' \texttt{type (ientcp(izone) = 1)} the
                          user must also define for each coal type \texttt{icha}:
                          the mass flow
                          \texttt{qimpcp\index{qimpcp}(izone,icha)}, the
                          granulometric distribution
                          \texttt{distch\index{distch}(izone,icha,iclapc)}
                          related to each class \texttt{iclacp}, and the
                          injection temperature
                          \texttt{timpcp\index{timpcp}(izone,icha)}

             \end{list}
\end{list}

%==================================
\subsection{Initialisation of the variables related to pulverised
  coal and gas combustion: \textmd{\texttt{usebui, usd3pi, uslwci and uscpiv}}}
%==================================

\noindent
\textit{Subroutines called only during the calculation initialisation.}

In this paragraph, ``specific physics'' refers to gas combustion or
to pulverised coal combustion.

These subroutines allow the user to initialise some variables specific
to the specific physics activated {\em via} \texttt{usppmo}. As usual,
the user may have access to several geometric variables to discriminate
between different initialisation zones if needed.

{\em WARNING: in the case of a specific physics modeling, all the
variables will be initialised here, even the eventual user scalars: {\em
\texttt{usiniv}} is no longer used.}


\begin{list}{$\bullet$}{}
       \item in the case of the EBU pre-mixed flame module, the user can
             initialise in every cell \texttt{iel}: the mixing rate
             \texttt{rtp\index{rtp}(iel,isca(ifm))} in variable richness, the
             fresh gas mass fraction \\
             \texttt{rtp(iel,isca(iygfm\index{iygfm}))}
             and the mixture enthalpy \texttt{rtp(iel,isca(ihm\index{ihm}))} in
             permeatic conditions

        \item in the case of the rapid complete chemistry diffusion flame
             module, the user can initialise in every cell \texttt{iel}: the
             mixing rate \texttt{rtp(iel,isca(ifm\index{ifm}))}, its variance
             \texttt{rtp(iel,isca(ifp2m\index{ifp2m}))} and the mixture mass
             enthalpy \texttt{rtp(iel,isca(ihm))} in permeatic conditions

        \item in the case of the pulverised coal combustion module, the
             user can initialise in every cell \texttt{iel}:
              \begin{list}{$\rightarrow$}{}
                     \item the transport variables related to the solid phase
                           \begin{list}{}{}
                                  \item \texttt{rtp(iel,isca(ixch\index{ixch}(icla)))} the reactive coal mass fraction related to the class \texttt{icla} (\texttt{icla} from 1 to \texttt{nclacp} which is the total number of classes, {\em i.e.} for all the coal type)
                                  \item \texttt{rtp(iel,isca(ixck(\index{ixck}icla)))} the coke mass fraction related to the class \texttt{icla}
                                  \item        \texttt{rtp(iel,isca(inp\index{inp}(icla)))} the number of particles related to class \texttt{icla} per kg of air-coal mixture
                                  \item \texttt{rtp(iel,isca(ih2\index{ih2}(icla)))} the mass enthalpy related to the class \texttt{icla} in permeatic conditions
                           \end{list}
                     \item \texttt{rtp(iel,isca(ihm))} the mixture enthalpy
                     \item the transport variables related to the gas phase
                           \begin{list}{}{}
                                  \item
                                       \texttt{rtp(iel,isca(if1m\index{if1m}(icha)))} the mean value of the tracer 1 representing the light volatile matters released by the coal \texttt{icha}
                                  \item
                                       \texttt{rtp(iel,isca(if2m\index{if2m}(icha)))} the mean value of the tracer 2 representing the heavy volatile matters released by the coal \texttt{icha}
                                  \item \texttt{rtp(iel,isca(if3m\index{if3m}))}
                                        the mean value of the tracer 3
                                        representing the carbon released
                                        as CO during coke burnout
                                  \item \texttt{rtp(iel,isca(if4p2m\index{if4p2m}))} the variance associated with the tracer 4 representing the air (the mean value of this tracer is not transported, it can be deduced directly from the three others)
                                  \item \texttt{rtp(iel,isca(ifp3m\index{ifp3m}))} the variance associated with the tracer 3
                           \end{list}
              \end{list}
\end{list}


%==================================
\subsection{Initialisation of the options of the variables related to
  pulverised coal and gas combustion: \textmd{\texttt{usebu1, usd3p1,
  uslwc1, uscpi1 and uscpl1}}}
%==================================

\noindent
\textit{Subroutines called at calculation beginning.}

In this paragraph, ``specific physics'' refers to gas combustion or
pulverised coal combustion.

These 3 subroutines are used to complete \texttt{usini1} for the
considered specific physics.
They allow to:
\begin{list}{$\bullet$}{}
\item generate, for the variables which are specific to the activated
             specific physics module, chronological outputs (indicators
             \texttt{ichrvr\index{ichrvr}(ipp)}), follow-ups in the listings
             (indicator \texttt{ilisvr\index{ilisvr}(ipp)}) and to activate
             chronological records at the probes defined in
             \texttt{usini1} (indicators \texttt{ihisvr(ipp)}).\\
The way of doing it is the same as in \texttt{usini1} and the writing
      frequencies of these ouputs are set by \texttt{usini1}. The values
      of the indicators \texttt{ipp} are
      \texttt{ipp=ipppro\index{ipppro}(ipproc\index{ipproc}(ivar))}, with \texttt{ivar}
      the number of the specific physics variable.
Concerning the main variables (velocity, pressure, etc ...) the user
      must still complete \texttt{usini1} if he wants to get
      chronological records, printings in the listing or chronological
      outputs.
The variables which can be activated by the user for each specific
      physics are listed below. The calculation variables \texttt{ivar} (defined
      at the cell \texttt{iel} by \texttt{rtp(iel,ivar)}) and the properties
      \texttt{iprop} (defined at the cell \texttt{iel} by
      \texttt{propce(iel,ipproc(iprop))}) are listed now:
      \begin{list}{$\rightarrow$}{}
       \item EBU pre-mixed flame modeling:
       \begin{list}{-}{}
        \item Calculation variables \texttt{rtp(iel,ivar)}
              \begin{list}{\texttt{ivar} = }{}
               \item \texttt{isca(iygfm\index{iygfm})} fresh gas mass fraction
               \item \texttt{isca(ifm\index{ifm})} mixing rate
               \item \texttt{isca(ihm\index{ihm})} enthalpy, if transported
              \end{list}
        \item Properties \texttt{propce(iel,ipproc(iprop))}
              \begin{list}{\texttt{iprop} = }{}
               \item \texttt{itemp\index{itemp}} temperature
               \item \texttt{iym(1)\index{iym(1)}} fuel mass fraction
               \item \texttt{iym(2)\index{iym(2)}} oxidiser mass fraction
               \item \texttt{iym(3)\index{iym(3)}} product mass fraction
               \item \texttt{ickabs\index{ickabs}} absorption
                     coefficient, when the radiation modeling is
                     activated
               \item \texttt{it3m\index{it3m}} and \texttt{it4m\index{it4m}}
                     ``$T^3$'' and ``$T^4$'' terms, when the radiation
                     modeling is activated
              \end{list}
       \end{list}
       \item rapid complete chemistry diffusion flame modeling:
             \begin{list}{}{}
              \item  everything is identical to the ``EBU'' case, except from
                     the fresh gas mass fraction which is replaced by the
                     variance of the mixing rate \texttt{ivar=isca(ifp2m\index{ifp2m})}
             \end{list}
       \item pulverised coal modeling with 3 comustables:
             \begin{list}{}{}
              \item {\em variables shared by the two phases}:
                    \begin{list}{-}{}
                     \item Calculation variables \texttt{rtp(iel,ivar)}
                           \begin{list}{\texttt{ivar} = }{}
                            \item \texttt{isca(ihm\index{ihm})}: gas-coal mixture enthalpy
                            \item \texttt{isca(immel\index{immel})}: molar mass of the
                                  gas mixture
                           \end{list}
                    \end{list}
              \item {\em variables specific to the dispersed phase}:
              \begin{list}{-}{}
               \item Calculation variables \texttt{rtp(iel,ivar)}
                     \begin{list}{\texttt{ivar} = }{}
                      \item \texttt{isca(ixck\index{ixck}(icla))}: coke mass
                            fraction related to the class \texttt{icla}
                      \item \texttt{isca(ixch\index{ixch}(icla))}: reactive coal
                            mass fraction related to the class \texttt{icla}
                      \item \texttt{isca(inp\index{inp}(icla))}: number of
                            particles of the class \texttt{icla} per kg of
                            air-coal mixture
                      \item \texttt{isca(ih2\index{ih2}(icla))}: mass enthalpy of
                            the coal of class \texttt{icla}, if we are in
                            permeatic conditions
                     \end{list}
               \item Properties \texttt{propce(iel,ipproc(iprop))}
                     \begin{list}{\texttt{iprop} = }{}
                      \item \texttt{immel\index{immel}}: molar mass of the gas mixture
                      \item \texttt{itemp2\index{itemp2}(icla)}: temperature of
                            the particles of the class \texttt{icla}
                      \item \texttt{irom2\index{irom2}(icla)}: density of
                            the particles of the class \texttt{icla}
                      \item \texttt{idiam2\index{idiam2}(icla)}: diameter of the
                            particles of the class \texttt{icla}
                      \item \texttt{igmdch\index{igmdch}(icla)}: disappearance
                            rate of the reactive coal of the class \texttt{icla}
                      \item \texttt{igmdv1\index{igmdv1}(icla)}: mass transfer
                            caused by the release of light volatiles
                            from the class \texttt{icla}
                      \item \texttt{igmdv2\index{igmdv2}(icla)}: mass transfer
                            caused by the release of heavy volatiles
                            from the class \texttt{icla}
                      \item \texttt{igmhet\index{igmhet}(icla)}: coke
                            disappearance rate during the coke burnout
                            of the class \texttt{icla}
                      \item \texttt{ix2\index{ix2}(icla)}: solid mass fraction
                            of the class \texttt{icla}
                     \end{list}
              \end{list}
              \item {\em variables specific to the continuous phase}:
              \begin{list}{-}{}
               \item Calculation variables \texttt{rtp(iel,ivar)}
                     \begin{list}{\texttt{ivar} = }{}
                      \item \texttt{isca(if1m\index{if1m}(icha))}: mean value of
                            the tracer 1 representing the light
                            volatiles released by the coal \texttt{icha}
                      \item \texttt{isca(if2m\index{if2m}(icha))}: mean value of
                            the tracer 2 representing the heavy
                            volatiles released by the coal \texttt{icha}
                      \item \texttt{isca(if3m)\index{if3m}}: mean value of the
                            tracer 3 representing the carbon released as
                            CO during coke burnout
                      \item \texttt{isca(if4pm\index{if4pm})}: variance of the
                            tracer 4 representing the air
                      \item \texttt{isca(if3p2m\index{if3p2m})}: variance of the
                            tracer 3
                     \end{list}
               \item Properties \texttt{propce(iel,ipproc(iprop))}
                     \begin{list}{\texttt{iprop} = }{}
                      \item \texttt{itemp1\index{itemp1}}: temperature of the gas
                            mixture
                      \item \texttt{iym1(1)\index{iym1(1)}}: mass fraction of
                            $CH_{X1m}$ (light volatiles) in the gas
                            mixture
                      \item \texttt{iym1(2)\index{iym1(2)}}: mass fraction of
                            $CH_{X2m}$ (heavy volatiles) in the gas
                            mixture
                      \item \texttt{iym1(3)\index{iym1(3)}}: mass fraction of
                            CO in the gas mixture
                      \item \texttt{iym1(4)\index{iym1(4)}}: mass fraction of
                            $O_2$ in the gas mixture
                      \item \texttt{iym1(5)\index{iym1(5)}}: mass fraction of
                            $CO_2$ in the gas mixture
                      \item \texttt{iym1(6)\index{iym1(6)}}: mass fraction of
                            $H_2O$ in the gas mixture
                      \item \texttt{iym1(7)\index{iym1(7)}}: mass fraction of
                            $N_2$ in the gas mixture
                     \end{list}
              \end{list}
             \end{list}
      \end{list}

 \item set the relaxation coefficient of the density \texttt{srrom}, with \\
$\rho^{n+1}=\texttt{srrom}*\rho^{n}+(1-\texttt{srrom})\rho^{n+1}$\\
(by default, the adopted value is \texttt{srrom\index{srrom}} = 0.8. At the
      beginning of a calculation, a sub-relaxation of 0.95 may reduce
      the numerical ``schocks'').

 \item set the dynamic viscosity \texttt{diftl0}. By default
      \texttt{diftl0\index{diftl0}}= 4.25 $kgm^{-1}s^{-1}$
(the dynamic diffusivity being the ratio between the thermal
      conductivity $\lambda$ and the mixture specific heat $C_p$ in the
      equation of enthalpy).

 \item set the value of the constant \texttt{cebu\index{cebu}} of the Eddy Break
      Up model (only in \texttt{usebu1}. By default \texttt{cebu}=2.5)

\end{list}



%==================================
\subsection{Management of Boundary Conditions of the electric arc: \texttt{uselcl}}
%==================================


\noindent
\textit {sub routine called at each time step.}

As in the \texttt{usini1} and \texttt{usppmo}, the use of \texttt{usecl}
is required to run an electric calculation. The main use is the same as
occurs in \texttt{usclim} for the standard \CS calculations, for which 
different loops on the boundary faces is defined. Each faces list is
built with the use of selection criteria (cf. \S\ref{fvm_selector}),
and is referenced by their group(s), their color(s) or geometrical
criterions. The face type, the boundary conditions for each variable,
and finally the value of each variable or imposed flow are fixed.

{\em WARNING:for the electric module,  , the boundary conditions of all
 the variables are defined here,
even those of the eventual user scalars: {\em \texttt{usclim}} is not
used at all.}

For the electric module, each boundary face is associated with a number
 \texttt{izone} \footnote{\texttt{izone} must be less than the maximum
 value allowed by the code, \texttt{nozzppm}. This is fixed at 2000 in \texttt
{ppvar.h} and cannot be modified.}(the color \texttt{icoul} for example) in
 order to group together all the boundary faces of the same type. In the report
 \texttt{usclim}, the main change from the users point of view concerns the
 specification of the boundary conditions of the potential, which isn't
 implied by default. The Dirichlet and Neumann conditions must be imposed
 explicitly using \texttt{icodcl} and \texttt{rcodcl} (as would be done for
 the classical scalar).

Whats more, if one wishes to slow down the power dissipation(Joule module
effect) or the current (electric arc module) from the imposed values
\texttt{(puismp\index{puismp}} and \texttt{couimp\index{couimp}} respectively),
 they can be changed by the potential scalar as shown below:

\begin{list}{-}{}
\item For the electric arc, the imposed potential difference can be a fixed variable:
 for example, the cathode can be fixed at 0 and the potential at the anode
 contains the variable \texttt{dpot}. This variable is initialised in \texttt{useli1}
 by an estimated potential difference. If \texttt{ielcor}=1 (see
 \texttt{useli1}), \texttt{dpot} is updated automatically during the
 calculation to obtain the required current.
\item For the Joule module effect, \texttt{dpot} is again used with the same
 signification as in the electric arc module. If \texttt{dpot} is not wanted
 in the setting of the boundary condtions, the variable \texttt{coejou} can be
 used. \texttt{coejou} is the coefficient by which the potential difference is
 multiplied to obtain the desired power dissipation. By default this begins at
 1 and is updated automatically. If \texttt{ielcor}=1 (see \texttt
{useli1}), multiply the imposed potentials in \texttt{uselcl} by \texttt{coejou}
 at each time step to achieive the desired power dissipation.
 \end{list}

 {\em WARNING: In alternative current, attention should be paid to the values of potential
 imposed at the limits: the variable named "real potential" represents an affective
 value if the current is in single phase, and a "real part" if not.}
\begin{list}{-}{}
\item For the Joule studies, a complex potential is someitmes needed
 (\texttt{ippmod(ieljou)}=2): this is the  case in particular where the current
 has 3 phases. To have access to the phase of the potential, and not just its
 amplitude, the 2 variables must be deleted: in \CS, there are 2 arrays
 specified for this role, the real part and the imaginary
 part of the potential. For use in the code, these variables are named
 ``real potential'' and ``imaginary potential''. For an alternative
 sinusoidal potential $Pp$, the maximum value is noted as $Pp_\text{max}$,
 the phase is noted as $\phi$, the real potential
 and the imaginary potential are respecively $Pp_\text{max}\,cos\phi$ and
$Pp_\text{max}\,sin\phi$.
\item For the Joule studies in which one does not have access to the phases, the real
 potential (imaginary part =0) will suffice (\texttt{ippmod(ieljou)=1}): this is obviously the case with
 continous current, but also with single phase alternative current. In \CS
there is only 1 varialbe for the potential,  called "real potential". Pay attention to
 the fact that in alternate current, the "real potential" represents a effective value
 of potential , $\frac{1}{\sqrt{2}}\,Pp_\text{max}$ (in continous current there is no
 such ambiguity).
\end{list}


%==================================
\subsection{Initialisation of the variables in the electric module}
%==================================

\noindent
\textit{subroutine called only at the initialisation of the calculation}

This subroutine allows the user to initialise some of the specific physics variables
 prompted via \texttt{usppmo}
. The user has access, as usual, to many geometric variables so that the zones can
 be differentiated if needed.

{\em WARNING: For the specific physics, it is here that all varialbes are initialsed:
 \texttt{usiniv} is not used}

This subroutine works like \texttt{usiniv}. The values of potential and its
constiuents are initialised if required.

It should be noted that the enthalpy is important.

\begin{list}{-}{}
\item For the electric arc module, the enthalpy value is taken from the temperature
 of reference \texttt{t0(iphas)} (given is \texttt{usini1}) from the temperature-enthalpy tables
 supplied in the data file \texttt{dp\_ELE.} The user must not intervene here.
\item For the Joule effect module, the value of enthalpy must be specified by the user
. An example is given of how to obtain the enthalpy from the temperature of reference
 T0 (IPHAS)(given in \texttt{usini1}), the the temperature-enthalpy low must be
supplied. A code is suggested in the sub routine \texttt{usthht}(which is there for
 the determination of physical properties).
\end{list}
%====================================
\subsection { Initialisation of the variable options in the electric module}
%==================================
\label{prg_useli1}%
\noindent
\textit{subroutine called at each time step}

This subroutine is completed in \texttt{usini1} for the specific physics. It allows:
\begin{list}{$\bullet$}{}
\item Activates the variables in the specific physics module, the chronolgical
outputs (\texttt{ichrvr(ipp)} indicators), the listings (\texttt{ilisvr(ipp)}
indicators) and the
historical exits at the probes defined in \texttt{usini1} (\texttt{ihisvr(ipp)}
indicators).
The functions are the same as in \texttt{usini1} and the script frequency of the
exits are fixed using \texttt{usini1.} The indicators \texttt{ipp} are for the value \texttt{ipp=ipppro} (\texttt{ipproc(ivar)}, with \texttt{ivar}, the number of specific physics varibles. With the main variables
 which concern the user (velocity, pressure, etc), the user must always use \texttt{usini1} if the history,the listings or the chronological files are required.
 The variables which the user can activate are marked out. The number of variables in
the calculation is given in \texttt{ivar} (defined by
\texttt{propce(iel,ipproc(iprop)} for cell \texttt{iel}):

\begin{list}{$\rightarrow$}{}
  \item Electric Arc Module:
  \begin{list}{-}{}
     \item Calculation variables \texttt{rtp(iel,ivar)}
     \begin{list}{\texttt{ivar} = }{}
       \item \texttt{isca(ihm\index{ihm})} enthalpy
       \item \texttt{isca(ipotr\index{ipotr})} real potentiel
       \item \texttt{isca(ipotva(i)\index{ipotva})} solved components of the potential vector.
       \item \texttt{isca(iycoel(iesp)\index{iycoel})} the mass fraction of \texttt{ngazg} composites if there are more than 1
     \end{list}
     \item Properties \texttt{propce(iel,ipproc(iprop))}
     \begin{list}{\texttt{iprop} = }{}
       \item \texttt{itemp\index{itemp}}  temperature
       \item \texttt{iefjou\index{iefjou}} power dissipation by the Joule effect.
       \item \texttt{ilapla(i)\index{ilapla(i)}} components of the laplace forces.
     \end{list}
   \end{list}
   \item Joule Module effect~:
   \begin{list}{-}{}
     \item Calculation variables \texttt{rtp(iel,ivar)}
     \begin{list}{\texttt{ivar} = }{}
       \item \texttt{isca(ihm\index{ihm})} enthalpy
       \item \texttt{isca(ipotr\index{ipotr})} real potential
       \item \texttt{isca(ipoti\index{ipoti})} imaginary potential if its to be taken into account
       \item \texttt{isca(iycoel(iesp)\index{iycoel}}) the mass fraction of \texttt{ngazg} composites if there are more than 1
     \end{list}
     \item Properties \texttt{propce(iel,ipproc(iprop))}
     \begin{list}{\texttt{iprop} = }{}
       \item \texttt{itemp\index{itemp}} temperature
       \item \texttt{iefjou\index{iefjou}} volumic power dissipation by Joule effect.
     \end{list}
   \end{list}
\end{list}

       \item to give the coefficient of relaxation of the density \texttt{srrom}:\\
$\rho^{n+1}=\texttt{srrom}*\rho^{n}+(1-\texttt{srrom})\rho^{n}$\\
(for the electric arc, the sub-relaxation is taken into account during the 2nd time step; for the Joule effect the sub relaxation is not accounted for unless the user specifies in \texttt{uselph}

       \item indicates if the data will be fixed in the power dissipation or in the current, done in \texttt{ielcor}.
       \item target current fixed as \texttt{couimp} (electric arc module) or the power dissipation \texttt{puism} (Joule module effect).
       \item Fix the initial value of potential difference \texttt{dpot},
 the for the calculations with a single fixed parameter as \texttt{couimp} or \texttt{puism}.

\end{list}

%==================================
\subsection{Management of variable physical properties in the electric module}
%==================================

\noindent
\textit{Subroutine called at each time step}

All the laws of the variation of physical data of the fluid are written (where neccessary)
in this subroutine... The subroutine replaces \texttt{usphyyv} and a similar component.

{\em WARNING: For the electric module, it is here that all the physical variables are defined
 (including the relative cells and the eventuel user scalars):\texttt{usepelph} is not used.}

The user should ensure that the defined variation laws are valid for the whole range of
variables. Particular attention should be taken with the non-linear laws (for example, a
 3rd degree polynomial law giving negative values of density)

{\em WARNING: with the electric module, all the physical propertie are assumed as variables
 and so are stored in the \texttt{propce} array. \texttt{cp0}, \texttt{viscls0}, \texttt{viscl0} are not used}

For the Joule effect, the user is required to supply the physical properties in the sub-
routine. Examples are given which are to be adapted by the user. If the temperature is
to be determined to calculate the physical properties, the solved variable, enthalpy must
 be deduced. The preffered temperature-enthalpy law can be selected in the subruotine
 \texttt{usthht} (an example of the interpolation is given from the law table. This
subroutine can be re-used for the initialisation of the variables(\texttt{useliv}))
 For the elecrtic arc module, the physical properties are intepolated from the data file
 \texttt{dp\_ELE} supplied by the user. Modification is not generally necessary.



%==================================
\subsection[Management of the {\em EnSight} output in the electric module: \texttt{uselen}]
{Management of the post-processing output in the electric module: \textmd{\texttt{uselen}}}
%==================================

\noindent
\textit{Subroutine called at each chronological output}

This subroutine allows the addition on $n$ variables in the preprocessing output and
 works like the subroutine \texttt{usvpst} (with the electric module, it is however also
 possible to use \texttt{usvpst}.

The algebraic variables related to the electric module are provided by default provided
 that they are not explicitely contained in the \texttt{propce} array:
\begin{list}{-}{}
\item gradient of real potential in $V m^{-1}$ ($\grad Pot_R = -\vect{E}$)
\item density of real current in $A m^{-2}$  ($\vect{j}=\sigma \vect{E}$)
\end{list}
specifically for the Joule module effect with \texttt{ippmod(ieljou)}=2~:
\begin{list}{-}{}
\item gradient of imaginary potential in $V m^{-1}$
\item density of real current in $A m^{-2}$
\end{list}
specifically for the electric arc module with \texttt{ippmod(ielarc)}=2~:
\begin{list}{-}{}
\item magnetic field in $T$ (\vect{B} = \vect{rot}\,\vect{A})
\end{list}

If it is convenient for the user, there is no need to add this subroutine into the
 SRC directory: the post-processing will be done automatically (at the same frequency
 (\texttt{NTCHR}) as the other calculation variables)


%==================================
\subsection{Compressible module}
%==================================

When the compressible module\footnote{For more details concerning the
compressible version, the user may refer to the document ``Implantation
d'un algorithme compressible dans \CS'', Rapport EDF 2003,
HI-83/03/016/A, P. Mathon, F. Archambeau et J.-M. H\'erard.} is
activated, it is recommended to:
\begin{list}{-}{}
 \item use the option ``time step variable in time and uniform in
       space'' (\texttt{idtvar}=1) with a maximum Courant number of 0.4
       (\texttt{coumax}=0.4): these choices must be written in \texttt{usini1}
 \item keep the convective numerical schemes proposed by default.
\end{list}

%==================================
\subsubsection{ Initialisation of the options of the variables related
   to the compressible module: \textmd{\texttt{uscfx1}} and \textmd{\texttt{uscfx2}}}
%==================================
\label{prg_uscfx12}%
\noindent
\textit{Subroutine called every time step.}

These subroutines complete \texttt{usini1}.

\texttt{uscfx1} allows to set non standard calculation options related to the
compressible module, and in particular to fill in the key word \texttt{icfgrp}
allowing to take into account the hydrostatic equilibrium in the
boundary conditions.

\texttt{uscfx2} allows to specify for the molecular thermal conductivity and
the volumetric viscosity the following pieces of information:
\begin{list}{-}{}
  \item variable or not (\texttt{iviscv})
  \item reference value (\texttt{viscv0})
\end{list}

%==================================
\subsubsection{Management of the boundary conditions related to the
   compressible module: \textmd{\texttt{uscfcl}}}
%==================================


\noindent
\textit{Subroutine called every time step.}

The use of \texttt{uscfcl}
is obligatory to run a calculation using the compressible module just
as it is in both \texttt{usini1} and \texttt{usppmo} . The
way of using it is the same as the way of using
\texttt{usclim} in the framework of standard calculations, that is to
say several loops on the boundary faces lists (cf. \S\ref{fvm_selector})
marked out by their colors, groups, or  geometrical criterion, where
the type of face, the type of boundary condition for each variable and
eventually the value of each variable are defined.

{\em WARNING: in the case of a calculation using the compressible
module, the boundary conditions of all the variables are defined here,
even those of the eventual user scalars: {\em \texttt{usclim}} is not
used at all.}

In the compressible module, the different available boundary conditions
are the followings:

\begin{list}{-}{}
  \item inlet/outlet for which everything is known
  \item supersonic outlet
  \item subsonic inlet
  \item subsonic wall
  \item wall
  \item symmetry
\end{list}


%==================================
\subsubsection{Ininitialisation of the variables related to the
  compressible module: \textmd{\texttt{uscfxi}}}
%==================================

\noindent
\textit{Subroutine called only during calculation initialisation.}

This subroutine is used to initialise some variables specific to the
specific physics activated {\em via} \texttt{usppmo}.  As usual,
the user may have access to several geometric variables to discriminate
between different initialisation zones if needed.

{\em WARNING: in the case of a specific physics modeling, all the
variables are initialised here: {\em \texttt{usiniv}} is not used at
all.}

This subroutine works like \texttt{usiniv} for velocity,
turbulence and passive scalars. Concerning pressure, density,
temperature and specific total energy, only 2 variables out of the 4 are
independant. The user may also initialise the variable pair he wants
(apart from temperature-energy) and the two other variables will be
calculated automatically by giving the right value to the variable
\texttt{iccfth} used for the call to \texttt{uscfth}.

%==================================
\subsubsection{Compressible module thermodynamics: \textmd{\texttt{uscfth}}}
%==================================

\noindent
\textit{This subroutine is called several times every time step (boundary conditions, physical properties, solving of the energy equation, ...).}

This subroutine is used to set the thermodynamics parameters. By
default, the perfect gas laws are implemented. If the user needs to use
other laws (perfect gas with variable Gamma, Van der Waals), he must
modify this subroutine.

%==================================
\subsubsection{Management of the variable physical properties in the
   compressible module: \textmd{\texttt{uscfpv}}}
%==================================

\noindent
\textit{Subroutine called every time step.}

If necessary, all the variation laws of the fluid physical properties
(viscosity, specific heat, ...) are described here. This subroutine
replaces and is similar to \texttt{usphyv}.

The user should make sure that the defined variation laws are valid for
the whole variation range of the variables.

%==================================
\subsection{Lagrangian modeling of multiphasic flows with dipersed inclusions}
%==================================


%==================================
\subsubsection{Initialisation of the main key words in the Lagrangian
   modeling: \textmd{\texttt{uslag1}}}
%==================================

\noindent
\textit{Subroutine called only during calculation initialisation.}

\noindent
This is one of the two subroutines which must be completed in
the case of a calculation modeling a Lagrangian multiphasic flow. This
subroutine gathers in different headings all the key word which are
necessary to configure the Lagrangian module. The different headings
refer to:
\begin{list}{$\bullet$}{}
\item the global configuration parameters
\item the specific physical models describing the particle behaviour
\item the backward coupling (influence of the dispersed phase on the
      continuous phase)
\item the numerical parameters
\item the volumetric statistics
\item the boundary statistics
\item the postprocessing in trajectory mode
\end{list}
%
\noindent
For more details about the different parameters, the user may refer to the
key word list (\S\ref{prg_motscles_lagr}).

\noindent
The results of the lagangian module consist in some information about
the particle cloud. These pieces of information are displayed in the
form of statistics. It is therefore necessary to activate the
calculation of the statistics at a given instant during the
simulation. To do so, there are different strategies which are strongly
related to the flow nature, stationary or not. \\
Except from the cases where the injection conditions depend on the time,
it is generally recommended to realise a first Lagrangian calculation
whose aim is to get a nearly constant particle number in the calculation
domain. In a second step, a calculation restart is done to calculate the
statistics. \\
When the single-phase flow is steady and the inclusion presence rate
is low enough to neglect their influence on the continuous phase
behaviour, it is better to realise a Lagrangian calculation on a fixed
field. It is then possible to calculate stationary volumetric statistics and
to give a statistical weight higher than 1 to the particles, in order to
reduce the number to treat while keeping the right concentrations. \\
Otherwise, when the continuous phase flow is stationary, but the backward
coupling must be taken into consideration, it is still possible to
activate stationary statistics. \\
When the continuous phase flow is non-stationary, it is no longer possible
to use stationary statistics. To have correct statistics at every moment
in the whole calculation domain, it is imperative to have an established
particle seeding and it is recommended (when it is possible) not to
impose statistical weights different from the unity. \\
Finally, when the complete model is used for the turbulent dispersion
modeling, the user must make sure that the volumetric statistics are
directly used for the calculation of the locally undisturbed fluid flow
field. \\

\noindent
When the thermal evolution of the particles is activated, the associated
particulate scalars are always the inclusion temperature and the locally
undisturbed fluid flow
temperature expressed in degrees Celsius, whatever the thermal scalar
associated with the continuous phase is (temperature or enthalpy). If the
thermal scalar associated with the continuous phase is the temperature
in Kelvin, the unit change is done automatically. If the
thermal scalar associated with the continuous phase is the enthalpy, the
enthalpy-temperature conversion subroutine \texttt{usthht} must be
completed for \texttt{mode}=1, and must express temperatures in degrees
Celsius. \\
In all cases, the thermal backward coupling of the dispersed phase on
the continuous phase is adapted to the thermal scalar transported by the
fluid.

\noindent
\emph{WARNING: Up to now, parallelism and periodicity are not compatible with
the Lagrangian module. This compatibility will be soon implemented. It
is however possible, in the framework of a Lagrangian calculation on a
fixed field, to realise in a first step the calculation of the
continuous phase using parallelism, and to conduct in a second step the
Lagrangian calculation by doing a restart on only one processor.}

%==================================
\subsubsection{Management of the boundary conditions related to the
  particles: \textmd{\texttt{uslag2}} and \textmd{\texttt{uslain}}}
%==================================

\noindent
In the framework of the multiphasic lagrangrian modeling, the management
of the boundary conditions concerns the particle behaviour when there
is an interaction between its trajectory and a boundary face. These
boundary conditions may be imposed independently of those concerning the
eulerian fluid phase (they are of course generally coherent). The
boundary condition zones are actually redefined by the Lagrangian
module (cf. \S\ref{fvm_selector}), and a type of particle behaviour
is associated with each one. \\
The management of the Lagrangian boundary conditions is done by means of
several user subroutines: \texttt{uslag2} for the classic conditions and
\texttt{uslain} to specify profiles if necessary. Otherwise, the
subroutine \texttt{uslabo} allows to define the type of particle/wall
interaction. It will be described in a specific paragraph.

\minititre{Subroutine \texttt{uslag2}}

\noindent
\textit{Subroutine called every time step.}

\noindent
It is the second indispensable subroutine for every calculation using the
Lagrangian module. The main numerical variables and ``pointers'' are
described below.

\variab{ifrlag}{ifrlag(nfabor)}{ia}{In the Lagrangian module, the user
defines \texttt{nfrlag\index{nfrlag}} boundary zones from the color of the
boundary faces, or more generally from their properties (colors, groups
...), from the boundary conditions defined in \texttt{usclim}, or even
from their coordinates. To do so, the array \texttt{ifrlag(nfabor)} giving for
each face \texttt{ifac} the number \texttt{ifrlag(ifac)} corresponding to the zone to
which it belongs, is completed. The zone numbers ({\em i.e.} the values
of \texttt{ifrlag(ifac)}) are chosen freely by the user, but must be strictly
positive integers inferior or equal to \texttt{nflagm\index{nflagm}} (parameter
stored in lagpar.h, whose default value is 100). A zone type is
associated with every zone; it will be used to impose global boundary
conditions. \emph{WARNING: it is essential that every boundary face
belongs to a zone.}}

\variab{iusncl}{iusncl(nflagm)}{ia}{For all the \texttt{nfrlag} boundary zones
previously identified, the number of classes \texttt{nbclas}\footnote{a class is a set
of particles sharing the same physical properties and the same
characteristics concerning the injection in the calculation domain} of
entering particles is given: \texttt{iusncl(izone)} = \texttt{nbclas}.
By default, the number of particle classes is zero. The maximum number of
classes is \texttt{nclagm\index{nclagm}} (parameter stored in lagpar.h,
whose default value is 20).}

\variablist{iusclb}{iusclb(nflagm)}{ia}{For all the \texttt{nfrlag} boundary zones
previously identified, a particle boundary condition type is
given. There are two categories of particle boundary condition types:
those predefined in the subroutine \texttt{uslabo} (marked out by the
key words \texttt{ientrl\index{ientrl}}, \texttt{isortl\index{isortl}},
\texttt{irebol\index{irebol}}, \texttt{idepo1\index{idepo1}},
\texttt{idepo2\index{idepo2}}, \texttt{idepo3\index{idepo3}},
\texttt{iencrl\index{iencrl}}) and the user boundary condition types (marked out
by the key words \texttt{jbord1} to \texttt{jbord5)\index{jbord1}}, whose corresponding
particle behaviour must be defined in the subroutine \texttt{uslabo}.

\begin{list}{$\bullet$}{}

 \item if \texttt{iusclb(izone)} = \texttt{ientrl, izone} is a particle injection zone.
       For each particle class associated with this zone, some pieces of
       information must be given (see below). If a particle trajectory
       crosses an injection zone, then we consider that this particle
       leaves the calculation domain.

 \item if \texttt{iusclb(izone)} = \texttt{isortl}, the particles interacting with
       the zone \texttt{izone} leave the calculation domain.

 \item if \texttt{iusclb(izone)} = \texttt{irebol}, the particles undergo an elastic
       rebound on the boundary zone \texttt{izone}.

 \item if \texttt{iusclb(izone)} = \texttt{idepo1}, the particles settle definitevely on
       the boundary zone \texttt{izone}. These particles can not be put in suspension
       again, and we consider that they leave the calculation domain.

 \item if \texttt{iusclb(izone)} = \texttt{idepo2}, the particles settle definitevely on
       the boundary zone \texttt{izone}, but they are kept in the calculation
       domain. This distinction with the type \texttt{idepo1} is useful only when
       post-processings in movement mode (\texttt{ifensi2} = 1) are realised: the
       particles do not disappear after touching the boundary
       zone. However, using \texttt{idepo2} type zones necessitates more memory
       than using \texttt{idepo1} type zones.

 \item if \texttt{iusclb(izone)} = \texttt{idepo3}, the particles settle on the boudary
       zone \texttt{izone}, but can be put in suspension again depending on the
       local description of the continuous phase flow.

 \item if \texttt{iusclb(izone)} = \texttt{iencrl}, the particles which are coal particles
       (if \texttt{iphyla} = 2) can become fouled up on the zone \texttt{izone}. The
       slagging is a \texttt{idepo1} type deposit of the coal particle if a certain
       criterion is respected. Otherwise, the coal particle rebounds
       (\texttt{irebol} type behaviour). This boundary condition type is available
       if \texttt{iencra} = 1. A limit temperature \texttt{tprenc\index{tprenc}}, a
       critical viscosity \texttt{visref\index{visref}} and the coal composition
       in mineral matters must be given in the subroutine
       \texttt{uslag1}. The slagging criterion given by default may be
       modified in the subroutine \texttt{uslabo}.

 \item if \texttt{iusclb(izone)} = \texttt{jbord1} to \texttt{jbord5}, then the particle
       interaction with the boundary zone \texttt{izone} is given by the user. The
       particle behaviour associated with each type \texttt{jbord}* must be defined in
       the subroutine \texttt{uslabo}.

\end{list}
}


\variablist{iuslag}{iuslag(nclagm, nflagm, ndlaim)}{ia}{Some pieces of
information must be given for each particle class associated with an
injection zone. The first part consists in integers contained in the
array \texttt{iuslag}. There are at the most \texttt{ndlaim\index{ndlaim}} integers. These
pieces of information must be provided for each class \texttt{iclas} and each
particle injection zone \texttt{izone}. They are marked out by means of ``pointers'':
\begin{list}{$\rightarrow$}{}

\item \texttt{iuslag(iclas,izone,ijnbp)}: number of particles to inject in the
      calculation domain per class and per zone.

\item \texttt{iuslag(iclas,izone,ijfre)}: injection period (expressed in number
      of time steps). If the period is null, then there is injection only
      at the first absolute Lagrangian time step (including the restart
      calculations).

\item \texttt{iuslag(iclas,izone,ijuvw)}: type of velocity condition:

\begin{list}{-}{}

\item if \texttt{iuslag(iclas,izone,ijuvw)} = 1, the particle velocity vector is
      imposed, and its components must be given in the array \texttt{ruslag} (see
      below).

\item if \texttt{iuslag(iclas,izone,ijuvw)} = 0, the particle velocity is imposed
      perpendicular to the injection boundary face and with the norm
      \texttt{ruslag(iclas,izone,iuno)}.

\item if \texttt{iuslag(iclas,izone,ijuvw)} = -1, the particle injection velocity
      is equal to the fluid velocity at the center of the cell
      neighboring the injection boundary face.

\end{list}

\item \texttt{iuslag(iclas,izone,inuchl)}: when the particles are coal particles
      (\texttt{iphyla} = 2), this part of the array contains the coal index-number,
      between 1 and \texttt{ncharb} (defined by the user in the thermo-chemical
      file dp\_FCP, with  \texttt{ncharb$\leqslant$ncharm =
      3).\index{ncharb}\index{ncharm}}

\end{list}
}

\variablist{ruslag}{ruslag(nclagm, nflagm, ndlagm)}{ra}{Some pieces of
information must be given for each particle class associated with an
injection zone. The second and last part consists in real numbers
contained in the array \texttt{ruslag}. There are at the most
\texttt{ndlagm\index{ndlagm}} such real numbers. These pieces of information must
be provided for each class \texttt{iclas} and each particle injection zone
\texttt{izone}. They are marked out by means of ``pointers'':
\begin{list}{$\rightarrow$}{}

\item \texttt{ruslag(iclas,izone,iuno)}: norm of the injection velocity,
\\useful if \texttt{iuslag(iclas,izone,ijuvw)}~=~0.

\item \texttt{ruslag(iclas,izone,iupt)}, \texttt{ruslag(iclas,izone,ivpt)},\\
\texttt{ruslag(iclas,izone,iwpt)}: components of the particle injection vector,
\\useful if \texttt{iuslag(iclas,izone,ijuvw)}~=~1.

\item \texttt{ruslag(iclas,izone,idebt)}: allows to impose a particle mass
      flow. According to the number of injected particles, the particle
      statistical weight \texttt{tepa(npt,jrpoi)} is recalculated in order to
      respect the required mass flow (the number of injected particles
      does not change). When the mass flow is null, it is not taken into
      account.

\item \texttt{ruslag(iclas,izone,ipoit)}: particle statistical weight per class and
      per zone.

\item \texttt{ruslag(iclas,izone,idpt)}: particle diameter. When the particles
      are coal particles (\texttt{iphyla} = 2), this diameter is provided by the
      thermo-chemical file dp\_FCP {\it via} the array \texttt{diam20(iclg)},
      where \texttt{iclg} is the ``pointer'' on the total class number ({\em
      i.e.} for all the coal types). When the standard deviation of the
      particle diameter is different from zero, this diameter becomes a
      mean diameter.

\item \texttt{ruslag(iclas,izone,ivdpt)}: standard deviation of the injection
      diameter. To impose this standard deviation allows to respect
      granulometric distribution: the diameter of each particle is
      calculated from the mean diameter, the standard deviation and a
      gaussian random number. In this case, it is strongly recommended
      to intervene in the subroutine \texttt{uslain} to
      restrict the diameter variation range, in order to avoid
      aberrant values. If this standard deviation is null, then the
      particle diameter is constant per class and per zone.

\item \texttt{ruslag(iclas,izone,iropt)}: particle density. When the particles
      are coal particles (\texttt{iphyla} = 2), this density is set in the
      thermo-chemical file dp\_FCP {\em via} the array \texttt{rho0ch(icha)},
      where \texttt{icha} is the coal number.

\item \texttt{ruslag(iclas,izone,itpt)}: particle injection temperature in
      \degresC. Useful if \texttt{iphyla} = 1 and if \texttt{itpvar} = 1.

\item \texttt{ruslag(iclas,izone,icpt)}: particle injection specific heat. Useful
      if \texttt{iphyla} = 1 and if \texttt{itpvar} = 1. When the particles are coal
      particles (\texttt{iphyla} = 2), the specific heat is set in the
      thermo-chemical file dp\_FCP {\em via} the array \texttt{cp2ch(icha)}.

\item \texttt{ruslag(iclas,izone,iepsi)}: particle emissivity. Useful if
      \texttt{iphyla} = 1 and if \texttt{itpvar} = 1, and if the radiation
      module is activated for the continuous phase (note: when \texttt{iphyla} = 2,
      the coal particle emissivity is given the value 1).

\item \texttt{ruslag(iclas,izone,ihpt)}: particle injection temperature in
      \degresC\ when these particles are coal
      particles. The array \texttt{ruslag(iclas,izone,itpt)} is then no longer
      active. Useful if \texttt{iphyla} = 2.

\item \texttt{ruslag(iclas,izone,imcht)}: mass of reactive coal. Useful if \texttt{iphyla} = 2.

\item \texttt{ruslag(iclas,izone,imckt)}:  mass of coke. This mass is null
      if the coal did not begin to burn before its injection. Useful if
      \texttt{iphyla} = 2.

\end{list}
}

\variab{iusvis}{iusvis(nflagm)}{ia}{In order to display the variables at
the boundaries defined in the subroutine \texttt{uslag1}, this array
allows to select the boundary zones on which a display is wanted. To do
so, a number is associated with each zone \texttt{izone}. If this number is
strictly positive, the corresponding zone is selected; if it is null,
the corresponding zone is eliminated. If several zones are associated
with the same number, they will be displayed together in the same
selection with \textit{EnSight}. Each selection will be split in
\textit{EnSight} parts according to the geometric types of the present
boundary faces ((\textit{i.e.} 'tria3', 'quad4' and 'nsided').}

\minititre{Subroutine \texttt{uslain}}

\noindent
\textit{Subroutine called every time step.}

\noindent
It is not obligatory to intervene in this subroutine.

\noindent
\texttt{uslain} is used to complete \texttt{uslag2} when the particles
must be injected in the domain according to fine constraints (profile,
position, ...): the arrays \texttt{ettp}, \texttt{tepa} and \texttt{itepa}
can be modified here for the new particles (these arrays were previously
completed automatically by the code from the data provided by the user
in \texttt{uslag2}).

\noindent
In the case of a more advanced utilisation, it is possible to modify
here all the arrays \texttt{ettp}, \texttt{tepa} and \texttt{itepa}.
The particles already present in the calculation domain are marked out
by an index varying between 1 and \texttt{nbpart}. The particles entering
the calculation domain at the current iteration are marked out by an index
varying between \texttt{nbpart}+1 and \texttt{nbpnew}.


%==================================
\subsubsection{Treatment of the particle/boundary interaction:
\textmd{\texttt{uslabo}}}
%==================================

\noindent
\textit{Subroutine called at every particle/boundary interaction.}

\noindent
It is not obligatory to intervene in this subroutine, but it is required
in four different cases.

\noindent
Firstly, an intervention is required when \texttt{jbord}* type boundary
conditions are used: it is then necessary to code in this subroutine the
corresponding particle/boundary interactions.

\noindent
Secondly, it is possible to select the particle/boundary interaction types
(\texttt{irebol}, \texttt{idepo1}, ...) for which the user wants to save the wall
statistics activated in the subroutine \texttt{uslag1}.

\noindent
Thirdly, if user boundary statistics are activated {\em via}
the key word \texttt{nusbor\index{nusbor}} in the subroutine \texttt{uslag1}, it
is then necessary to program them in the subroutine
\texttt{uslabo}. When the boundary statistics are stationary, these new
boundary statistics are added using the array \texttt{parbor}. When they are
non-stationary (number of Lagrangian iterations lower than \texttt{nstbor}, or
\texttt{isttio} = 0), the array \texttt{parbor} is reset at every iteration.

\noindent
Fourthly, when the user wants to modify the formulation of the wall
slagging by the coal particles, it is then necessary to program the new laws
in the subroutine \texttt{uslabo}.

\noindent
\minititre{Construction rules of a new particle/boundary interaction}
\begin{enumerate}
\item The real numbers \texttt{kx}, \texttt{ky}, \texttt{kz} provide the
      coordinates of the intersection
      point between the current particle trajectory and the interacting
      boundary face.

\item If the user wants to modify the particle position, it can be done
      directly {\em via} the arrays \texttt{ettp} and \texttt{ettpa}:

\begin{list}{-}{}
\item new departure point of the current trajectory segment: \\
\texttt{ettpa(npt,jxp)}, \texttt{ettpa(npt,jyp)}, \texttt{ettpa(npt,jzp)}
\item new arrival point of the current trajectory segment: \\
\texttt{ettp(npt,jxp)}, \texttt{ettp(npt,jyp)}, \texttt{ettp(npt,jzp)}
\end{list}

\item The particle and the fluid velocities may be modified according to
      the desired interaction {\em via} the arrays \texttt{vitpar\index{vitpar}}
      and \texttt{vitflu\index{vitflu}}, they \textbf{must not} be modified {\em
      via} \texttt{ettp} and \texttt{ettpa} in this subroutine.

\item For a given interaction, it is necessary to specify the key word
      \texttt{isuivi\index{isuivi}}:

\begin{list}{-}{}
\item \texttt{isuivi} = 0 if the particle does not need to be followed in
      the mesh after the interaction between its trajectory and the
      boundary face (by default, it is the case for \texttt{ientrl}, \texttt{isortl},
      \texttt{idepo1}, \texttt{idepo2});
\item \texttt{isuivi} = 1 to continue to follow the particle in the mesh
      after its interaction (by default, it is the case for \texttt{irebol} and
      \texttt{idepo3}). The value of \texttt{isuivi} may be a function of the
      particle and
      boundary state (for instance, \texttt{isuivi} = 0 or 1 depending on the
      physical properties for the interaction type \texttt{iencrl}).
\end{list}

\item The array zone \texttt{itepa(npt,jisor)}, containing the index-number of the
      cell where the particle is, must be updated. Generally:

\begin{list}{-}{}
\item \texttt{itepa(npt,jisor)} = \texttt{ifabor(kface)} when the particle stays in the
      calculation domain (\texttt{kface} is the number of the interacting
      boundary face).
\item \texttt{itepa(npt,jisor)} = 0 to eliminate definitively the particle from
      the calculation domain.
\end{list}

\end{enumerate}

\minititre{Note: order of the numerical scheme after a particle/boundary
interaction}

When a particle interacts with a boundary face, the integration order of
the associated stochastic equations is always a first-order, even if a
second-order scheme is used elsewhere.

%==================================
\subsubsection{Option for particle cloning/merging: \textmd{\texttt{uslaru}}}
%==================================

\noindent
\textit{Subroutine called every Lagrangian iteration.}

\noindent
An intervention in this subroutine is required if the particle
cloning/merging option is activated {\em via} the key word \texttt{iroule}. The
importance function \texttt{croule} must then be completed. \\
The aim of this technique is to reduce the number of particles to treat in
the whole flow and to refine the description of the particle cloud only
where the user wants to get volumetric statistics more accurate than in the
rest of the calculation domain. \\
The values given to the importance function are strictly positive real
numbers allowing to classify the zones according to their
importance. The higher the value given to the importance function, the
more important the zone.

\noindent
For instance, when a particle moves from a zone of importance 1 to a
zone of importance 2, it undergoes a cloning: the particle is replaced by two
identical particles, whose statistical weight is the half of the initial
particle. When a particle moves from a zone of importance 2 to a zone of
importance 1, it undergoes a fusion: the particle survives to its passing
through with a probability of 1/2. A random dawing is used to
determine if the particle will survive or disappear.\\
In the same way, when a particle moves from a zone of importance 3 to a
zone of importance 7, it undergoes a cloning. The particle is cloned in
Int(7/3)=2 or Int(7/3)+1=3 particles with a probability of respectively
1-(7/3-Int(7/3))=2/3 and 7/3-Int(7/3)=1/3. If the particle moves from a
zone of importance 7 to a zone of importance 3, it undergoes a fusion:
it survives with a probability of 3/7.

\noindent
\emph{WARNING: The importance function must be a strictly positive real
number in every cell}

%==================================
\subsubsection{Manipulation of particulate variables at the end of an
   iteration and user volumetric statistics: \textmd{\texttt{uslast}} and
   \textmd{\texttt{uslaen}}}
%==================================

\noindent
\texttt{uslast}\textit{: subroutine called at the end of every
Lagrangian iteration}

\noindent
\texttt{uslaen}\textit{: subroutine called at every chronological output
and every listing printing}

\noindent
The subroutine \texttt{uslast} is called at the end of every Lagrangian
iteration, it allows therefore the modification of variables related to
the particles, or the extraction and preparation of data to display in
the listing or the post-processing.

\noindent
An intervention in both subroutines \texttt{uslast} and \texttt{uslaen}
is required if supplementary user volumetric statistics are wanted.

\minititre{User volumetric statistics:}

\noindent
The volumetric statistics are calculated by means of the array \texttt{statis}. Two
situations may happen:
\begin{list}{-}{}
\item the calculation of the statistics is not stationary: \texttt{statis} is
      reset at every Lagrangian iteration;
\item the calculation of the statistics is stationary: the array
      \texttt{statis} is used to store cumulated values of variables, which will
      be averaged at the end of the calculation in the subroutine
      \texttt{uslaen}.
\end{list}
According to the user parameter settings, it may happen that during the
same calculation, the statistics will be non-stationary in a first part and
stationary in second part.

\begin{list}{$\bullet$}{}
\item\minititre{User volumetric statistics: subroutine \texttt{uslast}}
\noindent

\noindent
In this subroutine, the variable whose volumetric statistic is wanted is
stored in the array \texttt{statis}. In the framework of stationary statistics,
the average itself is calculated in the subroutine \texttt{uslaen}. This
average is obtained through the division of the cumulated value by: \\
\hspace*{1cm}- either the duration of the stationary statistics
     calculation stored in the variable \texttt{tstat\index{tstat}}, \\
\hspace*{1cm}- or the number of particles in statistical weight. \\
This method of averaging is applied to every piece in the listing and
     to the post-processing outputs.

\item\minititre{User volumetric statistics: subroutine \texttt{uslaen}}

\noindent
In this subroutine is calculated the average corresponding to the
cumulated value obtained in the subroutine \texttt{uslast}. This subroutine is
also used for the standard volumetric statistics. Several examples are
therefore described.
\end{list}

%==================================
\subsubsection{User stochastic differential equations:
   \textmd{\texttt{uslaed}}}
%==================================

\noindent
\textit{Subroutine called every Lagrangian sub-step.}

\noindent
An intervention in this subroutine is required if supplementary user
variables are added to the particle state vector (arrays \texttt{ettp}
and \texttt{ettpa}).

\noindent
The integration of the stochastic differential equations associated with
supplementary particulate variables is done in this subroutine. \\
When the integration scheme of the stochastic differential equations is
a first-order (\texttt{nordre} = 1), this subroutine is called once every
Lagrangian iteration, if it is a second-order (\texttt{nordre} = 2), it is called
twice. \\

\noindent
The solved stochastic differential equations must be written in the
form:
\begin{displaymath}
\frac{d \Phi_p}{dt} \,=\, - \frac{\Phi_p - \Pi}{\tau_\phi}
\end{displaymath}
where $\Phi_p$ is the I\textit{th} supplementary user variable (\texttt{nvls} in
total) available in \texttt{ettp(nbpmax, jvls(i))} and in
 \texttt{ettpa(nbpmax,jvls(i))},
$\tau_\phi$ is a quantity homogen to a characteristic time, and $\Pi$ is
a coefficient which may be expressed as a function of the other
particulate variables contained in \texttt{ettp} and \texttt{ettpa}. \\
In order to do the integration of this equation, the following
parameters must be provided:
\begin{list}{-}{}
\item $\tau_\phi$, equation characteristic time, in the array \texttt{auxl1} for
      every particle,
\item $\Pi$ , equation coefficient, in the array \texttt{auxl2}. If the
      integration scheme is a first-order, then $\Pi$ is expressed as a
      function of the particulate variables at the previous iteration,
      stored in the array \texttt{ettpa}. If the chosen scheme is a second-order,
      then $\Pi$ is expressed at the first call of the subroutine
      (prediction step \texttt{nor} = 1) as a function of the variables at the
      previous iteration (stored in \texttt{ettpa}), then at the second call
      (correction step \texttt{nor} = 2) as a function of the predicted variables
      stored in the array \texttt{ettp}.
\end{list}

\noindent
If necessary, the thermal characteristic time $\tau_c$, whose
calculation can be modified by the user in the subroutine
\texttt{uslatc}, is stored for each particle in the part
\texttt{tempct(nbpmax,1)} of the array \texttt{tempct}.


%==================================
\subsubsection{Particle relaxation time: \textmd{\texttt{uslatp}}}
%==================================

\noindent
\textit{Subroutine called every Lagrangian sub-step.}

\noindent
An intervention in this subroutine is not obligatory.

\noindent
In this subroutine, the particle relaxation time may be modified
according to the chosen formulation of the drag coefficient. \\
The particle relaxation time, modified or not by the user, is available
in the array \texttt{taup}.

%==================================
\subsubsection{Particle thermal characteristic time: \textmd{\texttt{uslatc}}}
%==================================

\noindent
\textit{Subroutine called every Lagrangian sub-step.}

\noindent
An intervention in this subroutine is not obligatory.

\noindent
In this subroutine, the particle thermal characteristic time may be
modified according to the chosen correlation for the calculation of the
Nusselt number. \\
The thermal characteristic time, modified or not by the user, is
available in the zone \texttt{tempct(nbpmax,1)} of the array \texttt{tempct}.
