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/IGE335/Section4.00.tex | 794 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 794 insertions(+)
 create mode 100644 doc/IGE335/Section4.00.tex

(limited to 'doc/IGE335/Section4.00.tex')

diff --git a/doc/IGE335/Section4.00.tex b/doc/IGE335/Section4.00.tex
new file mode 100644
index 0000000..d38b26a
--- /dev/null
+++ b/doc/IGE335/Section4.00.tex
@@ -0,0 +1,794 @@
+\section{THE UTILITY MODULES}\label{sect:UtilityModuleInput}
+
+DRAGON contains a number of utility modules used to perform tasks not
+related to reactor physics. These modules are also available to any code built
+around the Ganlib kernel and can be called from CLE-2000.\cite{ganlib5,cle2000}
+
+\subsection{The equality module}\label{sect:EQUData}
+
+This module is used to duplicate a {\sc lcm} object. The calling specifications
+are:
+
+\begin{DataStructure}{Structure \dstr{equality}}
+\dusa{NAME1} \moc{:=} $[$ \dusa{NAME1} $]$ \dusa{NAME2} \\
+~~~~~$[$ \moc{::} $[$ \moc{EDIT} \dusa{iprint} $]~[$ \moc{ERAS} $]~[~\{$ \moc{OLD} $|$ \moc{SAP}$\}~]~[[$ \moc{STEP} $\{$ \moc{UP} \dusa{NOMDIR} $|$ \moc{AT} \dusa{index} $\}~]]~]$ \moc{;} \\
+\end{DataStructure}
+
+\begin{ListeDeDescription}{mmmmmmmm}
+
+\item[\dusa{NAME1}] {\tt character*12} name of the output data
+structure. It can be a {\sc lcm} object (either memory-resident or {\sc xsm}-based), a sequential binary file,
+a sequential {\sc ascii} file or a {\sc hdf5} file. If \dusa{NAME1} is a {\sc lcm} object and if it appears on both sides,
+it is filled with the contents of \dusa{NAME2}.
+
+\item[\dusa{NAME2}] {\tt character*12} name of the input data
+structure. It can be a {\sc lcm} object (either memory-resident or {\sc xsm}-based), a sequential binary file,
+a sequential {\sc ascii} file or a {\sc hdf5} file.
+
+\item[\moc{EDIT}] keyword used to modify the print level \dusa{iprint}.
+
+\item[\dusa{iprint}] index used to control the printing of this module. The
+amount of output produced by this tracking module will vary substantially
+depending on the print level specified.
+
+\item[\moc{ERAS}] keyword used to erase the contents of the LCM object \dusa{NAME1} before the copy operation in case it appears on both sides of \moc{:=}.
+
+\item[\moc{OLD}] keyword used to import/export a LHS sequential {\sc ascii} file in 1995 {\sc lcm} specification. By
+default, the up-to-date specification is used.
+
+\item[\moc{SAP}] keyword used to import/export a LHS sequential {\sc ascii} file in Saphyr {\sc lcm} specification.
+
+\item[\moc{STEP}] keyword used to move in the {\sc lcm} object hierarchy of \dusa{NAME2} before making the copy.
+
+\item[\moc{UP}] keyword used to move up towards a sub-directory of \dusa{NAME2} of the
+active directory.
+
+\item[\dusa{NOMDIR}] copy the information located in the sub-directory named \dusa{NOMDIR}. If \dusa{NAME1} and \dusa{NAME2} are
+{\sc hdf5} files, \dusa{NOMDIR} is the name of a daughter group in \dusa{NAME2}.
+
+\item[\moc{AT}] keyword used to move up towards a component in an heterogeneous list of \dusa{NAME2}.
+
+\item[\dusa{index}] copy the information located in the \dusa{index}--th component of the heterogeneous list.
+
+\end{ListeDeDescription}
+
+If both the RHS and LHS are {\sc lcm} objects (either memory-resident or {\sc xsm}-based), a single copy is
+performed. A memory-resident {\sc lcm} object can be created from an {\sc xsm} file or an {\sc xsm}
+file can be created from a memory-resident {\sc lcm} object. If the LHS is a sequential file and the
+RHS is a {\sc lcm} object, an export is performed. The export
+format is either binary or ASCII.
+If the LHS is a {\sc lcm} object and the RHS is a sequential
+file, an import is performed. The case where both the LHS and the RHS are
+sequential files is not supported.
+
+\clearpage
+
+\subsection{The UTL: module}\label{sect:UTLData}
+
+The {\tt UTL:} module is used to perform utility actions on a {\sc lcm} object.
+The calling specifications are:
+
+\begin{DataStructure}{Structure \dstr{UTL:}}
+$[$ \dusa{NAME1} \moc{:=} $]$ \moc{UTL:} $[$ \dusa{NAME1} $]$ \moc{::} \\
+$[$ \moc{EDIT} \dusa{iprint} $]$ \\
+$[$ \moc{DIR} $]~[$ \moc{VAL} $]~[$ \moc{NAN} $]~[$ \moc{ERAS} $]$ \\
+$[[$ \moc{STEP} $\{$ \moc{UP} \dusa{NOMDIR} $|$
+\moc{AT} \dusa{index} $|$ \moc{DOWN} $|$ \moc{ROOT} $\}~[$ \moc{NEW} $\{$ \moc{DICT} $|$ \moc{LIST} \dusa{nsize} $\}~]~]]$ \\
+$[[$ \moc{IMPR} $\{$ \dusa{BLOCK} $|$ \dusa{index} $\}~\{$ \dusa{ileni} $|$ \moc{*} $\}~]]$ \\
+$[[$ \moc{CREA} $\{$ \dusa{BLOCK} $|$ \dusa{index} $\}~[$ \dusa{ilenc1} $]$ \dusa{ilenc2} \moc{=} $\{$
+(\dusa{valc}(i),i=\dusa{ilenc1},\dusa{ilenc2}) $|$ (\dusa{ivalc}(i),i=\dusa{ilenc1},\dusa{ilenc2}) \\
+$|$ (\dusa{hvalc}(i),i=\dusa{ilenc1},\dusa{ilenc2}) $|$ (\dusa{dvalc}(i),i=\dusa{ilenc1},\dusa{ilenc2}) $\}~]]$ \\
+$[[$ \moc{DEL} \dusa{BLOCK} $]]$ \\
+$[[~\{$ \moc{MULT} $|$ \moc{SADD} $\}~\{$ \dusa{BLOCK} $|$ \dusa{index} $\}$ \dusa{flott} $]]$ \\
+$[[~\{$ \moc{COPY} $|$ \moc{ADD} $\}$ \dusa{NOMREF} \dusa{NOMALT} $]]$ \\
+$[[$ \moc{STAT} $\{$ \moc{REL} $|$ \moc{ABS} $\}$ \dusa{NOMREF} \dusa{NOMALT} $[$ {\tt>>}\dusa{errmax}{\tt<<} $[$ {\tt>>}\dusa{erravg}{\tt<<} $]~]]$ \\
+$[$ \moc{DUMP} $]$ \moc{;}
+\end{DataStructure}
+
+\begin{ListeDeDescription}{mmmmmmmm}
+
+\item[\dusa{NAME1}] {\tt character*12} name of the {\sc lcm} object that will be treated by the utility module.
+
+\item[\moc{EDIT}] keyword used to modify the print level \dusa{iprint}. The default value is \dusa{iprint} $=1$.
+
+\item[\dusa{iprint}] index used to control the printing of this module. Set to 0 to
+reduce printing by the module.
+
+\item[\moc{DIR}] keyword used to print the active directory content.
+
+\item[\moc{VAL}] keyword used to validate the consistency of the connections in a LCM object.
+
+\item[\moc{NAN}] keyword used to scan the LCM object for NaN values.
+
+\item[\moc{ERAS}] keyword used to erase the contents of the LCM object.
+
+\item[\moc{STEP}] keyword used to move in the {\sc lcm} object hierarchy.
+
+\item[\moc{UP}] keyword used to move up towards a sub-directory (associative table) of the
+active directory.
+
+\item[\dusa{NOMDIR}] name of the sub-directory to which we wish to head.
+
+\item[\moc{AT}] keyword used to move towards a component in an heterogeneous list of \dusa{NAME1}.
+
+\item[\dusa{index}] access the information located in the \dusa{index}--th component of the heterogeneous list.
+
+\item[\moc{DOWN}] keyword to return to the sub-directory containing
+the active directory.
+
+\item[\moc{ROOT}] keyword to return to the root directory of the {\sc lcm} object.
+
+\item[\moc{NEW}] keyword to specify that \dusa{NOMDIR} or \dusa{index}--th component is a new entry.
+
+\item[\moc{DICT}] keyword to specify that \dusa{NOMDIR} or \dusa{index}--th component is an associative table.
+
+\item[\moc{LIST}] keyword to specify that \dusa{NOMDIR} or \dusa{index}--th component is an heterogeneous list.
+
+\item[\dusa{nsize}] size of the heterogeneous list.
+
+\item[\moc{IMPR}] keyword to print the complete contents or part of the record
+\dusa{BLOCK} or component \dusa{index} located on the current directory.
+
+\item[\moc{MULT}] keyword to multiply each element of a block or sub-directory
+in the active directory by a real constant. If \dusa{BLOCK} is a
+sub-directory, only floating point information contained in it is multiplied.
+
+\item[\moc{SADD}] keyword to add a real constant to each element of a block or sub-directory in the
+active directory. If \dusa{BLOCK} is a sub-directory, only floating point information contained in it is added.
+
+\item[\moc{CREA}] keyword used to create a block of information on the
+curent directory.
+
+\item[\moc{DEL}] keyword used to delete a block of information on the
+curent directory.
+
+\item[\dusa{BLOCK}] name of the block or sub-directory selected.
+
+\item[\dusa{ileni}] maximum number of elements that the user wishes to print.
+A value of \dusa{ileni}=0 is permitted.
+
+\item[\moc{*}] keyword, indicates that all the elements of a block will be
+printed. In a realistic case, the number of elements contained in a block may be
+rather large; this option must therefore be used with caution.
+
+\item[\dusa{ilenc1}] index of the first element included in the block. Can only be set if block
+\dusa{BLOCK} already exists. By default, \dusa{ilenc1} $=1$.
+
+\item[\dusa{ilenc2}] index of the last element included in the block.
+
+\item[\moc{=}] keyword, indicates that the input values will follow.
+
+\item[\dusa{valc}] real vector containing the information to be written in
+the record \dusa{BLOCK}.
+
+\item[\dusa{ivalc}] integer vector containing the information to be written in
+the record \dusa{BLOCK}.
+
+\item[\dusa{hvalc}] {\tt character*4} array containing the information to be
+written in the record \dusa{BLOCK}.
+
+\item[\dusa{dvalc}] double precision array containing the information to be
+written in the record \dusa{BLOCK}.
+
+\item[\dusa{flott}] constant by which a block or sub-directory will be
+multiplied.
+
+\item[\moc{COPY}] keyword used to copy an existing record or sub-directory
+onto a new record or sub-directory.
+
+\item[\moc{ADD}] keyword used to add the contents of two records or two
+sub-directories. If \dusa{NOMREF} and \dusa{NOMALT} are two
+sub-directories, only the floating point information contained in them is added.
+The result is written into \dusa{NOMALT}.
+
+\item[\dusa{NOMREF}] name of the reference block.
+
+\item[\dusa{NOMALT}] name of the block which is modified during the \moc{ADD} operation, modified or created
+for the \moc{COPY} operation and compared with the reference block for the \moc{STAT} operation.
+
+\item[\moc{STAT}] keyword used to compare the contents of two records.
+
+\item[\moc{REL}] the relative differences are printed.
+
+\item[\moc{ABS}] the absolute differences are printed.
+
+\item[\dusa{errmax}] output variable for relative or absolute maximum error for the \moc{STAT} operation.
+
+\item[\dusa{erravg}] output variable for relative or absolute average error for the \moc{STAT} operation.
+
+\item[\moc{DUMP}] Dump the active directory of and its
+sub-directories to the printer.
+
+\end{ListeDeDescription}
+
+\clearpage
+
+\subsection{The HUTL: module}\label{sect:HUTLData}
+
+A HDF5 file is a hierarchical structure made of groups (sub-structures) and datasets (arrays). The {\tt HUTL:} module is used to perform
+utility actions on a {\sc hdf5} file.\cite{hdf5} The calling specifications are:
+
+\begin{DataStructure}{Structure \dstr{HUTL:}}
+$[$ \dusa{NAME1} \moc{:=} $]$ \moc{HUTL:} $[$ \dusa{NAME1} $]~[$ \dusa{NAME2} $]$ \moc{::} \\
+$[[$ \moc{DIR} $[$ \dusa{BLOCK} $]~]]$ \\
+$[[$ \moc{TEST} \dusa{BLOCK} $]]$ \\
+$[[$ \moc{INFO} \dusa{BLOCK} $]]$ \\
+$[[$ \moc{IMPR} \dusa{BLOCK} $]]$ \\
+$[[$ \moc{CREA} \dusa{BLOCK} $]]$ \\
+$[[$ \moc{CREA} \dusa{BLOCK} $[~[$ \dusa{ilenc1} $]$ \dusa{ilenc2} $]$ \moc{=} $\{$
+(\dusa{valc}(i),i=\dusa{ilenc1},\dusa{ilenc2}) $|$ (\dusa{ivalc}(i),i=\dusa{ilenc1},\dusa{ilenc2}) \\
+$|$ (\dusa{hvalc}(i),i=\dusa{ilenc1},\dusa{ilenc2}) $|$ (\dusa{dvalc}(i),i=\dusa{ilenc1},\dusa{ilenc2}) $\}~]]$ \\
+$[[$ \moc{DELE} \dusa{BLOCK} $]]$ \\
+$[[$ \moc{COPY} \dusa{BLOCK} \moc{=} \dusa{BLOCK2} $]]$ \\
+$[[$ \moc{GREP} \dusa{BLOCK} $[$ \dusa{ilenc1} $]$ {\tt>>}\dusa{value}{\tt <<} $]]$ \moc{;} \\
+\end{DataStructure}
+
+\begin{ListeDeDescription}{mmmmmmmm}
+
+\item[\dusa{NAME1}] {\tt character*12} name of the {\sc hdf5} file that will be treated by the utility module.
+
+\item[\dusa{NAME2}] {\tt character*12} name of the source {\sc hdf5} file used with the action \moc{COPY}.
+
+\item[\moc{DIR}] keyword used to print a group table of content. If \dusa{BLOCK} is not set, the table of content of the root group is printed.
+
+\item[\moc{TEST}] keyword used to test existence of a group.
+
+\item[\moc{INFO}] keyword used to print information about a dataset.
+
+\item[\moc{IMPR}] keyword to print the complete contents of a dataset.
+
+\item[\moc{CREA}] keyword used to create a dataset. If both \dusa{ilenc1} and \dusa{ilenc2} are missing, a single value is readed. If
+only \moc{CREA} \dusa{BLOCK} is defined, a group named \dusa{BLOCK} is created. Otherwise, a dataset is created.
+
+\item[\dusa{BLOCK}] name of the group or dataset selected. The name of a group can include one or many path separators (character~$\slash$)
+to list different hierarchical levels.
+
+\item[\dusa{ilenc1}] index of the first element included in the block. Can only be set if block
+\dusa{BLOCK} already exists. By default, \dusa{ilenc1} $=1$.
+
+\item[\dusa{ilenc2}] index of the last element included in the block.
+
+\item[\moc{=}] equality keyword, indicates that the input values will follow.
+
+\item[\dusa{valc}] real vector containing the information to be written in the record \dusa{BLOCK}.
+
+\item[\dusa{ivalc}] integer vector containing the information to be written in the record \dusa{BLOCK}.
+
+\item[\dusa{hvalc}] {\tt character*4} array containing the information to be written in the record \dusa{BLOCK}.
+
+\item[\dusa{dvalc}] double precision array containing the information to be written in the record \dusa{BLOCK}.
+
+\item[\moc{DELE}] keyword used to delete group or dataset \dusa{BLOCK}.
+
+\item[\moc{COPY}] keyword used to copy a group or a dataset in destination \dusa{BLOCK} of the {\sc hdf5} file named \dusa{NAME1}.
+
+\item[\moc{=}] equality keyword, indicates that the input value will follow.
+
+\item[\dusa{BLOCK2}] name of the source group or dataset selected in the {\sc hdf5} file named \dusa{NAME2}.
+
+\item[\moc{GREP}] keyword used to recover a single component in a dataset of rank 1. If \dusa{ilenc1} is missing, the first value is recovered.
+
+\item[\dusa{value}] {\tt character*12} CLE-2000 variable name in which the recovered value will be placed. This variable should be
+declared integer, real, character or double precision.
+
+\end{ListeDeDescription}
+
+\clearpage
+
+\subsection{The DELETE: module}\label{sect:DELETEData}
+
+This module is used to delete one or many {\sc lcm} objects. The calling
+specifications are:
+
+\begin{DataStructure}{Structure \dstr{DELETE:}}
+$[[$ \dusa{NAME1} $]]$ \moc{:=} \moc{DELETE:} $[[$ \dusa{NAME1} $]]$ \moc{;}
+\end{DataStructure}
+
+\begin{ListeDeDescription}{mmmmmmmm}
+
+\item[\dusa{NAME1}] {\tt character*12} name of a {\sc lcm} object.
+
+\end{ListeDeDescription}
+
+The names of the {\sc lcm} object should be present on both the LHS and
+the RHS. A {\sc lcm} object named {\tt PARENT} can be deleted using the following command:
+
+\begin{verbatim}
+PARENT := DELETE: PARENT ;
+\end{verbatim}
+
+\subsection{The ERASE: module}\label{sect:ERASEData}
+
+This module is used to erase one or many {\sc lcm} objects without destroying their pointers. The calling
+specifications are:
+
+\begin{DataStructure}{Structure \dstr{ERASE:}}
+$[[$ \dusa{NAME1} $]]$ \moc{:=} \moc{ERASE:} $[[$ \dusa{NAME1} $]]$ \moc{;}
+\end{DataStructure}
+
+\begin{ListeDeDescription}{mmmmmmmm}
+
+\item[\dusa{NAME1}] {\tt character*12} name of a {\sc lcm} object.
+
+\end{ListeDeDescription}
+
+The names of the {\sc lcm} object should be present on both the LHS and
+the RHS. A {\sc lcm} object named {\tt PARENT} can be erased using the following command:
+
+\begin{verbatim}
+PARENT := ERASE: PARENT ;
+\end{verbatim}
+
+\clearpage
+
+\subsection{The BACKUP: module}\label{sect:BACKUPData}
+
+This module is used to copy one or many {\sc lcm} objects (memory-resident or {\sc xsm}-based), along with all of its parent to a backup {\sc lcm} object. The backup data
+structure is a single {\sc lcm} object (either memory-resident or {\sc xsm}-based with a {\tt L\_ARCHIVE} signature). The calling specifications are:
+
+\begin{DataStructure}{Structure \dstr{BACKUP:}}
+\dusa{NAME1} \moc{:=} \moc{BACKUP:} $[$ \dusa{NAME1} $]$ $[[$ \dusa{NAME2} $]]~[$ \moc{::} \\
+ $[$ \moc{EDIT} \dusa{iprint} $]$ \\
+ $[~[$ \moc{LIST} \dusa{ndim} $]$ \moc{ITEM} \dusa{ipos} $]$ \\
+ $[[$ \moc{STEP} $\{$ \moc{UP} \dusa{NOMDIR} $|$ \moc{AT} \dusa{index} $\}~]]~]$ \moc{;}
+\end{DataStructure}
+
+\begin{ListeDeDescription}{mmmmmmmm}
+
+\item[\dusa{NAME1}] {\tt character*12} name of {\sc lcm} object ({\tt L\_ARCHIVE} signature) used as a backup media.
+
+\item[\dusa{NAME2}] {\tt character*12} name of {\sc lcm} object
+to be transfer to the backup {\sc lcm} object. This {\sc lcm} object must be in a
+memory-resident or {\sc xsm}-based format.
+
+\item[\moc{EDIT}] keyword used to modify the print level \dusa{iprint}.
+
+\item[\dusa{iprint}] index used to control the printing of this module. The
+amount of output produced by this tracking module will vary substantially
+depending on the print level specified.
+
+\item[\moc{LIST}] keyword to store \dusa{NAME2} objects as list components. By default, a single \dusa{NAME2} object is stored directly into \dusa{NAME1}.
+
+\item[\dusa{ndim}] number of heterogeneous list components set to store each \dusa{NAME2} object type.
+
+\item[\moc{ITEM}] keyword to set the index of the list component in the archive where objects \dusa{NAME2} are stored. This keyword is mandatory if
+\dusa{NAME2} is stored as a list component.
+
+\item[\dusa{ipos}] index (\dusa{ipos} $\le$ \dusa{ndim}) of the list component.
+
+\item[\moc{STEP}] keyword used to move in the {\sc lcm} object hierarchy of \dusa{NAME2} before making the backup. The {\sc lcm} object
+with {\tt L\_ARCHIVE} signature is created after \moc{STEP} moves are done.
+
+\item[\moc{UP}] keyword used to move up towards a sub-directory of \dusa{NAME2} of the
+active directory.
+
+\item[\dusa{NOMDIR}] backup the information into the sub-directory named \dusa{NOMDIR}.
+
+\item[\moc{AT}] keyword used to move up towards a component in an heterogeneous list of \dusa{NAME2}.
+
+\item[\dusa{index}] backup the information into the \dusa{index}--th component of the heterogeneous list.
+
+\end{ListeDeDescription}
+
+If \dusa{NAME1} appears only on the LHS, it is created. If \dusa{NAME1}
+appears on both the LHS and the RHS, it is updated.
+
+\clearpage
+
+\subsection{The RECOVER: module}\label{sect:RECOVERData}
+
+This module is used to recover from a backup {\sc lcm} object (see
+\Sect{BACKUPData}) one or many {\sc lcm} objects (memory-resident or {\sc xsm}-based with {\tt L\_ARCHIVE} signature).
+The calling specifications are:
+
+\begin{DataStructure}{Structure \dstr{RECOVER:}}
+$[[$ \dusa{NAME1} $]]$ \moc{:=} \moc{RECOVER:} \dusa{NAME2} $[[$ \dusa{NAME1} $]]~[$ \moc{::} \\
+$[$ \moc{EDIT} \dusa{iprint} $]$ \\
+$[$ \moc{ITEM} \dusa{ipos} $]$ \\
+$[[$ \moc{STEP} $\{$ \moc{UP} \dusa{NOMDIR} $|$ \moc{AT} \dusa{index} $\}~]]~]$ \moc{;}
+\end{DataStructure}
+
+\begin{ListeDeDescription}{mmmmmmmm}
+
+\item[\dusa{NAME1}] {\tt character*12} name of the {\sc lcm} objects that are to be recovered.
+
+\item[\dusa{NAME2}] {\tt character*12} name of a backup {\sc lcm} object ({\tt L\_ARCHIVE} signature).
+
+\item[\moc{EDIT}] keyword used to modify the print level \dusa{iprint}.
+
+\item[\dusa{iprint}] index used to control the printing of this module. The
+amount of output produced by this tracking module will vary substantially
+depending on the print level specified.
+
+\item[\moc{ITEM}] mandatory keyword used if the \moc{LIST} keyword was set in module {\tt BACKUP:}.
+
+\item[\dusa{ipos}] index of the list component in the archive where objects \dusa{NAME1} are recovered.
+
+\item[\moc{STEP}] keyword used to move in the {\sc lcm} object hierarchy of \dusa{NAME2} before making the recover. The {\sc lcm} object
+with {\tt L\_ARCHIVE} signature is reached after \moc{STEP} moves are done.
+
+\item[\moc{UP}] keyword used to move up towards a sub-directory of \dusa{NAME2} of the
+active directory.
+
+\item[\dusa{NOMDIR}] recover the information located in the sub-directory named \dusa{NOMDIR}.
+
+\item[\moc{AT}] keyword used to move up towards a component in an heterogeneous list of \dusa{NAME2}.
+
+\item[\dusa{index}] recover the information located in the \dusa{index}--th component of the heterogeneous list.
+
+\end{ListeDeDescription}
+
+If \dusa{NAME1} appears only on the LHS, it is created. If \dusa{NAME1}
+appears on both the LHS and the RHS, it is replaced by the information located
+on the backup media.
+
+\clearpage
+
+\subsection{The ADD: module}\label{sect:ADDData}
+
+This module is used to add the floating point information contained of the two
+{\sc lcm} object located on the RHS. The
+result is stored in a third output {\sc lcm} object. The calling specifications
+are:
+
+\begin{DataStructure}{Structure \dstr{ADD:}}
+\dusa{NAME1} \moc{:=} \moc{ADD:}  \dusa{NAME2} \dusa{NAME3} \moc{;}
+\end{DataStructure}
+
+\begin{ListeDeDescription}{mmmmmmmm}
+
+\item[\dusa{NAME1}] {\tt character*12} name of a {\sc lcm} object which
+contains the final information.
+
+\item[\dusa{NAME2}] {\tt character*12} name of a {\sc lcm} object which
+contains the first part of the initial information. One can use
+\dusa{NAME2}=\dusa{NAME1}.
+
+
+\item[\dusa{NAME3}] {\tt character*12} name of a {\sc lcm} object which
+contains the second part of the initial information.
+
+\end{ListeDeDescription}
+
+\clearpage
+
+\subsection{The MPX: module}\label{sect:MPXData}
+
+This module is used to multiply the floating point information contained in a
+{\sc lcm} object located on the RHS by a user-defined real number. The
+result is stored in a second output {\sc lcm} object. The calling specifications
+are:
+
+\vskip -0.2cm
+
+\begin{DataStructure}{Structure \dstr{MPX:}}
+\dusa{NAME1} \moc{:=} \moc{MPX:}  \dusa{NAME2} \moc{::} \dusa{real} \moc{;}
+\end{DataStructure}
+
+\begin{ListeDeDescription}{mmmmmmmm}
+
+\item[\dusa{NAME1}] {\tt character*12} name of a {\sc lcm} object which
+contains the final information.
+
+\item[\dusa{NAME2}] {\tt character*12} name of a {\sc lcm} object which
+contains the the initial information. One can use
+\dusa{NAME2}=\dusa{NAME1}.
+
+\item[\dusa{real}] real number used as a multiplication factor.
+
+\end{ListeDeDescription}
+
+\clearpage
+
+\subsection{The STAT: module}\label{sect:STATData}
+
+This module is used to compare the floating point information contained in two
+different {\sc lcm} object. The calling
+specifications are:
+
+\begin{DataStructure}{Structure \dstr{STAT:}}
+\moc{STAT:} \dusa{NAME1} \dusa{NAME2} \moc{;}
+\end{DataStructure}
+
+\begin{ListeDeDescription}{mmmmmmmm}
+
+\item[\dusa{NAME1}] {\tt character*12} name of the reference {\sc lcm} object.
+
+\item[\dusa{NAME2}] {\tt character*12} name of a compared {\sc lcm} object.
+
+\end{ListeDeDescription}
+
+\clearpage
+
+\subsection{The GREP: module}\label{sect:GREPData}
+
+ The GREP: module is used to extract a single value from a {\sc lcm} object. The
+calling specifications are:
+
+\vskip -0.2cm
+
+\begin{DataStructure}{Structure \dstr{GREP:}}
+\moc{GREP:} \dusa{NAME3} \moc{::} \\
+$[$ \moc{EDIT} \dusa{iprint} $]$ \\
+$[[$ \moc{STEP} $\{$ \moc{UP} \dusa{NOMDIR} $|$ \moc{AT} \dusa{index} $\}~]]$ \\
+$[[$ \moc{TYPE} $\{$ \dusa{BLOCK} $|$ \dusa{index} $\}~${\tt >>}\dusa{itype}{\tt <<}$~]]$ \\
+$[[$ \moc{LENGTH} $\{$ \dusa{BLOCK} $|$ \dusa{index} $\}~${\tt >>}\dusa{ilong}{\tt <<}$~]]$ \\
+$[[~\{$ \moc{GETVAL} $|$ \moc{MAXVAL} $|$  \moc{MINVAL} $|$ \moc{INDMAX} $|$  \moc{INDMIN} $|$ \moc{MEAN} $\}$ \\
+~~~~~~$\{$ \dusa{BLOCK} $|$ \dusa{index} $\}$ \dusa{index1} $[~\{~\{$ \dusa{index2} $|$ \moc{*} $\}~[$ \dusa{index3}
+    $]~|$~\moc{NVAL}~$\{$ \dusa{neval} $|$ \moc{*} $\}~\}~]$ \\
+~~~~~~$[[~${\tt >>}\dusa{value}{\tt <<}$~]]$ \\
+$]]$ \moc{;}
+\end{DataStructure}
+
+\begin{ListeDeDescription}{mmmmmmmm}
+
+\item[\dusa{NAME3}] {\tt character*12} name of the {\sc lcm} object from which
+extractions will be performed.
+
+\item[\moc{EDIT}] keyword used to modify the print level \dusa{iprint}.
+
+\item[\dusa{iprint}] index set to 1 to enable printing in this module. By default, \dusa{iprint} $=0$.
+
+\item[\moc{STEP}] keyword used to move in the {\sc lcm} object hierarchy.
+
+\item[\moc{UP}] keyword used to move up towards a sub-directory of the
+active directory.
+
+\item[\dusa{NOMDIR}] name of the sub-directory or heterogeneous list to which we wish to head.
+
+\item[\moc{AT}] keyword used to move up towards a component in the heterogeneous list.
+
+\item[\dusa{index}] access the information located in the \dusa{index}--th component of the heterogeneous list.
+
+\item[\dusa{BLOCK}] name of the record which will be analyzed by the
+\moc{GREP:} utility.
+
+\item[\dusa{index}] index of the record which will be analyzed by the
+\moc{GREP:} utility.
+
+\item[\moc{TYPE}] keyword used to get the {\sc lcm} type of record \dusa{BLOCK}.
+
+\item[\dusa{itype}] type of block \dusa{BLOCK} or list component \dusa{index} ($=1$: integer;
+$=2$: real; $=3$: character; $=4$: double precision; $=5$: logical; $=10$: list; $=99$: undefined).
+
+\item[\moc{LENGTH}] keyword used to get the length of {\sc lcm} record \dusa{BLOCK}.
+
+\item[\dusa{ilong}] length of record. If the record is made of characters (\dusa{itype} $=3$),
+then \dusa{ilong} is a character count.
+
+\item[\moc{GETVAL}] keyword used to get values from an existing record.
+The receiving CLE-2000 variables are assumed to be of the same type as the
+picked values (all CLE-2000 types are supported).
+
+\item[\moc{MAXVAL}] keyword used to get the maximum value of an existing
+record. The receiving CLE-2000 single variable is assumed to be of the same type
+as the  picked maximum (valid for integer, real and double precision types).
+
+\item[\moc{MINVAL}] keyword used to get the minimum value of an existing
+record.
+The receiving CLE-2000 single variable is assumed to be of the same type as the
+picked minimum (valid for integer, real and double precision types).
+
+\item[\moc{INDMAX}] keyword used to get the index (position inside the block)
+of the maximum value of an existing
+record.
+The receiving CLE-2000 single variable is assumed of an integer type
+(valid for integer, real and double precision blocks).
+
+\item[\moc{INDMIN}] keyword used to get the index (position inside the block)
+of the minimum value of an existing
+record.
+The receiving CLE-2000 single variable is assumed of an integer type
+(valid for integer, real and double precision blocks).
+
+\item[\moc{MEAN}] keyword used to get the mean value of an existing
+record.
+The receiving CLE-2000 single variable is assumed to be of the same type as the
+computed mean (valid only for real and double precision types).
+
+\item[\dusa{index1}] the first element number in record \dusa{BLOCK} to be
+considered.
+
+\item[\dusa{index2}] the last element in record \dusa{BLOCK} to be
+considered. If \dusa{index2} is absent only element \dusa{index1} will be
+considered.
+
+\item[\moc{*}] the search will extend to the last
+element in the record \dusa{BLOCK}.
+
+\item[\dusa{index3}] specifies the stride between
+values to be extracted between \dusa{index1} and \dusa{index2}. By default, a
+stride of 1 is assumed.
+
+\item[\moc{NVAL}] keyword used to specify the number of elements to be
+extracted from the specified record.
+
+\item[\dusa{neval}] the number of  elements to be extracted from
+the the specified record. If the record contains {\tt character}
+information, elements
+\dusa{index1} to
+\dusa{index1}$+$\dusa{neval}$-1$ are extracted.
+
+\end{ListeDeDescription}
+
+The output parameters, denoted as $>>$\dusa{value}$<<$, are recovered as CLE-2000 variables in the
+module data located after the \moc{::} keyword.
+
+\clearpage
+
+\subsection{The MSTR module}\label{sect:MSTRData}
+
+This module is used to create user-defined structures. In particular, it can be used to store and
+retrieve user variables in a structure or copy specific records from different structures to a single
+one so that the user can have an easy access to the information he wants from a CLE-2000 procedure.
+The calling specifications are:
+
+\begin{DataStructure}{Structure \dstr{MSTR:}}
+$[$ \dusa{STRUCT} \moc{:=} $]$ \moc{MSTR:} $[$ \dusa{STRUCT} $]$ $[[$ \dusa{EXTSTR} $]]$ \moc{::} \\
+$[$ \moc{EDIT} \dusa{iprint} $]$ \\
+$[$ \moc{TYPE} \dusa{type}  $]$ \\
+$[[$ \moc{CD} $[$\dusa{ilcm}:$]$\dusa{path} $]]$ \\
+$[[$ \moc{GET} \dusa{nbelem} $[$ \dusa{indexfirst} $[$ \dusa{increment} $]$ $]$ $[$\dusa{ilcm}:$]$$[$\dusa{path}$]$\dusa{recname} $[[$ $>>VAR\_IN<<$ $]]$ $]]$ \\
+$[[$ \moc{PUT} \dusa{nbelem} $[$ \dusa{indexfirst} $[$ \dusa{increment} $]$ $]$ $[$\dusa{ilcm}:$]$$[$\dusa{path}$]$\dusa{recname} $[[$ \dusa{value} $]]$ $]]$ \\
+$[[$ \moc{CP}~ \dusa{nbelem} $[$ \dusa{indexfirst} $[$ \dusa{increment} $]$ $]$ $[$\dusa{ilcm1}:$]$$[$\dusa{path1}$]$\dusa{recname1} $[$\dusa{ilcm2}:$]$  $[$\dusa{path2}$]$\dusa{recname2} $]]$ \\
+\moc{;}
+\end{DataStructure}
+
+\begin{ListeDeDescription}{mmmmmmmm}
+
+\item[\dusa{STRUCT}] {\tt character*12} name of the user-defined {\sc lcm} object in creation, modification or read-only mode depending on the requested actions.
+
+\item[\dusa{EXTSTR}] {\tt character*12} name of existing {\sc lcm} object from which information will be retrieved.
+
+\item[\moc{EDIT}] keyword used to modify the print level \dusa{iprint}.
+
+\item[\dusa{iprint}] index used to control the printing of this module.
+
+\item[\moc{TYPE}] keyword used to modify the structure signature.
+
+\item[\dusa{type}] string containing the user-defined signature, limited to 12 characters.
+
+\item[\moc{CD}] keyword for introducing a UNIX-like command to change the active directory of the structures.
+\item[\dusa{ilcm}] integer defining the structure index according to its position in the LHS or RHS list of parameters. By default, equal to 1 (i.e. \dusa{STRUCT} is affected by the \moc{CD} command).
+
+\item[\dusa{path}] string containing the UNIX-like path (relative or absolute) of the directory to access. Note that if the directory does not exist and that the structure is in creation/modification mode, it is created.
+
+\item[\dusa{recname}] string containing the record name. Note that if this record does not exist and that the structure is in creation/modification mode, it is created.
+
+For example, \dusa{2:/dir/rec} refers to the record \dusa{rec} in the directory \dusa{dir} of the second structure in the calling specifications of the module.
+
+\item[\moc{GET}] keyword for introducing the action of retrieving variables from the structure.
+
+\item[\moc{PUT}] keyword for introducing the action of storing variables in the structure.
+
+\item[\moc{CP}] keyword for introducing the UNIX-like action of copying some elements from one record (defined by $[$\dusa{ilcm1}:$]$$[$\dusa{path1}$]$$[$\dusa{recname1}$]$) to another ($[$\dusa{ilcm2}:$]$  $[$\dusa{path2}$]$$[$\dusa{recname2}$]$).
+
+\item[\dusa{nbelem}] integer defining the number of elements to store/retrieve/copy.
+
+\item[\dusa{indexfirst}] integer defining the index of the first element to store/retrieve/cpoy. By default, equal to 1.
+
+\item[\dusa{increment}] integer defining the stride in the record between the values to be stored/retrieved/copied. By default, equal to 1.
+
+\item[$VAR\_IN$] {\tt character*12} CLE-2000 variable name in which the extracted value will be placed. It is expected that the number of values extracted and the number (and types) of variables agree.
+
+\item[\dusa{value}] value to be stored. The first one defines the record type and all the values should be of the same type.
+
+\end{ListeDeDescription}
+
+\clearpage
+
+\subsection{The FIND0: module}\label{sect:FIND0Data}
+
+The FIND0: module is used to find the root of a function using the  Brent's
+method.  This procedure assumes that the zero is bracketed in an interval given
+in the input using the two first points, and that the function used is continuous
+in this interval. The calling specifications are:
+
+\begin{DataStructure}{Structure \dstr{FIND0:}}
+\dusa{L0} \moc{:=} \moc{FIND0:} $[$ \dusa{L0} $]$ \moc{::} \\
+$\{$ $[$ \moc{DEBUG} $]$  $[$ \moc{ITMAX} \dusa{itmax} $]$
+                          $[$ \moc{TOL} \dusa{tol} $]$
+\moc{POINT} \moc{X} \dusa{x1} \moc{Y} \dusa{y1}
+\moc{POINT} \moc{X} \dusa{x2} \moc{Y} \dusa{y2}
+$|$ \moc{Y} \dusa{y3} $\}$ \\
+$>>$\dusa{lFlag}$<<$ $>>$\dusa{rRoot}$<<$ \moc{;}
+\end{DataStructure}
+
+\begin{ListeDeDescription}{mmmmmmmm}
+
+\item[\dusa{L0}] {\tt character*12} names of the {\sc FIND0} {\sc lcm} object (type {\tt
+L\_0}) that will contain all information necessary for the
+zero-finding procedure. If \dusa{L0} appears on both sides, it is updated;
+otherwise, it is created.
+
+% \item[\dusa{NAME2}] {\tt character*12} names of a CLE-2000 parameter.
+%  The \dusa{NAME2} parameter is expected to be a CLE-2000 real variable,
+%  that will contain the next value (to approximate zero) to be used as in
+%  the zero-finding procedure. In creation mode, this value will be computed
+%  using the two points given as input; when it is modified, the procedure
+%  checks if it receives the last given value.
+%  It is important to used this particular value for the next function evaluation.
+%
+% \item[\dusa{NAME3}] {\tt character*12} name of a \dds{FIND0} {\sc lcm} object
+%  that will contain all information necessary for the
+% zero-finding procedure. If \dusa{NAME2} appears on both sides, it is updated;
+% otherwise, it is created.
+
+\item[\moc{DEBUG}] keyword used to edit the content of most variables in
+\dds{FIND0}; used only for debugging purposes.
+
+\item[\moc{ITMAX}] keyword used to specify the maximum number of iterations
+that will be allowed for the zero-finding procedure. The procedure will
+abort if the number of iterations goes beyond this maximum value.
+
+\item[\dusa{itmax}] the maximum number of iterations. Default value: 100.
+
+\item[\moc{TOL}] keyword used to specify the tolerance on the zero to be found.
+
+\item[\dusa{tol}] tolerance. Default value: 1.E-5.
+
+\item[\moc{POINT}] keyword used to specify that the next point will be given.
+
+\item[\moc{X}] keyword used to specify that an abscissa will be given.
+
+\item[\moc{Y}] keyword used to specify that an ordinate will be given.
+
+\item[\dusa{x1}] the first abscissa value.
+
+\item[\dusa{y1}] the first ordinate value.
+
+\item[\dusa{x2}] the second abscissa value.
+
+\item[\dusa{y2}] the second ordinate value.
+
+\item[\dusa{y3}] in the case we are in an update mode,
+only a new ordinate value is given.
+
+\item[\dusa{lFlag}] CLE-2000 logical variable in writable mode. The value
+returned is \dusa{true} if the new guessed root is within \dusa{tol},
+ \dusa{false} otherwise.
+
+\item[\dusa{rRoot}] CLE-2000 real variable in writable mode. The value
+returned is the last guess for the root.
+
+\end{ListeDeDescription}
+
+Note that the zero-finding procedure has an initial mode where \dusa{NAME1},
+\dusa{NAME2} and \dusa{NAME3} are created. In the initialization process,
+the two points specifying the interval must be given, and it is expected
+that  \dusa{y1}$\times$\dusa{y2}$< 0$.
+In the updated mode, there is no need to put back the abscissa of the next point
+because it is expected to be the last real value that was generated by the
+procedure. This explains why you will only input \moc{Y} \dusa{y3}.
+
+The \dds{FIND0} specification is used to store intermediate values needed
+by the zero-finding procedure.
+There are no directories in this object, and it is created and updated only by
+the \moc{FIND0:} module.
+To understand the content of the object, it is possible, using the labels given
+for every block, to refer to Brent's algorithm.\cite{recipie}.
+
+\subsection{The ABORT: module}\label{sect:ABORTData}
+
+This module is used to abort the overall calculation, calling the \moc{XABORT()}
+subroutine from the Ganlib.
+
+\vskip -0.2cm
+
+\begin{DataStructure}{Structure \dstr{ABORT:}}
+\moc{ABORT:} \moc{;}
+\end{DataStructure}
+
+\clearpage
+
+\subsection{The END: module}\label{sect:ENDData}
+
+This module is used to delete all the memory-resident {\sc lcm} objects, to close all  the
+remaining local files and to return from a procedure or to stop the run. The
+calling specifications are:
+
+\vskip -0.2cm
+
+\begin{DataStructure}{Structure \dstr{END:}}
+\moc{END:}  \moc{;}
+\end{DataStructure}
-- 
cgit v1.2.3

