%                      Code_Saturne version 1.3
%                      ------------------------
%
%     This file is part of the Code_Saturne Kernel, element of the
%     Code_Saturne CFD tool.
% 
%     Copyright (C) 1998-2007 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 two main elements :
\begin{itemize}
\item the Kernel module is the numerical solver
\item the Preprocessor module is in charge of mesh
data reading (many file formats allowed), mesh pasting (arbitrary interfaces), 
domain decomposition for parallel computing and definition of periodicity
boundary conditions (translation and/or rotation)\\
\end{itemize}

\indent\CS\ also relies on two compulsory libraries (under LGPL licence) : 
\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 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{gest02},
which is newer and more detailled
(the latest updated version of this document
is available on-line with the version of \CS\ and accessible through the command
\texttt{info\_cs noyau}).

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_environnementCS}
At the install procedure of \CS, a directory is dedicated to the code and
its components. It is stored in the environment variable \texttt{PATHCS}.
It is usually the root of a specific account \texttt{/home/saturne} (as it
is the case on the servers of the MFEE department or on the Chatou cluster) or a
subdirectory \texttt{/home/saturne/Saturne} (as it is the case on the CCRT
machines). For installs outside EDF R\&D, please refer to the administrator who
installed the code for the \texttt{PATHCS} location.

The current version of \CS\ (\verscs) is located in the directory
\texttt{\$PATHCS/Noyau/ncs-\verscs}. 

In order to use \CS, every user must add the following line in their file
``\texttt{.profile}''\footnote{or \texttt{.monprofile} if the
 modifications of the \texttt{.profile} file are reserved for the
 administators, as is the case in the MFEE departement}:

\hspace*{2cm}\texttt{. }\tildeunix\texttt{saturne/Noyau/ncs-\verscs/bin/cs\_profile} for the MFEE
server and Chatou cluster.

\hspace*{2cm}\texttt{. }\tildeunix\texttt{saturne/Saturne/Noyau/ncs-\verscs/bin/cs\_profile}
for the CCRT machines.

\hspace*{2cm}\texttt{. }\texttt{xxxxxxx/Noyau/ncs-\verscs/bin/cs\_profile} for
the other cases, where \texttt{xxxxxxx} represents the PATHCS directory where
\CS\ and its components have been installed (refer to the administrator
responsible for \CS).

This command runs the environment file of \CS, which sets the different
environment variables to their correct value. {\bf \CS\ will not work correctly
if those variables have not been set properly}.\\
After adding this line to the \texttt{.profile}, it is
necessary to logout of the session and relog in (simply reading the file by
typing ``\texttt{. \tildeunix/.profile}'' is usually not enough and might not
set the \texttt{PATH} variable correctly for the whole session).

{\em WARNING: Other pieces of information related
to \CS\ must not be included in \texttt{.profile}. In particular,
lines referring to previous versions of the code must be suppressed}


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

\noindent
A study directory containing:
\begin{list}{$\bullet$}{}
\item A directory \texttt{MAILLAGE} 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{FORT} 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{SUITE.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{listenv.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{FORT.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{lance.mmddhhmm}). \texttt{compil.log.mmddhhmm} and
\texttt{resume.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{FICHIERS\_RESULTATS\_UTILISATEUR}
of the launch script, see \S\ref{prg_lance}}.


During calcualtions 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 localisation 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{FORT\_SYR} for the potential \syrthes\ user subroutines  
\item a directory \texttt{DATA\_SYR} containing the configuration file \texttt{syrthes.env}
(localisation 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.

\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}. The compilation
report file is the same for \syrthes\ and \CS. It is placed in the \texttt{RESU}
directory under the name  \texttt{compil.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{FORT\_SYR.mmddhhmm} in the
directory \texttt{RESU}.


\begin{table}[!t]
\begin{tabular}{lll}
\multicolumn{3}{l}{Below are typical contents of a case directory CASE1 in a study STUDY} \\
\multicolumn{3}{r}{(\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 \\
                                \multicolumn{3}{r}{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/FORT:}}&{\bf \CS\ user subroutines }\\
&	\texttt{USERS}   		&	examples of a user subroutines\\
&	\texttt{usclim.F}  		&user subroutines used for the present the calculation\\
&	\texttt{usini1.F}  &\\
\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{FORT.08211921}	      &\CS\ user subroutines  
                                        used for the\\
&                                      &calculation 08211921\\
&	\texttt{FORT\_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 directroy containing the
                                     user results files\\
&	\texttt{SUITE.08211921}       &directory containing the \CS\ restart files \\
&	\texttt{compil.log.08211921}  &compilation report\\  
&     \texttt{study.xml.08211921}   &Graphical User Interface parameter file
                                    used for the\\ 
&                                   &calculation 08211921\\
&	\texttt{lance.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{lance.*}'' in the
                                       \texttt{RESU} directory)\\
&	\texttt{listenv.08211921}     &execution report for the Preprocessor module of
                                    \CS\ (pre-processing)\\
&	\texttt{listing.08211921}     &execution report for the Kernel module of \CS\\
&	\texttt{listsyr.08211921}     &execution report for \syrthes\\
&	\texttt{resume.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\ chronolgical solid
                                      post-processing file (may be tranformed \\
&                                    &into the {\em Ensight} format with the 
                                     {\em syrthes2ensight} utility)\\
\multicolumn{2}{l}{\texttt{STUDY/CASE1/SCRIPTS:}}&{\bf launch script}\\
&	\texttt{lance}                &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}%
Below are given information about the content of the \CS\ base directories. They
are not of vital interest for the user, but given only as general
information. Indeed, the case preparer \texttt{cree\_sat} 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_creesat}).
The \texttt{info\_cs} gives direct
access to the most needed information (especially the user and progammer's
guides) without the user having to look for them in the \CS\ directories.


The subdirectory \texttt{lib} contains the libraries. 

\noindent
The environment variable \texttt{NOM\_ARCH} allows to distinguish the different
architectures:
\begin{list}{$\bullet$}{}
\item\texttt{HP-UX} for HP-UX system
\item\texttt{IRIX64} for SGI Irix system
\item\texttt{Linux} for general PC machines under Linux
\item\texttt{Linux\_CCRT} for the Tantale cluster at CCRT
\item\texttt{Linux\_Ch} for the Chatou cluster
\item\texttt{OSF1} for the Nickel/Chrome clusters at CCRT
\item\texttt{SunOS} for Sun machines
\end{list}


For each architecture, a subdirectory (named after \texttt{NOM\_ARCH}) 
stores the compilated libraries
\texttt{libsaturne*.a}. The launch script automatically loads them for
the standard calculations. The different libraries correspond to the
different modules of \CS\:
\begin{list}{$\bullet$}{}
\item\texttt{libsaturneBASE.a} for the basic Kernel, 
\item\texttt{libsaturneCOGZ.a} for the gas combustion module, 
\item\texttt{libsaturneCFBL.a} for the compressible module, 
\item\texttt{libsaturneCPLV.a} for the pulverised coal combustion module, 
\item\texttt{libsaturneELEC.a} for the electric module,
\item\texttt{libsaturneLAGR.a} for the lagrangian module,
\item\texttt{libsaturneMATI.a} for the Matisse module,
\item\texttt{libsaturneRAYT.a} for the radiation module. 
\end{list}

\noindent 
When a specific module is not available in the distribution of \CS,
the corresponding file \texttt{libsaturne*.a} is replaced by an empty library
which is marked out by \texttt{STUB}
(\texttt{libsaturneCPLV\_STUB.a} for example) to allow the complilation. 

\noindent Different compilation options are available for each module:
\begin{list}{$\bullet$}{}
\item DBG for debugging,
\item EF for the ``Electric Fence'' utility,
\item LO for low optimisation,
\item PROF for profiling,
\item PUR to use the ``Purify'' utility.
\end{list}
Each option is related to a specific library, for instance \texttt{libstaurneBASELO.a}
for the ``low optimisation'' library of the base module.

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

The source files, when available, are stored in the directory \texttt{src},
under subdirectories corresponding to each module: \texttt{base\_1} (general
routines of moderate confidentiality), \texttt{base\_2} (general
routines of high confidentiality), \texttt{cfbl} (compressible flows),
\texttt{cogz} (gas combustion),
\texttt{cplv} (pulverised coal combustion), \texttt{elec} (electric module),
\texttt{mati} (Matisse module),
\texttt{pprt} (general specific physics routines) and \texttt{rayt} (radiative heat
transfer).

The user subroutines are available in the directory \texttt{users},
under similar subdirectories corresponding to each module: \texttt{base} (general
routines), \texttt{cfbl}, \texttt{cogz}, \texttt{cplv}, \texttt{elec},
\texttt{pprt} and \texttt{rayt}.
The case preparer \texttt{cree\_sat} copies all these files in the
user directory \texttt{FORT/USERS} 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{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{info\_cs 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_environnementCS}).  

\item Prepare the different directories using \texttt{cree\_sat}(see
\S\ref{prg_creesat}) and, when needed, add the directories \texttt{DATA\_SYR}
and \texttt{FORT\_SYR} which are required to accomodate the \syrthes\ files.

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

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

\item Place the necessary user subroutines in the directory \texttt{FORT} (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 compliant with 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'':}

(Lagrangian mode not compliant with the Graphical User Interface in version \verscs)
    \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 arc:)}

(not compliant with 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 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 compliant with 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 compliant with the Graphical User Interface in version \verscs)
    \begin{list}{}{}
        \item {\em compulsory:}
        \begin{list}{-}{}
            \item \texttt{uscfx1} et \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{lance}, directly or through the
      Graphical Interface (see \S\ref{prg_lance})

\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_lance})
\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/\$ETUDE/\$CAS.mmddhhmm} for stand-alone
workstations or for the Chatou cluster\\
\texttt{RUN=\$TMPDIR} on Nickel/Chrome at the CCRT (\texttt{\$TMPDIR} is a
directory created by the batch manager for the job and deleted after its
completion)\\
\texttt{RUN=\$SCRATCHDIR/tmp\_Saturne/\$ETUDE/\$CAS.mmddhhmm} for Tantale at the
CCRT\\
where \texttt{\$ETUDE} and \texttt{\$CAS} 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. Or, on
Nickel/Chrome, it might be useful to use an alternate \texttt{RUN} directory
that will not be deleted at the end (for debugging purposes for instance).

For this matter, the variable \texttt{CS\_TMP\_PREFIX} of the launch script (see
\S\ref{prg_lance}) 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/\$ETUDE/\$CAS.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 modules, the Preprocessor and the
Kernel. The Preprocessor is in charge of the pre-processing. It reads the meshes and
performs the necessary pastings and domain decompositions. The resulting data
are transfered to the Kernel through specific files, one for each processor the
Kernel will be running on. For a monoprocessor calculation, the file is named
\texttt{enveloppe\_vers\_solveur}. For a parallel calculation on $N$ processors,
the files are named \texttt{enveloppe\_vers\_solveur\_n0001} to
\texttt{enveloppe\_vers\_solveur\_n$N$}. In a standard calculation, these files
are created in the temporary execution directory and left there after
calculation. They have no interest for data analysis and are too dependent on
the number of processors or the machine to be kept.

Yet, the Preprocessor module does not work in parallel and sometimes requires a
large amount of memory. Hence it is sometimes useful to run the Preprocessor
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 defines three ``execution modes'', that can
be specified in the variable \texttt{MODE\_EXEC} (see \S\ref{prg_lance}):\\
\hspace*{0.5cm}\texttt{complet}: complete mode. The Preprocessor module is executed
for pre-processing, followed by the Kernel for the calculation. The 
\texttt{enveloppe\_vers\_solveur*} files are created and left in the
temporary execution directory.\\
\hspace*{0.5cm}\texttt{pre-traitement}: only the Preprocessor module is
executed. The \texttt{enveloppe\_vers\_solveur*} files are stored in a directory
\texttt{PRE\_TRAITEMENT.mmddhhmm} automatically created in the \texttt{RESU}
directory, for later use.\\
\hspace*{0.5cm}\texttt{calcul}: only the Kernel is executed. The
\texttt{enveloppe\_vers\_solveur*} files are read from the directory specified
in the variable \texttt{PRE\_TRAITEMENT\_AMONT} of the launch script


%==================================
\subsubsection{Interactive modification of the target time step}
%==================================
\label{prg_ficstp}%
During a calculation, it is possible to change the limit time step number
(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_creesat}%
The case preparer \texttt{cree\_sat} 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{cree\_sat} is as follows:

\noindent
\texttt{cree\_sat -etude 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{CAS1} is
created.

\noindent
\texttt{cree\_sat -cas DEBIT3 DEBIT4}\\
executed in the directory \texttt{STUDY} adds the case directories
\texttt{DEBIT3} and \texttt{DEBIT4}.  

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

In the directory \texttt{DATA}, \texttt{cree\_sat} 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 DONNEES\_THERMOCHIMIE. All other files in
the \texttt{DATA} or in the \texttt{THCH} will be ignored.\\
\texttt{cree\_sat} also places in the directory \texttt{DATA} the launch script
for the Graphical User Interface:  \texttt{SaturneGUI}.


In the directory \texttt{FORT}, \texttt{cree\_sat} creates a
subdirectory \texttt{USERS} containing all the user subroutines,
classified by module type:  \texttt{base} (general
routines), \texttt{cfbl}, \texttt{cogz}, \texttt{cplv}, \texttt{elec},
\texttt{pprt} and \texttt{rayt}. Only the user subroutines placed directly under
the directory \texttt{FORT} will be considered. The others will be ignored.

In the directory \texttt{SCRIPTS}, \texttt{cree\_sat} copies and pre-fills an
example of launch scripts: \texttt{lance}.
The study, case and user name are filled
automatically in the launch script, as are the paths leading to the
different directories.  The name of the mesh file(s) must be specified
(by default its name is \texttt{\$ETUDE.unv}). 
If necessary, optional instructions may be added (see \S\ref{prg_lance}).


%==================================
\subsection{Pre-processing}
%==================================
The Preprocessor module of \CS\ is in charge of the pre-processing. It reads the
mesh file(s) (under any supported format) and transfers the necessary
information to the Kernel. Mesh pasting and domain decomposition for parallel
calculations are made during this phase. In case of periodic boundary
conditions, the Preprocessor module also identifies the boundary faces that are
related through periodicity and creates the corresponding connectivity table.

For a complete information on the Preprocessor module, please refer to the
corresponding user guide \cite{ecsmu} (available on-line through the command
\texttt{info\_cs ecsmu}).


%==================================
\subsubsection{Usable meshes}
%================================== 
\label{prg_maillages}%
\CS\ allows to run calculations using meshes of different formats:
\begin{list}{-}{}

\item Universal I-DEAS format (Master Series, versions 6 to 9) generated
      by I-DEAS, ICEM, SIMAIL, ...\\
{\footnotesize\it It should be noted, though, that NOPO files
(\texttt{*.des}) created by SIMAIL are directly usable by \CS. It is therefore
not necessary to convert them to the I-DEAS format. Moreover the conversion
procedure is quite tedious if one wishes to keep the colour of the boundary
faces. Indeed, once the mesh M is created and its boundary faces couloured, the
boundary faces have to be extracted, and the resuting surface mesh has to be
repasted with the original volume mesh M (using the option to paste all
nodes). The resulting composite mesh must then be exported in the SIMAIL format
(M.des) and transformed into the I-DEAS format with the
\texttt{sim2sup}\footnote{this utility comes with the SIMAIL distribution. The
current version on the MFEE servers is \texttt{/logiciels/simulog/SIMAIL-6.5/bin/sim2sup}/}
utility, using mode 1 (\mbox{\texttt{SIMAIL --> MASTERSERIES}}). This procedure
can be very long for meshes of more than 100\,000 cells.}

\item SIMAIL NOPO format: the \texttt{*.des} files may be read directly
      by \CS.

\item Hexa NUMECA format (\texttt{*.hex}files): this format is seldom used. It
is the product of {\em IggHexa} (which has since become {\em Hespress}. It is
not maintained, since the corresponding mesh generator in not available at
MFEE. The filter is based on specifications and some example meshes provided by
the NUMECA company in 2001.

\item MED 2.2. format.

\item CGNS 2.0 (or later) format: this format is seldom used or tested at EDF,
but more largely used elsewhere.

\item EnSight 6 or later and EnSight Gold format.

\item Gmsh format (free 3D mesh generation tool with integrated pre- and
      post-processing functions).

\item Comet-Design format (polyhedric mesh generation tool).

\item Gambit Neutral format: format of the Fluent mesh generator.
\end{list}

The use of files of the ``Common Solver'' type\footnote{File type specifically
developped for the early prototype versions of \CS\ to be read directly by the
Kernel while the Preprocessor module was under development (extension \texttt{tlc})}
is still possible but is not maintained anymore. The reading of the mesh
is done directly from the Kernel, without the Preprocessor module.
The variable IFOENV must
 be set to 0 in the launch scripts. Many potentialities of \CS\ are not
compliant with this file format (mesh pasting with hanging nodes, periodicity,
parallel computing, ...).
The \texttt{slc2ideas} utility can be used to convert the 
'Common Solver' files to the I-DEAS format. \texttt{slc2ideas}
 is automatically available in the user's PATH (who can therefore enter the
command \texttt{slc2ideas} directly) when the environment variables for \CS\
have been set correctly. However, not all the files can be converted. In particular,
they must comply with the initial choice (\texttt{tlc}) according to which 
each internal face possesses two and only two neighbouring cells, and each
boundary face only one neighbouring cell. For non-converted,
or non-convertale meshes of the 'Common Solver' type,
the calculation must be done without using the Preprocessor (keyword IFOENV=0).
For all the other formats, the Preprocessor must be used (IFOENV=1).

The Preprocessor can also accept zipped mesh file (for the formats I-DEAS, SIMAIL and Hexa NUMECA).

{\em WARNING:} Unless a specific option is used, the Preprocessor module
determines the mesh format directly from the file suffix:
{\em``\texttt{.unv}''} for the universal IDEAS format,
{\em``\texttt{.des}''} for the SIMAIL format,
{\em``\texttt{.hex}''} fot the Hexa NUMECA format,
{\em``\texttt{.med}''} for the MED format, 
{\em``\texttt{.cgns}''} for the CGNS format,
{\em``\texttt{.case}''} for the EnSight format,
{\em``\texttt{.ngeom}''} for the Comet format,
{\em``\texttt{.msh}''} for the Gmsh format, 
{\em``\texttt{.neu}''} for the Gambit Neutral format,
(voir \texttt{info\_cs ecsmu}).\\


{\em WARNING: }
Some turbulence models ($k-\varepsilon$, $R_{ij}-\varepsilon$ SSG, ...) used in
\CS\ are ``High-Reynolds'' models. Therefore the size of the cells
neighbouring 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} p.\pageref{prg_iturb}. 

%==================================
\subsubsection{Preprocessor command line options}
%==================================
\label{prg_optappelecs}%
A complete description of the Preprocessor command line options can be found in
\cite{ecsmu}, accessible by the command \texttt{info\_cs ecsmu}. The executable
of the Preprocessor module is \texttt{ecs}, accessible directly once the environment
variables of \CS\ are set properly. A summary of the command line options is
also given by the command \texttt{ecs -help}.

For the main options, the launch script \texttt{lance} contains corresponding
environment variables at its beginning, that are used later when the executable
is called. This way, the user only has to fill these variables and doesn't need
to search deep in the script for the Preprocessor command line.

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 \$MAILLAGE}, where \texttt{MAILLAGE} is the variable where the user has
specified the different meshes to be used.

\item \texttt{-p n}: to trigger the decomposition of the domain into \texttt{n}
subdomains, for parallel computing. In the launch script, the number of
processors used is specified in the \texttt{NOMBRE\_DE\_PROCESSEURS} variable,
or through the batch headers. If necessary, the launch script then automatically
passes the \texttt{-p} option to the Preprocessor command line (see \ref{prg_lance}).

\item \texttt{-rc}: triggers the mesh pasting functions. If nothing more is
specified, every area of contact between two meshes will be pasted together. The
pasting can be limited to certain selected faces. For instance, to paste only
the faces of colours 6 and 7, the full option will be \mbox{\texttt{-rc -couleur
6 7}}. These options are to be specified in the \texttt{COMMANDE\_RC} 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 -ptinv px py pz}\\
(with obvious notations), or by giving the rotation matrix and an invariant point\\
\texttt{-perio -rota -matrice m11 m12 m13 m21 m22 m23 m31 m32 m33 -ptinv 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{-couleur}. 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 -couleur 2} \verb+\+\\
\texttt{-perio -rota -angle 90 -dir 0 0 1 -ptinv 0 0 0 -couleur 3 4} \verb+\+\\
\texttt{-perio -trans 0 1 0 -rota -matrice 1 0  0 0 0 -1 0 1 0 -ptinv 0 0 -0.2}\\
This option is to be specified in the \texttt{COMMANDE\_PERIO} variable in
the launch script, to be automatically passed to the command line.

\item \texttt{-df}: triggers the division 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 modelling, 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{-df 0.02}}.\\
This option is to be specified in the \texttt{COMMANDE\_DF} variable in
the launch script, to be automatically passed to the command line.

\item \texttt{-ve}: to trigger the determination of the ``extended
neighbourhood''. Indeed, for certain gradient calculation methods (IMRGRA=2 or
3) as well as for the dynamic LES model (ITURB=41), the code needs the list of
the different cells sharing at least one vertex with a given cell. This
``extended neighbourhood'' list is created by the Preprocessor when necessary and
passed to the Kernel. The launch script automatically detects whether this list
is needed and applies the \texttt{-ve} option, without any user intervention.
\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{-ec n} or \texttt{--echo-comm n}: triggers the display of the
communications between the
Preprocessor module and the Kernel.\\
\hspace*{0.5cm}\texttt{n=-1}: display only the error messages\\
\hspace*{0.5cm}\texttt{n=0}: display the headers of messages\\
 \hspace*{0.5cm}\texttt{n$>$0}: display the headers and the n first and last
elements of the messages\\
The usage of this option is very limited, and generally restricted to
developpers. The value of \texttt{n} is to be placed in the \texttt{ECHOCOMM}
variable of the launch script, the option \texttt{--echo-comm \$ECHOCOMM} is
then automatically passed to the Kernel command line.

\item \texttt{-ifoenv n}: specifies the use (\texttt{n}=1) or not (\texttt{n}=0)
of the Preprocessor module. If the \texttt{-ifoenv 0} option is used, only the mehes
of the ``Common Solver'' type can be used (see \S\ref{prg_maillages} for
restrictions).\\
The value of \texttt{n} is to be placed in the \texttt{IFOENV} variable in the launch
script. The option \mbox{\texttt{-ifoenv \$IFOENV}} is automatically added to the
Kernel command line.\\
The value of \texttt{n} is accessible in the variable IFOENV\index{IFOENV} in
the FORTRAN code.

