path: root/doc/IGE344/SectACR.tex

\subsection{The {\tt ACR:} module}\label{sect:ACRData}

The APOLLO2 Portable data EXchange file (APEX) contains the results obtained by a set of APOLLO2 calculation steps as well as restart data.

The APEX file is written in {\sc hdf5} format, allowing full portability and hierarchical data organization. It can be edited and modified using
the HDFView tool.

This file constitutes a natural boundary between the spectral code and the downstream codes. Particularly, it contains all the data needed by the
code in charge of cross-sections (XS) library generation for 3D core simulators.
Each elementary calculation is characterized by a set of parameters. Parameterization allows external codes building their own XS representation
by defining XS dependencies through appropriate functions or laws. For instance, standard parameters for PWR reactors are burn-up, water temperature,
water density, boron concentration, xenon concentration, fuel temperature and history parameters. BWR specific parameters are instant void fraction and
void history.

This component of DONJON is dedicated to the interpolation of {\sc macrolib} data from an APEX file, the reactor database produced by APOLLO2-A.\cite{apollo2A}
A set of {\sl global parameters} are defined for each material mixture and used as multi-dimensional interpolation variables.

\vskip 0.02cm

The calling specifications are:

\begin{DataStructure}{Structure \dstr{ACR:}}
\dusa{MLIB}~\moc{:=}~\moc{ACR:}~$[~\{$~\dusa{MLIB} $|$ \dusa{MLIB2}~$\}~]$ \dusa{APXNAM1} $[[$~\dusa{APXNAM2}~$]]~[$~\dusa{MAPFL}~$]$~\moc{::}~\dstr{acr\_data} \\
\end{DataStructure}

\noindent where
\begin{ListeDeDescription}{mmmmmmm}

\item[\dusa{MLIB}] {\tt character*12} name of a {\sc microlib} (type {\tt L\_LIBRARY}) or {\sc macrolib} (type {\tt L\_MACROLIB}) containing the interpolated data.
If this object also appears on the RHS of structure \dstr{ACR:}, it is open in modification mode and updated.

\item[\dusa{MLIB2}] {\tt character*12} name of an optional {\sc microlib} object whose content is copied on \dusa{MLIB}.

\item[\dusa{APXNAM1}] {\tt character*12} name of the {\sc hdf5} file containing the {\sc apex} data structure.

\item[\dusa{APXNAM2}] {\tt character*12} name of an additional {\sc hdf5} file containing an auxiliary
{\sc apex} data structure. This object is optional.

\item[\dusa{MAPFL}] {\tt character*12} name of the {\sc map} object containing fuel regions description, global parameter
information (burnup, fuel/coolant temperatures, coolant density, etc). Keyword \moc{TABLE} is expected in \dstr{acr\_data}.

\item[\dusa{acr\_data}] input data structure containing interpolation information (see \Sect{descacr}).

\end{ListeDeDescription}

\subsubsection{Interpolation data input for module {\tt ACR:}}\label{sect:descacr}

\vskip -0.5cm

\begin{DataStructure}{Structure \dstr{acr\_data}}
$[$~\moc{EDIT} \dusa{iprint}~$]$ \\
$[$~\moc{RES} $]~[$~\moc{PURE}~$]~[$~\moc{UPS}~$]$ \\
$[~\{$~\moc{MACRO}~$|$~\moc{MICRO}~$[$ \moc{TOTAL} $]~\}~]~[~\{$~\moc{LINEAR}~$|$~\moc{CUBIC}~$\}~]~[$~\moc{LEAK}~\dusa{b2}~$]~[$~\moc{EQUI}~\dusa{text80}~$]$ \\
$[$~\moc{NMIX} \dusa{nmixt}~$]$ \\
$\{~[[$~\moc{APEX} \dusa{APXNAM} \dstr{ACRdescints}~$]]~|~[[$~\moc{TABLE} \dusa{APXNAM} $[$ \dusa{namburn} $[$ \dusa{naval} $]~]$ \dstr{ACRdescints}~$]]~\}$ \\
$[$ \dstr{descdepl} $]$ \\
{\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 ACR:}. =0 for no print; =1 for minimum printing (default value).
 
