\subsection{The {\tt SAP:} module}\label{sect:SAPHYBData}

This component of the lattice code is dedicated to the constitution of the
reactor database intended to store {\sl all} the nuclear data, produced in
the lattice code, that is useful
in reactor calculations including fuel management and space-time kinetics.
Multigroup lattice calculations are too expensive to be executed dynamically
from the driver of the global reactor calculation. A more feasible
approach is to create a reactor database where a finite number of lattice
calculation results are tabulated against selected {\sl global parameters}
chosen so as to represent expected operating conditions of the reactor.

\vskip 0.1cm

The \moc{SAP:} operator is used to create and construct a {\sc saphyb} object.
This object is generally {\sl persistent} and used to collect information gathered
from many DRAGON {\sl elementary calculations} performed under various conditions.
The {\sc saphyb} object is based on a specification of the Saphyr code system.\cite{Apollo2}

\vskip 0.1cm

Each elementary calculation is characterized by a tuple of {\sl global parameters}.
These global parameters are of different types, depending on the nature of the
study under consideration: type of assembly, power, temperature in a mixture,
concentration of an isotope, time, burnup or exposure rate in a depletion calculation,
etc. Each step of a depletion calculation represents an elementary calculation.
The {\sc saphyb} object is often presented as a {\sl multi-parameter reactor database}.

\vskip 0.1cm

For each elementary calculation, the results are recovered from the output of the
\moc{EDI:} operator and stored in a set of {\sl homogenized mixture}
directories. The \moc{EDI:} operator is responsible for performing condensation
in energy and homogenization in space of the macroscopic and microscopic cross
sections. All the elementary calculations gathered in a single {\sc saphyb} object are
characterized by a single output geometry and a unique output energy-group
structure.

\vskip 0.1cm

The {\sc saphyb} object contains table-of-content information apart from a set of specific
{\sl elementary calculation} directories. These directories are themself subdivided
into {\sl homogenized mixture} directories. The localization of an elementary calculation
is done using a tuple of global parameters. The elementary calculation indices are
stored in a tree with the number of levels equal to the number of global parameters.
An example of a tree with three global parameters is shown in \Fig{tree}. Each node
of this tree is associated with the index of the corresponding global parameter and with the
reference to the daughter nodes if they exist. The number of leaves is equal to the number
of nodes for the last (third) parameter and is equal to the number of elementary
calculations stored in the {\sc saphyb} object. The index of each elementary calculation is
therefore an attribute of each leaf.

\begin{figure}[h!]  
\begin{center} 
\epsfxsize=12cm
\centerline{ \epsffile{tree.eps}}
\parbox{14cm}{\caption{Global parameter tree in a {\sc saphyb} object}\label{fig:tree}}   
\end{center}  
\end{figure}

\vskip 0.1cm

In each homogenized mixture directory, the \moc{SAP:} operator recover
cross sections for a number of {\sl particularized isotopes} and {\sl macroscopic
sets}, a collection of isotopic cross sections weighted by isotopic number densities.
Cross sections for particularized isotopes and macroscopic sets are recovered for
{\sl selected reactions}. Other information is also recovered: multigroup neutron
fluxes, isotopic number densities, fission spectrum and a set
of {\sl local variables}. The local variables are values that characterize each
homogenized mixture: local power, burnup, exposure rate, etc. Some local variables
are arrays of values (eg: SPH equivalence factors). Finally, note that cross section
information written on the {\sc saphyb} is {\sl not} transport corrected and {\sl not}
SPH corrected.

\vskip 0.1cm

A different specification of the \moc{SAP:} function call is used for
creation and construction of the {\sc saphyb} object.
\begin{itemize}
\item The first specification is used to initialize the {\sc saphyb} data structure
as a function of the \dds{microlib} used in the reference calculation. Optionnally,
the homogenized geometry is also provided. The initialization call is also used to
set the choice of global parameters, local variables, particularized isotopes,
macroscopic sets and selected reactions.
\item A modification call to the \moc{SAP:} function is performed after each
elementary calculation in order to recover output information processed by \moc{EDI:}
(condensed and homogenized cross sections) and \moc{EVO:} (burnup dependant values).
Global parameters and local variables can optionnally be recovered from \dds{microlib}
objects. The \moc{EDI:} calculation is generally performed with option {\tt MICR ALL}.
\end{itemize}

The calling specifications are:

\vskip -0.5cm