\item \texttt{-longia n}: specifies the size \texttt{n} of the macro-array of
integers IA (number of integers in the array). If the size is not sufficient,
\CS\ stops and indicates the additional size needed.\\
The value of \texttt{n} is to be placed in the \texttt{LONGIA} variable in the launch
script. The option \mbox{\texttt{-longia \$LONGIA}} is automatically added to the
Kernel command line.\\
The value of \texttt{n} is accessible in the variable LONGIA\index{LONGIA} in
the FORTRAN code.

\item \texttt{-longra n}: specifies the size \texttt{n} of the macro-array of
reals RA (number of reals in the array). If the size is not sufficient,
\CS\ stops and indicates the additional size needed.\\
The value of \texttt{n} is to be placed in the \texttt{LONGRA} variable in the launch
script. The option \mbox{\texttt{-longra \$LONGRA}} is automatically added to the
Kernel command line.\\
The value of \texttt{n} is accessible in the variable LONGRA\index{LONGRA} in
the FORTRAN code.

\item \texttt{-mc xx} or \texttt{--mode-comm xx}: indicates the communication
mode between the Preprocessor and the Kernel.\\
\hspace*{0.5cm}\texttt{xx=bin}: binary files\\
\hspace*{0.5cm}\texttt{xx=txt}: ASCII files\\
The usage of this option is very limited, and generally restricted to
developpers. Hence it does not appear in the launch script, which induces the
default behaviour (binary files).

\item \texttt{-p n} or \texttt{-parallel n}: specifies the number of processors
(potentially virtual) on
which the Kernel will run.  In the launch script, the number of
processors used is specified in the \texttt{NOMBRE\_DE\_PROCESSEURS} variable,
or through the batch headers. If necessary, the launch script then automatically
passes the \texttt{-p} option to the Kernel command line (see \ref{prg_lance}).

\item \texttt{--coupl-cs}: this option concerns the coupling of different
executions of \CS. It is still under development. Please refer to \CS\
development team for further information.

\item \texttt{-syrthes}: triggers the coupling with the code \syrthes\ (thermal
diffusion and transparent radiation in a solid). It has to be combined with a
selection sub-option, to specify the boundary faces that need to be coupled. The
syntax for selecting the faces is similar to that in the Preprocessor command line,
with keywords \texttt{couleur} (for colour selection), \texttt{groupe} (for
group selection) and \texttt{invsel} (to invert the selection). See
\cite{ecsmu} for further details. For instance, to couple all the boundary faces
except the faces of colour 2 and 3, the command line option would be\\
\texttt{-syrthes -couleur 2 3 -invsel}\\
It is possible to couple a \CS\ calculation with a 2D \syrthes\ calculation. To
do so, the sub-option \texttt{-2d} must be added, potentially completed by the
specification of the direction normal to the 2D mesh: \texttt{-X}, \texttt{-Y}
or \texttt{-Z} (default). For instance:\\
\texttt{-syrthes -groupe PAROI -2d -X}\\
All these options are to be placed in the \texttt{COMMANDE\_SYRTHES} variable of
the launch script to be passed automatically to the Kernel command line.\\
{\footnotesize\it To be thourough, there are two other sub-options to the
\texttt{-syrthes} option: \texttt{-proc n} the specify that the \syrthes\
executable is running on the processor \texttt{n} and \texttt{-socket} in to
specify that the communication between \CS\ and \syrthes\ is made through
sockets. These options are not to be specified by the user. They are
automatically set and passed to the command line by the launch script.}

\item \texttt{-v n} or \texttt{--verif n}: 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.\\
\hspace*{0.5cm}\texttt{n=-1}: no test (default value if no \texttt{-v} option is
specified. The code runs normally\\
\hspace*{0.5cm}\texttt{n=0}: the quality criteria of the mesh are calculated
(non-orthogonality angles, internal faces off-set, ...) and corresponding
EnSight post-processing parts are created.\\
\hspace*{0.5cm}\texttt{n=1}: 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 option IMRGRA=0.\\
\hspace*{0.5cm}\texttt{n=2}: 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 option IMRGRA=1.\\
\hspace*{0.5cm}\texttt{n=3}: 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 option IMRGRA=2.\\
\hspace*{0.5cm}\texttt{n=4}: 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 option IMRGRA=3.\\
\hspace*{0.5cm}\texttt{n=5}: 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 option IMRGRA=4.\\
The value of \texttt{n} is to be placed in the \texttt{ARG\_CS\_VERIF} variable
in the launch script. The option \mbox{\texttt{-v \$ARG\_CS\_VERIF}} is
automatically added to the Kernel command line.\\
The value of \texttt{n} is accessible in the variable IVERIF\index{IVERIF} in
the FORTRAN code.

\item \texttt{--log n}: specifies the destination of the output for a
monoprocessor 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{-param xxx}: specifies the name of the Interface 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_lance}%

The case preparer \texttt{cree\_sat} places an example of launch script,
\texttt{lance}, 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 (Nickel/Chrome/Tantale). 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{IFOENV}: value of the parameter IFOENV to be passed to the Kernel
(see \ref{prg_optappelnoy})

\item \texttt{LONGIA}: value of the parameter LONGIA to be passed to the Kernel
(see \ref{prg_optappelnoy}).

\item \texttt{LONGRA}: value of the parameter LONGIA to be passed to the Kernel
(see \ref{prg_optappelnoy})
\end{list}

{\it For parallel computations, LONGIA and LONGRA can theoretically
be divided by the number of processors, since each execution only deals with a
fraction of the domain. It is however advised to add a safety margin (10\%) to
account for non-optimal distribution of the domain among the processors and for
the presence of phantom cells (see \S\ref{prg_paralperio}).}

\begin{list}{$\bullet$}{}
\item \texttt{ETUDE}: name of the study directory (automatically set by
\texttt{cree\_sat}, see \S\ref{prg_architecture})

\item \texttt{CAS}: name of the case directory (automatically set by
\texttt{cree\_sat}, see \S\ref{prg_architecture}) 

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

\item \texttt{MAILLAGE}: 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{REPMAIL} (see below).

\item \texttt{COMMANDE\_RC}: Preprocessor command line option for mesh pasting (see
\ref{prg_optappelecs})

\item \texttt{COMMANDE\_DF}: Preprocessor command line option for the division of
faces with too large a warp angle (see \ref{prg_optappelecs})

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

\item \texttt{COMMANDE\_SYRTHES}: Kernel command line option for coupling with
\syrthes\ (see \ref{prg_optappelnoy})

\item \texttt{DONNEES\_THERMOCHIMIE}: 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{NOMBRE\_DE\_PROCESSEURS}: 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{NOMBRE\_DE\_PROCESSEURS}
will be equal to the number of processors reserved, and in case of an
interactive calculation, it will be set to 1.\\
When using a batch system,
\texttt{NOMBRE\_DE\_PROCESSEURS} 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{NOMBRE\_DE\_PROCESSEURS} 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{NOMBRE\_DE\_PROCESSEURS-1} processors.

\item \texttt{LISTE\_PROCESSEURS}: 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{FICHIERS\_DONNEES\_UTILISATEUR}: 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{FICHIERS\_DONNEES\_UTILISATEUR} (see \S\ref{prg_usvort}) 

\item \texttt{FICHIERS\_RESULTATS\_UTILISATEUR}: 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. 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{FICHIERS\_RESULTATS\_UTILISATEUR}},
restart files) do not need to be specified in
\texttt{FICHIERS\_RESULTATS\_UTILISATEUR}.

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

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

\item \texttt{LISTE\_LIB\_SAT}: list of \CS\ module libraries to use (see
\S\ref{prg_library}). Specifying
a list allows to use the ``STUB'' libraries (for modules that are not available)
or to use different optimisation options for different modules. If a list is
given, all modules must be referenced once (and only once). Leaving
the variable empty implies taking the standard optimisation library for all the
modules (BASE, COGZ, CFBL, CPLV, ELEC, LAGR, MATI, RAYT). An example of list
could be:\\ 
\texttt{LISTE\_LIB\_SAT=``libsaturneBASEDBG.a libsaturneCOGZ\_STUB.a
libsaturneCFBLDBG.a}\verb+ \+\\
\texttt{\phantom{LISTE\_LIB\_SAT=``}libsaturneCPLV\_STUB.a libsaturneELECDBG.a
libsaturneLAGR\_STUB.a}\verb+ \+\\ 
\texttt{\phantom{LISTE\_LIB\_SAT=``}libsaturneMATI\_STUB.a libsaturneRAYT\_STUB.a''}

\item \texttt{OPTION\_LIB\_EXT}: 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{OPTION\_LIB\_EXT=``-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 cs13.exe ...}). 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=-1).

\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{PILOTAGE\_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{REPBASE}: root directory of the calculation. This variable is
automatically set by \texttt{cree\_sat} and should not be changed.

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

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

\item \texttt{FORT}: FORT directory of the case (see \ref{prg_architecture}).
This variable is automatically set by \texttt{cree\_sat} and should not be
changed.

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

\item \texttt{SUITE\_AMONT}: directory containing the files for calculation
restart.

\item \texttt{PRE\_TRAITEMENT\_AMONT}: directory containing the
\texttt{enveloppe\_vers\_solveur*} files for a calculation in ``calculation''
mode (see \ref{prg_executionmodes})

\item \texttt{REPMAIL}: directory containing the mesh files (see
\ref{prg_architecture}). This variable is automatically set by
\texttt{cree\_sat} 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{FORT\_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{MODE\_COUPLAGE}: coupling mode between \CS\ and \syrthes, when
such coupling is activated (see \texttt{COMMANDE\_SYRTHES}). Three options are
available:\\
\hspace*{0.5cm}\texttt{MPI}: for a coupling based on MPI messages (requires an
MPI library)\\
\hspace*{0.5cm}\texttt{pipes}: for a coupling based on pipe files (on clusters,
such a coupling is valid only if all the processors are located on the same
node)\\
\hspace*{0.5cm}\texttt{sockets}: for a coupling based on sockets

\item \texttt{MODE\_EXEC}: execution mode for \CS\ (\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 interpretated by the code.

In version \verscs, the Graphical Interface manages calculation parameters,
standard initialisation values and boundary
conditions for standard physics and pulverised coal combustion. 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 optionnal. 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.

For example, in order to set the boundary conditions of a calculation
corresponding to a channel flow with a given inlet velocity profile, one
possibility could be to:\\
- set the boundary conditions corresponding to the wall and the output
using the Graphical Interface\\
- define in \texttt{usclim} the inlet area with its velocity
profile. The wall and output areas do not need to appear in
\texttt{usclim}. Moreover, if the inlet area has already been set in
the interface (for example with a uniform velocity), it is the boundary
conditions defined in the subroutine \texttt{usclim} which will be taken
into account.

The Graphical User Interface is launched with the \texttt{./SaturneGUI} commande
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 colours of the boundary
      faces).

\item Thermophysical models: physical model, turbulence model, thermal model,
      initialisation of the variables.

\item Physical properties: 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 colours 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 step, location of
      the probes where some variables will be monitored over time,
      definition of the periodicity 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.

\end{list}

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_lance}). 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{-noihm} of cree\_sat}
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{FORT}. 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{cree\_sat} automatically
comments out the examples in \texttt{usini1} (\texttt{Cex} at the beginning of
each line) while copying it in the directory \texttt{USERS}. 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{-noihm}
option of \texttt{cree\_sat} 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).


%==================================
\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{gest02}.

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}

\variab{NDIM}{NDIM}{I}{Space dimension (NDIM=3)}

\bigskip

\variab{NCEL}{NCEL}{I}{Number of real cells in the mesh}

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

\variab{NFAC}{NFAC}{I}{Number of internal faces (see note 2)}

\variab{NFABOR}{NFABOR}{I}{Number of boundary faces (see note 2)}

\variab{NCELBR}{NCELBR}{I}{Number of cells with at least one boundary
face (see note 2)} 

\bigskip

\variab{LNDFAC}{LNDFAC}{I}{Size of the array NODFAC\index{NODFAC} of
internal faces - nodes connectivity (see note 3)}

\variab{LNDFBR}{LNDFBR}{I}{Size of the array NODFBR\index{NODFBR} of
boundary faces - nodes connectivity (see note 3)}

\variab{NNOD}{NNOD}{I}{Number of vertices in the mesh}

\bigskip

\variab{NFML}{NFML}{I}{Number of referenced families of entities (boundary
faces, elements, ...)} 

\variab{NPRFML}{NPRFML}{I}{Number of properties per referenced entity family} 

\bigskip
 
\variab{NPHAS}{NPHAS}{I}{Effective number of phases. NPHAS must be
inferior or equal to NPHSMX. In the current version, NPHAS is forced to 1 and
should not be changed.} 

\variab{NPHSMX}{NPHSMX}{I}{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 NPHAS different from 1.}}

\variab{NVAR}{NVAR}{I}{Number of solved variables (must be lower than NVRMAX)}

\variab{NSCAMX}{NSCAMX}{I}{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)}

\variab{NSCAL}{NSCAL}{I}{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: NSCAUS
user-defined scalars and NSCAPP scalars related to a ``specific
physics''. NSCAL=NSCAUS+NSCAPP, and NSCAL must be inferior or equal to NSCAMX}

\variab{NSCAPP}{NSCAPP}{I}{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, ...}

\variab{NSCAUS}{NSCAUS}{I}{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 NSCAPP scalars related to the
``specific physics''. For example: passive tracers, temperature (when no
specific physics model is selected), ...}

\variab{NESTMX}{NESTMX}{I}{Maximum number of error estimators for
Navier-Stokes} 

\bigskip

\variab{LONGIA}{LONGIA}{I}{Size of the macro array of integer IA} 

\variab{LONGRA}{LONGRA}{I}{Size of the macro array of real RA} 

\variab{NPROMX}{NPROMX}{I}{Maximum number of physical properties. They
will be stored in the arrays PROPCE, PROPFA or PROPFB} 

\variab{NPROCE}{NPROCE}{I}{Number of properties defined at the
cells. They will be stored in the array PROPCE} 

\variab{NPROFA}{NPROFA}{I}{Number of properties defined at the internal
faces. They will be stored in the array PROPFA}  

\variab{NPROFB}{NPROFB}{I}{Number of properties defined at the boundary
faces. They will be stored in the array PROPFB}

\variab{NVISLS}{NVISLS}{I}{Number of scalars with variable diffusivity} 


\bigskip

\variab{NUSHMX}{NUSHMX}{I}{Maximum number of user chronological files
(in the case where \texttt{ushist} is used)} 

\variab{NBMOMT}{NBMOMT}{I}{Effective number of calculated time-averages.
NBMOMT must be inferior or equal to NBMOMX} 

\variab{NBMOMX}{NBMOMX}{I}{Maximum number of calculated time-averages (default
value: 50)}


\variab{NDGMOX}{NDGMOX}{I}{Maximum degree of the time-averages (default value:
5)}


\bigskip
 
\variab{NCLACP}{NCLACP}{I}{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. NCLACP must
be inferior or equal to NCLCPM}

\variab{NCLCPM}{NCLCPM}{I}{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 NCELET. \\
\hspace*{1cm} Indeed, when periodicity is enabled, the cells with
periodic faces do not have any real neighbouring cell across these
particular faces. Their neighbouring cell is elsewhere in the calculation
domain (its position is determined by the periodicity). In order to
store temporarily the information coming from this ``distant''
neighbouring 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 neighbouring cells, some of them being treated by another processor. The
creation of ghost cells allows to store temporarily the information
coming from real neighbouring cells treated by other processors.\\
The variables are generally arrays of size NCELET (number of real and
fictitious cells). The calculations (loops) are made on 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
neighbouring 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: IPNFAC and NODFAC for the internal
faces, IPNFBR and NODFBR for the boundary faces. NODFAC (dimension 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.
IPNFAC (dimension: NFAC+1) gives the position IPNFAC(IFAC) in NODFAC of the
first node of each internal face IFAC. Therefore, the reference numbers of all
the nodes of the internal face IFAC are : NODFAC(IPNFAC(IFAC)),
NODFAC(IPNFAC(IFAC)+1), ..., NODFAC(IPNFAC(IFAC+1)-1). In order for this last
formula to be valid even for IFAC=NFAC, IPNFAC is of dimension NFAC+1 and
IPNFAC(NFAC+1) is equal to LNDFAC+1.\\
The composition of the arrays NODFBR and 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.

%FIN DE TRADUCTION
%=================
%=================
%=================
%=================
%=================
%=================
%=================



%==================================
\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
centres of the internal faces} 

\variab{CDGFBO}{CDGFBO(NDIM,NFABOR)}{RA}{Coordinates of the centres of the
boundary face} 


\variab{IFACEL}{IFACEL(2,NFAC)}{IA}{Index-numbers of the two (only) neighbouring
cells for each internal face}

\variab{IFABOR}{IFABOR(NFABOR)}{IA}{Index-number of the (unique) neighbouring
cell for each boundary face} 


\variab{IPNFAC}{IPNFAC(NFAC+1)}{IA}{Position of the first node of the each internal
face in the array NODFAC (see note 3 in paragraph \ref{prg_nnod}).}

\variab{IPNFBR}{IPNFBR(NFABOR+1)}{IA}{Position of the first node of the each boundary
face in the array NODFBR (see note 3 in paragraph \ref{prg_nnod}).}


\variab{NODFAC}{NODFAC(LNDFAC)}{IA} {Index-numbers of the nodes of each
internal face (see note 3 in paragraph \ref{prg_nnod}).}

\variab{NODFBR}{NODFBR(LNDFBR)}{IA}{Index-numbers of the nodes of each
boundary face (see note 3 in paragraph \ref{prg_nnod}).}

\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 IFACEL(1,.)
to 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 centres}

\variab{XYZNOD}{XYZNOD(NDIM,NNOD)}{RA}{Coordinates of the mesh vertices}

In addition, additionnal geometric variables are accessible in sections of
the unidimensional macro-arrays\footnote{in FORTRAN, a multidimensional
array A(3,2) is in fact a unidimensional array containing the elements
A(1,1), A(2,1), A(3,1), A(1,2), A(2,2) and A(3,2) in this order.} 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 in IA and RA is indicated by
an integer stored in a ``common'' (in the file
\texttt{pointe.h})\footnote{With this system, it is possible for example to
reach the surface of an
internal face IFAC with RA(ISRFAN+IFAC-1) in every subroutine where RA
is known and \texttt{pointe.h} is present. \\
In the same manner, DOFIJ(II,IFAC) can be obtained with
RA(IDOFIJ+(IFAC-1)*NDIM+II-1).} By analogy, these integers will be referred here
as ``pointers''. The main ones are listed below.

 

\variab{IDIJPF}{IDIJPF}{I}{In RA, pointer to
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 on a straight line orthogonal to
the face of the centres of the first and the second neighbouring cells}

\variab{IDIIPB}{IDIIPB}{I}{In RA, pointer to
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, centre of the neighbouring cell, on the
straight line perpendicular to the face and crossing its centre}

\variab{IDIST}{IDIST}{I}{In RA, pointer to 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 centre
of the first and the second neighbouring 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 RA, pointer to DISTBR(NFABOR), real array
giving, for every boundary face, the scalar product between
the vectors $\vect{IF}$ and $\vect{n}$. I is the centre of the
neighbouring cell. F is the face centre. 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 RA, pointer to 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 centres of the two neighbouring cells. F
is the face centre} 

\variab{IICELB}{IICELB}{I}{In IA, pointer to ICELBR(NFABOR), integer array
giving, for every boundary face, the index-number of the neighbouring cell}

\variab{IPOND}{IPOND}{I}{In RA, pointer to 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 RA, pointer to SURFAN(NFAC), real array
giving the absolute value of the surface of the internal faces}

\variab{ISRFBN}{ISRFBN}{I}{In RA, pointer to SURFBN(NFABOR), real array
giving the absolute value of the surface of the boundary faces}

%==================================
%\subsubsection{Variables physiques}
\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 centres. 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 variables,
solved at the current time step} 

\variab{RTPA}{RTPA(NCELET,NVAR)}{RA}{Array storing the variables,
solved at the previous time step} 

\bigskip

\underline{Concerning RTP and RTPA}

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

For example, IPR(IPHAS) refers to the variable ``pressure'' of the phase
IPHAS (with 1$\leqslant$IPHAS$\leqslant$NPHAS): the pressure of the
phase IPHAS in the cell IEL at the current time step is therefore
RTP(IEL,IPR(IPHAS)). 

The list of integers referring to solved variables is given below. These
variable index-numbers do not only allow to access to the value of the
variable at the cell centre (for instance RTP(IEL,IPR(IPHAS))) but are also
used to access to arrays whose size is the number of variables, like
some numerical options (for instance, BLENCV(IK(IPHAS)) is the
percentage of second-order convective scheme for the turbulent energy of
the phase IPHAS when the $k-\varepsilon$ model is used).

\begin{list}{$\bullet$}{}
\item IPR(IPHAS)\index{IPR}: pressure.
\item IU(IPHAS)\index{IU}: velocity along the X axis.
\item IV(IPHAS)\index{IV}: velocity along the Y axis.
\item IW(IPHAS)\index{IW}: velocity along the Z axis.
\item IK(IPHAS)\index{IK}: turbulent energy, in $k-\varepsilon$ modelling.
\item IR11(IPHAS)\index{IR11}: Reynolds stress R11, in
      $R_{ij}-\varepsilon$ modelling.
\item IR22(IPHAS)\index{IR22}: Reynolds stress R22, in
      $R_{ij}-\varepsilon$ modelling.
\item IR33(IPHAS)\index{IR33}: Reynolds stress R33, in
      $R_{ij}-\varepsilon$ modelling.
\item IR12(IPHAS)\index{IR12}: Reynolds stress R12, in
      $R_{ij}-\varepsilon$ modelling.
\item IR13(IPHAS)\index{IR13}: Reynolds stress R13, in
      $R_{ij}-\varepsilon$ modelling.
\item IR23(IPHAS)\index{IR23}: Reynolds stress R23, in
      $R_{ij}-\varepsilon$ modelling.