\item[\moc{RES}] keyword indicating that the interpolation is done only for the microscopic cross sections and not for the isotopic densities. In this case, a RHS {\sc microlib} must be defined and the number densities are recovered from it. This option is useful for micro-depletion applications. {\bf Important note:} It is possible to force interpolation of some isotopic densities with \moc{RES} option if these
isotopes are explicitely specified with a ``\moc{*}'' flag after \moc{MICRO} keyword in \dusa{ACRdescints} input data structure (see \Sect{ACRdescints}).

\item[\moc{PURE}] keyword indicating that the interpolation is a pure linear combination of terp factors. The fission spectra are {\sl not}
renormalized. By default, non-linear effects are produced by renormalization operations.

\item[\moc{UPS}] keyword to specify that the macrolib and/or microlib cross sections recovered from an APEX file are
corrected so as to eliminate up-scattering. This option is useful for reactor analysis codes which cannot
take into account such cross sections.

\item[\moc{MACRO}] keyword indicating that \dusa{MLIB} is a {\sc macrolib} (default option).

\item[\moc{MICRO}] keyword indicating that \dusa{MLIB} is a {\sc microlib}. Object \dusa{MLIB} contains an embedded {\sc macrolib}, but the CPU time required to obtain it is longer.

\item[\moc{TOTAL}] keyword to force using the total macroscopic set {\tt xs/mac/TOTAL} of the Apex file. By default, the residual
macroscopic set {\tt xs/mac/RESIDUAL} is used together with microscopic cross-section information available in the {\tt xs/mic/} group.

\item[\moc{LINEAR}] keyword indicating that interpolation of the {\sc apex} uses linear Lagrange polynomials (default option).

\item[\moc{CUBIC}] keyword indicating that interpolation of the {\sc apex} uses the Ceschino method
with cubic Hermite polynomials, as presented in Ref.~\citen{Intech2011}.

\item[\moc{LEAK}] keyword used to introduce leakage in the embedded {\sc macrolib}. This option should only be used for non-regression tests.

\item[\dusa{b2}] the imposed buckling corresponding to the leakage.

\item[\moc{EQUI}] keyword used to select a SPH factor set in the Apex file. By default, the cross sections and diffusion coefficients
are not SPH-corrected.

\item[\dusa{text80}] {\tt character*80} name of the SPH factor set.

\item[\moc{NMIX}] keyword used to define the maximum number of material mixtures. This information is required only if \dusa{MLIB} is created.

\item[\dusa{nmixt}] the maximum number of mixtures (a mixture is characterized by a distinct set of 
macroscopic cross sections) the {\sc macrolib} may contain. The default value is \dusa{nmixt} $=0$ or the value recovered from \dusa{MLIB} if it appears on the RHS
of structure \dstr{acr\_data}.

\item[\moc{APEX}] keyword used to set \dusa{APXNAM} and to define each global parameter.

\item[\moc{TABLE}] keyword used to set \dusa{APXNAM} and to recover some global parameter from a {\sc map} object named \dusa{MAPFL}.

\item[\dusa{APXNAM}] {\tt character*12} name of the {\sc lcm} object containing the
{\sc apex} data structure where the interpolation is performed. This name must be set in the RHS of structure \dstr{ACR:}.

\item[\dusa{namburn}] {\tt character*24} name of the parameter for burnup (or irradiation).
This value is defined if option \moc{TABLE} is set {\sl and} if burnup (or irradiation) is to be considered as parameter.

\item[\dusa{naval}] {\tt character*4} identification name corresponding to the basic naval-coordinate position of the assembly where burnups are recovered. The axial burnup distribution of this assembly is
used for interpolation. {\tt SIM} option should be set in module {\tt RESINI:} (see Sect.~\ref{sect:resinimain}). This option is useful to interpolate reflector properties as a function of the
neighbour fuel assembly burnup. By default, burnup values of the interpolated fuel assembly are used.

\item[\dusa{ACRdescints}] input data structure containing interpolation information relative to the {\sc apex} data structure named \dusa{APXNAM} (see \Sect{ACRdescints}).

\item[\dstr{descdepl}] input structure describing the depletion chain (see \Sect{ACRdescdepld}). This input structure requires option \moc{MICRO}. By
default, the depletion chain data is not written in the output {\sc microlib}.

\end{ListeDeDescription}

\subsubsection{Defining global parameters}\label{sect:ACRdescints}

\vskip -0.5cm

If a {\sc map} object is defined on the RHS of structure \dstr{ACR:}, and if the \moc{TABLE} keyword is set, some information required to set the interpolation points is found in this object.
In this case, the {\tt ACR:} operator search the {\sc apex} file for global parameters  having an arbitrary name specified in the {\sc map} object or set directly in this module.
Note that any parameter's value set directly in this module prevails on a value stored in the \dusa{MAPFL} object.

