\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 GAN generalized driver.\cite{utilitaire}

\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{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 or
a sequential {\sc ascii} file. If \dusa{NAME1} is a {\sc lcm} object and if it appears on both sides,
it is erased and refilled 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 or
a sequential {\sc ascii} 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{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}.

\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 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{DIR} $]]$  $[[$ \moc{STEP} $\{$ \moc{UP} \dusa{NOMDIR} $|$
\moc{AT} \dusa{index} $|$ \moc{DOWN} $|$ \moc{ROOT} $\}~]]$ \\
$[[$ \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} $\{$ \dusa{BLOCK} $|$ \dusa{index} $\}$ \dusa{flott} $]]$ \\ $[[$ $\{$
\moc{COPY} $|$ \moc{STAT} $\{$ \moc{REL} $|$ \moc{ABS} $\}~|$ \moc{ADD} $\}$ \dusa{NOMREF} \dusa{NOMALT} $]]$ \\
$[$ \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{DIR}] keyword used to print the active directory content.

\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 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{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{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[\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{NOMREF}] name of the reference block.

\item[\dusa{NOMALT}] name of the block which may possibly be modified during
the \moc{ADD} and \moc{COPY} operations.

\item[\moc{DUMP}] Dump the active directory of and its
sub-directories to the printer.

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

\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 can be stored on a single {\sc lcm} object (either memory-resident or {\sc xsm}-based), a sequential binary
file or a sequential ASCII file. The calling specifications are:

\begin{DataStructure}{Structure \dstr{BACKUP:}}
\dusa{NAME1} \moc{:=} \moc{BACKUP:} $[$ \dusa{NAME1} $]$ $[[$ \dusa{NAME2} $]]~[$ \moc{::} \\
 $[$ \moc{EDIT} \dusa{iprint} $]$ \\
 $[[$ \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 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{STEP}] keyword used to move in the {\sc lcm} object hierarchy of \dusa{NAME2} before making the backup.

\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).
The calling specifications are:

\begin{DataStructure}{Structure \dstr{RECOVER:}}
$[[$ \dusa{NAME1} $]]$ \moc{:=} \moc{RECOVER:} \dusa{NAME2} $[[$ \dusa{NAME1} $]]~[$ \moc{::} \\
$[$ \moc{EDIT} \dusa{iprint} $]$ \\
$[[$ \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.

\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{STEP}] keyword used to move in the {\sc lcm} object hierarchy of \dusa{NAME2} before making the recover.

\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{STEP} $\{$ \moc{UP} \dusa{NOMDIR} $|$ \moc{AT} \dusa{index} $\}~]]$ \\
$[[$ \moc{TYPE} $\{$ \dusa{BLOCK} $|$ \dusa{index} $\}~${\tt >>}\dusa{itype}{\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{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{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}