\begin{DataStructure}{Structure \dstr{SAP:}}
$\{$~~\dusa{SAPNAM} \moc{:=} \moc{SAP:} $[$ \dusa{SAPNAM} $]~[$~\dusa{HMIC} $]$ \moc{::} \dstr{saphyb\_data1} \\
~~~$|$~~~\dusa{SAPNAM} \moc{:=} \moc{SAP:} \dusa{SAPNAM}~\dusa{EDINAM}~$[$ \dusa{BRNNAM} $]~[$ \dusa{HMIC1}~$[$~\dusa{HMIC2} $]~]~[$ \dusa{FLUNAM} $]$\\
~~~~~~~~~~ \moc{::} \dstr{saphyb\_data2} \\
~~~$|$~~~\dusa{SAPNAM} \moc{:=} \moc{SAP:} \dusa{SAPNAM} $[[$ \dusa{SAPRHS} $]]$ \moc{::} \dstr{saphyb\_data3} $\}$ \\
\end{DataStructure}

\noindent where
\begin{ListeDeDescription}{mmmmmmm}

\item[\dusa{SAPNAM}] {\tt character*12} name of the {\sc lcm} object containing the
{\sl master} {\sc saphyb} data structure.

\item[\dusa{HMIC}] {\tt character*12} name of the reference \dds{microlib} (type {\tt
L\_LIBRARY}) containing the microscopic cross sections.

\item[\dusa{EDINAM}] {\tt character*12} name of the {\sc lcm} object (type {\tt
L\_EDIT}) containing the {\sc edition} data structure corresponding to an elementary
calculation. The {\sc edition} data produced by the last call to the {\tt EDI:} module
is used.

\item[\dusa{BRNNAM}] {\tt character*12} name of the {\sc lcm} object (type {\tt
L\_BURNUP}) containing the {\sc burnup} data structure. This object is compulsory if one
of the following parameters is used: \moc{IRRA}, \moc{FLUB} and/or \moc{TIME}.

\item[\dusa{HMIC1}] {\tt character*12} name of a \dds{microlib} (type {\tt
L\_LIBRARY}) containing global parameter information.

\item[\dusa{HMIC2}] {\tt character*12} name of a \dds{microlib} (type {\tt
L\_LIBRARY}) containing global parameter information.

\item[\dusa{FLUNAM}] {\tt character*12} name of the reference \dds{flux} (type {\tt
L\_FLUX}). By default, the reference flux is not recovered and not written on the {\sc saphyb}.

\item[\dusa{SAPRHS}] {\tt character*12} name of the {\sl read-only} {\sc saphyb} data structure. This
data structure is concatenated to \dusa{SAPNAM} using the \dusa{saphyb\_data3} data structure,
as presented in \Sect{descsap3}. \dusa{SAPRHS} must be defined with the same number of energy
groups and the same number of homogeneous regions as \dusa{SAPNAM}. Moreover, all the
global and local parameters of \dusa{SAPRHS} must be defined in \dusa{SAPNAM}. \dusa{SAPNAM}
may be defined with {\sl global} parameters not defined in \dusa{SAPRHS}.

\item[\dusa{saphyb\_data1}] input data structure containing initialization information (see \Sect{descsap1}).

\item[\dusa{saphyb\_data2}] input data structure containing information related to the recovery of an
elementary calculation (see \Sect{descsap2}).

\item[\dusa{saphyb\_data3}] input data structure containing information related to the catenation of one or many
{\sl read-only} {\sc saphyb} (see \Sect{descsap3}).

\end{ListeDeDescription}

\newpage

\subsubsection{Initialization data input for module {\tt SAP:}}\label{sect:descsap1}