Each instance of \dusa{ACRdescints} is a data structure specified as

\begin{DataStructure}{Structure \dstr{ACRdescints}}
$[[$~\moc{MIX} \dusa{imix}~$[~\{$~\moc{FROM}~\dusa{imixold}~$|$~\moc{USE}~$\}~]$ \\
~~~~~~$[~\{$~\moc{TIMAV-BURN} $|$ \moc{INST-BURN} $|$ \moc{AVG-EX-BURN}~\dusa{ivarty}~$\}~]$ \\
~~~~~~$[[~\{$~\moc{SET} $|$ \moc{DELTA} $|$ \moc{ADD}~$\}~\}~[~\{$ \moc{LINEAR} $|$ \moc{CUBIC}~$\}~]$ \dusa{PARKEY} $\{$~\dusa{val1} $|$ \moc{MAP}~$\}~[~\{$~\dusa{val2} $|$ \moc{MAP}~$\}~]$ \\
~~~~~~~~~~~~$[$~\moc{REF} $[[$~\dusa{PARKEY}~$\{$~\dusa{valref} $|$ \moc{SAMEASREF}~$\}$~$]]$~\moc{ENDREF}~$]~]]$  \\
~~~~~~$[$~\moc{MICRO}~$\{$~\moc{ALL} $|$ \moc{ONLY}~$\}~[[$~\dusa{HISO} $\{$ \dusa{conc} $|$ \moc{*} $\}~[$ \moc{NOEV} $]~]]~]$ \\
\moc{ENDMIX}~$]]$
\end{DataStructure}

\noindent where
\begin{ListeDeDescription}{mmmmmmmm}

\item[\moc{MIX}] keyword used to set \dusa{imix}.

\item[\dusa{imix}] index of the mixture that is to be created in the {\sc microlib} and {\sc macrolib}.

\item[\moc{FROM}] keyword used to set the index of the mixture from group {\tt xs}//\dusa{imixold} in the {\sc apex} file. By default, group {\tt xs} is recovered.

\item[\dusa{imixold}] index of the mixture that is recovered in the {\sc apex} file.

\item[\moc{USE}] keyword used to set the index of the mixture from group {\tt xs}//\dusa{imix} in the {\sc apex} file. By default, group {\tt xs} is recovered.

\item[\moc{TIMAV-BURN}] keyword used to compute time-averaged cross-section information. This option is available {\sl only if} a \dusa{MAPFL} object is set.
By default, the type of calculation (\moc{TIMAV-BURN} or \moc{INST-BURN}) is recovered from the \dusa{MAPFL} object.

\item[\moc{INST-BURN}] keyword used to compute cross-section information at specific bundle burnups. This option is available {\sl only if} a \dusa{MAPFL} object is set.
By default, the type of calculation (\moc{TIMAV-BURN} or \moc{INST-BURN}) is recovered from the \dusa{MAPFL} object.

\item[\moc{AVG-EX-BURN}] keyword used to compute the derivatives of cross-section information relative to the exit burnup of a single combustion zone. The derivatives are computed using Eq.~(3.3) of Ref.~\citen{chambon}, written as
$$
{\partial \bar\Sigma_x\over \partial B_j^{\rm e}}={1\over B_j^{\rm e}\, (B_{j,k}^{\rm eoc}-B_{j,k}^{\rm boc})}
\left[- \int_{B_{j,k}^{\rm boc}}^{B_{j,k}^{\rm eoc}}dB \, \Sigma_x(B)+B_{j,k}^{\rm eoc}\, \Sigma_x(B_{j,k}^{\rm eoc})-B_{j,k}^{\rm boc}\, \Sigma_x(B_{j,k}^{\rm boc})\right]
$$

\noindent where $B_{j,k}^{\rm boc}$, $B_{j,k}^{\rm eoc}$, and $B_j^{\rm e}$ are the beginning of cycle burnup of bundle $\{j,k\}$, end of cycle burnup of bundle $\{j,k\}$ and exit burnup of channel $j$. This option is available {\sl only if} a \dusa{MAPFL} object is set.
By default, the type of calculation (\moc{TIMAV-BURN} or \moc{INST-BURN}) is recovered from the \dusa{MAPFL} object.

