Initial commit from Polytechnique Montreal

1 files changed, 129 insertions, 0 deletions

diff --git a/doc/IGE335/AppendixA.tex b/doc/IGE335/AppendixA.tex
new file mode 100644
index 0000000..bc84ebe
--- /dev/null
+++ b/doc/IGE335/AppendixA.tex
@@ -0,0 +1,129 @@
+\section{THE GAN GENERALIZED DRIVER}
+
+A scientific application can be built around the GAN generalized driver by
+linking it with application-dependent modules. Such a
+scientific application will share the following specifications:
+
+\begin{enumerate}
+
+\item  The GAN generalized driver can handle a custom data type called a {\sl LCM object}
+and implemented as an {\sl associative table} or {\sl heterogeneous list}. A associative
+table is a data structure similar to the example shown in \Fig{LkList}. An heterogeneous list
+is an alternative structure where the component are identified by integer values instead of names. Each
+data type mapped to a LCM object is dynamically
+allocated using the computer's memory management algorithm and is accessed with
+a pointer. LCM objects are the {\sl only} memory-resident data type used to
+transfer information between modules. However, interface files can also be used to transfer information
+between modules in cases where we want to reduce the memory resource
+requirements. A LCM object can therefore be declared as {\tt LINKED\_LIST} to make it
+memory-resident or as {\tt XSM\_FILE} to make it persistent. Sequential files (either
+binary or ASCII) can also be used.
+
+\begin{figure}[h!]
+\begin{center} 
+\epsfxsize=7cm \centerline{ \epsffile{GLkList.eps}}
+\parbox{14.0cm}{\caption{An example of an associative table.}\label{fig:LkList}}   
+\end{center}  
+\end{figure}
+
+\item  Building a scientific application requires the definition of the LCM
+objects and interface files and the programming of application-dependent modules
+to manage these LCM objects.
+
+\item  A driver was written to support the LCM objects and to read
+macro-language instructions. The modules are callable from this driver, but  the
+possibility of having ``embedded modules", i.e.  modules called directly from a
+subroutine written in any of these four languages has also been introduced.
+
+\item  Utility modules are available to backup the LCM object on an XSM
+file and to permit code restart.
+
+\end{enumerate}
+
+The modules must be declared in the calling procedure using directives of the form:
+
+\begin{DataStructure}{Structure \dstr{descmodule}}
+\moc{MODULE} $[[$ \dusa{name} $]]$ \moc{;} \\
+\end{DataStructure}
+\noindent with
+
+\begin{ListeDeDescription}{mmmmmmm}
+
+\item[\dusa{name}] character*12 symbolic name of a module used in the procedure.
+
+\end{ListeDeDescription}
+
+\vskip 0.4cm
+\goodbreak
+
+The LCM objects or files must be declared in the calling procedure using directives of the form:
+
+\begin{DataStructure}{Structure \dstr{descobject}}
+$[[~\{$ \moc{LINKED\_LIST} $|$ \moc{XSM\_FILE} $|$ \moc{SEQ\_ASCII} $|$ \moc{SEQ\_BINARY} $|$ \moc{HDF5\_FILE} $\}~[[$ \dusa{name} $]]$ \moc{;} $]]$ \\
+$[[~\{$ \moc{XSM\_FILE} $|$ \moc{SEQ\_ASCII} $|$ \moc{SEQ\_BINARY} $|$ \moc{HDF5\_FILE} $\}$ \dusa{name} \moc{::} \moc{FILE} \dusa{path} \moc{;} $]]$
+\end{DataStructure}
+\noindent with
+
+\begin{ListeDeDescription}{mmmmmmm}
+
+\item[\dusa{name}] character*12 symbolic name of a LCM object (memory-resident or XSM file) or of a sequential file used in the procedure.
+
+\item[\moc{FILE}] keyword used to set a file path.
+
+\item[\dusa{path}] character*72 path name of a XSM or sequential file used in the procedure. The \moc{FILE} directive is useful to select or
+create a file anywhere in the directory structure of the computer. It is also useful to tag a created file and avoid its deletion at end of
+execution.
+
+\end{ListeDeDescription}
+
+\vskip 0.4cm
+
+With this user interface, the input to a module named {\tt MOD:} with two
+embedded modules {\tt EMB1:} and {\tt EMB2:} will always be of the form:
+
+\vskip 0.4cm
+
+\noindent \begin{tabular}{|c|}
+\hline \\
+{\sl (list of output LCM objects or files)} := {\tt MOD:} {\sl (list of input LCM objects or files){\tt~::~}(data input)}
+\\ 
+ {\tt~~~~~~~~~::: EMB1:} {\sl (data input for EMB1:)} {\tt~;} {\tt~~}
+\\ 
+ {\tt~~~~~~~~~::: EMB2:} {\sl (data input for EMB2:)} {\tt~;} {\tt~;}
+\\ \\ \hline
+\end{tabular}
+
+\vskip 0.4cm
+Note that the main use of embedded modules is to define gigogne geometries in module {\tt GEO:}.
+
+\vskip 0.4cm
+
+The following user's directives are always followed by an application built
+around the generalized driver:
+
+\begin{itemize}
+\item An LCM object is resident in core memory if
+declared as {\tt LINKED\_LIST} in the input data or mapped in a direct
+access file (of {\sc xsm} type) if declared as {\tt XSM\_FILE} in the
+input data. 
+\item All the information declared as {\tt LINKED\_LIST} is
+destroyed at the end of a run. All other information is located on files which
+are kept at the end of the run, unless explicitely destroyed by a {\tt
+DELETE:} command. 
+\item Consider the following example in which the operator {\tt MOD1:} is called with the following command: 
+\begin{verbatim}
+DATA1 DATA2 := MOD1: DATA4 DATA2 ; 
+\end{verbatim} 
+Here, {\tt DATA1} is opened in {\bf create} mode because it appears only on the left-hand side (LHS) of the
+command. {\tt DATA2} is opened in {\bf modification} mode because it appears on
+both sides of the command. Finally, {\tt DATA4} is opened in {\bf read-only}
+mode because it appears only on the right-hand side (RHS) of the command.
+\item The calling sentence to an operator should always end by a ``;". A comment
+can follow on the same input data record but a carriage return should be
+performed before other significant data can be read by {\tt REDGET}.
+\item The possibility of user-defined procedures is also offered. These procedures
+give the user the possibility to ``program" an application using the capabilities of
+the generalized driver and to use it as a new operator in the main data stream or in a
+calling procedure.
+
+\end{itemize}