From 7dfcc480ba1e19bd3232349fc733caef94034292 Mon Sep 17 00:00:00 2001
From: stainer_t <thomas.stainer@oecd-nea.org>
Date: Mon, 8 Sep 2025 13:48:49 +0200
Subject: Initial commit from Polytechnique Montreal

---
 doc/IGE344/SectMCR.tex | 326 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 326 insertions(+)
 create mode 100644 doc/IGE344/SectMCR.tex

(limited to 'doc/IGE344/SectMCR.tex')

diff --git a/doc/IGE344/SectMCR.tex b/doc/IGE344/SectMCR.tex
new file mode 100644
index 0000000..51b49b7
--- /dev/null
+++ b/doc/IGE344/SectMCR.tex
@@ -0,0 +1,326 @@
+\subsection{The {\tt MCR:} module}\label{sect:MCRData}
+
+The Multiparameter Output file (MPO) contains the results obtained by a set of APOLLO3 calculation steps as well as restart data.
+
+The MPO 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 MPO file, the reactor database produced by APOLLO3.\cite{apollo3}
+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{MCR:}}
+\dusa{MLIB}~\moc{:=}~\moc{MCR:}~$[~\{$~\dusa{MLIB} $|$ \dusa{MLIB2}~$\}~]$ \dusa{MPONAM1} $[[$~\dusa{MPONAM2}~$]]~[$~\dusa{MAPFL}~$]$~\moc{::}~\dstr{mcr\_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{MCR:}, 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{MPONAM1}] {\tt character*12} name of the {\sc hdf5} file containing the {\sc mpo} data structure.
+
+\item[\dusa{MPONAM2}] {\tt character*12} name of an additional {\sc hdf5} file containing an auxiliary
+{\sc mpo} 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{mcr\_data}.
+
+\item[\dusa{mcr\_data}] input data structure containing interpolation information (see \Sect{descmcr}).
+
+\end{ListeDeDescription}
+
+\subsubsection{Interpolation data input for module {\tt MCR:}}\label{sect:descmcr}
+
+\vskip -0.5cm
+
+\begin{DataStructure}{Structure \dstr{mcr\_data}}
+$[$~\moc{EDIT} \dusa{iprint}~$]$ \\
+$[$~\moc{RES} $]~[$~\moc{PURE}~$]~[$~\moc{UPS}~$]$ \\
+$[~\{$~\moc{MACRO}~$|$~\moc{MICRO}~$\}~]~[~\{$~\moc{LINEAR}~$|$~\moc{CUBIC}~$\}~]~[$~\moc{LEAK}~\dusa{b2}~$]~[$~\moc{EQUI}~\dusa{text80}~$]~[$~\moc{MASL}~\dusa{text80}~$]$  \\
+$[$~\moc{NMIX} \dusa{nmixt}~$]~[$ \moc{MDF} $]$ \\
+$\{~[[$~\moc{MPO} \dusa{MPONAM} \dusa{NAMDIR} \dstr{MCRdescints}~$]]$ \\
+$~|~[[$~\moc{TABLE} \dusa{MPONAM} \dusa{NAMDIR} $[$ \dusa{namburn} $[$ \dusa{naval} $]~]$ \dstr{MCRdescints}~$]]~\}$ \\
+$[$ \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 MCR:}. =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{MCRdescints} input data structure (see \Sect{MCRdescints}).
+
+\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 a MPO 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{LINEAR}] keyword indicating that interpolation of the {\sc mpo} uses linear Lagrange polynomials (default option).
+
+\item[\moc{CUBIC}] keyword indicating that interpolation of the {\sc mpo} 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 MPO file. By default, the cross sections and diffusion coefficients
+are not SPH-corrected.
+
+\item[\moc{MASL}] keyword used to recover the heavy metal density in the local parameter data of the MPO file. 
+
+\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{mcr\_data}.
+
+\item[\moc{MDF}] keyword used to store non-matrix discontinuity factors and albedos into $G\times G$ matrices. By default, non-matrix information is stored into vectors.
+
+\item[\moc{MPO}] keyword used to set \dusa{MPONAM} and to define each global parameter.
+
+\item[\moc{TABLE}] keyword used to set \dusa{MPONAM} and to recover some global parameter from a {\sc map} object named \dusa{MAPFL}.
+
+\item[\dusa{MPONAM}] {\tt character*12} name of the {\sc lcm} object containing the
+{\sc mpo} data structure where the interpolation is performed. This name must be set in the RHS of structure \dstr{MCR:}.
+
+\item[\dusa{NAMDIR}] access the {\sc mpo} output group named \dusa{NAMDIR}. This name is the concatenation of prefix {\tt 'output\_'} with an integer $\ge 0$.
+If the value is set equal to {\tt 'default'}, it will be replaced by {\tt 'output\_0'}.
+
+\item[\dusa{namburn}] {\tt character*12} 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{MCRdescints}] input data structure containing interpolation information relative to the {\sc mpo} data structure named \dusa{MPONAM} (see \Sect{MCRdescints}).
+
+\item[\dstr{descdepl}] input structure describing the depletion chain (see \Sect{MCRdescdepld}). 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:MCRdescints}
+
+\vskip -0.5cm
+
+If a {\sc map} object is defined on the RHS of structure \dstr{MCR:}, 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 MCR:} operator search the {\sc mpo} 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{MCRdescints} is a data structure specified as
+
+\begin{DataStructure}{Structure \dstr{MCRdescints}}
+$[[$~\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 zone\_}//\dusa{imixold} in the {\sc mpo} file. By default, group {\tt zone\_0} is recovered.
+
+\item[\dusa{imixold}] index of the mixture that is recovered in the {\sc mpo} file.
+
+\item[\moc{USE}] keyword used to set the index of the mixture from group {\tt zone\_}//\dusa{imix} in the {\sc mpo} file. By default, group {\tt zone\_0} 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 mpo} 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:descmcr}.
+
+\item[\moc{CUBIC}] keyword indicating that interpolation of the {\sc mpo} 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:descmcr}.
+
+\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 mpo} 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 mpo} file will be used in the {\sc microlib} and {\sc macrolib} objects. Concentrations of these isotopes will be recovered from the {\sc mpo} 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 mpo} 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:MCRdescdepld}
+
+Part of the depletion data used in the isotopic depletion calculation (the fission yields and the
+radioactive decay constants) is recovered from the MPO 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 MPO 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 MPO 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 := MCR: MPOFILE ::
+   EDIT 40 NMIX 1 MPO MPOFILE output_0
+   MIX 1  !(* delta sigma contribution *)
+          SET 'CELL' '3D'
+          DELTA 'PITCH' 0.0 1.0
+   ENDMIX
+;
+\end{verbatim}
+
+\clearpage
-- 
cgit v1.2.3