\item[\dusa{ivarty}] index of the combustion zone for differentiation of cross-section information.

\item[\moc{SET}] keyword used to indicate a simple interpolation at \dusa{val1} or an averaging between \dusa{val1} and \dusa{val2}. The result $\sigma_{\rm ref}$ is also used as the reference value when the \moc{ADD} is used. Note: see at the ending note of this section for a detailed description and examples.

\item[\moc{DELTA}] keyword used to indicate a delta-sigma calculation between \dusa{val2} and \dusa{val1}
(i.e., $\Delta\sigma_{\rm ref}=\sigma_{\rm val2}-\sigma_{\rm val1}$ is computed). This keyword can be used only once in each mixture data block (initiated
with a \moc{MIX} keyword). Note: see at the ending note of this section for a detailed description and examples.

\item[\moc{ADD}] keyword used to indicate a delta-sigma calculation between \dusa{val2} and \dusa{val1} is added to the reference value
(i.e., $\Delta\sigma=\sigma_{\rm val2}-\sigma_{\rm val1}$ is used as contribution, $\sigma_{\rm ref}+\Delta\sigma$ or $\Delta\sigma_{\rm ref}+\Delta\sigma$ is returned). Note: see at the ending note of this section for a detailed description and examples.

\item[\moc{LINEAR}] keyword indicating that interpolation of the {\sc apex} for parameter \dusa{PARKEY} uses linear Lagrange
polynomials. It is possible to set different interpolation modes to different parameters. By default, the interpolation mode is set in Sect.~\ref{sect:descacr}.

\item[\moc{CUBIC}] keyword indicating that interpolation of the {\sc apex} for parameter \dusa{PARKEY} uses the Ceschino method
with cubic Hermite polynomials, as presented in Ref.~\citen{Intech2011}. By default, the interpolation mode is set in Sect.~\ref{sect:descacr}.

\item[\dusa{PARKEY}] {\tt character*24} user-defined keyword associated to a global
parameter to be set.

\item[\dusa{val1}] value of a global parameter used to interpolate. \dusa{val1} is the initial value of this parameter in case an average is required. \dusa{val1} can be an integer, real or string value.

\item[\dusa{val2}] value of the final global parameter. By default, a simple interpolation is performed, so that \dusa{val2}$=$\dusa{val1}. \dusa{val2} is always a real value with \dusa{val2}$\ge$\dusa{val1}.

\item[\moc{MAP}] keyword used to indicate that the value of parameter \dusa{val1} or the second value for the $\Delta\sigma$ calculation is
recovered from \dusa{MAPFL}, i.e. the {\sc map} object containing fuel regions description.

\item[\moc{REF}] keyword only available together with the \moc{ADD} option. It is used to set all the other variable values when a $\Delta$ contribution is performed for one variable.  

\item[\dusa{valref}] value of the reference parameter, when it is directly given by the user. Note that there is no default value.

\item[\moc{SAMEASREF}] keyword used to specify that the reference value will be the same as in the refence case, i.e. for the $\sigma_{\rm ref}$ computation.

\item[\moc{ENDREF}] keyword only available together with the \moc{ADD} option. It is used to specify that all the other variable values which are required are given.  

\item[\moc{MICRO}] keyword used to set the number densities of some isotopes present in the {\sc apex} file. The data statement ``\moc{MICRO} \moc{ALL}" is used by default.

\item[\moc{ALL}] keyword to indicate that all the isotopes present in the {\sc apex} file will be used in the {\sc microlib} and {\sc macrolib} objects. Concentrations of these isotopes will be recovered from the {\sc apex} file or set using
the ``\dusa{HISO} \dusa{conc}" data statement.

\item[\moc{ONLY}] keyword to indicate that only the isotopes set using the ``\dusa{HISO} \dusa{conc}" data statement will be used in the {\sc microlib} and {\sc macrolib} objects.

\item[\dusa{HISO}] {\tt character*8} name of an isotope.

\item[\dusa{conc}] user-defined value of the number density (in $10^{24}$ particles per ${\rm cm}^3$) of the isotope.

\item[\moc{*}] the value of the number density for isotope \dusa{HISO} is recovered from the {\sc apex} file.

\item[\moc{NOEV}] keyword to force the isotope \dusa{HISO} to be non-depleting.

\item[\moc{ENDMIX}] end of specification keyword for the material mixture.

\end{ListeDeDescription}

