path: root/doc/IGE344/SectHST.tex

\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