path: root/doc/IGE335/Section4.00.tex

\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}