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