Initial commit from Polytechnique Montreal

1 files changed, 348 insertions, 0 deletions

diff --git a/doc/IGE344/SectHST.tex b/doc/IGE344/SectHST.tex
new file mode 100644
index 0000000..a47e8ba
--- /dev/null
+++ b/doc/IGE344/SectHST.tex
@@ -0,0 +1,348 @@
+\subsection{The \moc{HST:} module}\label{sect:HSTData}
+
+The \moc{HST:} module has been designed to manage a full reactor execution in DONJON using explicit DRAGON calculations for each
+cell.\cite{hst} This module saves in an \dds{history} data structure the information available in \dds{burnup} data
+structures generated by DRAGON. It can also read \dds{map} data structure generated by DONJON to prepare the \dds{history} data structure for a
+new series of cell calculations in DRAGON. The \dds{history} data structure  can also be used to update the \dds{map} data structure. Finally, the module
+\moc{HST:} can be used to create an initial \dds{burnup} data structure that can be used to evolve the cell another time step in DRAGON. 
+
+The \moc{HST:} module can be used to create or update an \dds{history} data structure. The possible options are:
+
+\begin{DataStructure}{Updating an \dds{history} structure using a \dds{map} structure}
+\dusa{\dds{history}}  \moc{:=} \moc{HST:} $[$ \dusa{\dds{history}} $]$  \dusa{\dds{map}} $[$ \moc{::} 
+$[$ \dstr{hstdim} $]$  $[$ \moc{GET} \dstr{hstpar} $]$    $]$ 
+\end{DataStructure}
+
+\begin{DataStructure}{Updating an \dds{history} structure using a \dds{burnup} structure}\label{tab2}
+\dusa{\dds{history}}  \moc{:=} \moc{HST:}   $[$ \dusa{\dds{history}} $]$  $[$ \dusa{\dds{burnup}} $]$ $[$ \moc{::} 
+$[$ \dstr{hstdim} $]$ \\
+\hspace*{1.0cm}  $[$ \moc{GET} \dstr{hstpar} $]$ 
+ $[$ \moc{CELLID} \dusa{icha} \dusa{ibun} $[$ \dusa{idfuel} $]$ $[$ \moc{GET} \dstr{hstpar}
+$]$  $]$   $]$ 
+\end{DataStructure} It can also be used to create a \dds{burnup} data structure from the information available on an \dds{history} data structure:
+\begin{DataStructure}{Updating a \dds{burnup} structure using an \dds{history} structure}
+\dusa{\dds{burnup}}  \moc{:=} \moc{HST:}   \dusa{\dds{history}} $[$  \moc{::} $[$ \dstr{hstdim} $]$ \\
+\hspace*{1.0cm} $[$ \moc{PUT} \dstr{hstpar} $]$\\
+\hspace*{1.0cm}  \moc{CELLID} \dusa{icha} \dusa{ibun}\\
+\hspace*{1.0cm} $[$ \moc{PUT} 
+   $\{$  \moc{BREFL}  \dstr{hstbrn} \dstr{hstpar} \moc{AREFL}
+\dstr{hstbrn} \dstr{hstpar} $|$ $[$ \moc{AREFL} $]$ \dstr{hstbrn} \dstr{hstpar} $\}$
+$]$ $]$   
+\end{DataStructure}
+\noindent  It can also be used to update a \dds{map} data structure from the information available on an \dds{history} data structure:
+\begin{DataStructure}{Updating an \dds{history} structure using a \dds{map} structure}
+\dusa{\dds{map}}  \moc{:=} \moc{HST:}  \dusa{\dds{map}}  \dusa{\dds{history}}  
+\end{DataStructure}
+
+\noindent where
+
+\begin{ListeDeDescription}{mmmmmmmm}  
+
+\item[\dusa{\dds{history}}] \verb|character*12| name of an \dds{history} data structure. 
+
+\item[\dusa{\dds{burnup}}] \verb|character*12| name of a \dds{burnup} data structure. 
+
+\item[\dusa{\dds{map}}] \verb|character*12| name of a \dds{map} data structure. 
+
+\item[\dstr{hstdim}] structure containing the dimensions for the \dds{history} data structure.
+
+\item[\moc{CELLID}] keyword to identify the cell for which history information is to be processed.
+
+\item[\dusa{icha}] channel number for which history information is to be processed. 
+
+\item[\dusa{ibun}] bundle number for which history information is to be processed. 
+
+\item[\dusa{idfuel}] fuel type number associated with this cell. One can associate to each fuel cell a different fuel type. By default a single fuel type is
+defined and it fills every fuel cell. Only the initial properties of each fuel type are saved. These properties are used for refueling. 
+
+\item[\moc{GET}] keyword to specify that the values of the parameters selected in \dstr{brnpar} will be read from the input stream or CLE-2000 local variables
+and stored on the \dds{history} data structure.
+
+\item[\moc{PUT}] keyword to specify that the values of the parameters selected in \dstr{brnpar} will be read from the \dds{history} data structure and
+transferred to local CLE-2000 variables.
+
+\item[\moc{BREFL}] to specify that the information to extract from the \dds{history} data structure is related to the properties of the cell before refueling takes
+place.
+
+\item[\moc{AREFL}] to specify that the information to extract from the \dds{history} data base is related to the properties of the cell after refueling took
+place.
+
+ \item[\dstr{hstbrn}] structure containing the burnup options.
+
+\item[\dstr{hstpar}] structure containing the local parameters options.
+\end{ListeDeDescription}
+
+The \dstr{hstdim} input structure is required for general dimensioning purpose. It is generally used only when creating the \dds{history} data structure.
+However, the number of global and local parameters used in a \dds{history} data structure can be increased at all time. The number of channels, bundles and the
+refueling scheme must be defined at the creation of the \dds{history} data structure. This information can be provided manually or extracted from a \dds{map}
+data structure. The general form of the \dstr{hstdim} input structure follows:
+
+\begin{DataStructure}{Structure \dstr{hstdim}}
+$[$ \moc{EDIT} \dusa{iprint} $]$ \\
+$[$ \moc{DIMENSIONS} 
+$[$ \moc{GLOBAL}   \dusa{nglo} $]$ $[$ \moc{LOCAL} \dusa{nloc} $]$ 
+$[$ \moc{BUNDLES}  \dusa{nbun} \dusa{bunl} $]$ $[$ \moc{CHANNELS} \dusa{ncha} $]$  $]$ 
+\end{DataStructure}
+
+\noindent
+ where
+\begin{ListeDeDescription}{mmmmmmmmm}   
+
+\item[\moc{EDIT}] keyword used to modify the print level \dusa{iprint}.
+
+\item[\dusa{iprint}] index used to control the printing in this module. It must be set to 0 if no printing on the output file is required. 
+
+\item[\moc{DIMENSIONS}] keyword used to indicate that the general dimensioning of the \dds{history} data structure will be modified.
+
+\item[\moc{GLOBAL}] keyword used to modify the number of global parameters on the \dds{history} data structure.
+
+\item[\dusa{nglo}] the number of global parameters. Note that the history module will use the maximum value between the current \dusa{nglob} and the value, if
+any, defined on the \dds{history} data structure.
+
+\item[\moc{LOCAL}] keyword used to modify the number of local parameters on the \dds{history} data structure.
+
+\item[\dusa{nloc}] the number of local parameters. Note that the history module will use the maximum value between the current \dusa{nloc} and the value, if
+any, defined on the \dds{history} data structure.
+
+\item[\moc{BUNBLES}] keyword used to specify the number of bundles per channels for the reactor model considered in the \dds{history} data structure.
+
+\item[\dusa{nbun}] the number of bundles per channels for the reactor model. Note that if \dusa{nbun} is different from the value already defined on the
+\dds{history} data structure or the \dds{map} data structure, the execution will be aborted. 
+
+\item[\dusa{bunl}] bundle length in cm. This information is required to compute inital fuel weight. 
+
+\item[\moc{CHANNELS}] keyword used to specify the number of fuel channels for the reactor model considered in the \dds{history} data structure.
+
+\item[\dusa{ncha}] the number of fuel channels for the reactor model. Note that if \dusa{ncha} is different from the value already defined on the \dds{history}
+data structure or the \dds{map} data structure, the execution will be aborted. 
+
+\end{ListeDeDescription}   
+
+The \dstr{hstbrn} serves a unique purpose, mainly to extract from the \dds{history} file the information required to process a burnup evaluation in DRAGON using
+the \moc{EVO:} module. The information must be stored inside CLE-2000 variables. The general form of this output structure is:
+
+\begin{DataStructure}{Structure \dstr{hstbrn}}
+\moc{BURN} \dusa{period} \dusa{power} \\
+\end{DataStructure}
+\noindent
+ where
+\begin{ListeDeDescription}{mmmmmmmm}   
+
+\item[\moc{BURN}] keyword to indicate that burnup information follows.
+
+\item[\dusa{period}] the burnup period (in days) that will be transferred to a real CLE-2000 variable. 
+
+\item[\dusa{power}] the power density (in kW/kg) that will be transferred to a real CLE-2000 variable. 
+\end{ListeDeDescription}
+
+
+The \dstr{hstpar} serves two purposes. First, it is used to define the names of the local and global parameters that may be used in our calculations as well as
+the values of these local parameters. In can also be used to extract from a \dds{history} data structure the values of these parameters. The general form of
+this structure is:
+
+\begin{DataStructure}{Structure \dstr{hstpar}}
+$[[$ \dusa{NAMPAR} \dusa{valpar} $]]$ 
+\end{DataStructure}
+
+\noindent
+ where
+\begin{ListeDeDescription}{mmmmmmmm}   
+
+\item[\dusa{NAMPAR}] name of a local or global parameter to process. The parameters specified before the keyword \dusa{CELLID} is read will be considered global
+otherwise they will be considered local.
+
+\item[\dusa{valpar}] real value for the local or global parameter to process. In the case where the \moc{GET} option is activated, the history module will
+extract this parameter from the input data stream. In the case where the \moc{PUT} option is activated, the history module will try to transfer this information
+into a real CLE-2000 variable.
+\end{ListeDeDescription}
+ 
+\subsubsection{Example}\label{sect:HSTExample}
+
+The history interface between the codes DRAGON and DONJON has been written as a new module in 
+order to facilitate the access to the GANLIB utilities that manage the required hierarchical data structures. The 
+resulting \moc{HST:} module can be called both by DRAGON and DONJON.
+
+The reactor model we will consider as an example is a 3--D model with an $x = 3$, $y = 3$ and $z = 3$ mesh. Here 
+we will assume that the $x - y$ plane describes fuel channels. The $z$ plane will be associated with the so-called fuel 
+bundles. This choice is somewhat arbitrary, however it is useful if the refueling takes place in a specific direction as 
+in a CANDU reactor. Here, a 2--bundle shift fueling strategy will be considered. To each fresh fuel cell introduced 
+in the core the \moc{HST:} module will associate a unique cell number between 1 and \moc{Nc}, the maximum number of 
+cells in the reactor. Most of the information associated with the fresh fuel cells will be extracted from a DRAGON 
+\dds{burnup} file or defined using variable local parameters. Each fresh fuel cell inserted in the core will also be 
+associated with a specific fuel type. Each fuel type is defined as a unique initial fuel composition. 
+The fuel management for the reactor, including burnup and refueling will be performed by the DONJON code. 
+Here the \moc{HST:} will interact with this code via the \dds{map} data structure. Typically, each cell in the reactor will be 
+burned inside DRAGON using the power provided in the \moc{AX-SHAPE} record and the depletion time provided in 
+the \moc{BURNUP-BEG} record stored in the \dds{map} structure. When refueling takes place some of the 
+fuel cells will be extracted, other will be displaced from one position to another and finally new fresh fuel cells 
+inserted. The fresh fuel cells properties will be extracted from the fuel types properties available on the \dds{history} 
+data structure.
+
+In a coupled DRAGON/DONJON execution, the \moc{HST:} module will be called at various points and for various 
+reasons. The first call to \moc{HST:} can be performed using:
+
+\begin{verbatim}
+MODULE HST: ; 
+*---- 
+* Map data structure for initialization: MAP0 
+* History data structure : History 
+*---- 
+SEQ_ASCII MAP0 ; 
+XSM_FILE History ; 
+XSM_FILE Reseau ; 
+*---- 
+* Reactor parameters 
+* ncha = nunber of channels = 9 
+* nbun = nunber of bundles = 3 
+* nevo = nunber of evolution = 3 
+* nglo = nunber of global parameters = 1 
+* nloc = nunber of local parameters = 2 
+* bunl = bundle length in cm = 49.53 cm 
+*---- 
+INTEGER ncha nbun nevo nglo nloc := 
+9 3 3 1 2 ; 
+REAL bunl := 49.53 ; 
+*---- 
+* Initialize History using MAP0 
+*---- 
+Reseau := MAP0 ; 
+History := HST: Reseau :: 
+DIMENSIONS GLOBAL <<nglo>> LOCAL <<nloc>> 
+BUNDLES <<nbun>> <<bunl>> 
+CHANNELS <<ncha>> ;
+\end{verbatim}
+
+Here, the \dds{history} data structure will be stored in the XSM file \moc{History}. One global and two local parameters 
+are considered. No information about the name or the value of the global and local parameters will be available. 
+This initialization procedure stores information only on the main level of the \dds{history} data structure if the \dds{map} 
+data structure is not available. In this case the \dds{history} is updated using a \dds{map} data structure (in sequential ASCII 
+file \moc{MAP0}). The number of channels and bundles per channel are stored and compared with the same information 
+in the \dds{map} structure. For each bundle in the \dds{map}, cell type and fuel type directories are constructed. The bundle 
+powers and burnups available in \dds{map} are used to generate the power rates in kW/kg and the depletion time in days 
+required to reach the specified burnups. These values are stored in the \dds{history} in the \moc{PARAMBURNTAR} record. 
+The fuel mass is mandatory for such calculation, thus the fuel weight is recovered from the \dds{map}. If the \dds{history} 
+is in modification mode, the fuel weight is computed using the bundle lenght and the initial fuel density. 
+Now, let us assume that a DRAGON calculation was performed for the cell located in bundle $j=1$ of channel 
+$i=1$. We will also assume that these cells contain a single type of fuel. Here the moderator temperature \moc{TMod} is a 
+global parameter while the fuel (\moc{TComb}) and coolant (\moc{TCalo}) temperatures are considered local parameters. We 
+assume that after the cell flux calculation a \dds{burnup} data structure was generated using the following instructions: 
+
+\begin{verbatim}
+*---- 
+* Procedures for cell calculation: CellCalc 
+*---- 
+PROCEDURE CellCalc ; 
+*---- 
+* Global parameter: Tmod for moderator temperature 
+* Local parameters: TComb for fuel temperature 
+* TCalo for coolant temperature 
+*---- 
+REAL TMod := 345.66 ; 
+REAL TComb TCalo := 941.29 560.66 ; 
+*---- 
+* Initial burnup options for cell calculation 
+*---- 
+REAL Power DeltaT := 31.9713 5.0 ; 
+*---- 
+* Local data structures 
+*---- 
+LINKED_LIST Burnup Edition ; 
+*---- 
+* Execution control parameters 
+* icha = channel number = 1 
+* ibun = bundle number = 1 
+*---- 
+INTEGER icha ibun := 1 1 ; 
+*---- 
+* Perform cell calculation 
+*---- 
+Burnup Edition := CellCalc Burnup :: 
+<<TComb>> <<TCalo>> <<TMod>> 
+<<Power>> <<DeltaT>> ; 
+\end{verbatim}
+
+Then, assuming that the history structure \moc{HistXSM} was created using the options above, we can use
+
+\begin{verbatim}
+*---- 
+* Update history structure 
+*---- 
+History := HST: History Burnup ::
+GET TMod <<TMod>> 
+CELLID <<icha>> <<ibun>> 
+GET TComb <<TComb>> TCalo <<TCalo>> ; 
+\end{verbatim}
+
+where no \moc{idfuel} is given (see Table~\ref{tab2}), thus we have used the default value for \moc{idfuel}$=1$ to store in \dds{history} the 
+general information associated with fuel channel 1 and bundle 1. Here, the initial properties associated with fuel 
+type 1 will be generated from the initial isotope densities in the \dds{burnup}. For the \moc{CELLID}, here \moc{icha}$=1$ and 
+\moc{ibun}$=1$, the burnup information, isotope densities, depletion parameters and initial fuel density are stored in a 
+\dir{celldir} directory. Moreover the power rate 31.9713 kW/kg and the depletion time 5.0 days are kept in the 
+\moc{PARAMBURNTAR} record.
+
+A \dds{history} data structure that contains the initial cell information can be updated using a \dds{map} data structure:
+
+\begin{verbatim}
+*---- 
+* Map data structure for refueling: MAP1 
+*---- 
+SEQ_ASCII MAP1 ; 
+*---- 
+* Refuel 
+*---- 
+Reseau := MAP1 ; 
+History := HST: History Reseau ; 
+\end{verbatim}
+
+Here, new burnup power ratings will be stored in the \dds{history} data structure reflecting the power distribution in 
+the DONJON calculation. The refueling information available in the \dds{map} structure will also be used to redistribute 
+the fuel in the \dds{history} structure at various cell location.
+
+Finally the last option is to recover this information in DRAGON to perform a new series of cell calculations:
+
+\begin{verbatim}
+*---- 
+* Local parameters 
+* Initial burnup options for cell calculation 
+* *A is after refueling 
+* *B is before refueling 
+*---- 
+REAL TCombA TCaloA TCombB TCaloB ; 
+REAL PowerA DeltaTA PowerB DeltaTB ; 
+Burnup := HST: History :: 
+PUT TMod >>TMod<< 
+CELLID <<icha>> <<ibun>> 
+PUT BREFL BURN >>DeltaTB<< >>PowerB<< 
+TComb >>TCombB<< TCalo >>TCaloB<< 
+AREFL BURN >>DeltaTA<< >>PowerA<< 
+TComb >>TCombA<< TCalo >>TCaloA<< ; 
+IF DeltaTB 0.0 > THEN 
+*---- 
+* Burn before refueling 
+*---- 
+Burnup Edition := CellCalc Burnup :: 
+<<TCombB>> <<TCaloB>> <<TMod>> 
+<<PowerB>> <<DeltaTB>> ; 
+Edition := DELETE: Edition ; 
+ENDIF ; 
+*---- 
+* Burn after refueling 
+*----
+Burnup Edition := CellCalc Burnup :: 
+<<TCombA>> <<TCaloA>> <<TMod>> 
+<<PowerA>> <<DeltaTA>> ; 
+*---- 
+* Update History 
+*---- 
+History := HST: History Burnup :: 
+CELLID <<icha>> <<ibun>> ;
+\end{verbatim}
+
+Note that here, there are two sets of local parameters that can be extracted from the history data structure, namely 
+the before (\moc{BREFL}) and the after (\moc{AREFL}) refueling information. In the case of fresh fuel (single fuel description 
+or a refueled bundle) extracting the before information is not required. However, if one uses the general procedure 
+described above to extract the before and after information, one will be able to identify the new fuel bundles as 
+well as the bundle that have not been moved in the core by the fact that $\Delta t = 0$ for burnup before refueling. For 
+bundles that have been displaced in the core during refueling then $\Delta t > 0$.
+
+\clearpage