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