{\noindent\Huge\bfseries User Guide - CLASS v3.0 }\\[2\baselineskip]% Title
{\large\textit{Core Library for Advanced Scenario Simulation}}\\[4\baselineskip]% Tagline or further description
{\Large\textsc{B. Mouginot\& B. LENIAU}}% Author name
{\Large\textsc{B. MOUGINOT\& B. LENIAU}}% Author name
\vspace{0.5\textheight}% Whitespace between the title block and the publisher
{\noindent CNRS:IN2P3:Subatech:Erdre }\\[\baselineskip]% Publisher and logo
...
...
@@ -55,28 +85,712 @@
\tableofcontents
\listoffigures
%\listoftables
%%%%%%%%%%%%%%%%%%%%%%%%%
%% CHAPTER : INTRODUCTION
%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Introduction}
code de scenar tatati c'est gnial a sert a a et a ...
donner le forge in2p3
\chapter{First Steps}
\section{Package Contents}
Ya quoi dans ce que je viens de downloader
\section{Install procedure}
Et comment que je l'install et commen,t je compile mon intput ...
First use example
\subsection{Requirement}
\begin{minipage}{\linewidth}
\begin{itemize}
\item User skills : Good knowledge of C++.
\item OS : CLASS is known to work under Linux (64 bits) and MacOSX (64 bits). It has never been tested on any Windows distribution.
\item Root (CERN) :
CLASS uses Root to store output data.
The graphical user interface CLASSGui is based on Root.
Some algorithms uses the TMVA module of Root.
\item C++ compiler : we recommend to use a gnu compiler like gcc4.8.
If your platform is DARWIN (Mackintosh OSX) we strongly recommend not to use the clang compiler\\
You should install macport. then types this following command in terminal :\\
\begin{lstlisting}[style=terminal]
sudo port install gcc48
sudo port select --set gcc mp-gcc48
\end{lstlisting}
\end{itemize}
\end{minipage}
\begin{center}
\line(1,0){250}
\end{center}
\begin{large}
\begin{center}
\textbf{IMPORTANT NOTE : }\\
\end{center}
\end{large}
The actual root package (version 5.34/20 ) and earlier (and maybe latter) has a memory leak issue when using TMVA leading to a \textbf{freeze of your computer.}
To avoid this dramatical error to happen do the following : \\
or \href{https://sft.its.cern.ch/jira/browse/ROOT-6551}{RootSupport}\footnote{https://sft.its.cern.ch/jira/browse/ROOT-6551}
indicates status solved then download and install the more recent ROOT version.\\
If the status is still unresolved proceed as follow : \\
Open with your favourite text editor the file \$ROOTSYS/tmva/src/Reader.cxx (\$ROOTSYS is the path to your ROOT installation folder) and replace the following :\\
Decompress the CLASS.tar.gz in your wanted location \footnote{\$CLASS\_PATH is the path of your CLASS installation folder}. Then type in terminal:\\
\begin{minipage}{\linewidth}
\begin{lstlisting}[style=terminal]
cd $CLASS_PATH/
mkdir lib
cd source/src
make -j
make install
\end{lstlisting}
\end{minipage}
Then to install the Graphical User Interface :
\begin{minipage}{\linewidth}
\begin{lstlisting}[style=terminal]
cd $CLASS_PATH/gui
mkdir bin
make -j
\end{lstlisting}
\end{minipage}
Finally add the following environment variables (in your .tcsh or .csh ):
\begin{minipage}{\linewidth}
\begin{lstlisting}
setenv CLASS_PATH YourPathToCLASS
setenv CLASS_lib ${CLASS_PATH}/lib
setenv CLASS_include ${CLASS_PATH}/source/include
setenv PATH ${PATH}:${CLASS_PATH}/bin/gui
\end{lstlisting}
\end{minipage}
\section{CLASS Execution}
CLASS is a set of C++ libraries, there is no CLASS binary file. A CLASS executable has to be build by user using objects and methods defined in the CLASS package. \\
The compilation line for generating your executable from a .cxx file is the following :
CLASS has a \href{https://forge.in2p3.fr/projects/classforge}{forge}\footnote{https://forge.in2p3.fr/projects/classforge} hosted by the IN2P3 where you can find :
\begin{itemize}
\item\href{https://forge.in2p3.fr/projects/classforge/boards}{A forum}\footnote{https://forge.in2p3.fr/projects/classforge/boards} where you are invited to post your trouble about CLASS installation and usage. You may find the answer to your trouble on a already posted thread.
\item\href{https://forge.in2p3.fr/projects/classforge/embedded/annotated.html}{A doxygen}\footnote{https://forge.in2p3.fr/projects/classforge/embedded/annotated.html} where all the CLASS objects and methods are defined and explained.
\item\href{https://forge.in2p3.fr/projects/classforge/news}{News}\footnote{https://forge.in2p3.fr/projects/classforge/news} : All the news related to CLASS
Reactor *PWR_MOX = new Reactor(log, PHYMOD, fabricationplant, Pool, creationtime, lifetime, cycletime, HMMass, BurnUp);
...
}
\end{lstlisting}
\end{minipage}
In this latter example a physics model called "PHYMOD" is defined, it contains the bateman solver "Solver" which is the Runge Kutta ($4^{th}$ order) method. The mean cross sections predictor, "XS", used is based on a Multi Layer Perceptron. The Equivalence Model "Equivalence" is the one used for PWR MOX fuels. The arguments of the 3 objects constructor are explained in its corresponding sections.
All the existing models are define in the following sections, furthermore, the way to build its own Model is presented.
The aim of an equivalence model is to predict the content of fissile element needed in a fuel to reach a given burn-up or to satisfied criticality conditions.
\subsection{Available Equivalence Models}
The CLASS package contains, for the moment, 4 different equivalence models where three are related to the building of fuels for a PWR-MOX and one to the building of PWR-UOX fuels :
\paragraph{PWR-MOX models :}
The following models returns the molar fraction $\%_{Pu}$ of plutonium needed to reach a given burn-up according to the plutonium isotopic composition available in stocks.
\subsubsection{Linear BU model : EQM\_LIN\_MOX }
@@@ enlever ??
@@@BAM
\subsubsection{Quadratic Model : EQM\_QUAD\_MOX}
The $\%_{Pu}$ is calculated according a quadratic model. See equation~\ref{eq:EQM_LIN}.
Where $n_{i}$ is the molar proportion (in $\%mol.$) of isotope $i$\footnote{from $^{238}Pu$ to $^{242}Pu$} in the fresh plutonium vector. $\alpha_{ij}$, $\alpha_{i}$ and $\alpha_{0}$ are the weights resulting from a minimization procedure and are related to one targeted burn-up and one fuel management. Furthermore, $^{241}Am$ from $^{241}Pu$ decay is not one of the considered component of the model ($n_{i}$), instead the model considers a fixed time since plutonium separation. For instance the $\alpha$ given in file \$CLASS\_PATH/DataBase/Equivalence/PWR\_MOX\_45GW\_3Batch\_2y.dat
are representative of a PWR-MOX with a maximal burn-up of $45GWd/tHM$, a fuel management of 3 batches, and a time between separation and irradiation of 2 years.
The file containing the weights is formatted as follow :
Where 238Pu stands for $\alpha_{^{238}Pu}$ and it is the first order weight related to the molar proportion of $^{238}Pu$ and $1$ is $\alpha_{0}$. The weights are in units of $\%mol. \cdot\%mol.^{-1}$ for $\alpha_{i}$ in units of $\%mol. \cdot\%mol.^{-2}$ for $\alpha_{ij}$ and in units of $\%mol.$ for $\alpha_{0}$. The Keyword "PARAM" has to be present in the file before the $\alpha$ values. For more informations about this model and the generation of the coefficients please refer to reference [@@PAPIER BAM].
\\
\\
\textbf{Implementation in a .cxx : }
\begin{minipage}{\linewidth}
\begin{lstlisting}
...
#include "Equivalence/EQM_QUAD_PWR_MOX.hxx"
...
int main()
{
...
EQM_QUAD_PWR_MOX* Equivalence = new EQM_QUAD_PWR_MOX( LogObject, AlphasFile );
// or
// EQM_QUAD_PWR_MOX* Equivalence = new EQM_QUAD_PWR_MOX( AlphasFile );
...
}
\end{lstlisting}
\end{minipage}
With LogObject a CLASSLogger object (see section~\ref{sec:logclass}) and AlphasFile a string which is the complete path to the file containing the weights (the $\alpha$ parameters)
\\
\\
\textbf{Available weight file (.dat) : }
\begin{minipage}{\linewidth}
\begin{itemize}
\item\textbf{@@@ BAM}
\item\textbf{@@@ BAM}
\item ...
\end{itemize}
\end{minipage}
\subsubsection{Neural network model : EQM\_MLP\_MOX}
This equivalence model is based on a Multi Layer Perceptron (MLP) and predict the amount of plutonium needed to reach \textbf{any burn-up}. The MLP inputs are the isotopic compositions of the plutonium (\textbf{including $^{241}Am$}), the enrichment of depleted uranium, and the targeted burn-up. The output is the plutonium content needed to reach the burn-up. This method uses the neural networks of the root module TMVA (@@@ Ref TMVA). To executes this model, TMVA is run in CLASS and need a .xml file. This file contains the neural network architecture and the weights resulting from the training procedure.
\\
\\
\textbf{Implementation in a .cxx : }
\begin{minipage}{\linewidth}
\begin{lstlisting}
...
#include "Equivalence/EQM_MLP_PWR_MOX.hxx"
...
int main()
{
...
EQM_MLP_PWR_MOX* Equivalence = new EQM_MLP_PWR_MOX( LogObject, TMVAWeightPath );
// or
// EQM_MLP_PWR_MOX.* Equivalence = new EQM_MLP_PWR_MOX( TMVAWeightPath );
...
\end{lstlisting}
\end{minipage}
With LogObject a CLASSLogger object (see section~\ref{sec:logclass}) and TMVAWeightPath a string containing the path to the .xml file.
In order to make his own .xml file one need to have a training data containing the fresh fuel composition and the achievable burn-up of many examples. The fuel composition is characterized by the mean of :
\begin{itemize}
\item The plutonium composition (\emph{i.e :}\%mol. of $^{238}Pu$, $^{239}Pu$, $^{240}Pu$, $^{241}Pu$, $^{242}Pu$, and $^{241}Am$)
\item The plutonium content (\emph{i.e :}$\frac{Pu}{Pu+U}$)
\item The $^{235}U$ content in the depleted uranium.
\end{itemize}
The file \$CLASS\_PATH/DataBases/Equivalence/EQM\_MLP\_PWR\_MOX\_3batch.xml has been generated from the file \$CLASS\_PATH/Utils/EquivalenceGeneration/PWR\_MOX\_MLP/Train\_MLP.cxx
To train a new MLP from your own training sample proceed as follow :
\begin{minipage}{\linewidth}
\begin{lstlisting}[style=terminal]
cd $CLASS_PATH/Utils/EquivalenceGeneration/PWR_MOX_MLP
Where YourTrainingData.root is a root file containing a TTree filled with fuel compositions and corresponding burn-ups. The .xml file will be generated in a folder named weight. The results of the testing procedure of the MLP are in a file named TMVA\_MOX\_Equivalence.root but will be presented to you graphically as soon as the training and the testing procedure are finished.
To make your YourTrainingData.root file you have to fill a TTree with your data. To do so, create a .cxx file and copy past this :
\begin{minipage}{\linewidth}
\begin{lstlisting}
TFile* fOutFile = new TFile("YourTrainingData.root","RECREATE"); //create the .root file
TTree* fOutT = new TTree("Data", "Data");//create the TTree
/****Fill the tree with this fuel composition and this burnup****/
fOutT->Fill();
}
fOutFile->Write();
delete fOutT;
fOutFile-> Close();
delete fOutFile;
}
\end{lstlisting}
\end{minipage}
Then, build the arrays fU5\_enrichment, fPu8 ... with your data, compile and execute.
For more informations about this model please refer to [@@Papier BaL].
\\
\\
\textbf{Available weight file (.xml) : }
\begin{minipage}{\linewidth}
\begin{itemize}
\item\textbf{\$CLASS\_PATH/DataBases/Equivalence/EQM\_MLP\_PWR\_MOX\_3batch.xml} : Generated with 5000 MURE evolutions with different fuel composition, using a full mirrored assembly calculation with JEFF3.1.1 cross section and fission yield data bases. Valid for mono-recycling of plutonium and a fuel management of 3 batches. More details about the generation of this .xml file can be found in reference[@@@BaL paper].
\end{itemize}
\end{minipage}
\paragraph{PWR-UOX model :}
\subsubsection{Linear Model: EQM\_LIN\_UOX}
@@@BAM
\subsection{How to build an Equivalence Model}
The strength of CLASS is to allow the user to build his own physic models, this section explains how to build a new equivalence model and to incorporate it into CLASS.
First you have to create the file EQM\_NAME.cxx and EQM\_NAME.hxx, where NAME is a name you choose.
Then open with a text editor the .hxx and copy past the following replacing NAME by the name you want.
//Code your Equivalence Model : This function has to return the molar fraction of fissile in the fuel needed to reach the BurnUp(GWd/tHM) according to the composition of the Fissil and Fertil vectors
}
\end{lstlisting}
\end{minipage}
In the constructor (EQM\_NAME::EQM\_NAME) you have to fill two isotopic vectors named \textbf{fFissileList} and \textbf{fFertileList}. Don't declare these isotopic vector in the .hxx, there are already declare in the file src/EquivalenceModel.hxx. fFissileList is used by the FabricationPlant to do the chemical separation of the fissile element from the other present in stock. For instance, for the plutonium, add the ZAI $^{238}Pu$, $^{239}Pu$, $^{240}Pu$, $^{241}Pu$ and $^{242}Pu$. fFertile List is used by the FabricationPlant the same way fFissileList is used but you have to define a default IsotopicVector to be used if you didn't provide a fertile stock to your FabricationPlant. In the example given above the fertile is depleted uranium and the proportion of each isotope is given ($^{234}U$ is unheeded). Now you have to build the function \textbf{GetFissileMolarFraction(IsotopicVector Fissil, IsotopicVector Fertil, double BurnUp)}. Its parameters are provided by the FabricationPlant and are :
\begin{itemize}
\item IsotopicVector Fissil : it is the proportion of each nuclei you give in the fFissileList and the proportion of the nuclei that appears during the fabrication time (time given in the FabricationPlant constructor, is default is 2 years)
\item IsotopicVector Fertil : it is the proportion of each nuclei you give in the fFertileList and the proportion of the nuclei that appears during the fabrication time. If you didn't provide any fertile stock to your FabricationPlant then it's the default vector given in the EQM\_NAME constructor.
\item double BurnUp : The maximal average burn-up for your fuel to reach in GWd/tHM.
\end{itemize}
Fill free to have a look at the models present in \$CLASS\_PATH/source/Model/Equivalence to get inspiration.
Now that your equivalence model is ready two choices are offered to you. You can compile the two files of your model with your CLASS input or you can add this model to the CLASS package. The second option will modify the CLASS software and we will be no longer able to troubleshoot your scenario. So use the second option only if you are a completely independent user !
\paragraph{Compile your equivalence model with your CLASS executable :}
\paragraph{Your equivalence model in the CLASS library :}
Move your EQM\_NAME.hxx and EQM\_NAME.cxx in \$CLASS\_PATH/source/Model/Equivalence/. Then open with your favourite text editor the file \$CLASS\_PATH/source/src/Makefile, find "OBJMODEL" and add \$(EQM)/EQM\_NAME.o within the others \$(EQM) objects. Then re-compile CLASS, fix the compilation errors ;) and voil your equivalence model is now available in the CLASS library.
%%%%%%%%%%%%%%%%%%%%%%%%%
%% XS MODEL
%%%%%%%%%%%%%%%%%%%%%%%%%
\section{XS Model}
The aim of a mean cross section model (XSModel) is to predict the mean cross sections of a fuel build by a EquivalenceModel (EQM)(see section \ref{sec:Equivalence}. The mean cross sections are required to compute fuel depletion in a reactor.
\subsection{Available XS Models}
There is, for the moment, 2 XSModel in CLASS :
\subsubsection{Pre-calculated XS : XSM\_CLOSEST}
This method looks, in a data base, for a fresh fuel with a composition \textbf{close} to the brandy new fuel built by the EquivalenceModel. Here, close means that the fresh fuel in the data base minimizes the distance d (see equation~\ref{eq:distance}).
where $n_{i}^{DB}$ is the number of nuclei $i$ in one element of the data base and $n_{i}^{new}$ the number of nuclei $i$ in the new fuel built by the EQM. $w_{i}$ is a weight associated to each isotopes, its value is 1 by default.
When the closest evolution in the database is found, the corresponding mean cross sections are extracted and used for the calculation of the depletion of the new fuel.
\\
\\
\textbf{Implementation in a .cxx : }
\begin{minipage}{\linewidth}
\begin{lstlisting}
...
#include "XS/XSM_CLOSEST.hxx"
...
int main()
{
XSM_CLOSEST* XSMOX = new XSM_CLOSEST( gCLASS->GetLog(), PathToIdxFile );
//or
//XSM_CLOSEST* XSMOX = new XSM_CLOSEST( PathToIdxFile );
}
\end{lstlisting}
\end{minipage}
With LogObject a CLASSLogger object (see section~\ref{sec:logclass}) and PathToIdxFile a string containing the path to the .idx file. The .idx file lists all the EvolutionData (see section~\ref{sec:EvolutionData}) of the data base. This file is formatted as follow :
\begin{minipage}{\linewidth}
\begin{lstlisting}
TYPE "NameOfTheFuel(withoutspace)"
"PATH_TO_DATA_BASE/EvolutionName.dat"
"PATH_TO_DATA_BASE/OtherEvolutionName.dat"
....
\end{lstlisting}
\end{minipage}
Each EvolutionName.dat file contains a fuel depletion calculation formatted as follow :
The meaning of each keyword is listed in table~\ref{tab:meanKeyWord}. The number of .dat files has an influence on the model accuracy. Furthermore, the initial composition of the different fuel depletion calculations has to be representative of the fresh fuel compositions encounter in a scenario. For more details on this method please refer to [ref @@@ BAM physor].
\begin{table}[H]
\begin{center}
\caption{.dat Key words meaning}
\label{tab:meanKeyWord}
\begin{tabular}{|c|c|}
\hline
Key words & Meaning \\
\hline
Inv & Inventory \\
\hline
Z & Charge number\\
A & Mass number\\
I & State (fundamental=0, $1^{st}$ excited =1, ...)\\
\hline
XSFis & mean fission cross section \\
XSCap & mean $(n,\gamma)$ cross section\\
XSn2n & mean $(n,2n)$ cross section \\
\hline
\end{tabular}
\end{center}
\end{table}
Each EvolutionName.dat files comes with a EvolutionName.info file, which describes the reactor, it is formatted like this :
\begin{minipage}{\linewidth}
\begin{lstlisting}
Reactor "ReactorName" //What ever string without space
Fueltype "FuelName" //What ever string without space
CycleTime "t" //The final time simulated
ConstantPower "P" //Simulated power (in W)
\end{lstlisting}
\end{minipage}
\textbf{Available .idx file : }
\begin{itemize}
\item\textbf{@@@ BAM}
\item\textbf{@@@ BAM}
\item ...
\end{itemize}
\textbf{For MURE user only : } The program \$CLASS\_PATH/Utils/XS/XS\_CLOSEST/WriteDataBase converts a list of MURE evolution to a list of .dat and .info files and creates the .idx file, type in terminal the following command for more details.
Users of others fuel depletion code (\emph{e.g} VESTA, ORIGEN, MONTEBURNS, SERPENT .... ) have to create their own program to generate these files.
\subsubsection{XS predictor : XSM\_MLP}
This method calculates the mean cross sections by the mean of a set of neural networks (MLP). There is two configurations available :
\begin{itemize}
\item One MLP per nuclear reaction and per time step.
\item One MLP per nuclear reaction. the irradiation time is one of the MLP inputs.
\end{itemize}
\textbf{Implementation in a .cxx : }
\begin{minipage}{\linewidth}
\begin{lstlisting}
...
#include "XS/XSM_MLP.hxx"
...
int main()
{ ...
XSM_MLP* XSMOX = new XSM_MLP( ClassLog, PathToWeightFolder, InfoFileName, IsTimeStep );
//or
//XSM_MLP* XSMOX = new XSM_MLP(PathToWeightFolder, InfoFileName, OneMLPPerTime);
...
}
\end{lstlisting}
\end{minipage}
\textbf{PathToWeightFolder}(string) is the path to the folder containing the weight files (.xml files). \textbf{OneMLPPerTime} is a boolean setted to true if there is one MLP per reaction and per time step. \textbf{InfoFileName}(string) is the name of the file located in PathToWeightFolder which is informing on the reactor and on the inputs of the XS\_MLP model.
Format of InfoFileName is :
\begin{minipage}{\linewidth}
\begin{lstlisting}
ReactorType :"ReactorName" //without space
FuelType :"FuelName" //without space
Heavy Metal (t) :"m"
Thermal Power (W) :"P" //power corresponding to the heavy metal mass
Time (s) :"0 t2 t3 t4 ..." //Time when the cross section are updated
Z A I Name (input MLP) : //see explanations below
"z a i InputName"
"z2 a2 i2 InputName2"
"..."
\end{lstlisting}
\end{minipage}
The input of MLPs are the atomic proportion of each nuclei present in the fresh fuel (plus time if OneMLPPerTime=false). The InfoFile has to indicates the variable names (nuclei name) you used for the \textcolor{blue}{\textbf{training of your MLPs}}. For instance if the fresh fuel contains $^{238}Pu$ you will write in the InfoFile :
\begin{minipage}{\linewidth}
\begin{lstlisting}
...
Z A I Name (input MLP) :
942380 Pu8//(if Pu8 is the variable name used for 238Pu proportion in fresh fuel in your training sample)
...
\end{lstlisting}
\end{minipage}
\\
\\
\\
\textcolor{blue}{\large{\textbf{Training MLPs for cross sections prediction :}}}\\
Like for the equivalence model, first of all you have to create a training sample. This is one of the most important thing since the way of filling the hyperspace of