\item IEP(IPHAS)\index{IEP}: turbulent dissipation in $k-\varepsilon$,
$R_{ij}-\varepsilon$ or v2f ($\varphi$-model) modelling.
\item IOMG(IPHAS)\index{IOMG}: Specific dissipation rate $\omega$, in
$k-\omega$ SST modelling.
\item IPHI(IPHAS)\index{IPHI}: variable $\varphi=\overline{v^2}/k$ in v2f ($\varphi$-model).
\item IFB(IPHAS)\index{IFB}: variable $\overline{f}$ in v2f ($\varphi$-model).
\item ISCA(J)\index{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:
      NSCAUS ``user'' scalars and NSCAPP ``specific physics'' scalars, with
      NSCAL=NSCAUS+NSCAPP. NSCAL must be inferior or equal to NSCAMX.
\item The phase related to the scalar J is IPHSCA(J)\index{IPHSCA}. 
\item The J$^{\text{th}}$ scalar related to a specific physics is, in
      the whole list of the NSCAL scalars, the scalar number
      ISCAPP(J). In the list of the NVAR solved variables, it
      corresponds to the variable number ISCA(ISCAPP(J))\index{ISCAPP},
      whose value in the cell IEL at the current time step is given by
      RTP(IEL,ISCA(ISCAPP(J))). 

\item The J$^{\text{th}}$ ``user'' scalar
      (0$\leqslant$J$\leqslant$NSCAUS$\leqslant$NSCAL) is,si $J>0$, the
 scalar number J in the thorough list of NSCAL scalars' In the list of 
solved NVAR variables, it corresponds to the variable number cell IEL 
and its value in the cell is RTP(IEL,ISCA(J)).
    
\item The temperature (or the enthalpy) is the scalar number
      ISCALT(IPHAS)\index{ISCALT} in the list of the NSCAL scalars. It
      corresponds to the variable number ISCA(ISCALT(IPHAS)) and its
      value in the cell IEL is RTP(IEL,ISCA(ISCALT(IPHAS))=1 if there is no thermal scalar.
\item A ``user'' scalar number J may represent the mean value of the
      square of the fluctuations ({\em i.e.}
      $\overline{\varphi^\prime\varphi^\prime}$) of a ``user'' scalar K
      (called $\varphi$). This can be made either {\em via} the
      interface or by indicating ISCAVR(J)=K\index{ISCAVR} in
      \texttt{usini1} (if the scalar in question is not a ``user''
      scalar, the selection is made automatically). For instance, if J
      and K are ``user'' scalars, the variable $\varphi$ corresponding
      to K is the variable number ISCA(K)=ISCA(ISCAVR(J)), and its value
      in the cell IEL is \\ 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 ISCA(J) and its value in the cell IEL is
      RTP(IEL,ISCA(J)).  
\end{list} 

\bigskip

\underline{Concerning PROPCE, PROPFA and PROPFB} 

The indexes referring  to the different properties stored in the generic
arrays are given respectively by the following integer arrays:

\variab{IPPROC}{IPPROC(NPROMX)}{IA}{Rank I in PROPCE(.,I) of the
properties defined at the cell centres} 

\variab{IPPROF}{IPPROF(NPROMX)}{IA}{Rank I in PROPFA(.,I) of the
properties defined at the internal faces}

\variab{IPPROB}{IPPROB(NPROMX)}{IA}{Rank I in PROPFB(.,I) of the
properties defined at the boundary faces}

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
(whose size may be the maximum number of phases, the maximum
number of scalars or the maximum number of variables).

For instance, the number corresponding to the density of the phase
IPHAS is IROM(IPHAS). \\
In the list of the properties defined at the cell centre, the density of
the phase IPHAS is therefore the IPPROC(IROM(IPHAS))$^{\text{th}}$
property: its value at the centre of the cell IEL is given by \\
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 IPHAS is the
IPPROB(IROM(IPHAS)))$^{\text{th}}$ property: its value at the boundary
face is given by \\
PROP{\bf FB}(IEL,IPPRO{\bf B}(IROM(IPHAS)))

The number of each foreseen property is given below:

\variab{IROM}{IROM(NPHSMX)}{IA}{For each phase, property number
corresponding to the density ({\em i.e.} $\rho$ in $kg.m^{-3}$)} 

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

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

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

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

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

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

\variab{ICPA}{ICP(NPHSMX)}{IA}{For each phase,  property number
corresponding to the specific heat, in the 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}

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

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

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

\variab{IESTIM}{IESTIM(NESTMX,NPHSMX)}{IA}{For each phase, property
number for the NESTMX error estimators of Navier-Stokes. These are
currently IESTIM(IESPRE\index{IESPRE},IPHAS),
IESTIM(IESDER\index{IESDER},IPHAS), IESTIM(IESCOR\index{IESCOR},IPHAS),
IESTIM(IESTOT\index{IESTOT},IPHAS)}

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

\variab{IFLUAA}{IFLUAA(NVARMX)}{IA}{Property number corresponding to the
convective flow associated with each variable ({\em i.e.} for each face
with the surface $S$, $\rho \vect{u} \,.\,\vect{S}$ in $kg.s^{-1}$) at
the previous time step, in the case of a second-order extrapolation in time}

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

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

\variab{ISMAGO}{ISMAGO(NPHSMX)}{IA}{For each phase, property number
corresponding to the ``constant'' $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} 

\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 diminish the necessary memory, these
properties are stored in a simple real number rather than in a real
array whose size would be the number of cells.
\begin{list}{$\bullet$}{}
\item It is the case for the specific heat $C_p$. 
\begin{list}{-}{}
\item If $C_p$ is constant in the phase IPHAS, it can be specified in 
	the interface or by indicating ICP(IPHAS)=0 in \texttt{usini1},
	and the property will be stored in the real number CP0(IPHAS).
\item If $C_p$ is variable, it can be specified in the interface or by
      indicating ICP(IPHAS)=1 in \texttt{usini1}. The code will then
      modify this value to make ICP(IPHAS) refer to the effective
      property number corresponding to the specific heat of the phase
      IPHAS, in a way which is transparent for the user. For each cell
      IEL, the value of $C_p$ is then given in \texttt{usphyv} and
      stored in the array PROPCE(IEL,IPPROC(ICP(IPHAS))). 
\end{list}
\item It is the same for the diffusivity $K$ of each scalar ISCAL. 
\begin{list}{-}{} 
\item If $K$ is constant, it can be specified in the interface or by
	indicating IVISLS(ISCAL)=0 in \texttt{usini1}, and the property
	will be stored in the real number VISLS0(ISCAL).
\item If $K$ is variable, it can be specified in the interface or by
      indicating  IVISLS(ISCAL)=1 in \texttt{usini1}. The code will then
      modify this value to make IVISLS(ISCAL) refer to the effective
      property number corresponding to the diffusivity of the scalar
      ISCAL, in a way which is transparent for the user. For each cell
      IEL, the value of $K$ is then given in \texttt{usphyv} and stored
      in the array PROPCE(IEL,IPPROC(IVISLS(ISCAL))). 
\end{list}  
\end{list}  


\bigskip

\variab{ICMOME}{ICMOME(NBMOMX)}{IA}{Property number corresponding to
every average defined by the user. In fact it is not really a
time-average, but a cumulation over time (the division by the cumulated
duration is done just before the results are written)}

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

\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-average
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 IMOM, it is the
real number DTCMOM(-IDTMOM(IMOM)). \\
When this cumulated duration can vary in space (for instance in the case of a
spatially variable time step), it must be stored in a array whose size is
the number of cells, which may be accessed to in PROPCE. It must be
noticed that the cumulated duration associated with the calculation of 
the average IMOM is variable in space if IDTMOM(IMOM) is strictly
positive. The number of the associated property in PROPCE is then
ICDTMO(IDTMOM(IMOM)). For instance, for the average IMOM, the
cumulated duration in the cell IEL will be
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-average in a particular case (printing of extrem
values, writing of the results).

\bigskip

The 2 variables, HBORD and TBORD should be noted as they are relatively local
(in the treatment of boundary conditions) and are used only by developers.

\variab{HBORD}{HBORD(NFABOR)}{RA}{Array of the coefficients of exchange of 
temperature (or enthalpy) at the boundary faces (must set ISVHB=1\index{ISVHB}
 in \texttt{tridim}, or else the array could crash. Used in coupling with \syrthes.}

\variab{TBORD}{TBORD(NFABOR)}{RA}{Temperature (or enthalpy) array of the boundary
 faces (must set ISVTB=ISCAL\index{ISVTB} (number of the scalar representing temperature
 or enthalpy) in \texttt{tridim}, or else the array could crash).
 Used in coupling with \syrthes.}   



%Les deux variables HBORD et TBORD peuvent \^etre not\'ees, 
%bien qu'elles soient relativement locales (traitement des conditions aux
%limites) et utiles aux d\'eveloppeurs uniquement.   

%\variab{HBORD}{HBORD(NFABOR)}{RA}{Tableau du coefficient d'\'echange de la
%temp\'erature  (ou de l'enthalpie) sur les faces de bord (n\'ecessite d'avoir
%pos\'e ISVHB=1\index{ISVHB} dans \texttt{tridim}, sinon on risque des \'ecrasements de
%tableaux). Utilis\'e pour 
%le couplage avec \syrthes. Le tableau est de taille NFABOR bien que l'utilit\'e
%de la variable soit limit\'ee aux faces de paroi}

%\variab{TBORD}{TBORD(NFABOR)}{RA}{Tableau de la temp\'erature (ou de
%l'enthalpie) sur les faces de bord (n\'ecessite d'avoir
%pos\'e ISVTB=ISCAL\index{ISVTB} (num\'ero du scalaire repr\'esentant la temp\'erature ou
%l'enthalpie) dans \texttt{tridim}, sinon on risque des \'ecrasements de 
%tableaux). Utilis\'e pour le couplage avec \syrthes. 
%Le tableau est de taille NFABOR bien que l'utilit\'e
%de la variable soit limit\'ee aux faces de paroi}  


%==================================
%\subsubsection{Variables des m\'ethodes num\'eriques}
\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 box 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 IVAR
(1$\leqslant$IVAR$\leqslant$NVAR$\leqslant$ NVARMX), rank in COEFA and
COEFB of the boundary conditions. See note 2}

\variab{ICOEF}{ICOEF}{I}{Rank in ICLRTP of the rank in COEFA and COEFB
of the ``standard'' boundary conditions. See note 2}

\variab{ICOEFF}{ICOEFF}{I}{Rank in ICLRTP of the rank in COEFA and 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 IA of the first
element of the section allowing to mark out the ``wall'' (ITYPFB=IPAROI)
or ``symmetry'' (ITYPFB=ISYMET) boundary faces in order to prevent the
mass flow (these faces are impermeable). For instance, for the phase
IPHAS, if the face IFAC is a wall or symmetry face, IA(IISMPH+IFAC-1)=0 (with
IISMPH=IISYMP+NFABOR*(IPHAS-1)).\\ 
Otherwise IA(IISYMP+IFAC-1)=1. \\
In some subroutines, an array called ISYMPA(NFABOR)\index{ISYMPA} allows
to simplify the coding with ISYMPA(IFAC)=IA(IISMPH+IFAC-1)}

\variab{IITRIF}{IITRIF}{I}{In IA, pointer to ITRIFB} 

\variab{IITYPF}{IITYPF}{I}{In IA, pointer to ITYPFB} 

\variab{ITRIFB}{ITRIFB(NFABOR,NPHAS)}{IA}{Indirection array allowing to
sort the boundary faces according to their boundary condition type ITYPFB}

\variab{ITYPFB}{ITYPFB(NFABOR,NPHAS)}{IA}{Boundary condition type at the
boundary face IFAC for the phase IPHAS (see user subroutine
\texttt{usclim})} 

\variab{IUETBO}{IUETBO}{I}{In RA, pointer to 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 IA which
 marks out the number of the wall face(type ITYPFB=IPAROI) which is closest
 to the centre 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 ICDPAR=2. The number of the wall
face (for the phase IPHAS) which is the closest to the centre of the
cell IEL is therefore IA(IIFAPA(IPHAS)+IEL-1). This calculation method
is not compatible with parallelism and periodicity}

\variab{IDIPAR}{IDIPAR}{I}{For each phase, pointer in RA to the section
allowing to mark out the distance between the centre 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 ICDPAR=1. The distance between the centre of the cell IEL and the
closest wall is therefore  RA(IDIPAR+IEL-1)}

\variab{IYPPAR}{IYPPAR}{I}{For each phase, pointer in 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 ICDPAR=1. The adimensional distance $y^+$
between the centre of the cell IEL and the closest wall is therefore
RA(IYPPAR+IEL-1)} 

\minititre{Pressure drops}

\variab{IICEPD}{IICEPD(NPHSMX)}{IA}{For each phase IPHAS, pointer in IA to \\
ICEPDC(NCEPDC(IPHAS)), array allowing to mark out the index-numbers of the \\
NCEPDC(IPHAS) cells in which a pressure drop is imposed. \\
The number of these cells is therefore given by ICEPDC(II)=IA(IICEPD(IPHAS)+II-1), with 1$\leqslant$II$\leqslant$NCEPDC(IPHAS). See the user subroutine
\texttt{uskpdc}} 

\variab{ICEPDC}{ICEPDC(NCEPDC(IPHAS))}{IA}{Number of the NCEPDC(IPHAS)
cells in which a pressure drop is imposed. See IICEPD and the user
subroutine \texttt{uskpdc}} 

\variab{ICKUPD}{ICKUPD(NPHSMX)}{IA}{For each phase IPHAS, pointer in RA to \\
CKUPDC(NCEPDC(IPHAS),NCKPDC(IPHAS)), array allowing to mark out the\\
NCKPDC(IPHAS) coefficients of the pressure drop tensor of the
NCEPDC(IPHAS) cells in which a pressure drop is imposed. See the user
subroutine \texttt{uskpdc}}

\variab{CKUPDC}{CKUPDC(NCEPDC(IPHAS),NCKPDC(IPHAS))}{RA}{Value of the
NCKPDC(IPHAS) coefficients of the pressure drop tensor of the
NCEPDC(IPHAS) cells in which a pressure drop is imposed. See 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}}

\variab{NCKPDC}{NCKPDC(NPHSMX)}{IA}{For each phase, type of the pressure
drop tensor (NCKPDC=3: diagonal, NCKPDC=6: non-diagonal). See the user
subroutine \texttt{uskpdc}} 


\minititre{Mass sources}

\variab{IICESM}{IICESM(NPHSMX)}{IA}{For each phase IPHAS, pointer in IA
to \\ ICETSM(NCETSM(IPHAS), array allowing to mark out the numbers of the \\
NCETSM(IPHAS) cells in which a source of mass is imposed. The number of
these cells is therefore given by ICETSM(II)=IA(IICESM(IPHAS)+II-1), with
1$\leqslant$II$\leqslant$NCETSM(IPHAS). See the user subroutine
\texttt{ustsma}} 

\variab{IITPSM}{IITPSM(NPHSMX)}{IA}{For each phase IPHAS, pointer in IA
to ITYPSM (type of mass source for each variable). See ITYPSM and the
user subroutine \texttt{ustsma}}

\variab{ICETSM}{ICETSM(NCETSM(IPHAS))}{IA}{Number of the NCETSM(IPHAS)
cells in which a mass source term is imposed. See IICESM and the user
subroutine \texttt{ustsma}}

\variab{ISMACE}{ISMACE(NPHSMX)}{IA}{For each phase IPHAS, pointer in RA
to SMACEL (mass source term and if necessary injection value for every
variable apart from pressure). See 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 IA, pointer to IFPT1D(NFPT1D), array allowing to
mark out the numbers of the NFPT1D boundary faces which are coupled with
a wall 1D thermal module. The number of these boundary faces is
therefore given by IFPT1D(II)=IA(IIFPT1+II-1), with 
1$\leqslant$II$\leqslant$NFPT1D. See the user subroutine \texttt{uspt1d}}

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

\variab{IEPPT1}{IEPPT1}{I}{In IA, pointer to EPPT1D(NFPT1D), array
giving the thickness of the 1D wall for the NFPT1D boundary faces which
are coupled with a wall 1D thermal module. The wall thickness for these
boundary faces is therefore given by EPPT1D(II)=IA(IEPPT1+II-1), with
1$\leqslant$II$\leqslant$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 IPHAS, pointer in RA to
the section storing the square of the norm of the deformation
rate tensor. In the cell IEL, for the phase IPHAS, $S^2=2S_{ij}S_{ij}$
is therefore given by RA(IS2KW(IPHAS)+IEL-1). This array is defined only
when the phase IPHASE is treated with the SST $k-\omega$ turbulence model}

\variab{IDVUKW}{IDVUKW(NPHSMX)}{IA}{For each phase IPHAS, pointer in RA
to the section storing the divergence of the velocity. In the
cell IEL, for the phase IPHAS, $div(\vect{u})$ is therefore given by
RA(IDVUKW(IPHAS)+IEL-1). This array is defined only when the phase
IPHASE 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 NGRMAX)}

\variab{IA}{IA(LONGIA)}{IA}{Integer work array}

\variab{RA}{RA(LONGRA)}{RA}{Real work array}


\minititre{Note 1: families and properties}
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 colour.
When the mesh is created using I-DEAS, boundary faces and volume
      elements may be given colours. When it is created using SIMAIL, the
      colours of boundary faces are called ``references'', and the colours
      of volume elements are called ``subdomains''.
\item groups.
For instance, in I-DEAS, mesh entities may be gathered in ``groups''
      and manipulated together. In \CS, every mesh entity belonging to
      a group is then given a group number.
\end{list}
From \CS 's point of view, all the references to mesh entities (boundary faces
and volume elements) correspond to a number (colour number or group
number) associated with the entity. An entity may have several
references (for instance, one entity may have one colour 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 colour) 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 colour (for example using SIMAIL). The family of the boundary
face IFAC is IFML=IFMFBR(IFAC). The first (and only) property of this
family is the colour ICOUL, obtained for the face IFAC with
ICOUL=IPRFML(IFML,1). In order to know the property number corresponding
to a group, the user may refer to the listing of the Preprocessor, or use
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}).