\begin{DataStructure}{Structure \dstr{saphyb\_data1}}
$[$~\moc{EDIT} \dusa{iprint}~$]$ \\
$[$~\moc{NOML}~\dusa{nomlib}~$]$ \\
$[$~\moc{COMM}~$[[$~\dusa{comment}~$]]$~\moc{ENDC}~$]$ \\
$[[$~\moc{PARA}~\dusa{parnam}~\dusa{parkey} \\
~~~\{~\moc{TEMP}~\dusa{micnam}~\dusa{imix}~$|$~\moc{CONC}~\dusa{isonam1}~\dusa{micnam}~\dusa{imix}~$|$~\moc{IRRA}~$|$~\moc{FLUB}~$|$ \\
~~~~~~\moc{PUIS}~$|$~\moc{MASL}~$|$~\moc{FLUX}~$|$~\moc{TIME}~$|$~\moc{VALE}~\{~\moc{FLOT}~$|$~\moc{CHAI}~$|$~\moc{ENTI}~\}~\} \\
$]]$ \\
$[[$~\moc{LOCA}~\dusa{parnam}~\dusa{parkey} \\
~~~\{~\moc{TEMP}~$|$~\moc{CONC}~\dusa{isonam2}~$|$~\moc{IRRA}~$|$~\moc{FLUB}~$|$~~\moc{FLUG}~$|$~\moc{PUIS}~$|$~\moc{MASL}~$|$~\moc{FLUX}~$|$~\moc{EQUI}~\} \\
$]]$ \\
$[$~\moc{ISOT}~\{~\moc{TOUT}~$|$ \moc{MILI}~\dusa{imil}~$|~[$~\moc{FISS}~$]~[$~\moc{PF}~$]~[$~(\dusa{HNAISO}(i),~i=1,$N_{\rm iso}$) $]$~\}~$]$ \\
$[[$~\moc{MACR}~\dusa{HNAMAC}~\{~\moc{TOUT}~$|$~\moc{REST}~\}~$]]$ \\
$[$~\moc{REAC}~(\dusa{HNAREA}(i),~i=1,$N_{\rm reac}$) $]$ \\
$[$ \moc{NAME} (\dusa{HNAMIX}(i),~i=1,$N_m$) $]$ \\
{\tt ;}
\end{DataStructure}

\goodbreak
\noindent where
\begin{ListeDeDescription}{mmmmmmmm}

\item[\moc{EDIT}] key word used to set \dusa{iprint}.

\item[\dusa{iprint}] index used to control the printing in module {\tt
SAP:}. =0 for no print; =1 for minimum printing (default value).

\item[\moc{NOML}] key word used to input a user--defined name for the {\sc saphyb}. This information is mandatory
if the Saphyb is to be read by the Lisaph module of Cronos.

\item[\dusa{nomlib}] {\tt character*80} user-defined name.

\item[\moc{COMM}] key word used to input a general comment for the {\sc saphyb}.

\item[\dusa{comment}] {\tt character*80} user-defined comment.

\item[\moc{ENDC}] end--of--comment key word.

\item[\moc{PARA}] keyword used to define a single global parameter.

\item[\moc{LOCA}] keyword used to define a single local variable (a local variable
may be a single value or an array of values).

\item[\dusa{parnam}] {\tt character*80} user-defined name of a global parameter or
local variable.

\item[\dusa{parkey}] {\tt character*4} user-defined keyword associated to a global
parameter or local variable.

\item[\dusa{micnam}] {\tt character*12} name of the \dds{microlib} (type {\tt
L\_LIBRARY}) associated to a global parameter. The corresponding \dds{microlib} will be required on
RHS of the \moc{SAP:} call described in Sect.~\ref{sect:descsap2}.

\item[\dusa{imix}] index of the mixture associated to a global parameter. This mixture is
located in \dds{microlib} named \dusa{micnam}.

\item[\dusa{isonam1}] {\tt character*8} alias name of the isotope associated to a global
parameter. This isotope is located in \dds{microlib} data structure named \dusa{micnam}.

\item[\dusa{isonam2}] {\tt character*8} alias name of the isotope associated to a local
variable. This isotope is located in the \dds{microlib} directory of the {\sc edition}
data structure named \dusa{EDINAM}.

\item[\moc{TEMP}] keyword used to define a temperature (in $^{\rm o}$C) as global parameter or
local variable.

\item[\moc{CONC}] keyword used to define a number density as global parameter or
local variable.

\item[\moc{IRRA}] keyword used to define a burnup (in MWday/Tonne) as global
parameter or local variable.

\item[\moc{FLUB}] keyword used to define a {\sl fuel-only} exposure rate (in n/kb) as global
parameter or local variable. The exposure rate is recovered from the \dusa{BRNNAM}
LCM object.

\item[\moc{FLUG}] keyword used to define an exposure rate in global homogenized mixtures (in n/kb) as
local variable. The exposure rate is recovered from the \dusa{BRNNAM}
LCM object.

\item[\moc{PUIS}] keyword used to define the power as global parameter or
local variable.

\item[\moc{MASL}] keyword used to define the mass density of heavy isotopes as
global parameter or local variable.

\item[\moc{FLUX}] keyword used to define the volume-averaged, energy-integrated flux as
global parameter or local variable.

\item[\moc{TIME}] keyword used to define the time (in seconds) as global parameter.