\subsubsection{Depletion data structure}\label{sect:ACRdescdepld}

Part of the depletion data used in the isotopic depletion calculation (the fission yields and the
radioactive decay constants) is recovered from the Apex file. Remaining depletion data is
recovered from the input data structure \dstr{descdepl}. This data describes the heredity of the radioactive decay
and the neutron activation chain.

\begin{DataStructure}{Structure \dstr{descdepl}}
\moc{CHAIN} \\
\hskip 0.3cm $[[$ \dusa{NAMDPL} $[$ \dusa{izae} $]$ \\
\hskip 0.6cm $[[$ \dusa{reaction} $[$ \dusa{energy} $]~]]$ \\
\hskip 0.6cm $[~\{$ \moc{STABLE} $|$ \moc{FROM} $[[~\{$ \moc{DECAY} $|$ \dusa{reaction} $\}$
$[[$ \dusa{yield} \dusa{NAMPAR} $]]~]]~\}~]~]]$\\
\moc{ENDCHAIN}
\end{DataStructure}

\noindent
with:

\begin{ListeDeDescription}{mmmmmm}

\item[\moc{CHAIN}] keyword to specify the beginning of the depletion chain.

\item[\dusa{NAMDPL}] {\tt character*12} name of an isotope (or isomer) of the
depletion chain that appears as a particularized isotope of the Apex file.

\item[\dusa{izae}] optional six digit integer representing the isotope. The first two
digits represent the atomic number of the isotope; the next three indicate its
mass number and the last digit indicates the  excitation level of the nucleus (0
for a nucleus in its ground state, 1 for an isomer in its first exited state,
etc.). For example, $^{238}$U in its ground state will be represented by
\dusa{izae}=922380.

\item[\dusa{reaction}] {\tt character*6} identification of a neutron-induced
reaction that takes place either for production of this isotope, its depletion,
or for producing energy. Example of reactions are following:

\begin{ListeDeDescription}{mmmmmmmm}
\item[\moc{NG}] indicates that a radiative capture reaction takes place either
for production of this isotope, its depletion or for producing energy.

\item[\moc{N2N}] indicates that the following reaction is taking place:
$$ n +^{A}X_Z \to 2 n + ^{A-1}X_Z$$

\item[\moc{N3N}] indicates that the following reaction is taking place:
$$ n +^{A}X_Z \to 3 n + ^{A-2}X_Z$$

\item[\moc{N4N}] indicates that the following reaction is taking place:
$$ n +^{A}X_Z \to 4 n + ^{A-3}X_Z$$

\item[\moc{NP}] indicates that the following reaction is taking place:
$$ n +^{A}X_Z \to p + ^AY_{Z-1}$$

\item[\moc{NA}] indicates that the following reaction is taking place:
$$ n +^{A}X_Z \to ^4{\rm He}_2 + ^{A-3}X_{Z-2}$$

\item[\moc{NFTOT}] indicates that a fission is taking place.
\end{ListeDeDescription}

\item[\dusa{energy}] energy (in MeV) recoverable per neutron-induced
reaction of type \dusa{reaction}. If the energy associated to radiative capture
is not explicitely given, it should be added to the energy released per fission. By
default, \dusa{energy}=0.0 MeV.

\item[\moc{STABLE}] non depleting isotope. Such an isotope may produces
energy by neutron-induced reactions (such as radiative capture).

\item[\moc{FROM}] indicates that this isotope is produced from decay or
neutron-induced reactions.

\item[\moc{DECAY}] indicates that a decay reaction takes place for its
production.

\item[\dusa{yield}] branching ratio or production yield expressed in fraction.

\item[\dusa{NAMPAR}] {\tt character*12} name of the a parent isotope
(or isomer) that appears as a particularized isotope of the Apex file.

\item[\moc{ENDCHAIN}] keyword to specify the end of the depletion chain.

\end{ListeDeDescription}


\subsubsection{Interpolation in the parameter grid}

The following example corresponds to a delta-sigma computation in mixture 1 corresponding to a perturbation. Note that in this case, the \moc{MACROLIB} object  may content negative cross-section. 
\begin{verbatim}
MACROLIB := ACR: APEXFILE ::
   EDIT 40 NMIX 1 APEX APEXFILE
   MIX 1  !(* delta sigma contribution *)
          SET 'CELL' '3D'
          DELTA 'PITCH' 0.0 1.0
   ENDMIX
;
\end{verbatim}

\clearpage