\minititre{Note 2: 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 centre of the adjacent cell on the straight line
perpendicular to the boundary face and crossing its centre:
$\phi_f=A_{\phi,f}+B_{\phi,f}\phi_{I'}$.  \\ 
For a face IFAC, the pair of coefficients $A_{\phi,f},B_{\phi,f}$ is
stored in COEFA(IFAC,ICLVAR) and
COEFB(IFAC,ICLVAR), where the integer ICLVAR=ICLRTP(IVAR,IJCL)
determines the rank in COEFA and COEFB of the set of boundary conditions
of the variable IVAR. \\
The second index of the array ICLRTP allows to have several sets of
boundary conditions for each variable. The ``standard'' boundary
conditions are determined by IJCL=ICOEF, where 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 IJCL=ICOEFF. \\
In practice, for a variable IVAR whose value $\phi_{I'}$ in a
boundary cell is known, the value at the corresponding boundary face
IFAC is: \\ 
\mbox{$\phi_f$=COEFA(IFAC,ICLVAR)+COEFB(IFAC,ICLVAR) $\phi_{I'}$} 
with ICLVAR=ICLRTP(IVAR,ICOEF) 


%==================================
%\subsubsection{Tableaux utilisateurs}
\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{useevo}).

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

%==================================
%\subsubsection{Tableaux d\'eveloppeurs}
\subsection{Developer arrays}
%==================================
The code allows to define two developer arrays (similar to the user
arrays ITUSER and RTUSER), one integer array a 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 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}

%==================================
%\subsubsection{Parall\'elisme et p\'eriodicit\'e}
\subsection{Parallelism and periodicity}
%==================================
\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 the MFTT cluster, the launching of a parallel running calculation
      requires to complete the batch cards \texttt{PBS} located in the
      beginning of \texttt{cntl}, and particularly to set the number of
      physical nodes (\texttt{nodes}) and the number of physical
      processors per node (\texttt{ppn}) wanted. Generally, the number of
      used virtual processors is the same as the number of reserved physical
      processors, that is to say:
\texttt{NOMBRE\_DE\_PROCESSEURS}=\texttt{nodes}$\times$\texttt{ppn}.

\item On the C.C.R.T., the launching of a parallel running calculation
      requires to complete the batch cards \texttt{LSF} located in the
      beginning of \texttt{lance\_ccrt}, and particularly to set the
      number of processors (\texttt{\#BSUB -n}) wanted and the limit CPU
      time (\texttt{\#BSUB -c}). The variable
      \texttt{NOMBRE\_DE\_PROCESSEURS} which stands for the number of
      virtual processors used for the calculation must be completed,
      too. In the case of a communication by files between the Preprocessor
      and the Kernel ((\texttt{IFOENV=1}), the number of used virtual
      processors is the same as the number of reserved processors. In
      the case of a communication by MPI (\texttt{IFOENV=2}), a
      supplementary processor must be reserved to run the Preprocessor.

\item Concerning the periodicity, it is enough to complete the option
      \texttt{COMMANDE\_PERIO} of the launch scripts. The transformation
      allowing to pass from a boundary to the other one must be defined
      (the direction does not matter) and the set of periodical faces
      should be (optional but strongly advised) marked out (for instance
      by means of a colour).

\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 couples
      by 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 periodicity is activated by testing the variable IPERIO
      (=1 if the periodicity is activated);
\item that rotation periodicities are present by testing the variable
      IPEROT (number of rotation periodicities);
\item that the calculation is run is a parallel way by testing the
      variable IRANGP (IRANGP is worth -1 in the case of a non-parallel
      calculation and N-1 in the case of a parallel calculation, N 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 neighbouring cells in
      parallel and periodic cases}.\\
When periodicity or parallelism are brought into use, some cells of the
      mesh become physically distant from their neighbours. Concerning
      parallelism, the calculation domain is split and distributed
      between the processors: a cell located at the ``edge'' of a
      given processor may have neighbours on different processors. \\
In the same way, in case of periodicity, the neighbouring cells of cells
      adjacent to a periodic face are generally distant. \\
When data concerning neighbouring 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 neighbouring cells (use of 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 colour 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 frontiers between
      subdomains consist of {\bf internal} faces shared between
      two processors (these are indeed internal faces, even if they are
      located at a ``processor edge''). They should not be counted twice
      (once per processor) during global operations about 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 The writing ; operations that should be made on one
      processor in parallel mode}.\\
In parallel mode, the user must pay attention during the writing of
      pieces of information. The writing of pieces of information in the
      listing can be done simply by using the logic unit NFECRA (each
      processor will write in 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 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}


\begin{figure}[!h]
\centerline{
\includegraphics*[width=17cm]{\repgraphics/halo.\extgraphics}}
\caption{Periodicity and parallelism: exchange structure.}\label{Fig_haluile}
\end{figure}


{\bf Some notes about the periodicity}

Some particular points should be reminded: 
\begin{list}{-}{}
\item periodicity is incompatible with 
  \begin{list}{-}{}
   \item  multigrid algorithm,
   \item  Lagrangian module, 
   \end{list}
\item rotation periodicity is incompatible with 
  \begin{list}{-}{}
  \item semi-transparent radiation, 
  \item reinforced velocity-pressure coupling (IPUCOU=1). 
  \end{list}
\item although it has not been the case so far, eventual problemes might be met
      in the case of rotation periodicity with the $R_{ij}-\varepsilon$
      model. They would come from the way of taking into account the
      orthotrope viscosity (however, this term has usually a low influence).
\end{list} 
%==================================
%\subsubsection[Tableaux g\'eom\'etriques et particulaires li\'ees \`a la
%      mod\'elisation lagrangienne] 
%{Tableaux g\'eom\'etriques et particulaires li\'ees \`a la
%      mod\'elisation lagrangienne} 
\subsection{Geometric and particulate arrays
      related to lagrangian modelling}
%==================================

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 ICOCEL concerning the cells-faces
connectivity (the faces-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 ILPHAS\index{ILPHAS}. The standard value
is ILPHAS = 1.

\minititre{Lagrangian arrays}

\variab{ICOCEL}{ICOCEL(LNDNOD)}{IA}{Cells - internal/boundary faces
connectivity. The numbers of the boundary faces are marked out in 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 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 NVP:
\begin{list}{$\rightarrow$}{}
\item JMP: particle mass
\item JDP: particle diameter
\item JXP, JYP, JZP: particle coordinates
\item JUP, JVP, JWP: particle velocity components
\item JUF, JVF, JWF: locally undisturbed fluid flow velocity components
\item JTP, JTF: particle and locally undisturbed fluid flow temperature
      (\degresC) 
\item JCP: particle specific heat
\item JHP: coal particle temperature (\degresC)
\item JMCH: mass of reactive coal of the coal particle
\item JMCK: mass of coke of the coal particle
\item 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 JISOR: Number of the current cell containing the particle; this
      number is reactualised during the trajectography step
\item 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 JRTSP: particle residence time
\item JRPOI: particle statistic weight
\item JRDCK: coal particle shrinking core diameter
\item JRD0P: coal particle initial diameter
\item 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, 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, ETTP is updated with VITPAR}

\variab{VITFLU}{VITFLU(NBPMAX,3)}{RA}{At the beginning of the
trajectography, 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, ETTP is updated with 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 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 ILVX,ILVY,ILVZ: mean dispersed phase velocity
\item ILVX2,ILVY2,ILVZ2: dispersed phase velocity standard deviation
\item ILFV: dispersed phase volumetric concentration
\item ILPD: sum of the statistical weights
\item ILTP: dispersed phase temperature (\degresC)
\item ILDP: dispersed phase mean diameter
\item ILMP: dispersed phase mean mass
\item ILHP: temperature of the coal particle cloud (\degresC)
\item ILMCH: mass of reactive coal of the coal particle cloud
\item ILMCK: mass of coke of the coal particle cloud
\item ILMDK: shrinking core diameter of the coal particle cloud
\item 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 INBR: number of particle/boundary interactions
\item IFLM: particle mass flow at the boundary faces
\item IANG: mean interaction angle with the boundary faces (see example
      in \texttt{uslabo}) 
\item IVIT: mean interaction velocity with the boundary faces
\item IENC: mass of coal deposit at the walls
\item 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 ITSVX, ITSVY, ITSVZ: explicit source terms for the continuous
      phase velocity
\item ITSLI: implicit source term for the continuous phase velocity and for the
      turbulent energy if the $k-\varepsilon$ model is used
\item 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 ITSR11,... 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 ITSMAS: mass source term
\item ITSTE, ITSTI: explicit and implicit thermal source terms for the
      thermal scalar of the continuous phase 
\item ITSMV1(ICHA), ITSMV2(ICHA): source terms respectively for the
      light and heavy volatile matters
\item ITSCO: source term for the carbon released during
      heterogeneous combustion
\item ITSF: source term for the air variance (not used at the
      present time)
\end{list}}

\variab{CROULE}{CROULE(NCELET)}{TR}{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{SUITE*} contains:
\begin{list}{-}{}
\item \texttt{suiava}: main restart file,
\item \texttt{suiavx}: auxiliary restart file (see ILEAUX\index{ILEAUX}, 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 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 the 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 ICDPAR\index{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 IENTAT, IENTCP, TIMPAT, X20 (in case of coupling
with the lagrangian module, IENCP and X20 are not saved),
\item for the electric module: the tuned potential difference DPOT\index{DPOT}
and, for the electric arc module, the tuning coefficient COEJOU\index{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).

When reading \texttt{suiava}, \texttt{suiavx}, \texttt{rayava},
\texttt{lagava}, \texttt{lasava} or \texttt{t1dava}, the file format (binary or
ASCII) is automatically determined by the code. When writing these files, the
format can be specified by the user (see IFOAVA\index{IFOAVA}, IFOAVX\index{IFOAVX},
IFOAVR\index{IFOAVR}, IFOAVL\index{IFOAVL}, IFOVLS\index{IFOVLS} and
IFOVT1\index{IFOVT1}). The file \texttt{vorava} has a different structure from
the other ones and is always in ASCII. Therefore there is no variable to specify
its format.

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{listenv} 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 interdace
 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{USERS} directory by the
 case preparer \texttt{cree\_sat}. 
 


%==================================
%\subsection[Initialisation des principaux mots cl\'es : \texttt{usini1}]
%{Initialisation des principaux mots cl\'es : \textmd{\texttt{usini1}}}
\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.F} 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{FORT/USERS/base}; in this case, understanding
 of the comments is needed to add the key words in the appropriate subroutine (the most
 widely used is IPHAS, it will assure that the value has been well defined ). 
The modifiable parameters in each of the subroutines of \texttt{usini1.F} are:

\begin{list}{$\bullet$}{}
\item \texttt{usipph}: ITURB and ICP (don't modify these parameters anywhere else)
\item \texttt{usinsc}: NSCAUS (don't modify these parameters anywhere else)
\item \texttt{usipsc}: ISCAVR and IVISLS (don't modify these parameters anywhere else)
\item \texttt{usipgl}: IDTVAR, IPUCOU, 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 treatment display parameters (periodicity, variable names,
 position of probes,...)
\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 NSCAUS user scalars, representing
 the mean square fluctuations of another whilst informing the ISCAVR 
array (warning, this was not the case in version 1.0). For
the other scalars, ISCAVR does not need to be completed (by default,
ISCAVR(II)$\leqslant$0). For instance, if the scalar JJ represents the
average of the square of the fluctuations of the scalar KK, the user
must indicate ISCAVR(JJ)=KK
(1$\leqslant$KK$\leqslant$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{cree\_sat} comments automatically all the
example lines of \texttt{usini1} with a code \texttt{Cex}. The user
needs then only to uncomment the lines which are useful in his
case. This function of 
\texttt{cree\_sat} can be inactivated with
the option \texttt{-noihm} (useful if the user knows that he will not
use the interface).

%==================================
%\subsection[Gestion des conditions aux limites : \texttt{usclim}]
%{Gestion des conditions aux limites : \textmd{\texttt{usclim}}}
\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 a loop on the boundary
faces. A sequence of \texttt{IF ... ELSE IF ... ENDIF} allows to
differentiate the boundary faces according to their colour (or, more
generally, the properties IPRFML of the family IFMFBR to which the face
belongs). If needed, disposal geometric and
physical variables are also available to the user, these allow him to differentiate the boundary
faces using other criterions.

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

From the user point of view, the boundary conditions are totally
determined by three arrays\footnote{except with lagrangien}~: ITYPFB(NFABOR,NPHAS)\index{ITYPFB},
ICODCL(NFABOR,NVAR)\index{ICODCL} and RCODCL(NFABOR,NVAR,3)\index{RCODCL}. 
\begin{list}{-}{}
\item ITYPFB(IFAC,IPHAS) defines the type of the face IFAC (input, wall
      ...) for the phase IPHAS.
\item ICODCL(IFAC,IVAR) defines the type of boundary
      condition for the variable IVAR at the face IFAC (Dirichlet, flow ...).
\item RCODCL(IFAC,IVAR,.) gives the numerical values associated with the
      type of boundary condition (value of the Dirichlet, of the flow ...).
\end{list}

In the case of standard boundary conditions (see
\S\ref{prg_clstandard}), it is enough to complete ITYPFB(IFAC,IPHAS) and
some boxes of the array RCODCL, the array ICODCL and most of the boxes
of RCODCL are completed automatically. For non-standard boundary
conditions (see \S\ref{prg_clnonstandard}), the arrays ICODCL and RCODCL
must be totally completed.

%==================================
%\subsubsection{Codage des conditions aux limites standards}
\subsubsection{Coding of standard boundary conditions}
%==================================
\label{prg_clstandard}%
The standard values taken by the indicator ITYPFB are: IENTRE\index{IENTRE}, 
IPAROI\index{IPAROI}, ISYMET\index{ISYMET}, ISOR09\index{ISOR09},
ISOR10\index{ISOR10} and IINDEF\index{IINDEF}.

\begin{list}{$\bullet$}{}
\item If ITYPFB=IENTRE: inlet face.

\begin{list}{$\rightarrow$}{}
\item Zero flow condition for pressure and Dirichlet condition for all
      other variables. The value of the Dirichlet must be given in
      RCODCL(IFAC,IVAR,1) for every value of IVAR, apart from
      IVAR=IPR(IPHAS). The other boxes of RCODCL and ICODCL are completed automatically.
\end{list}

\item If ITYPFB=IPAROI: 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 RCODCL(IFAC,IVAR,1) (IVAR being IU(IPHAS), IV(IPHAS) or
      IW(IPHAS)). The initial value of 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}ICODCL(IFAC,IVAR)=5\\
\hspace*{1cm}RCODCL(IFAC,IVAR,1)=imposed value\\
\item Imposed flow at the wall. The user must write\\
\hspace*{1cm}ICODCL(IFAC,IVAR)=3\\
\hspace*{1cm}RCODCL(IFAC,IVAR,3)=flow imposed value (for the flow
      definition according to the variable, the user may refer to the
      case ICODCL=3 of the paragraph \ref{prg_clnonstandard}).
\item If the user does not complete these arrays, the default condition
      is zero flow. 
\end{list}
\end{list}

\item If ITYPFB=ISYMET: symmetry face (or wall without friction)
\begin{list}{$\rightarrow$}{}
\item Nothing to write in ICODCL and  RCODCL.
\end{list}

\item If ITYPFB=ISOR09: ''zero flow'' outlet face 
\begin{list}{$\rightarrow$}{}
\item If the mass flow is going out, zero flow condition for the scalars
      (apart from pressure) and the velocity.
\item If the mass flow is coming in, zero flow condition for the scalars
      (apart from pressure) and the value zero is imposed to the
      velocity at the face (but not to the mass flow).
\item In both cases the boundary condition type for pressure is a
      Dirichlet, 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 ISOR09 met(the fixed reference is always linked to just 1 face, even if there are several exits).
\item Nothing to write in ICODCL or RCODCL.
\end{list}

\item If ITYPFB=ISOR10: ``entering Dirichlet'' outlet face
\begin{list}{$\rightarrow$}{}
\item If the mass flow is going out, zero flow condition for the scalars
      (apart from pressure) and the velocity.
\item If the mass flow is coming in, Dirichlet condition for the scalars
      and the value zero is imposed to the velocity at the face (but not
      to the mass flow). 
\item In both cases, the boundary condition type for pressure is a
      Dirichlet, 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 ISOR09 met. The pressure drop is always linked
 to just 1 face, even is there are several exits. 
\item  RCODCL(IFAC,IVAR,1) must be completed to give the value of the
      Dirichlet for every scalar apart from pressure. In the case of the
      $R_{ij}-\varepsilon$ model, the value zero will be given to the
      extra-diagonal terms of the stress tensor.
\end{list}


\item Si ITYPFB=IINDEF: non-defined type face (non-standard case)
\begin{list}{$\rightarrow$}{}
\item The coding is done by completing every array RCODCL and ICODCL
      (see \S\ref{prg_clnonstandard}). 
\end{list}
\end{list}

\minititre{Notes}
$\bullet\ $ Whatever the value of the indicator ITYPFB(IFAC,IPHAS), if
the array 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 IVAR at the face IFAC, but will take into
account the values of ICODCL and 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.8D0}\\
(\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
ITYPFB(IFAC,IPHAS)=$N$. The value of $N$ must be between 1 and
NTYPMX\index{NTYPMX} (maximum number of boundary face types), and of
course different from the values IENTRE, IPAROI, ISYMET, ISOR09, ISOR10
and IINDEF (the value of these variables is given in the file
\texttt{paramx.h}). This allows to isolate easily some boundary faces,
in order to calculate balances.

%==================================
%\subsubsection{Codage des condition limites non standards}
\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 ITYPFB, ICODCL and
RCODCL. ITYPFB(IFAC,IPHAS) is then worth IINDEF or another value defined
by the user (see note in the end of paragraph \ref{prg_clstandard}). The
arrays ICODCL and RCODCL must be completed as follows:

\begin{list}{$\bullet$}{}
\item If ICODCL(IFAC,IVAR)=1: Dirichlet condition at the face IFAC for
      the variable IVAR.

\begin{list}{$\rightarrow$}{}
\item RCODCL(IFAC,IVAR,1) is the value of the variable IVAR at the face IFAC.

\item RCODCL(IFAC,IVAR,2) is the value of the exchange coefficient
      between the outside and the fluid for the variable IVAR. An
      infinite value (\texttt{RCODCL(IFAC,IVAR,2)=RINFIN}) indicates a
      perfect transfer between the outside and the fluid (default case).

\item RCODCL(IFAC,IVAR,3) is not used.

\item RCODCL(IFAC,IVAR,1) is expressed in the unit of the variable
      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 RCODCL(IFAC,IVAR,2) is expressed in the following unit (defined so
      that by multiplying the exchange coefficient and the variable, the
      obtained flow has the same unit as the flow defined below for 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 ICODCL(IFAC,IVAR)=3: flow condition at the face IFAC for the
      variable IVAR. 

\begin{list}{$\rightarrow$}{}
\item RCODCL(IFAC,IVAR,1) and RCODCL(IFAC,IVAR,2) are not used.

\item RCODCL(IFAC,IVAR,3) is the flow value of IVAR at the wall. This
      flow 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 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
      flow condition type is generally used).\\

\item If ICODCL(IFAC,IVAR)=5: friction condition, for the 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 (RCODCL(IFAC,IU(IPHAS),1),
      RCODCL(IFAC,IV(IPHAS),1), and 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 ICODCL=5 is similar to
      ICODCL=1, but with a wall exchange coefficient calculated from a
      theoretical law. The values of RCODCL(IFAC,IVAR,1) and
      RCODCL(IFAC,IVAR,2) must therefore be specified: see \cite{gest02}.
\end{list}

\item If 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 flow 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).\\
RCODCL is not used.

\item If ICODCL(IFAC,IVAR)=10: free outlet condition for the other
      variables. This condition can be applied to every variable apart
      from the velocity components and the pressure.\\
If the mass flow at the face is going out, this condition is equivalent
      to a zero flow condition.\\
If the mass flow at the face is coming in, this condition is equivalent
      to a Dirichlet condition. The array RCODCL(IFAC,IVAR,1) must
      therefore be completed in order to set the value of this Dirichlet.

\end{list}

\minititre{Note}
$\bullet\ $A standard ISOR09 outlet face amounts to a Dirichlet condition
(ICODCL=1) for the pressure, a free outlet condition (ICODCL=9) for the
velocity and a zero flow condition (ICODCL=3) for the other variables.\\
$\bullet\ $A standard ISOR10 outlet face amounts to a Dirichlet condition
(ICODCL=1) for the pressure, a free outlet condition (ICODCL=9) for the
velocity and a free outlet condition (ICODCL=10) for the other variables.

%==================================
%\subsubsection{V\'erification des conditions aux limites}
\subsubsection{Checking of the boundary conditions}
%==================================

The code checks itself 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 (ICODCL=4), the conditions for $R_{ij}$ must belong to
the ``symmetry'' type (ICODCL=4), and vice versa.\\
$\bullet\ $If the boundary conditions for the velocity belong to the
``friction'' type (ICODCL=5), 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.

%==================================
%\subsubsection{Tri des faces de bord}
\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 IPHAS: ITRIFB(NFABOR,IPHAS)\index{ITRIFB}.\\
IFAC=ITRIFB(n,IPHAS) is the number of the n$^{\text{th}}$  face of type
1.\\
IFAC=ITRIFB(n+N,IPHAS) is the number of the n$^{\text{th}}$ face de type
2, if there are N faces of type 1.\\
... etc.

Two auxiliary arrays of size NTYPMX are also defined.\\
IDEBTY(ITYP,IPHAS)\index{IDEBTY} is the number of the first box
corresponding to the
faces of type ITYP in the array ITRIFB.\\
IFINTY(ITYP,IPHAS)\index{IFINTY} is the number of the last box
corresponding to the
faces of type ITYP in the array ITRIFB.

Therefore, a number IFAC0 between IDEBTY(ITYP,IPHAS) and
IFINTY(ITYP,IPHAS) corresponds to each face of type
ITYP=ITYPFB(IFAC,IPHAS), so that IFAC=ITRIFB(IFAC0,IPHAS).

If there is no face of type ITYP, the code imposes \\
IFINTY(ITYP,IPHAS)=IDEBTY(ITYP,IPHAS)-1,\\
which allows to bypass, for all the missing 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 inlet 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 of 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(NNENTT\index{NNENT}) and them number of vortex for each inlet (NVORT\index{NVORT}), 
where IENT represents the number of inlets.
\item The 2nd part (IAPPEL=1) defines the boundary faces at which the vortex method
 is applicable. The boundary faces can be represented as colours (ICOUL) or by the
 geometric co-ordinates. The IREPVO\index{IREPVO} array is informed by IENT whic
h 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 FIDCAT and in the final case only 1 initial velocity and
 energy are imposed.):

\begin{list}{*}{}
\item ICAS=1, For the outlet of a rectangluar pipe; 1 boundary condition is defined 
for each side of the rectangle takin ginto account their interaction with the vortex.
\item ICAS=2, For the outllet of a circular pipe; the entry face is considered as a
 wall (as far as interaction with the vortex is concerned)
\item 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 ICAS=4, similar to ICAS=3 except the data file is not used (FIDCAT); 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 DIR1 and DIR2). The 3rd vector is automatically calculated by the code, 
defined as a product of DIR1 and DIR2. DIR1 and DIR2 must be chosen impreitavely to
 give (CEN, DIR1, DIR2) an orthoganol reference of the inlet plane and so DIR3 is
 orientated in the entry domain.If ICAS=2, the position CEN has to be the centre of
 gravity of the rectangle or disc.

The reference points (CEN, DIR1, DIR2, DIR3) wihch define the values of the variable in the FIDCAT file.\\
In the case where  ICAS=4, the vectors DIR1 and
DIR2 are generated by the code.

If ICAS=1, The boundary condtions at the rectangle's edges must be defined. They are defined in 
the array ICLVOR\index{ICLVOR}. ICLVOR(II,IENT) represents the standard boundary conditions at 
the edge II(1$\leqslant$II$\leqslant$4) of the inlet IENT. The code for the boundary conditions
 is as follows:
\begin{list}{*}{}
\item ICLVOR=1 for a wall
\item ICLVOR=2 for symmetry
\item ICLVOR=3 for the periodicity of of transfer (the face corresponding to periodicity will 
automatically be taken as 3)
\end{list}
The 4 edges are numbered relative to the directions DIR1 and DIR2 as shown in figue \ref{Fig_vortex}:

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

%C'est dans le rep\`ere (CEN, DIR1, DIR2, DIR3)  C_\mu \displaystyle \frac{k^{\frac{3}{2}}}{\varepsilon U}$,
%o\`u $C_\mu=0,09$ et $k$, $\varepsilon$ et $U$ que sont d\'efinies les valeurs
%des variables dans le fichier FICDAT\index{FICDAT}.\\
%Dans le cas ICAS=4, les vecteurs DIR1 et DIR2 sont g\'en\'er\'es par le code. 
%
%Si ICAS=1, les conditions aux limites aux fronti\`eres (arêtes) du
%rectangle d'entrée doivent \^etre d\'efinies. Elles sont définies par le tableau
%ICLVOR\index{ICLVOR}. ICLVOR(II,IENT) représente le type de condition à la
%limite pour l'arête II (1$\leqslant$II$\leqslant$4) de l'entrée IENT.
%Le code des conditions aux limites est le suivant:
%\begin{list} {*}{}
%\item ICLVOR=1 pour une paroi
%\item ICLVOR=2 pour une sym\'etrie{\repgraphics/vortex.\extgraphics}}
%\item ICLVOR=3 pour une p\'eriodicit\'e de translation (la face correspondante de
%p\'eriodicit\'e sera automatiquement mise \`a 3) 
%\end{list}
%Les quatre arêtes sont numérotées à partir des directions de DIR1 et DIR2, comme
%indiqué dans la figure \ref{Fig_vortex}.
%\begin{figure}[hp]
%\centerline{
%\includegraphics*[width=8cm]{\repgraphics/vort{\repgraphics/vortex.\extgraphics}}ex.\extgraphics}}
%\caption{Numérotation des arêtes d'une entrée rectangulaire (ICAS=1) traitée par
%la méthode des vortex}\label{Fig_vortex}
%\end{figure{\repgraphics/vortex.\extgraphics}}}

If ICAS=1, the user must define LLX and LLY which give the lengths of the rectangular
 pipe in the directions DIR1 and dir2.\\
If ICAS=2, LLD represents the diameter of the circular pipe.
If ICAS=4, UDEBIT,KDEBIT and 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 parameter not case dependant are defined as follows:
\begin{list}{*}{}
\item ITMPL represents the indicator of the advancement in time of the vortex. If ITMPLI=1, 
the vortex will be regenerated after a fixed time of TMPLIM second (defined as ITMPLI=1).
 If ITMPLI=2, following hte data indicated in FIDCAT 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. 
 
%o\`u $C_\mu=0,09$ et $k$, $\varepsilon$ et $U$  C_\mu \displaystyle \frac{k^{\frac{3}{2}}}{\varepsilon U}$,
%o\`u $C_\mu=0,09$ et $k$, $\varepsilon$ et $U$ turbulent dissipation and the convective velocity in the normal to the wall. 

%Si ICAS=1, l'utilisateur doit définir LLX et LLY qui donnent les longueurs de la
%conduite rectangulaire dans les directions DIR1 et DIR2.
%
%Si ICAS=2, LLD repr\'esente le diam\`etre de la conduite circulaire.
%
%Si ICAS=4, on d\'efinit UDEBIT, KDEBIT et EDEBIT pour chaque entr\'ee,
%ce qui impose respectivement 
%la vitesse d\'ebitante, le niveau d'\'energie turbulente et le niveau de
%dissipation. On pourrait se baser,
%pour obtenir ces grandeurs, sur les corr\'elations introduites dans la routine
%utilisateur \texttt{usclim} pour 
%un \'ecoulement dans une conduite pleinement d\'evelopp\'ee.

%Les param\`etres restants ne d\'ependent pas du cas, on doit d\'efinir ce qui suit :

%\begin{list} {*}{}
%\item ITMPLI\index{ITMPLI} repr\'esente l'indicateur de l'avanc\'ee en temps des
%vortex. Si ITMPLI=1, les vortex
%seront reg\'en\'er\'es après un temps fixe de TMPLIM\index{TMPLIM} secondes (\`a
%d\'efinir si ITMPLI=1). Si ITMPLI=2, suivant les donn\'ees
%fournies dans le fichier FICDAT, les vortex auront une dur\'ee de vie variable \'egale \`a $\displaystyle \frac{\partial U}{\partial y}$ 
% $5 \displaystyle C_\mu \displaystyle \frac{k^{\frac{3}{2}}}{\varepsilon U}$,
%o\`u $C_\mu=0,09$ et $k$, $\varepsilon$ et $U$ repr\'esentent respectivement
%l'\'energie turbulente, la dissipation turbulente et la vitesse convective dans
%la direction normale au plan d'entr\'ee. 

\item XSIGMA represents the support functions used in the vortex method. They are representative
 of the eddy sizes entered in the vortex method. ISIGMA is used to define their size: if ISIGMA=1,nction with the co-ordinates XDAT and YDAT (given in the FIDCAT file). Note that using an indicator III to accelerate the calculations
 XSIGMA will be constant across the inlet face and is defined in \texttt{usvort}, if ISIGMA=2, 
nction with the co-ordinates XDAT and YDAT (given in the FIDCAT file). Note that using an indicator III to accelerate the calculationsXSIGMA 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
 ISIGMA=3, XSIGMA 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 IDELPA gives the vortex displacement method in the 2D inlet plane (the vortex method 
is a langrangian method in which the eddy centres are replaced by a set velocity). If IDELPA=1, 
the velocity displacement referred to by 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 centre 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 IDEPLA=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, FIDCAT, must be defined in the cases of 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 interger
 NDAT. $x$ and $y$ are the co-ordinates in the inlet plane defined by the vectors DIR1 and 
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 , ICAS=1, ICAS=2.
 Where ICAS=3 and 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
 PHIDAT. An example is given at the end of \texttt{usvort} where the user can define the 
interpolation required. In the PHIDAT function, XX and YY are the co-ordinates by which the valu
e of PHIDAT is calculated. XDAT and YDAT are the co-ordinates in the FIDCAT file. VARDAT is the 
value of the PHIDAT function with the co-ordinates XDAT and YDAT (given in the FIDCAT file). Note
 that using an indicator III accelerateas the calculations(the user need not modify or delete).
 The user must also define the parameter ISUIVO wich indicates if the vortex were started at 0
 or if the file must be re-read (FICMVO).

\end{list}

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


%==================================
 %\subsection[Gestion des propri\'et\'es physiques variables : \texttt{usphyv}]
%{Gestion des propri\'et\'es physiques variables : \textmd{\texttt{usphyv}}}
\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}(IROVAR(IPHAS)=1, 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 IPHAS and the
      diffusivity of the scalars ISCAL ($\lambda/C_p$ for the
      temperature) are considered as constant in time and uniform in
      space, with the values CP0(IPHAS) and 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 ICP(IPHAS) in \texttt{usini1},
      and complete for each cell IEL the array PROPCE(IEL,IPCCP) in
      \texttt{usphyv}. Completing the array PROPCE(IEL,IPCCP) while
      ICP(IPHAS)=0 induces array overwriting problems and produces wrong
      results.

\item In the same way, to have variable diffusivities for the scalars
      ISCAL, the user must specify it in the interface or give the value
      1 to IVISLS(ISCAL) in \texttt{usini1}, and complete for each cell
      IEL the array  PROPCE(IEL,IPCVSL) in \texttt{usphyv}. Completing
      PROPCE(IEL,IPCVSL) while 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}: \\
IVISLS(1)=0, IVISLS(2)=1, IVISLS(3)=0 and IVISLS(4)=1. \\
The indicators IVISLS(2) and 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 IVISLS$>$0 is synonymous with variable property}. The
      arrays \mbox{PROPCE(IEL,IPCVSL)} in \texttt{usphyv} must then be
      completed with IPCVSL=IPPROC(IVISLS(2)) and IPCVSL=IPPROC(IVISLS(4)). \\

{\em Note}: The indicators 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 JJ representing the average of the square of the
      fluctuations of a user scalar KK comes directly from the
      diffusivity of this last scalar. In particular, the diffusivity
      of the scalar JJ is variable if the diffusivity of KK is variable.
\end{list}

%==================================
%\subsection[Initialisation non standard des variables : \texttt{usiniv}]
%{Initialisation non standard des variables : \textmd{\texttt{usiniv}}}
\subsection{Non-standard initialisation of the variables:
  \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 SCAMAX or SCAMIN if 0 is outside the acceptable scalar variation
range), and the turbulent variables are estimated from UREF and
ALMAX. \\
For $k$ in $k-\varepsilon$, $R_{ij}-\varepsilon$, v2f or $k-\omega$
model:\\
\texttt{RTP(IEL,IKIPH) = 1.5D0*(0.02D0*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.5D0*CMU/ALMAX(IPHAS)}\\
For $\omega$ in $k-\omega$ model:\\
\texttt{RTP(IEL,IOMGIP) = RTP(IEL,IKIPH)**0.5D0/ALMAX(IPHAS)}\\
For $\varphi$ and $\overline{f}$ in v2f model:\\
\texttt{RTP(IEL,IPHIPH) = 2.D0/3.D0}\\
\texttt{RTP(IEL,IFBIPH) = 0.D0}

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
      (IDTVAR=0), the value of the time step is DTREF, given in the
      parametric file of the interface or \texttt{usini1}, the
      calculation being whether a restart (ISUITE=1) or not (ISUITE=0).
\item In the case of a calculation with non-constant time step
      (IDTVAR=1 or 2) which is not a calculation restart (ISUITE=0), the
      value of 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
      (IDTVAR=1 or 2) which is a restart (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 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
      (IDTVAR=1 or 2) which is a restart (ISUITE=1) of a calculation
      whose time step type was the same (for instance, restart with
      IDTVAR=1 of a calculation run with IDTVAR=1), the time step is
      read from the restart file and the value of 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 (IDTVAR=1
or 2) which is a restart (ISUITE=1) of a calculation in which IDTVAR had
the same value, DTREF does not allow to modify the time step. The user
subroutine \texttt{usiniv} allows to modify the array DT which contains
the value of the time step read from the restart file (array whose size
is NCELET, defined at the cell centres whatever the chosen time step type).

{\em WARNING: to initialise the variables in the framework of a
specific physics module} (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[Gestion non standard des fichiers historiques : \texttt{ushist}]
%{Gestion non standard des fichiers historiques :
%\textmd{\texttt{ushist}}}
\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
      II varies between 1 and the number of probes. The coordinates XX,
      YY and ZZ of each probe are given. The subroutine \texttt{findpt}
      gives then the number ICAPT(II)\index{ICAPT} of the cell centre
      which is the closest to the defined probe.

\item Opening of the writing files (only at the first passage): in the
      version given as example, the program opens a different file for
      all the NVAR variables. FICUSH(J) contains the name of the
      J\raisebox{1ex}{\small th} file and IMPUSH(J) its unit number
      (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 in 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 NCAPT=0} in the interface or
in {\em \texttt{usini1}} to deactivate the automatical 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 FICHIERS\_RESULTATS\_UTILISATEUR in the launch script.

%==================================
%\subsection[Termes sources utilisateur dans Navier-Stokes : \texttt{ustsns}]
%{Termes sources utilisateur dans Navier-Stokes : \textmd{\texttt{ustsns}}}
\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 IPHAS, it is called three times every time
step, once for each velocity component (IVAR is successively worth
IU(IPHAS), IV(IPHAS) and IW(IPHAS)). At each passage, the user must
complete if necessary the arrays CRVIMP and CRVEXP expressing
respectively the implicit and explicit part of the source term. If
 no other source terms apart from IVAR=IU(IPHAS)for example, are require
d, CRVIMP and CRVEXP must be read over and their 2 other components,
 IVAR=IV(IHPAS) and IVAR=IW(IPHAS) must be cancelled. 

{\em WARNING: The decomposition of the soure terms of CVRIMP/CRVEXP is
 different to that of the code ESTET: be careful of reflex working} 

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{CRVIMP}_i=\Omega_iS_{impl,i}$\\
$\text{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{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{gest02} 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{CRVIMP}_i=\Omega_i\frac{dF}{d\varphi}(\varphi_i^{(n)})$\\
$\displaystyle\text{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{CRVIMP}_i=-2K\Omega_i\varphi_i^{(n)}$\\
$\text{CRVEXP}_i=K\Omega_i[\varphi_i^{(n)}]^2$



%==================================
%\subsection[Termes sources utilisateur pour $k$ et $\varepsilon$ :
%\texttt{ustske}] 
%{Termes sources utilisateur pour $k$ et $\varepsilon$ :
%\textmd{\texttt{ustske}}}
\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 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 CRKIMP and
CRKEXP for $k$ and CREIMP and CREEXP for $\varepsilon$. These arrays are
similar to the arrays CRVIMP and 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[Termes sources utilisateur pour $R_{ij}$ et $\varepsilon$ :
%  \texttt{ustsri}] 
%{Termes sources utilisateur pour $R_{ij}$ et $\varepsilon$ :
%\textmd{\texttt{ustsri}}}
\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 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 CRVIMP and CRVEXP for the
variable IVAR (refering successively to IR11(IPHAS), IR22(IPHAS),
IR33(IPHAS), IR12(IPHAS), IR13(IPHAS), IR23(IPHAS) and
IEP(IPHAS)). These arrays are similar to the arrays CRVIMP and CRVEXP
given for the velocity in the user subroutine \texttt{ustsns}. The way
of making implicit the resulting source terms is the same as that
presented in \texttt{ustsns}.

%==================================
%\subsection[Termes sources utilisateur pour $\varphi$ et $\overline{f}$ : \texttt{ustsv2}]
%{Termes sources utilisateur pour $\varphi$ et $\overline{f}$ :\textmd{\texttt{ustsv2}}}
\subsection{User source terms for $\varphi$ and $\overline{f}$:
  \textmd{\texttt{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 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 CRVIMP and
CRVEXP for IVAR refering successively to IPHI(IPHAS) and
IFB(IPHAS). Concerning $\varphi$, these arrays are similar to the arrays
CRVIMP and 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{CRVIMP}_i=\Omega_iS_{impl,i}$\\
$\text{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[Termes sources utilisateur pour $k$ et $\omega$ : \texttt{ustskw}]
%{Termes sources utilisateur pour $k$ et $\omega$ : \textmd{\texttt{ustskw}}}
\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 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 CRKIMP and CRKEXP for the variable $k$ the arrays
CRWIMP and CRWEXP for the variable $\omega$. These arrays are
similar to the arrays CRVIMP and 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}.

%==================================
%\subsection[Termes sources utilisateur pour les scalaires utilisateur : \texttt{ustssc}]
%{Termes sources utilisateur pour les scalaires utilisateur : \textmd{\texttt{ustssc}}}
\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 CRVIMP and CRVEXP
related to each scalar. CVIMP and 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[Gestion des pertes de charge : \texttt{uskpdc}]
%{Gestion des pertes de charge : \textmd{\texttt{uskpdc}}}
\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
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
      IPHAS. This number is called NCEPDP\index{NCEPDP} in
      \texttt{uskpdc} (and corresponds to
      NCEPDC(IPHAS)\index{NCEPDC}). It is used to lay out the arrays
      related to the pressure drops. If there is no pressure drop,
      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 ICEPDP\index{ICEPDP} whose size is
      NCEPDP. \mbox{ICEPDC(IELPDC)} is the number of the
      IELPDC\raisebox{1ex}{\small th} cell containing pressure drops (for
      the current phase). It is specified if the tensor of pressure
      drops will be diagonal (3 elements) or not (6 elements), by means
      of the variable NCKPDP\index{NCKPDP}=NCKPDC(IPHAS), which is worth
      3 or 6.

\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{CKUPDC(NCEPDP,NCKPDP)}\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):: K11, K22, K33 or K11, K22, K33, K12, K13, K23
      (depending on wether NCKPDP is worth 3 or 6). 
\end{list}


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

%==================================
%\subsection[Gestion des sources de masse : \texttt{ustsma}]
%{Gestion des sources de masse : \textmd{\texttt{ustsma}}}
\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 IPHAS. This number is called NCESMP\index{NCESMP} in
      \texttt{ustsma} (and corresponds to
      NCETSM(IPHAS)\index{NCETSM}). It is used to lay out the arrays
      related to the mass sources. If there is no mass source,
      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 ICETSM\index{ICETSM} whose dimension is
      NCESMP. \mbox{ICETSM(IELTSM)} is the number of the
      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{ITYPSM(NCESMP,NVAR)}\index{ITYPSM} and
      \mbox{SMACEL(NCESMP,NVAR)}\index{SMACEL}:\\ 
- ITYPSM(IELTSM,IVAR) is the flow type associated with the variable IVAR
      in the IELSTM\raisebox{1ex}{\small th} cell containing a mass
      source.\\
\hspace*{1cm}ITYPSM=0: $\varphi_i=\varphi^{(n+1)}$ condition\\
\hspace*{1cm}ITYPSM=1: imposed $\varphi_i$ condition\\
\hspace*{1cm}ITYPSM is not used for IVAR=IPR(IPHAS)\\
- SMACEL(IELTSM,IPR(IPHAS)) is the value of the mass source term $\Gamma$, in
$kg.m^{-3}.s^{-1}$.\\
- SMACEL(IELTSM,IVAR), for IVAR different from IPR(IPHAS), is the value
      of $\varphi_i$ for the variable IVAR in the
      IELSTM\raisebox{1ex}{\small th} cell containing a mass source.\\

\minititre{Notes}
$\bullet$ If ITYPSM(IELTSM,IVAR)=0, SMACEL(IELTSM,IVAR) is not used.\\
$\bullet$ If $\Gamma$=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 ITYPSM(IELTSM,IVAR) and 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 envronment 
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
 flow) or a coupling with \syrthes.\\

The use of this code requires that theres is only 1 phase (NPHAS=1) and that
 the thermal scalar is defined as (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 not 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 NFKPT1D. It
 applies dimension to the arrays in the thermal module.  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 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 FILMT1).
\item The 2nd call (initialisation)again concern the wall faces, it completes
 the IFPT1D array of dimension NFPT1D.  \mbox{IFPT1D(IFBT1D)}is the number 
IFBT1D\raisebox{1ex}{\small th} boundary faces coupled with the thermal module
 of a 1D wall. The discretional parameters are then completed for a pseudo
 wall accosiated to each face
\begin{list}{-}{}
\item NPPT1D(NFPT1D)\index{NPPT1D}: number of cells in the 1D mesh associated
 to the pseudo wall.
\item EPPT1D(NFPT1D)\index{EPPT1D}: thickness of the pseudo wall.
\item RGPT1D(NFPT1D)\index{RGPT1D}: geometery of the pseudo wall mesh (refined
 as a fluid if RGT1D is smaller than 1) 
\item TPPT1D(NFPT1D)\index{TPPT1D}: initialisation temperature of the wall 
(uniform in thckness). 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 (FICMT1), TPPT1D is not used.  NPPT1D, IFPT1D,
RGPT1D and EPPT1D are compared to data from the follow-up file and they must 
be identical.

{\em WARNING: The test in IFPT1D implicilty assumes that the array is completed
 in ascending order (i.e IFPT1D(II)$>$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 ICLT1D(NFPT1D)\index{ICLT1D}:Typical boundary condition at the external
 (pseudo) wall: Dirichlet condition (ICLT1D=1) or flow condition (ICLT1D=3)
\item TEPT1D(NFPT1D)\index{TEPT1D}: External temperature of the pseudo wall in the
 Dirichlet case.
\item HEPT1D(NFPT1D)\index{HEPT1D}: External coefficient of transfer in the pseudo
 wall under Dirichlet conditions(en $W.m^{-2}.K^.$).
\item FEPT1D(NFPT1D)\index{NFPT1D}: External heat flow in the pseado wall  under
 the flow conditions(en $W.m^{-2}$,negative value for energy entering the wall)
\item XLMT1D(NFPT1D)\index{XLMT1D}: Conductivity$\lambda$ of the wall uniform 
in thickness, (in $W.m^{-1}.K^{-1}$).
\item RCPT1D(NFPT1D)\index{RCPT1D}: Volumetric heat capapcity $\rho C_p$ of the
wall uniform in thickness in $J.m^{-3}.K^{-1}$)
\item 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
 calcualtion)
\end{list}

\end{list}

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

%==================================
%\subsection[Modification de la viscosit\'e turbulente: \texttt{usvist}]
%{Modification de la viscosit\'e turbulente : \textmd{\texttt{usvist}}}
\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 IPHAS, {\em i.e.} $\mu_t$ in $kg.m^{-1}.s^{-1}$
(this piece of information, at the mesh cell centres, is conveyed by the
variable PROPCE(IEL,IPCVST), with 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 ITURB(IPHAS)).\\
{\em WARNING: The calculation of the turbulent viscosity being a
particularly sensible stage, a wrong use of {\em\texttt{usvist}} may
distort seriously the results.}

%==================================
%\subsection[Modification de la vitesse de frottement : \texttt{usruet}]
%{Modification de la vitesse de frottement : \textmd{\texttt{usruet}}}
\subsection{Modification of the friction velocity: \textmd{\texttt{usruet}}}
%==================================

\noindent
\textit{Subroutine called every time step for every wall face.}

This subroutine is used to modify the calculation of the friction
velocity $u_*$ (variable UET\index{UET}) for each phase. For more
precisions concerning the friction velocity and the wall boundary
conditions, the user may refer to the report \cite{bouckermattei00} and
to the theoretical and computer documentation \cite{gest02} of the
subroutine \texttt{clptur}. To access to this document from a
workstation, use the command \texttt{info\_cs noyau}.
% or refer to \mbox{$_\text{\Large\~~\hspace{-0.2cm}}$\texttt{sc\_doc/saturne.html}}

The subroutine allows in particular to access to the value of $y^+$ at
the wall.

%==================================
%\subsection[Modification de la ``constante'' du modèle LES dynamique: \texttt{ussmag}]
%{Modification de la ``constante'' du modèle LES dynamique: \textmd{\texttt{ussmag}}}
\subsection{Modification of the ``constant'' 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 ``constant'' 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 ``constant'' 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 (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 $CSMAGO$\index{CSMAGO}.

In the case of the dynamic model (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 neighbouring cells (this average uses the extended
neighbourhood 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[Conversion temp\'erature-enthalpie et enthalpie-temp\'erature : \texttt{usthht}]
%{Conversion temp\'erature-enthalpie et enthalpie-temp\'erature : \textmd{\texttt{usthht}}}
\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 de la g\'eom\'etrie du maillage : \texttt{usmodg}]
%{Modification de la g\'eom\'etrie du maillage : \textmd{\texttt{usmodg}}}
\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
characteristics\footnote{The family properties must not be modified:
they have already been used to define the periodic faces.In fact, a face 
defined as periodic in the script cannot be changed at the inlet, even 
if the colour of the inlet face is altered}:
\begin{list}{$\bullet$}{}
\item \mbox{XYZCEN(3,NCELET)} (cell centre coordinates),
\item \mbox{CDGFAC(3,NFAC)} (internal face centre coordinates),
\item \mbox{CDGFBO(3,NFABOR)} (boundary face centre coordinates),
\item \mbox{SURFAC(3,NFAC)} (internal face surface vector components) and
\item \mbox{SURFBO(3,NFABOR)} (boundary face surface vector components).
\end{list}

This subroutine may also be used to test the mesh quality (which is done by
default). But it must be reminded that the Preprocessor, when running in
the ``verification'' mode, allows to get quality criterions which are
more complete and easier to exploit (using EnSight or in the execution
report). For instance, for a mesh ``\texttt{mesh}'' (in \texttt{des},
\texttt{unv} or any other acceptable format), the command to execute is: 
\mbox{\texttt{verifmail mesh.unv}} (this command calls the Preprocessor
with the necessary options).\\

%==================================
%\subsection[Gestion des sorties interm\'ediaires de post-traitement : \texttt{usnpst}]
%{Gestion des sorties interm\'ediaires de post-traitement : \textmd{\texttt{usnpst}}}
\subsection{Management of the post-treatment intermediary outputs: \textmd{\texttt{usnpst}}}
%==================================

\noindent
\textit{Subroutine called every time step(even if the user hasn't moved it to the FORT directroy).}

This subroutine is used to determine when post-treatment outputs will be
generated. By default, it tests if the current time step number (NTCABS) is a
multiple of the chosen output frequency (NTCHR). If it is the case, the
indicator IIPOST turns to 1, which triggers the writing of an
intermediary output. If the frequency is given a negative value, the
test is not done.

For instance, a user who wants to generate post-treatment 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-treatment output is generated after the last time
step, \texttt{usnpst} being used or not.

\newpage
%==================================
%\subsection[Gestion des sorties au format {\em EnSight} par l'enveloppe : \texttt{useevo}]
%{Gestion des sorties au format {\em EnSight} par l'enveloppe : \textmd{\texttt{useevo}}}
\subsection{Management by the Preprocessor of the outputs in {\em EnSight} format: \textmd{\texttt{useevo}}} 
%==================================

\noindent
\textit{Subroutine called at every chronological output.}

This subroutine can be used only when the calculation is made with a
call to the Preprocessor ({\em i.e.} IFOENV=1 or 2). If it is not the case,
refer to \text{usensi}.

This subroutine allows to add N supplementary variables to the output
files in {\em EnSight} format (it is for instance possible to write
automatically $k=\frac{1}{2}(R_{11}+R_{22}+R_{33})$ when the
$R_{ij}-\varepsilon$ model is used). Every time a chronological output
is generated, \texttt{useevo} is first called N times (with the indicator
\mbox{IPASS=0}) to reserve the memory, then called N times again (with
the indicator \mbox{IPASS=1}) to set the value of every supplementary variable.

For each of the two series of N calls, the variable IVARSU, available
among the subroutine arguments, refers to the index-number of the
supplementary variable defined by the user (from 1 to N). IVARSU must
not be modified by the user.

The number N of supplementary variables is determined by the code as
being the value of IVARSU for which the value 0 is given by the user to
the variable IBOUCL (indicating that the loop on the supplementary variables is
coming to an end). 

The syntax to use is presented in the following example:
\begin{tabbing}
\hspace{0.5cm}\=\hspace{0.5cm}\=\hspace{0.5cm}\=\kill\\
\texttt{IF(IVARSU.EQ.1) THEN}$\quad\longleftarrow$ Treatment of the
 first supplementary variable\\
\>\texttt{IF(IPASS.EQ.0) THEN}$\quad\longleftarrow$ Initialisation phase\\ 
\>\>\texttt{IBOUCL = 1}$\quad\longleftarrow$ It is not the last
 variable. There will be a call with IVARSU=2\\ 
\>\>\texttt{IDIMT  = 1}$\quad\longleftarrow$ The variable is a scalar
 (dimension 1)\\
\>\>\texttt{ICHVAR = 1}$\quad\longleftarrow$ The priting is asked\\
\>\>\texttt{WRITE(NAMVAR,'(A8,I4.4)') 'Unit   ',IVARSU}$\quad\longleftarrow$
Name of the variable\\
\>\texttt{ELSE}$\quad\longleftarrow$ Writing phase\\
\>\>\texttt{DO IEL = 1, NCEL}\\
\>\>\>\texttt{VARENS(IEL,1) = 1.D0}$\quad\longleftarrow$ Value of the variable\\
\>\>\texttt{ENDDO}\\
\>\texttt{ENDIF}\\
\texttt{ELSEIF(IVARSU.EQ.2) THEN}$\quad\longleftarrow$ Treatment of the
 second supplementary variable\\
\>\texttt{IF(IPASS.EQ.0) THEN}$\quad\longleftarrow$ Initialisation phase\\ 
\>\>\texttt{IBOUCL = 0}$\quad\longleftarrow$ It is the last
 variable. There will be no call with IVARSU=3\\ 
\>\>\texttt{IDIMT  = 3}$\quad\longleftarrow$ The variable is a vector\\
\>\>\texttt{ICHVAR = 1}$\quad\longleftarrow$ The printing is asked\\
\>\>\texttt{WRITE(NAMVAR,'(A8,I4.4)') 'VectTwo',IVARSU}$\quad\longleftarrow$
Name of the variable\\
\>\texttt{ELSE}$\quad\longleftarrow$ Writing phase\\
\>\>\texttt{DO IEL = 1, NCEL}\\
\>\>\>\texttt{VARENS(IEL,1) = 2.D0}\\
\>\>\>\texttt{VARENS(IEL,2) = 2.D0}$\quad\longleftarrow$ Value of the  variable(here the vector is uniform in its components (2;2;2)\\
\>\>\>\texttt{VARENS(IEL,3) = 2.D0}\\
\>\>\texttt{ENDDO}\\
\>\texttt{ENDIF}\\
\texttt{ENDIF}
\end{tabbing}

To complete the arrays VARENS, all the code main variables are passed as
arguments, especially the array RTP, the geometric parameters,the
physical properties and the user array ITUSER and RTUSER.

(For any value of IVARSU, it is always the same array, VARENS, where the 
variable is placed for posttreatment (the code carries out the treatment 
of the variable between each call to \texttt{useevo})
\newpage
%==================================
%\subsection[Gestion des sorties au format {\em EnSight} hors enveloppe : \texttt{usensi}]
%{Gestion des sorties au format {\em EnSight} hors enveloppe : \textmd{\texttt{usensi}}}
\subsection{Management of the outputs in {\em EnSight} format without
  the Preprocessor: \textmd{\texttt{usensi}} }
%==================================

\noindent
\textit{Subroutine called at every chronogical output.}

This subroutine can be used only when the calculation is made without a
call to the Preprocessor ({\em i.e.} IFOENV=0). If it is not the case,
refer to \text{useevo}.

The functioning and the syntax of this subroutine are absolutely
identical to those of \texttt{useevo}.

%==================================
%\subsection[Gestion des sorties au format {\em Rubens} : \texttt{usrubm}]
%{Gestion des sorties au format {\em Rubens} : \textmd{\texttt{usrubm}}}
\subsection{Management of the outputs in {\em Rubens} format: \textmd{\texttt{usrubm}}}
%==================================

\noindent
\textit{Subroutine called at every chronological output.}

This subroutine gives the possibility to generate chronological outputs
using the {\em Rubens} mesh tool format. The given example manages the
writing of the pressure, the velocity and the first four scalars. All
the variables are however passed as arguments, to allow the user to add
everry variable he wants.

%==================================
%\subsection[D\'efinition de coupes pour les sorties par listes de faces : \texttt{uslfac}]
%{D\'efinition de coupes pour les sorties par listes de faces : \textmd{\texttt{uslfac}}}
\subsection{Definition of sections for outputs in the form of lists of faces: \textmd{\texttt{uslfac}}}
%==================================

\noindent
\textit{Subroutine called at the calculation beginning.}

This subroutine gives the possibility to define sections in the form of
lists of \texttt{NLFAC} internal faces (\texttt{LSTFAC}) and
\texttt{NLFAB} boundary faces (\texttt{LSTFAB}), in order to generate
chronological outputs in {\em EnSight}, {\em MED} or {\em CGNS} format.

The given example proposes to define two sections (\texttt{NBCOUP =
2}). The first one is consituted of internal and boundary faces marked
out by means of the coordinates of their centres. The second one is constituted
of internal faces marked out by means of the colour of their neighbouring
cells and of boundary faces marked out by means of their colour.

It must be noticed that the lists of faces can not be modified during
the calculation (they are set at the calculation beginning).

In order to ease the post-treatment, a distinct name should be given to
each section (\texttt{COUPE = }): this character string will be the name
of the corresponding {\em EnSight} ``part'' and will be used in the eventual
{\em MED} file.

The content of the character string \texttt{CAS = } will be used as a
prefix in the name of the EnSight directory containing the
post-treatment files and in the eventual MED file. If several sections
are requested and the user does not wish to post-treat the data on each
one at the same time step (see \texttt{usvfac}), it
may be useful, in order to ease the post-treatment, to specify a
different value of \texttt{CAS} for each section (for instance
\texttt{CAS=''CAS\_COUPE1''}, \texttt{CAS=''CAS\_COUPE2''}...), so that
a distinct {\em EnSight} directory will be generated for each one. If
\texttt{CAS} is not specified, the post-treatment files are stored with
the usual chronological post-treatment files (it is recommended to
always specify the value of the variable \texttt{CAS}).

The post-treatment format is set by means of the variable \texttt{FORMA
= }. By default, the {\em EnSight} format is generated. Outputs in the
{\em MED} or {\em CGNS} formats may be also requested.

The values to post-treat on the sections are precisely defined in the subroutine \texttt{usvfac}

%==================================
%\subsection[D\'efinition des informations \`a post-traiter sur les coupes : \texttt{usvfac}]
%{D\'efinition des informations \`a post-traiter sur les coupes : \textmd{\texttt{usvfac}}}
\subsection{Definition of the data to post-treat on the sections:
  \textmd{\texttt{usvfac}}}  
%==================================

\noindent
\textit{Subroutine called every time step and for every section.}

For the sections defined in \texttt{uslfac}, the subroutine
\texttt{usvfac} is used to define the instants at which outputs will
be generated and to specify which variables have to be
post-treated. Basically, the communication for the current section is
initialised by calling \texttt{MSGDSC}, which provides the section number,
the time step number and the physical time. For this section, the arrays
of values at internal (\texttt{TRAFAI}) and boundary faces
(\texttt{TRAFAB}) are sent to the Preprocessor by the subroutine
\texttt{MSGVAC}, as are the variable name (\texttt{NAMEVR}), the length
of the character string which contains it (\texttt{LNAME}), the
dimension of the variable (\texttt{IDIMT}=1 for a scalar and =3 for a
vector) and the numbers of the section internal (\texttt{NFAICP}) and
boundary (\texttt{NFABCP}) faces. 

More precisely, the user must first define the pairs (section, time
step) corresponding to expected post-treatment outputs. This is the goal
of the first part of the subroutine: an instruction \texttt{RETURN} is
placed in the beginning of the subroutine according to the section
number \texttt{NUMCOU} and the time step number \texttt{NTCABS}. It is
important to note that the section outputs are independent from the
other post-treatment outputs.In particular, there is no automatically
generated output after the last calculation time step (if an output
after the last time step is wanted, this must then be specified).
 
For each section, the given example proposes then to define the
variables to post-treat. For instance, concerning the section number 1,
the velocity, the pressure and the temperature at the boundary are
generated. Concerning the section number 2, all the usually post-treated
unknowns (according to \texttt{NTCHR} and \texttt{ICHRVR}) are generated.

%==================================
%\subsection[D\'efinition de post traitments et zones de maillage~: \texttt{usdpst}]
%{D\'efinition de post traitements et zones de maillage~: \textmd{\texttt{usdpst}}}
\subsection{Definition of post-treatments and mesh zones:
  \textmd{\texttt{usdpst}}} 
%==================================

\noindent
\textit{Subroutine called at the calculation beginning..}

This subroutine gives the opportunity to define surface or volumetric
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
(only the first one being implemented at the present time).

One or several ``writers'' can be associated with each post-treatment
mesh created. The arguments of the function \texttt{pstcwr} defining a
``writer'' are the followings: 

\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 character number: 32 for {\em MED}, 19 for
	     {\em EnSight}) or modified automatically (blanks or forbidden
	     character will be replaced by '\_') 
       \item \texttt{NOMREP}: name of the writing directory
       \item \texttt{NOMFMT}: choice of the writing format:
        \begin{list}{$\rightarrow$}{}
               \item {\em EnSight Gold} ({\em EnSight} being accepted, too)
               \item {\em MED\_fichier} ({\em MED} being accepted, too)
               \item {\em CGNS}
               \item {\em text} (readable with a text editor, with the
		     only aim of making a diagnosis).
         \end{list}
The case does not matter, 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 recognised by some post-processing tools); such
 faces will therefore appear as ``holes'' 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 recognised by
 some post-processing tools); such elements will therefore appear as ``holes'' 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 recognise 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 recognise 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)
         \end{list}
       \item \texttt{INDMOD}: indicates if the post-treatment meshs
	     (or ``parts'') are:
        \begin{list}{$\rightarrow$}{}
               \item 0 steady (``classic'' 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 a supplementary output format to
the main output format, or to add a supplementary mesh to the default
output, the lists of standard and user meshes and ``writers'' are not
separated. Negative numbers are used to mark out 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-treatment case defined {\em via}
\texttt{usini1} or {\em via} the interface.

The user chooses the numbers corresponding to the post-treatment
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-treatment case (-1), or to ask for outputs concerning the boundary
faces (-2) associated with a user ``writer''.

%Par sécurité, les fréquences de sortie des variables et la possibilité
%de modifier les maillages post sont associées aux ``writers'' plutôt
%qu'aux ``parts''. Ainsi, on évite l'erreur qui consisterait à sortir
%les champs associés à une ``part'' tous les 10 pas de temps et ceux
%associés à une autre ``part'' tous les 200 pas de temps dans un même
%cas EnSight, qui serait alors illisible.

As a precaution, the output frequency and the possibility to modify the
post-treatment meshes are associated with the ``writers'' rather than
with with the ``parts''. This logic avoids unwanted generation of 
incoherent post treatment cases whist protecting from a large surpless.

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-treatment 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 also possible to define an alias of a mesh given later. The same 
definition can be used for a "part" (with duplication  in the memory)
 as for the different output variables with 2 different writer (the
 choice of output variables at the exit is done in the base "part")
 An alias cna be associated to a different writer than that of the principle
 part. The creation of an alias is done in the subroutine \texttt{pstalm}.

Modifiation of a part or it's alias over time is always carried out
 by the most restrictive "writer" to which it's meshes have been asscoiated (essential
 that the structure is broken up in the 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-treatment tools being perturbed by such a case)\footnote{A term will
 probably be added to link the faces with the ``familly'' characteristics, but 
the faces will not be written in the correct way for the supporting formats 
(such as MED 2.2), and will not describe all of their attributes}. If the user
defines lists of faces and cells in the same time, only the entities of
higher dimension (the cells) will be taken into account.

For a better comprehension, the user may refer to the example given in
{\texttt{usdpst}}. We can note that the blanks 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-treat on the defined ``parts'' will be specified
in the subroutine \texttt{usvpst}.  ``

{\em WARNING In the paralllel case,cannot contain any elements of certain processors. 
It will not suffice to only define a "part" if it contains local faces or elements,...
(i.e every part must be defined in all the processors).}

All the post-treatments (apart from the probes) must pass by a mechanism, which 
does not need running through the Preprocessor. \texttt{usensi}, \texttt{useevo}, and the
 couple \texttt{uslfac} / \texttt{usvfac} can therefoe be ignored to the benefit of
 the group ({\texttt{usdpst}, \texttt{usmpst}, \texttt{usvpst}\} (\texttt{usnpst}
continues its role). Now, it is only the {\em Ensight}output where \texttt{IFOENV}
}$> 0$ that are operational,and the polygonals or polyhedral cells are not simplified
 or deleted, these can then be poorly placed in {\em Paraview}, which cannot read the 
{\em Ensight Gold} files containing polyhedrons (or any other tool in {\em VTK} using 
the {\em EnSight} reader of that library)\footnote{where the options{\em discard\_nsided}
 and {\em discard\_nfaced}are concerned}. {\em Ensight} itself is appears more fallible
 during some cases containing polygons or polyhedrons.  Even when it appears in theory
 preferable to post-treat the data in the "true" mesh calcualtions, the old outlet
 method is not erased until it is certain that they won't be needed.


%==================================
%\subsection[Modification de zones de maillage post traiter~: \texttt{usmpst}]
%{Modification de zones de maillag post traiter~: \textmd{\texttt{usmpst}}}
\subsection{Modification of the mesh zones to post-treat:
  \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-treatment mesh).

At first, the corresponding lists contain the previously defined
values. If these lists are modified for a given post-treatment 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 assebmly (if in doubt, let IMODIF=1). 

It can be noticed that the indicator \texttt{ITYPPS} can be used to know
whether the current post-treatment 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, adn that doesn't provide sufficient information)
. If at any instant in 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 dertimine if it will affect the cells or faces\footnote{It is not expressly forbidden to associate with the ``part'' the cells with a certain timestep and the faces with another, but this modification has not been tested}.

The user may refer to the example, in which cells are selected according
to a given criterion: \\
- For a volumetric ``part'', cells for which the velocity exceeds a certain
value. \\
- For a surface ``part'', internal 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 neighbouring a
cell in which the velocity exceeds this value). This surface
post-treatment mesh corresponds therefore to an approximation of a
velocity isosurface.

%==================================
%\subsection[D\'efinition des champs \`a post-traiter : \texttt{usvpst}]
%{D\'efinition des champs \`a post-traiter : \textmd{\texttt{usvpst}}}
\subsection{Definition of the variables to post-treat:
  \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-treat.

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
	     ``intertwined'' or not:
        \begin{list}{$\rightarrow$}{}
               \item 0: not intertwined, 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: intertwined, 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-treatement 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-treatment 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[Modifications des variables en fin de pas de temps : \texttt{usproj}]
%{Modifications des variables en fin de pas de temps : \textmd{\texttt{usproj}}}
\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 the tool
      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 neighbouring 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[Transferts thermiques radiatifs en milieu gris semi-transparent]
%{Transferts thermiques radiatifs en milieu gris semi-transparent}
\subsection{Radiative thermal transfers in semi-transparent gray media}
%==================================

%==================================
%\subsubsection[Initialisation des principaux mots cl\'es du rayonnement : \texttt{usray1}]
%{Initialisation des principaux mots cl\'es du rayonnement : \textmd{\texttt{usray1}}}
\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[Gestion des conditions aux limites du rayonnement : \texttt{usray2}]
%{Gestion des conditions aux limites du rayonnement : \textmd{\texttt{usray2}}}
\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}.\\ 
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 flow ...). 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 \textbf{ITPIMP}: wall face with imposed temperature,

\item \textbf{IPGRNO}: for a gray or black wall face, calculation of the
      temperature by means of a flux balance,

\item \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 \textbf{IFGRNO}: gray or black wall face to which a conduction
      flux is imposed,

\item \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 \textbf{ITPIMP}: the array TINTP must be completed with the
      imposed temperature value and the array EPSP must be completed
      with the emissivity value (strictly positive).

\item \textbf{IPGRNO}: must be given: an initialisation temperature in
      the array TINTP, the wall emissivity (strictly positive, in EPSP),
      thickness (in EPAP), thermal conductivity (in XLAMP) and an
      external temperature (in TEXTP) in order to calculate a conduction
      flux across the wall. 

\item \textbf{IPREFL}: must be given: an initialisation temperature (in
      TINTP), the wall thickness (in EPAP) and thermal conductivity (in
      XLAMP) and an external temperature (in TEXTP).

\item \textbf{IFGRNO}: must be given: an initialisation temperature (in
      TINTP), the wall emissivity (in EPSP) and the conduction flux (in
      $W/m^2$ whatever the thermal scalar, enthalpy or temperature) in
      the array RCODCL. The value of 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 \textbf{IFREFL}: must be given: an initialisation temperature (in
      TINTP) and the conduction flux (in $W/m^2$ whatever the thermal
      scalar) in the array RCODCL. The value of 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 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[Coefficient d'absortion du milieu, conditions aux limites
%pour la luminance et calcul du flux net radiatif : \texttt{usray3}]
%{Coefficient d'absortion du milieu, conditions aux limites
%pour la luminance et calcul du flux net radiatif : \textmd{\texttt{usray3}}}
\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 de la conversion temp\`erature-enthalpie : \texttt{usray4}]
%{Encapsulation de la conversion temp\'erature-enthalpie : \textmd{\texttt{usray4}}}
\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 MODE allows to know in which direction the
conversion will be made:
\begin{list}{$\bullet$}{}

\item \textbf{MODE = 1}: the fluid enthalpy in the cell must be
      converted into temperature (in Kelvin),

\item \textbf{MODE = -1}: the wall temperature (TEXT or TPAROI, in
      Kelvin) must be converted into enthalpy. 

\end{list}
%
{\em WARNING: the value of MODE is passed as argument and must not be
modified by the user.}\\ 



%==================================
%\subsection[Utilisation d'une physique particuli\`ere : \texttt{usppmo}]
%{Utilisation d'une physique particuli\`ere : \textmd{\texttt{usppmo}}}
\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 IPPMOD(I.....)\index{IPPMOD} in the subroutine
\texttt{usppmo}. By default, all the indicators 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 IPPMOD(ICOD3P\index{ICOD3P})}  
        \begin{list}{$\rightarrow$}{}
               \item IPPMOD(ICOD3P) = 0 adiabatic conditions
               \item IPPMOD(ICOD3P) = 1 permeatic conditions (enthalpy
		     transport)  
               \item IPPMOD(ICOD3P) =-1 module not activated
         \end{list}
        \item Eddy Break Up pre-mixed flame: indicator {\bf
	     IPPMOD(ICOEBU\index{ICOEBU})} 
         \begin{list}{$\rightarrow$}{}
                \item IPPMOD(ICOEBU\index{ICOEBU}) = 0 adiabatic
		      conditions at constant richness
                \item IPPMOD(ICOEBU) = 1 permeatic conditions at
		      constant richness 
                \item IPPMOD(ICOEBU) = 2 adiabatic conditions at
		      variable richness
                \item IPPMOD(ICOEBU) = 3 permeatic conditions at
		      variable richness
                \item IPPMOD(ICOEBU) =-1 module not activated
         \end{list}
        \item Libby-Williams pre-mixed flame: indicator {\bf IPPMOD(ICOLWC\index{ICOLWC})}
         \begin{list}{$\rightarrow$}{}        
               \item IPPMOD(ICOLWC)=0 two peak model with adibiatic conditions.
               \item IPPMOD(ICOLWC)=1 two peak model with permeatic conditions. 
               \item IPPMOD(ICOLWC)=2 three peak model with adibiatic conditions.
               \item IPPMOD(ICOLWC)=3 three peak model with permeatic conditions.
               \item IPPMOD(ICOLWC)=4 four peak model with adibiatic conditions.
               \item IPPMOD(ICOLWC)=5 four peak model with permeatic condintions.
               \item IPPMOD(ICOLWC)=-1 module not activated.
          \end{list}
        \item Multi-coals and multi-classes pulverised coal combustion:
              indicator {\bf IPPMOD(ICP3PL\index{ICP3PL})}
              The number of different coals must be inferior or equal to
	      NCHARM\index{NCHARM} = 3. The number of particle size
	     classes NCLPCH\index{NCLPCH}(ICHA) for the coal ICHA, must
	     be inferior or equal to NCPCMX\index{NCPCMX} = 10.
         \begin{list}{$\rightarrow$}{}
                \item IPPMOD(ICP3PL) = 0 imbalance between the
		      temperature of the continuous and the solid phases
                \item IPPMOD(ICP3PL) = 1 otherwise
                \item IPPMOD(ICP3PL) =-1 module not activated
         \end{list}
        \item Lagrangian modelling of multi-coals and
	     multi-classes pulverised coal combustion: 
 		indicator {\bf IPPMOD(ICPL3C\index{ICPL3C})}
              The number of different coals must be inferior or equal to
	      NCHARM\index{NCHARM} = 3. The number of particle size
	     classes NCLPCH\index{NCLPCH}(ICHA) for the coal ICHA, must
	     be inferior or equal to NCPCMX\index{NCPCMX} = 10.              
         \begin{list}{$\rightarrow$}{}
                \item IPPMOD(ICPL3C) = 1 coupling with the lagrangian
		      module, with transport of $H_2$
                \item IPPMOD(ICPL3C) =-1 module not activated
         \end{list}
       \item Electric arc module (Joule effect and Laplace forces):
             indicator {\bf IPPMOD(IELARC\index{IELARC})}  
        \begin{list}{$\rightarrow$}{}
               \item IPPMOD(IELARC) = 1 determination of the magnetic field by
		     means of the Ampere's theorem (not available)
               \item IPPMOD(IELARC) = 2 determination of the magnetic
		     field by means of the vector potential
               \item IPPMOD(IELARC) =-1 module not activated
         \end{list}
       \item Joule effect module (Laplace forces not taken into account):
             indicator {\bf IPPMOD(IELJOU\index{IELJOU})}  
        \begin{list}{$\rightarrow$}{}
               \item IPPMOD(IELJOU) = 1 use of a real potential 
               \item IPPMOD(IELJOU) = 2 use of a complex potential
               \item IPPMOD(IELJOU) = 3 use of real potential and specific boundary conditions for transformers.
	       \item IPPMOD(IELJOU) = 4 use of complex potential and specific boundary conditions for transformers.	
               \item IPPMOD(IELJOU) =-1 module not activated
         \end{list}
       \item Compressible module: indicator {\bf
	     IPPMOD(ICOMPF\index{ICOMPF})}  
        \begin{list}{$\rightarrow$}{}
               \item IPPMOD(ICOMPF) = 0 module activated 
               \item 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 modelling, the user may impose
his own enthalpy-temperature tabulation (conversion law). He needs then
to give the 
value zero to the indicator 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
DONNEES\_THERMOCHIMIE\index{DONNEES\_THERMOCHIMIE} in the launch script
(for instance: DONNEES\_THERMOCHIMIE=''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         &          NGAZE\index{NGAZE}  & Number of current species                        \\ \hline
  2     &        10         &           NPO\index{NPO}     & Number of points for the                         \\   
        &                   &                              & enthalpy-temperature tabulation                  \\ \hline
  3     &       300.        &          TMIN\index{TMIN}    & Temperature inferior limit                       \\   
        &                   &                              & for the tabulation                               \\ \hline
  4     &      3000.        &          TMAX\index{TMAX}    & Temperature superior limit                       \\   
        &                   &                              & for the tabulation                               \\ \hline
  5     &                   &                              & Empty line                                       \\ \hline
  6     & CH4 O2 CO2 H2O N2 &  NOMCOE\index{NOMCOE}(NGAZE) & List of the current species                      \\ \hline
  7     &         0         &         IRAYPP\index{IRAYPP} & 0: no radiation                                  \\   
        &                   &                              & 1: calculation of the absorption coefficient     \\
        &                   &                              & CKABS\index{CKABS} from the absorption           \\
        &                   &                              & coefficient KABSE of the current species         \\  
        &                   &                              & 2: calculation using Modak                       \\ 
        &                   &                              & 3: like 1 but P-1 model                          \\ 
        &                   &                              & 4: like 2 but P-1 model                          \\ \hline
  8     &.35 .35 .35 .35 .35&  KABSE\index{KABSE}(NGAZE)   & Absorption coefficient                           \\
        &                   &                              & of  the current species                          \\ \hline
  9     &         4         &          NATO\index{NATO}    & Number of elemental species                      \\ \hline
 10     &.012  1  0  1  0  0& WMOLAT\index{WMOLAT}(NATO),  & Molar mass of the elemental                      \\    
 11     &.001  4  0  0  2  0&                              & species (first column)                           \\  
 12     &.016  0  2  2  1  0&ATGAZE\index{ATGAZE}(NGAZE,NATO)& Composition of the current species             \\
 13     &.014  0  0  0  0  2&                              & as a function of the elemental species           \\       
        &                   &                              & (NGAZE following columns)                        \\ \hline
 14     &         3         &          NGAZG\index{NGAZG}  & Number of global species                         \\   
        &                   &                              & Here, NGAZG = 3 (Fuel, Oxidiser and Products)    \\ \hline
 15     &  1. 0. 0. 0. 0.   &                              & Composition of the global species as a           \\
 16     &  0. 1. 0. 0. 3.76 &COMPOG\index{COMPOG}(NGAZE,NGAZG)& fonction of the current species of the line 6 \\
 17     &  0. 0. 1. 2. 7.52 &                              & In the order: Fuel (line 15),                    \\
        &                   &                              & Oxidiser (line 16) and Product (line 17)         \\ \hline
 18     &         1         &          NRGAZ\index{NRGAZ}  & Number of global reactions                       \\
        &                   &                              & Here NRGAZ = 1 (always equal to 1                \\
        &                   &                              & in this version)                                 \\ \hline
 19     &                   & IGFUEL\index{IGFUEL}(NRGAZ), & Numbers of the global species concerned by       \\
        & 1 2 -1 -9.52 10.52&  IGOXY\index{IGOXY}(NRGAZ),  & the stoichiometric ratio                         \\
        &                   &                              & (first 2 integers)                               \\
        &                   &STOEG\index{STOEG}(NGAZG,NRGAZ)& Stoichiometry in reaction global species.       \\
        &                   &                               & Negative for the reactants (here                \\ 
        &                   &                               & ``Fuel'' and ``Oxidiser'') et 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              &           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&TH\index{TH}(NPO),           & Temperature(first column),                  \\
   4    & 450.  0.21E+07  0.14E+06 -0.13E+08& EHGAZG\index{EHGAZG}(1,NPO),& mass enthalpy of fuel, oxidiser             \\
   5    & 650.  0.50E+07  0.33E+06 -0.12E+08& EHGAZG(2,NPO),              & and products (columns 2,3 and 4)            \\
   6    & 850.  0.80E+07  0.54E+06 -0.12E+08& EHGAZG(3,NPO)               & from line 2 to line NPO+1                   \\
   7    &1050.  0.11E+08  0.76E+06 -0.11E+08&                             &                                             \\ \hline
   8    & .00219       .1387        .159    &WMOLG(1)\index{WMOLG},       & Molar mass of fuel,                         \\
        &                                   &                    WMOLG(2),& oxidiser                                    \\ 
        &                                   &                    WMOLG(3) & and products                                \\ \hline
   9    &                .11111             &          FS(1)\index{FS(1)} & Mixing rate at the stoichiometry            \\
        &                                   &                             & (relating to Fuel and Oxidiser)             \\ \hline
  10    &                     0             &         IRAYPP              & 0: no radiation                             \\   
        &                                   &                             & 1: calculation of the absorption coefficient\\
        &                                   &                             & CKABS\index{CKABS} from the absorption      \\
        &                                   &                             & coefficient KABSG of the 3 global species   \\  
        &                                   &                             & (Fuel, Oxydise, Products)                   \\  
        &                                   &                             & 2: calcul using Modak                       \\  
        &                                   &                             & 3: like 1 but P-1 model                     \\ 
        &                                   &                             & 4: like 2 but P-1 model                     \\\hline
  11    &    0.4      0.5       0.87        &CKABSG\index{CKABSG}(1),     & Absorption coefficient of fuel,             \\
        &                                   &                  CKABSG(2), & oxidiser                                    \\ 
        &                                   &                  CKABSG(3)  & and products                                \\ \hline
  12    &    1.       2.                    & XCO2\index{XCO2},   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                &          NCOEL\index{NCOEL}   & Number of current species                            \\ \hline
   3    &               8                &          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) & NOMCOEL\index{NOMCOEL}(NCOEL) & List of the                                          \\
        &                                &                               & current species                                      \\ \hline
   6    &               300.             &          TMIN\index{TMIN}     & Temperature inferior limit (Kelvin)                  \\
        &                                &                               & for the enthalpy-temperature tabulation              \\ \hline
   7    &              2400.             &          TMAX\index{TMAX}     & Temperature superior limit (Kelvin)                  \\
        &                                &                               & for the enthalpy-temperature tabulation              \\ \hline
   8    &               4                &          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  &WMOLAT\index{WMOLAT}(NATO),    & (first column)                                       \\
  11    &  .016  0  0  1  2  2  1  0  0  &ATCOEL\index{ATCOEL}(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    &               1                &         IRAYPP\index{IRAYPP}  & 0: no radiation                                      \\
        &                                &                               & 1: constant, given below                             \\
        &                                &                               & 2: using Modak                                       \\  
        &                                &                               & 3: like 1 but P-1 model                              \\ 
        &                                &                               & 4: like 2 but P-1 model                              \\ \hline
  15    &               0.1              &         CKABS1\index{CKABS1}  & Constant absorption coefficient                      \\
        &                                &                               & for the gas mixture                                  \\ \hline
  16    &   CARACTERISTIQUES CHARBONS    &                               & Comment line                                         \\ \hline
  17    &               2                &         NCHARB\index{NCHARB}  & Number of coal types                                 \\ \hline
  18    &         1            1         &  NCLPCH\index{NCLPCH}(NCHARB) & Number of classes for each coal                      \\
        &                                &                               & (each column corresponding to                        \\
        &                                &                               & one coal type )                                      \\ \hline
  19    &    50.E-6        50.E-6        & DIAM20\index{DIAM20}(NCLACP)  & Initial diameter of each class (m)                   \\ 
        &                                &                               & 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 
  20    &    74.8          60.5          &         CCH\index{CCH}(NCHARB)& Composition in C (mass.-\%, dry) of each coal        \\ \hline
  21    &     5.1           4.14         &         HCH\index{HCH}(NCHARB)& Composition in H (mass.-\%, dry) of each coal        \\ \hline
  22    &    12.01          5.55         &         OCH\index{OCH}(NCHARB)& Composition in O (mass.-\%, dry) of each coal        \\ \hline
  23    & 0  31524000.    0  31524000.   &IPCI\index{IPCI}(NCHARB),      & Value of the PCI ($Jkg^{-1}$) for each coal,         \\
        &                                & PCICH\index{PCICH}(NCHARB)    & the first integer indicating if this value refers    \\
	&                                &                               & to pure (0) or dry coal (1)                          \\ \hline
  24    &   1800.      1800.             &        CP2CH\index{CP2CH}(NCHARB)& Heat-storage capacity at constant pressure        \\
        &                                &                               & ($Jkg^{-1}K^{-1}$) for each coal                     \\ \hline
  25    &   1200.      1200.             &RHO0CH\index{RHO0CH}(NCHARB)   & Initial density ($kgm^{-3}$) of each                 \\ \hline
  26    &          Coke                  &                               & Comment line                                         \\ \hline
  27    &      0.         0.             &        CCK\index{CCK}(NCHARB) & Composition in C (mass.-\%, dry) of the coke         \\
        &                                &                               & for each coal                                        \\ \hline
  28    &      0.         0.             &        HCK\index{HCK}(NCHARB) & Composition in H (mass.-\%, dry) of the coke         \\
        &                                &                               & for each coal                                        \\ \hline
  29    &      0.         0.             &        OCK\index{OCK}(NCHARB) & Composition in O (mass.\%, dry) of the coke          \\
        &                                &                               & for each coal                                        \\ \hline
  30    &      0.         0.             &     PCICK\index{PCICK}(NCHARB)& PCI of the dry coke ($Jkg^{-1}$) for each coal       \\ \hline
  31    &          Cendres               &                               & Comment line                                         \\ \hline
  32    &      6.3        6.3            &   XASHCH\index{XASHCH}(NCHARB)& Ash mass fraction (mass.-\%, dry) in each coal       \\ \hline
  33    &      0.         0.             & H0ASHC\index{H0ASHC}(NCHARB)  & Ash formation enthalpy ($Jkg^{-1}$)                  \\
        &                                &                               & for each coal                                        \\ \hline
  34    &      0.         0.             &CPASHC\index{CPASHC}(NCHARB)   & CP of the ashes ($Jkg^{-1}K^{-1}$) for each coal     \\ \hline
  35    &  D\'evolatilisation (Kobayashi)  &                             & Comment line                                         \\ \hline
  36    &  1  0.37      0  0.37          & IY1CH\index{IY1CH}(NCHARB),   & For each coal, pairs (IY1CH, Y1CH).                  \\
        &                                &  Y1CH\index{Y1CH}(NCHARB)     & The real Y1CH is the adimensional stoich. coefficient\\
        &                                &                               & If the integer IY1CH is worth 1,                     \\
        &                                &                               & the provided value of Y1CH is adopted and            \\
        &                                &                               & the composition of the light volatile matters        \\
        &                                &                               & is calculated automatically.                         \\
        &                                &                               & If the integer IY1CH is worth 0,                     \\
        &                                &                               & the provided value of Y1CH is ignored:               \\
        &                                &                               & Y1CH is calculated automatically (the light          \\
        &                                &                               & volatiles are then composed of {$CH_{4}$}, {$CO$}).  \\ \hline
  37    &  1  0.74      1  0.74          & IY2CH\index{IY2CH}(NCHARB),   & For each coal, pairs (IY2CH, Y2CH).                  \\
        &                                &  Y2CH\index{Y2CH}(NCHARB)     & The real Y2CH is the adimensional stoich. coefficient\\
        &                                &                               & If the integer IY2CH is worth 1,                     \\
        &                                &                               & the provided value of Y2CH is adopted and            \\
        &                                &                               & the composition of the heavy volatile matters        \\
        &                                &                               & is calculated automatically.                         \\
        &                                &                               & If the integer IY2CH is worth 0,                     \\
        &                                &                               & the provided value of Y2CH is ignored:               \\
        &                                &                               & Y2CH is calculated automatically (the heavy          \\
        &                                &                               & volatiles are then composed of {$C_{2}H_{4}$}, {$CO$}).\\ \hline
  38    &  370000.      410000.          &       A1CH\index{A1CH}(NCHARB)& Devolatilisation pre-exponential factor A1 ($s^{-1}$)\\
        &                                &                               & for each coal (light volatile matters)               \\ \hline
  39    &  1.3E13       1.52E13          &       A2CH\index{A2CH}(NCHARB)& Devolatilisation pre-exponential factor A2 ($s^{-1}$)\\
        &                                &                               & for each coal (heavy volatile matters)               \\ \hline
  40    &   74000.       80000.          &       E1CH\index{E1CH}(NCHARB)& Devolatilisation activation energy E1 ($Jmol^{-1}$)  \\
        &                                &                               & for each coal (light volatile matters)               \\ \hline
  41    &  250000.      310000.          &       E2CH\index{E2CH}(NCHARB)& Energie d'activation E2 ($Jmol^{-1}$) de d\'evolatilisation\\ 
        &                                &                               & for each coal (heavy volatile matters)               \\ \hline
  42    &  Combustion h\'et\'erog\`ene   &                               & Ligne de commentaire                                 \\ \hline
  43    &      17.88        17.88        &AHETCH\index{AHETCH}(NCHARB)   & Char burnout pre-exponential constant                \\
        &                                &                               & ($kgm^{-2}s^{-1}atm^{-1}$) for each coal             \\ \hline
  44    &      16.55        16.55        &EHETCH\index{EHETCH}(NCHARB)   & Char burnout activation energy ($kcalmol{-1}$)       \\
        &                                &                               & for each coal                                        \\ \hline
  45    &       1            1           &IOCHET\index{IOCHET}(NCHARB)   & Char burnout reaction order for each coal            \\
        &                                &                               & 0.5 if IOCHET = 0 and 1 if 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         &    NGAZG\index{NGAZG}   & Number of species                                  \\   
        &                    &    NPO\index{NPO}       & Number of given temperature points for             \\  
        &                    &                         & the tabulated physical properties                  \\ 
        &                    &                         & (NPO $\leqslant$ NPOT set in ppthch.h)             \\ 
        &                    &                         & So there will be NGAZG blocks of 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 NGAZG species                      \\   
        &                    &    H                    & Enthalpy in J/kg                                   \\  
        &                    &    ROEL                 & Density in kg/m3                                   \\  
        &                    &    CPEL                 & Specific heat in J/(kg K)                          \\  
        &                    &    SIGEL                & Electric conductivity in Ohm/m                     \\  
        &                    &    VISEL                & Dynamic viscosity in kg/(m s)                      \\  
        &                    &    XLABEL               & Thermal conductivity in W/(m K)                    \\  
        &                    &    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[Gestion des conditions aux limites charbon pulv\'eris\'e et combustion gaz~: \texttt{usebuc, usd3pc,uslwcc, uscpcl et uscplc}]
%{Gestion des conditions aux limites charbon pulv\'eris\'e et combustion gaz~:
%\textmd{\texttt{usebuc, usd3pc, uslwcc, uscpcl et uscplc}}}
\subsection{Management of the boundary conditions related to pulverised
  coal and gas combustion: \textmd{\texttt{usebuc, usd3pc, uslwcc,
  uscpcl et 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
modelling. 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 a loop on the boundary faces marked out by their colour (or more
generally by a property of their family), where are defined: the type of
face, the type of boundary condition for each variable and eventually
the value of each variable.

{\em WARNING: In the case of a specific physics modelling, 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 modelling, a zone number IZONE
\footnote{IZONE must be less than the maximum number of boundary 
zone allowable by the code, NOZPPM. This is fixed at 2000 in
 \texttt{pppvar.h};not to be modified} (for
instance the colour 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
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
			  IENTGB\index{IENTGB}(IZONE\index{IZONE})=1) and the
			  ``fresh gas inlet'' type (marked out by
			  the fresh gas indicator
			  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
					     IQIMP\index{IQIMP}(IZONE)
					     the value 1,  
                                       \item  the
					     mass flow value is set in
					     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
					     RCODCL\index{RCODCL}(IFAC,IU\index{IU}(IPHAS)), RCODCL(IFAC,IV\index{IV}(IPHAS)) and RCODCL(IFAC,IW\index{IW}(IPHAS)) 
                                     \end{list}
                     
{\em WARNING: 
\begin{list}{-}{}
\item the variable QIMP(IZONE) refers to the mass flow across the whole
      zone 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 QIMP(izone) deals with the inflow across the area 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
				       IQIMP(IZONE) the value 0 and set
				       the three velocity components (in
				       $m.s^{-1}$) in
				       RCODCL(IFAC,IU(IPHAS)),
				       RCODCL(IFAC,IV(IPHAS)) and
				       RCODCL(IFAC,IW(IPHAS)) 
                          \end{list}
                    \item finally he specifies for each gas inlet type
			  the mixing rate FMENT\index{FMENT}(IZONE) and
			  the temperature  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
			  IENTOX\index{IENTOX}(IZONE)=1 and the ``fuel
			  inlet'' type marked out by
			  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
			  TINOXY\index{TINOXY} for each oxydiser inlet
			  and 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
			  (TINOXY) and one input temperature for the
			  fuel (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 IENTCP\index{IENTCP}(IZONE)=1, or to
			  the ``secondary or tertiary air inlet'' type,
			  marked out by 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 (IQIMP(IZONE)=1 or
			  0). If the mass flow is imposed, the user
			  must set the air mass flow value
			  QIMPAT\index{QIMPAT}(IZONE), its direction in
			  RCODCL(IFAC,IU(IPHAS)), RCODCL(IFAC,IV(IPHAS))
			  and \\ RCODCL(IFAC,IW(IPHAS)) and the incoming
			  air temperature TIMPAT\index{TIMPAT}(IZONE) in
			  Kelvin. If the velocity is imposed, he has to
			  set  RCODCL(IFAC,IU(IPHAS)), \\
			  RCODCL(IFAC,IV(IPHAS)) and RCODCL(IFAC,IW(IPHAS)).  

                    \item if the inlet belongs to the ``primary air and
			  pluverised coal'' type (IENTCP(IZONE) = 1) the
			  user must also define for each coal type ICHA:
			  the mass flow
			  QIMPCP\index{QIMPCP}(IZONE,ICHA), the
			  granulometric distribution
			  DISTCH\index{DISTCH}(IZONE,ICHA,ICLAPC)
			  related to each class ICLACP, and the
			  injection temperature
			  TIMPCP\index{TIMPCP}(IZONE,ICHA) 
			  
             \end{list}
\end{list} 

%==================================
%\subsection[Initialisation des variables charbon pulv\'eris\'e et
%combustion gaz~: \texttt{usebui, usd3pi, uslwci et uscpiv}]
%{Initialisation des variables charbon pulv\'eris\'e et combustion
%gaz~: \textmd{\texttt{usebui, usd3pi, uslwci et uscpiv}}}
\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 modelling, 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 IEL: the mixing rate
	     RTP\index{RTP}(IEL,ISCA(IFM)) in variable richness, the
	     fresh gas mass fraction \\
	     RTP(IEL,ISCA(IYGFM\index{IYGFM}))
	     and the mixture enthalpy 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 IEL: the
	     mixing rate RTP(IEL,ISCA(IFM\index{IFM})), its variance
	     RTP(IEL,ISCA(IFP2M\index{IFP2M})) and the mixture mass
	     enthalpy RTP(IEL,ISCA(IHM)) in permeatic conditions

        \item in the case of the pulverised coal combustion module, the
	     user can initialise in every cell IEL:
              \begin{list}{$\rightarrow$}{}
                     \item the transport variables related to the solid phase
                           \begin{list}{}{}
                                  \item RTP(IEL,ISCA(IXCH\index{IXCH}(ICLA))) the reactive coal mass fraction related to the class ICLA (ICLA from 1 to NCLACP which is the total number of classes, {\em i.e.} for all the coal type)
                                  \item RTP(IEL,ISCA(IXCK(\index{IXCK}ICLA))) the coke mass fraction related to the class ICLA 
                                  \item	RTP(IEL,ISCA(INP\index{INP}(ICLA))) the number of particles related to class ICLA per kg of air-coal mixture
                                  \item RTP(IEL,ISCA(IH2\index{IH2}(ICLA))) the mass enthalpy related to the class ICLA in permeatic conditions	
                           \end{list}
                     \item RTP(IEL,ISCA(IHM)) the mixture enthalpy   
                     \item the transport variables related to the gas phase 
                           \begin{list}{}{}
                                  \item
				       RTP(IEL,ISCA(IF1M\index{IF1M}(ICHA))) the mean value of the tracer 1 representing the light volatile matters released by the coal ICHA
                                  \item
				       RTP(IEL,ISCA(IF2M\index{IF2M}(ICHA))) the mean value of the tracer 2 representing the heavy volatile matters released by the coal ICHA
                                  \item RTP(IEL,ISCA(IF3M\index{IF3M}))
					the mean value of the tracer 3
					representing the carbon released
					as CO during coke burnout
                                  \item 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	RTP(IEL,ISCA(IFP3M\index{IFP3M})) the variance associated with the tracer 3
                           \end{list} 
              \end{list}
\end{list}


%==================================
%\subsection[Initialisation des options des variables charbon pulv\'eris\'e et combustion gaz~: \texttt{usebu1, usd3p1, uslwc1, uscpi1 et uscpl1}]
%{Initialisation des options des variables charbon pulv\'eris\'e et
%combustion gaz~: \textmd{\texttt{usebu1, usd3p1, uslwc1,  uscpi1 et uscpl1}}}
\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
	     ICHRVR\index{ICHRVR}(IPP)), follow-ups in the listings
	     (indicator ILISVR\index{ILISVR}(IPP)) and to activate
	     chronological records at the probes defined in
	     \texttt{usini1} (indicators 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 IPP are
      IPP=IPPPRO\index{IPPPRO}(IPPROC\index{IPPROC}(IVAR)), with 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 IVAR (defined
      at the cell IEL by RTP(IEL,IVAR)) and the properties IPROP (defined
      at the cell IEL by PROPCE(IEL,IPPROC(IPROP))) are listed now:
      \begin{list}{$\rightarrow$}{}
       \item EBU pre-mixed flame modelling: 
       \begin{list}{-}{}
	\item Calculation variables RTP(IEL,IVAR)
	      \begin{list}{IVAR = }{}
	       \item ISCA(IYGFM\index{IYGFM}) fresh gas mass fraction
	       \item ISCA(IFM\index{IFM}) mixing rate
	       \item ISCA(IHM\index{IHM}) enthalpy, if transported
	      \end{list}
	\item Properties PROPCE(IEL,IPPROC(IPROP))
	      \begin{list}{IPROP = }{}
	       \item ITEMP\index{ITEMP} temperature
	       \item IYM(1)\index{IYM(1)} fuel mass fraction
	       \item IYM(2)\index{IYM(2)} oxidiser mass fraction
	       \item IYM(3)\index{IYM(3)} product mass fraction
	       \item ICKABS\index{ICKABS} absorption
		     coefficient, when the radiation modelling is
		     activated 
	       \item IT3M\index{IT3M} and IT4M\index{IT4M}
		     ``$T^3$'' and ``$T^4$'' terms, when the radiation
		     modelling is activated
	      \end{list}
       \end{list}
       \item rapid complete chemistry diffusion flame modelling: 
	     \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 IVAR=ISCA(IFP2M\index{IFP2M})
	     \end{list}
       \item pulverised coal modelling with 3 comustables: 
	     \begin{list}{}{}
	      \item {\em variables shared by the two phases}:                
		    \begin{list}{-}{}
		     \item Calculation variables RTP(IEL,IVAR)
			   \begin{list}{IVAR = }{}
			    \item ISCA(IHM\index{IHM}): gas-coal mixture enthalpy
			    \item 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 RTP(IEL,IVAR)
		     \begin{list}{IVAR = }{}
		      \item ISCA(IXCK\index{IXCK}(ICLA)): coke mass
			    fraction related to the class ICLA
		      \item ISCA(IXCH\index{IXCH}(ICLA)): reactive coal
			    mass fraction related to the class ICLA
		      \item ISCA(INP\index{INP}(ICLA)): number of
			    particles of the class ICLA per kg of
			    air-coal mixture 
		      \item ISCA(IH2\index{IH2}(ICLA)): mass enthalpy of
			    the coal of class ICLA, if we are in
			    permeatic conditions 
		     \end{list}
	       \item Properties PROPCE(IEL,IPPROC(IPROP))
		     \begin{list}{IPROP = }{}
		      \item IMMEL\index{IMMEL}: molar mass of the gas mixture
		      \item ITEMP2\index{ITEMP2}(ICLA): temperature of
			    the particles of the class ICLA 
		      \item IROM2\index{IROM2}(ICLA): density of
			    the particles of the class ICLA
		      \item IDIAM2\index{IDIAM2}(ICLA): diameter of the
			    particles of the class ICLA
		      \item IGMDCH\index{IGMDCH}(ICLA): disappearance
			    rate of the reactive coal of the class ICLA
		      \item IGMDV1\index{IGMDV1}(ICLA): mass transfer
			    caused by the release of light volatiles
			    from the class ICLA 
		      \item IGMDV2\index{IGMDV2}(ICLA): mass transfer
			    caused by the release of heavy volatiles
			    from the class ICLA 
		      \item IGMHET\index{IGMHET}(ICLA): coke
			    disappearance rate during the coke burnout
			    of the class ICLA 
		      \item IX2\index{IX2}(ICLA): solid mass fraction
			    of the class ICLA
		     \end{list}
	      \end{list}
	      \item {\em variables specific to the continuous phase}:
	      \begin{list}{-}{}
	       \item Calculation variables RTP(IEL,IVAR)
		     \begin{list}{IVAR = }{}
		      \item ISCA(IF1M\index{IF1M}(ICHA)): mean value of
			    the tracer 1 representing the light
			    volatiles released by the coal ICHA 
		      \item ISCA(IF2M\index{IF2M}(ICHA)): mean value of
			    the tracer 2 representing the heavy
			    volatiles released by the coal ICHA 
		      \item ISCA(IF3M)\index{IF3M}: mean value of the
			    tracer 3 representing the carbon released as
			    CO during coke burnout
		      \item ISCA(IF4PM\index{IF4PM}): variance of the
			    tracer 4 representing the air
		      \item ISCA(IF3P2M\index{IF3P2M}): variance of the
			    tracer 3 
		     \end{list}
	       \item Properties PROPCE(IEL,IPPROC(IPROP))
		     \begin{list}{IPROP = }{}
		      \item ITEMP1\index{ITEMP1}: temperature of the gas
			    mixture
		      \item IYM1(1)\index{IYM1(1)}: mass fraction of
			    $CH_{X1m}$ (light volatiles) in the gas
			    mixture 
		      \item IYM1(2)\index{IYM1(2)}: mass fraction of
			    $CH_{X2m}$ (heavy volatiles) in the gas
			    mixture 
		      \item IYM1(3)\index{IYM1(3)}: mass fraction of
			    CO in the gas mixture 
		      \item IYM1(4)\index{IYM1(4)}: mass fraction of
			    $O_2$ in the gas mixture 
		      \item IYM1(5)\index{IYM1(5)}: mass fraction of
			    $CO_2$ in the gas mixture 
		      \item IYM1(6)\index{IYM1(6)}: mass fraction of
			    $H_2O$ in the gas mixture 
		      \item 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 SRROM, with \\
$\rho^{n+1}=SRROM*\rho^{n}+(1-SRROM)\rho^{n+1}$\\
(by default, the adopted value is 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 DIFTL0. By default
      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 CEBU\index{CEBU} of the Eddy Break
      Up model (only in \texttt{usebu1}. By default  CEBU=2.5)
  
\end{list} 



%==================================
%\subsection[Gestion des conditions aux limites module \'electrique~: \texttt{uselcl}]
%{Gestion des conditions aux limites module \'electrique~: \textmd{\texttt{uselcl}}}
\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, in that 
a loop on the boundary face, referenced by their colour (or more genrally
 the properties of their familly), where it is defined ;the face type,
 the boundary conditions for each variable, and finally the value of 
each variable or imposed flow. 

{\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, NOZZPPM. This is fixed at 2000 in \texttt
{ppvar.h} and cannot be modified.}( the colour 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 Neuman conditions must be imposed
 explicitly using ICODCL and RCODCL (as would be done for the classic 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(PUISMP\index{PUISMP}
 and 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 DPOT. This variable is initialised in \texttt{useli1}
 by an estimated potential difference. If IELCOR=1(see \texttt{useli1}), 
DPOT is updated automatically during the calcualtion to obtain the required 
current.
\item For the Joule module effect, DPOT is again used with the same significane
 as it held in the electric arc module. If DPOT is not wanted in the setting of the
 boundary condtions, the variable COEJOU can be used.  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 IELCOR-1 (see \texttt
{useli1}), multiply the imposed potentials in \texttt{uselcl} by 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 (IPPMOD(IELJOU)=2
): this is the  case in particular where the current is in 3 phase. In affect, 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 (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 des variables  module \'electrique~: \texttt{useliv}]
%{Initialisation des variables  module \'electrique~: \textmd{\texttt{useliv}}}
\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 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 des options des variables  module \'electrique~: \texttt{useli1}]
%{Initialisation des options des variables  module \'electrique~: \textmd{\texttt{useli1}}}
\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 (indicators ICHRVR(IPP)), the listings (indicator (ILISVR(IPP)) and the
historical exits at the probes defined in \texttt{usini1}(indicators IHISVR(IPP)).
The functions are the same as in \texttt{usini1} and the script frequency of the 
exits are fixed using \texttt{usini1.} The indicators IPP are for the value IPP=IPPPRO
(IPPROC(IVAR), with 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 IVAR ( defined to the cells IEL and accessible by PROPCE
IEL,IPPROC(IPROP)):

\begin{list}{$\rightarrow$}{}
                    \item Electric Arc Module: 
                          \begin{list}{-}{}
                                 \item Calculation variables RTP(IEL,IVAR)
                                       \begin{list}{IVAR = }{}
                                             \item ISCA(IHM\index{IHM}) enthalpy
                                             \item ISCA(IPOTR\index{IPOTR}) real potentiel 
                                            \item ISCA(IPOTVA(i))\index{IPOTVA}) solved components of the potential vector.
                                             \item ISCA(IYCOEL(IESP)\index{IYCOEL}) the mass fraction of NGAZG composites if there are more than 1
                                       \end{list}
                                 \item Properties PROPCE(IEL,IPPROC(IPROP))
                                       \begin{list}{IPROP = }{}
                                             \item ITEMP\index{ITEMP}  temperature
                                             \item IEFJOU\index{IEFJOU} power dissipation by the Joule effect.
                                             \item ILAPLA(i)\index{ILAPLA(i)} components of the laplace forces.
                                       \end{list}
                          \end{list}
                    \item Joule Module effect~: 
                          \begin{list}{-}{}
                                 \item Calculation variables RTP(IEL,IVAR)
                                      \begin{list}{IVAR = }{}
                                             \item ISCA(IHM\index{IHM}) enthalpy
                                             \item ISCA(IPOTR\index{IPOTR}) real potential 
                                             \item ISCA(IPOTI\index{IPOTI}) imaginary potential if its to be taken into account
                                             \item ISCA(IYCOEL(IESP)\index{IYCOEL})the mass fraction of NGAZG composites if there are more than 1
                                        \end{list}
                                 \item Properties PROPCE(IEL,IPPROC(IPROP))
                                       \begin{list}{IPROP = }{}
                                             \item ITEMP\index{ITEMP} temperature
                                             \item 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 SRROM:\\
$\rho^{n+1}=SRROM*\rho^{n}+(1-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 IELCOR.  
       \item target current fixed as COUIMP(electric arc module) or the power dissipation PUISM (Joule module effect).   	
       \item Fix the initial value of potential difference DPOT, the for the calculations with a single fixed parameter as COUIMP or PUISM.
  
\end{list}

%==================================
%\subsection[Gestion des propri\'et\'es physiques variables module \'electrique~: \texttt{uselph}]
%{Gestion des propri\'et\'es physiques variables module \'electrique~: \textmd{\texttt{uselph}}}
\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 PROPCE array. CP0, VISCLS0,VISCL0 are not used}

For the Joule effect, the user is obliged 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[Gestion des sorties au format {\em EnSight} module \'electrique~: \texttt{uselen}]
%{Gestion des sorties au format {\em EnSight} module \'electrique~: \textmd{\texttt{uselen}}}
\subsection[Management of the {\em EnSight} output in the electric module~: \texttt{uselen}]
{Management of the {\em EnSight} output in the electric module~: \textmd{\texttt{uselen}}}
%==================================

\noindent
\textit{Subroutine called at each chronological output}

This subroutine allow the addition on N variables in the {\em Ensight} output file and
 works like the subroutien \texttt{useevo}(with the electric module, it is however still
 possible to \texttt{useevo}.

The algebraic variables related to the electric module are provided by default provided
 that they are not explicitely contained in the POPCE 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 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 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
 FORT directory: the post-treatment will be done automatically (at the same frequency
 (NTCHR) as the other calculation variables) 


%==================================
%\subsection[Module compressible]
%{Module compressible }
\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'' (IDTVAR=1) with a maximum Courant number of 0.4
       (COUMAX=0.4): these choices must be written in \texttt{usini1}
 \item keep the convective numerical schemes proposed by default.
\end{list}

%==================================
%\subsubsection[Initialisation des options des variables module compressible : \texttt{uscfx1}
%et \texttt{uscfx2}]
%{Initialisation des options des variables module compressible : \textmd{\texttt{uscfx1}}
%et \textmd{\texttt{uscfx2}}}
\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 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 (IVISCV)
  \item reference value (VISCV0)
\end{list}

%==================================
%\subsubsection[Gestion des conditions aux limites module compressible : \texttt{uscfcl}]
%{Gestion des conditions aux limites module compressible : \textmd{\texttt{uscfcl}}} 
\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 a loop on the boundary faces marked out by their colour (or more
generally by a property of their family), 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[Initialisation des variables module compressible : \texttt{uscfxi}]
%{Initialisation des variables module compressible : \textmd{\texttt{uscfxi}}} 
\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 modelling, 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
ICCFTH used for the call to \texttt{uscfth}.

%==================================
%\subsubsection[Thermodynamique module compressible : \texttt{uscfth}]
%{Thermodynamique module compressible : \textmd{\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[Gestion des propri\'et\'es physiques variables module compressible~: \texttt{uscfpv}]
%{Gestion des propri\'et\'es physiques variables module compressible~: \textmd{\texttt{uscfpv}}}
\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[Approche lagrangienne des \'ecoulements multiphasiques \`a inclusions dispers\'ees]
%{Approche lagrangienne des \'ecoulements multiphasiques \`a inclusions dispers\'ees}
\subsection{Lagrangian modelling of multiphasic flows with dipersed inclusions}
%==================================


%==================================
%\subsubsection[Initialisation des principaux mots cl\'es de l'approche lagrangienne : \texttt{uslag1}]
%{Initialisation des principaux mots cl\'es de l'approche lagrangienne : \textmd{\texttt{uslag1}}}
\subsubsection{Initialisation of the main key words in the lagrangian
   modelling: \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 modelling 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 monophasic flow is stationary 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
modelling, 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 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[Gestion des conditions aux limites particulaires :
%\texttt{uslag2} et \texttt{uslain}]
%{Gestion des conditions aux limites particulaires : \textmd{\texttt{uslag2}} et
%\textmd{\texttt{uslain}}} 
\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 modelling, 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, 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 NFRLAG\index{NFRLAG} boundary zones 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 IFRLAG(NFABOR) giving for
each face IFAC the number IFRLAG(IFAC) corresponding to the zone to
which it belongs, is completed. The zone numbers ({\em i.e.} the values
of IFRLAG(IFAC)) are chosen freely by the user, but must be strictly
positive integers inferior or equal to 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 NFRLAG boundary zones
previously identified, the number of classes 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: IUSNCL(IZONE) = NBCLAS. By default, the
number of particle classes is zero. The maximum number of classes is
NCLAGM\index{NCLAGM} (parameter stored in lagpar.h, whose default value
is 20).}

\variablist{IUSCLB}{IUSCLB(NFLAGM)}{IA}{For all the 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 IENTRL\index{IENTRL}, ISORTL\index{ISORTL}, IREBOL\index{IREBOL},
IDEPO1\index{IDEPO1}, IDEPO2\index{IDEPO2}, IDEPO3\index{IDEPO3},
IENCRL\index{IENCRL}) and the user boundary condition types (marked out
by the key words JBORD1 to JBORD5)\index{JBORD1}, whose corresponding
particle behaviour must be defined in the subroutine \texttt{uslabo}.

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

 \item if IUSCLB(IZONE) = 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 IUSCLB(IZONE) = ISORTL, the particles interacting with the zone
       IZONE leave the calculation domain.

 \item if IUSCLB(IZONE) = IREBOL, the particles undergo an elastic
       rebound on the boundary zone IZONE.

 \item if IUSCLB(IZONE) = IDEPO1, the particles settle definitevely on
       the boundary zone IZONE. These particles can not be put in suspension
       again, and we consider that they leave the calculation domaine.

 \item if IUSCLB(IZONE) = IDEPO2, the particles settle definitevely on
       the boundary zone IZONE, but they are kept in the calculation
       domain. This distinction with the type IDEPO1 is useful only when
       post-treatments in movement mode (IFENSI2 = 1) are realised: the
       particles do not disappear after touching the boundary
       zone. However, using IDEPO2 type zones necessitates more memory
       than using IDEPO1 type zones.

 \item if IUSCLB(IZONE) = IDEPO3, the particles settle on the boudary
       zone IZONE, but can be put in suspension again depending on the
       local description of the continuous phase flow.

 \item if IUSCLB(IZONE) = IENCRL, the particles which are coal particles
       (if IPHYLA = 2) can become fouled up on the zone IZONE. The
       slagging is a IDEPO1 type deposit of the coal particle if a certain
       criterion is respected. Otherwise, the coal particle rebounds
       (IREBOL type behaviour). This boundary condition type is available
       if IENCRA = 1. A limit temperature TPRENC\index{TPRENC}, a
       critical viscosity 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 IUSCLB(IZONE) = JBORD1 to JBORD5, then the particle
       interaction with the boundary zone IZONE is given by the user. The
       particle behaviour associated with each type 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 IUSLAG. There are at the most NDLAIM\index{NDLAIM} integers. These
pieces of information must be provided for each class ICLAS and each
particle injection zone IZONE. They are marked out by means of ``pointers'':
\begin{list}{$\rightarrow$}{}
 
\item IUSLAG(ICLAS,IZONE,IJNBP): number of particles to inject in the
      calculation domain per class and per zone.

\item 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 IUSLAG(ICLAS,IZONE,IJUVW): type of velocity condition:

\begin{list}{-}{}

\item if IUSLAG(ICLAS,IZONE,IJUVW) = 1, the particle velocity vector is
      imposed, and its components must be given in the array RUSLAG (see
      below). 

\item if IUSLAG(ICLAS,IZONE,IJUVW) = 0, the particle velocity is imposed
      perpendicular to the injection boundary face and with the norm
      RUSLAG(ICLAS,IZONE,IUNO). 

\item if IUSLAG(ICLAS,IZONE,IJUVW) = -1, the particle injection velocity
      is equal to the fluid velocity at the centre of the cell
      neighbouring the injection boundary face.

\end{list}

\item IUSLAG(ICLAS,IZONE,INUCHL): when the particles are coal particles
      (IPHYLA = 2), this part of the array contains the coal index-number,
      between 1 and NCHARB (defined by the user in the thermo-chemical
      file dp\_FCP, with  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 RUSLAG. There are at the most
NDLAGM\index{NDLAGM} such real numbers. These pieces of information must
be provided for each class ICLAS and each particle injection zone
IZONE. They are marked out by means of ``pointers'': 
\begin{list}{$\rightarrow$}{}

\item RUSLAG(ICLAS,IZONE,IUNO): norm of the injection velocity,
\\useful if IUSLAG(ICLAS,IZONE,IJUVW)~=~0.

\item RUSLAG(ICLAS,IZONE,IUPT), RUSLAG(ICLAS,IZONE,IVPT),\\
RUSLAG(ICLAS,IZONE,IWPT): components of the particle injection vector,
\\useful if IUSLAG(ICLAS,IZONE,IJUVW)~=~1.

\item RUSLAG(ICLAS,IZONE,IDEBT): allows to impose a particle mass
      flow. According to the number of injected particles, the particle
      statistical weight 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 RUSLAG(ICLAS,IZONE,IPOIT): particle statistical weight per class and
      per zone.

\item RUSLAG(ICLAS,IZONE,IDPT): particle diameter. When the particles
      are coal particles (IPHYLA = 2), this diameter is provided by the
      thermo-chemical file dp\_FCP {\it via} the array DIAM20(ICLG),
      where 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 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 RUSLAG(ICLAS,IZONE,IROPT): particle density. When the particles
      are coal particles (IPHYLA = 2), this density is set in the
      thermo-chemical file dp\_FCP {\em via} the array RHO0CH(ICHA),
      where ICHA is the coal number.

\item RUSLAG(ICLAS,IZONE,ITPT): particle injection temperature in
      \degresC. Useful if IPHYLA = 1 and if ITPVAR = 1.

\item RUSLAG(ICLAS,IZONE,ICPT): particle injection specific heat. Useful
      if IPHYLA = 1 and if ITPVAR = 1. When the particles are coal
      particles (IPHYLA = 2), the specific heat is set in the
      thermo-chemical file dp\_FCP {\em via} the array CP2CH(ICHA).

\item RUSLAG(ICLAS,IZONE,IEPSI): particle emissivity. Useful if IPHYLA =
      1 and if ITPVAR = 1, and if the radiation module is activated for
      the continuous phase (note: when IPHYLA = 2, the coal particle
      emissivity is given the value 1).

\item RUSLAG(ICLAS,IZONE,IHPT): particle injection temperature in
      \degresC\ when these particles are coal
      particles. The array RUSLAG(ICLAS,IZONE,ITPT) is then no longer
      active. Useful if IPHYLA = 2.

\item RUSLAG(ICLAS,IZONE,IMCHT): mass of reactive coal. Useful if IPHYLA = 2.

\item RUSLAG(ICLAS,IZONE,IMCKT):  mass of coke. This mass is null
      if the coal did not begin to burn before its injection. Useful if
      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 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' et '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 ETTP, TEPA and 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 ETTP, TEPA and ITEPA. The particles already present in the
calculation domain are marked out by an index varying between 1 and
NBPART. The particles entering the calculation domain at the current
iteration are marked out by an index varying between NBPART+1 and NBPNEW.


%==================================
%\subsubsection[Traitement de l'interaction particules/fronti\`ere : \texttt{uslabo}]
%{Traitement de l'interaction particules/fronti\`ere : \textmd{\texttt{uslabo}}}
\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 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
(IREBOL, 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 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 PARBOR. When they are
non-stationary (number of lagrangian iterations lower than NSTBOR, or
ISTTIO = 0), the array 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 KX, KY, 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 ETTP and ETTPA:

\begin{list}{-}{}
\item new departure point of the current trajectory segment: \\
ETTPA(NPT,JXP), ETTPA(NPT,JYP), ETTPA(NPT,JZP)
\item new arrival point of the current trajectory segment: \\
ETTP(NPT,JXP), ETTP(NPT,JYP), ETTP(NPT,JZP)
\end{list}

\item The particle and the fluid velocities may be modified according to
      the desired interaction {\em via} the arrays VITPAR\index{VITPAR}
      and VITFLU\index{VITFLU}, they \textbf{must not} be modified {\em
      via} ETTP and ETTPA in this subroutine.

\item For a given interaction, it is necessary to specify the key word
      ISUIVI\index{ISUIVI}:  

\begin{list}{-}{}
\item 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 IENTRL, ISORTL,
      IDEPO1, IDEPO2) ;
\item ISUIVI = 1 to continue to follow the particle in the mesh
      after its interaction (by default, it is the case for IREBOL and
      IDEPO3). The value of ISUIVI may be a function of the particle and
      boundary state (for instance, ISUIVI = 0 or 1 depending on the
      physical properties for the interaction type IENCRL).
\end{list}

\item The array zone ITEPA(NPT,JISOR), containing the index-number of the
      cell where the particle is, must be updated. Generally:

\begin{list}{-}{}
\item ITEPA(NPT,JISOR) = IFABOR(KFACE) when the particle stays in the
      calculation domain (KFACE is the number of the interacting
      boundary face). 
\item 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 de clonage/fusion des particules : \texttt{uslaru}]
%{Option de clonage/fusion des particules : \textmd{\texttt{uslaru}}}
\subsubsection{Option of particle cloning/fusion: \textmd{\texttt{uslaru}}}
%==================================

\noindent
\textit{Subroutine called every lagrangian iteration.}

\noindent
An intervention in this subroutine is required if the particle
cloning/fusion option is activated {\em via} the key word IROULE. The
importance function 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 des variables particulaires en fin d'itération et statistiques volumiques utilisateur: \texttt{uslast} et \texttt{uslaen}]
%{Manipulation des variables particulaires en fin d'itération et statistiques volumiques utilisateur: \textmd{\texttt{uslast}} et \textmd{\texttt{uslaen}}}
\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 STATIS. Two
situations may happen:
\begin{list}{-}{}
\item the calculation of the statistics is not stationary: STATIS is
      reset at every lagrangian iteration ; 
\item the calculation of the statistics is stationary: the array
      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 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 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[\'Equations diff\'erentielles stochastiques utilisateur : \texttt{uslaed}]
%{\'Equations diff\'erentielles stochastiques utilisateur : \textmd{\texttt{uslaed}}}
\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 ETTP and 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 (NORDRE = 1), this subroutine is called once every
lagrangian iteration, if it is a second-order (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 (NVLS in
total) available in ETTP(NBPMAX, JVLS(I)) and in 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 ETTP and 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 AUXL1 for
      every particle, 
\item $\Pi$ , equation coefficient, in the array 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 ETTPA. If the chosen scheme is a second-order,
      then $\Pi$ is expressed at the first call of the subroutine
      (prediction step NOR = 1) as a function of the variables at the
      previous iteration (stored in ETTPA), then at the second call
      (correction step NOR = 2) as a function of the predicted variables
      stored in the array 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
TEMPCT(NBPMAX,1) of the array TEMPCT.


%==================================
%\subsubsection[Temps de relaxation des particules : \texttt{uslatp}]
%{Temps de relaxation des particules : \textmd{\texttt{uslatp}}}
\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 TAUP.

%==================================
%\subsubsection[Temps caractéristique thermique des particules: \texttt{uslatc}]
%{Temps caractéristique thermique des particules: \textmd{\texttt{uslatc}}}
\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 TEMPCT(NBPMAX,1) of the array TEMPCT.