\item[\moc{EQUI}] keyword used to define the SPH equivalence factors as
local variable. A set of SPH factors can be defined as local
variables. Note that the cross sections and fluxes stored in the {\sc saphyb} are
{\sl not} SPH corrected.

\item[\moc{VALE}] keyword used to define a user-defined quantity as global parameter.
This keyword must be followed by the type of parameter.

\item[\moc{FLOT}] keyword used to indicate that the user-defined global parameter
is a floating point value.

\item[\moc{CHAI}] keyword used to indicate that the user-defined global parameter
is a {\tt character*12} value.

\item[\moc{ENTI}] keyword used to indicate that the user-defined global parameter
is an integer value.

\item[\moc{ISOT}] keyword used to select the set of particularized isotopes.

\item[\moc{TOUT}] keyword used to select all the available isotopes in the reference
\dds{microlib} named \dusa{HMIC} as particularized isotopes.

\item[\moc{MILI}] keyword used to select the isotopes in the reference
\dds{microlib} named \dusa{HMIC} from a specific mixture as particularized isotopes.

\item[\dusa{imil}] index of the mixture where the particularized isotopes are recovered.

\item[\moc{FISS}] keyword used to select all the available fissile isotopes in the reference
\dds{microlib} named \dusa{HMIC} as particularized isotopes.

\item[\moc{PF}] keyword used to select all the available fission products in the reference
\dds{microlib} named \dusa{HMIC} as particularized isotopes.

\item[\dusa{HNAISO}(i)] {\tt character*12} user-defined isotope name. $N_{\rm iso}$ is the
total number of explicitely--selected particularized isotopes.

\item[\moc{MACR}] keyword used to select a type of macroscopic set. A maximum of two macroscopic sets is allowed.

\item[\dusa{HNAMAC}] {\tt character*8} user-defined name of the macroscopic set.

\item[\moc{TOUT}] keyword used to select all the available isotopes in the macroscopic set.

\item[\moc{REST}] keyword used to remove all the particularized isotope contributions
from the macroscopic set.

\item[\moc{REAC}] keyword used to select the set of nuclear reactions.

\item[\dusa{HNAREA}(i)] {\tt character*4} name of a user-selected reaction. $N_{\rm reac}$
is the total number of selected reactions. \dusa{HNAREA}(i)
is chosen among the following values:

\begin{tabular}{p{1.0cm} p{16cm}|}
\moc{TOTA} & Total cross sections \\
\moc{TOP1} & Total $P_1$-weighted cross sections \\
\moc{ABSO} & Absorption cross sections \\
\moc{SNNN} & Excess cross section due to (n,$x$n) reactions \\
\moc{FISS} & Fission cross section \\
\moc{CHI}  & Steady-state fission spectrum \\
\moc{NUFI} & $\nu\Sigma_{\rm f}$ cross sections \\
\moc{ENER} & Energy production cross section, taking into account all energy production reactions \\
\moc{EFIS} & Energy production cross section for (n,f) reaction only \\
\moc{EGAM} & Energy production cross section for (n,$\gamma$) reaction only \\
\moc{FUIT} & $B^2$ times the leakage coefficient \\
\moc{SELF} & within-group $P_0$ scattering cross section \\
\moc{DIFF} & scattering cross section for each available Legendre order. These cross sections
are \\
& {\sl not} multiply by the $2\ell+1$ factor.\\
\moc{PROF} & profile of the transfer cross section matrices (i.e. position of the non--zero element in \\
& the transfer cross section matrices) \\
\moc{TRAN} & transfer cross section matrices for each available Legendre order. These cross sections \\
& are multiply by the $2\ell+1$ factor.\\
\moc{CORR} & transport correction. Note that the cross sections stored in the {\sc saphyb} are {\sl not} \\
& transport corrected.\\
\moc{STRD} & STRD cross sections used to compute the diffusion coefficients \\
\moc{NP}   & (n,p) production cross sections \\
\moc{NT}   & (n,t) production cross sections \\
\moc{NA}   & (n,$\alpha$) production cross sections \\
\end{tabular}

\item[\moc{NAME}] key word used to define mixture names. By default, mixtures
names are of the form \dusa{HNAMIX}(i), where
\begin{verbatim}
WRITE(HNAMIX(I),'(3HMIX,I5.5)') I
\end{verbatim}

\item[\dusa{HNAMIX}(i)] Character*20 user-defined mixture name. $N_m$ is the number of mixtures. 

\end{ListeDeDescription}

\subsubsection{Modification data input for module {\tt SAP:}}\label{sect:descsap2}

\begin{DataStructure}{Structure \dstr{saphyb\_data2}}
$[$ \moc{EDIT} \dusa{iprint} $]$ \\
$[$ \moc{CRON} $]$ \\
$[[$ \dusa{parkey} \dusa{value} $]]$ \\
$[$ \moc{ORIG} \dusa{orig} $]$ \\
$[$ \moc{SET} \dusa{xtr} $\{$ \moc{S} $|$ \moc{DAY} $|$ \moc{YEAR} $\}$ $]$ \\
$[$ \moc{ICAL} {\tt >>} \dusa{ical} {\tt <<} $]$ \\
{\tt ;}
\end{DataStructure}

\goodbreak
\noindent where
\begin{ListeDeDescription}{mmmmmmmm}

\item[\moc{EDIT}] key word used to set \dusa{iprint}.

\item[\dusa{iprint}] index used to control the printing in module {\tt
SAP:}. =0 for no print; =1 for minimum printing (default value).

\item[\moc{CRON}] key word used to force the kinetics data to be placed into the {\tt divers} directory. By default,
the kinetics data is placed in the {\tt cinetique} directory of each mixture subdirectory. The \moc{CRON} option can
only be used if the Saphyb contains a unique mixture. This option is mandatory if the Saphyb is to be read by the Lisaph
module of Cronos.

\item[\dusa{parkey}] {\tt character*4} keyword associated to a user-defined global
parameter.

\item[\dusa{value}] floating-point, integer or {\tt character*12} value of a user-defined
global parameter.

\item[\moc{ORIG}] key word used to define the father node in the global parameter tree. By
default, the index of the previous elementary calculation is used.

\item[\dusa{orig}] index of the elementary calculation associated to the father node in the
global parameter tree.

\item[\moc{SET}] keyword used to recover the flux normalization factor already
stored on \dusa{BRNNAM} from a sub-directory corresponding to a specific time.

\item[\dusa{xtr}] time associated with the current flux calculation. The
name of the sub-directory where this information is stored will be given by
`{\tt DEPL-DAT}'//{\tt CNN} where {\tt CNN} is a  {\tt character*4} variable
defined by  {\tt WRITE(CNN,'(I4)') INN} where {\tt INN} is an index associated
with the time \dusa{xtr}.

\item[\moc{S}] keyword to specify that the time is given in seconds.

\item[\moc{DAY}] keyword to specify that the time is given in days.

\item[\moc{YEAR}] keyword to specify that the time is given in years.

\item[\moc{ICAL}]  keyword used to recover the last calculation index.

\item[\dusa{ical}] \texttt{character*12} CLE-2000 variable name in which the last calculation index will be placed.

\end{ListeDeDescription}

\subsubsection{Modification (catenate) data input for module {\tt SAP:}}\label{sect:descsap3}

\vskip -0.5cm

\begin{DataStructure}{Structure \dstr{saphyb\_data3}}
$[$ \moc{EDIT} \dusa{iprint} $]$ \\
$[$ \moc{ORIG} \dusa{orig} $]$ \\
$[[$ \dusa{parkey} \dusa{value} $]]$ \\
$[$ \moc{WARNING-ONLY} $]$ \\
{\tt ;}
\end{DataStructure}

\noindent where
\begin{ListeDeDescription}{mmmmmmmm}

\item[\moc{EDIT}] keyword used to set \dusa{iprint}.

\item[\dusa{iprint}] index used to control the printing in module {\tt
SAP:}. =0 for no print; =1 for minimum printing (default value).

\item[\dusa{parkey}] {\tt character*4} .keyword associated to a
global parameter that is specific to \dusa{SAPNAM} (not defined in \dusa{SAPRHS}).

\item[\dusa{value}] floating-point, integer or {\tt character*12} value of a user-defined
global parameter.

\item[\moc{ORIG}] keyword used to define the father node in the parameter tree. By
default, the index of the previous elementary calculation is used.

\item[\dusa{orig}] index of the elementary calculation associated to the father node in the
parameter tree.

\item[\moc{WARNING-ONLY}] This option is useful if an elementary calculation in \dusa{SAPRHS} 
is already present in \dusa{SAPNAM}. If this keyword is set, a warning is send and the \dusa{SAPNAM} values
are kept, otherwise the run is aborted (default).

\end{ListeDeDescription}

\clearpage