\documentstyle{article}

\include{macros}

\begin{document}

\begin{center}
{\LARGE \bf Complib\_Test Propagation Program}  \\

\vspace{.15in}
{\large \bf Subsection Test and Verification Driver}
\end{center}

\vspace{.2in}
\begin{tabbing}
00000000000000000000\=00000000012345678\=00000123\=0123456789\=0123456789\=0123456789\=0123456789\=0123456789 \kill
\> {\bf Authors: }\> dstool Software Group \\
\> \>        Center for Applied Mathematics  \\
\> \>        Cornell University \\
\> \>        305 Sage Hall \\
\> \>        Ithaca, New York \hspace{.1in}  14853 \\
\> \>          \>   \\
\>{\bf Version: }\> 1.0 \hspace{.07in}  (Last Change: August 1992)   \\
\>             \>   \\
\>{\bf Bug Reports: } \> dstool\_bugs@macomb.tn.cornell.edu
\end{tabbing}
\vspace{.2in}

\noindent {\large \bf Purpose:}  The {\em complib\_test} utility provides a standalone driver for
the propagation subsection of the dstool software package.
In construction, the main procedure performs the role of
a level 2 routine (see dstool PDS documentation), which initializes the data structure 
used to pass data to the iteration routines (iterated maps) or integration
algorithms (vector fields).  This program can emulate any propagation calculation which can
be performed by dstool and, in addition, allows the programmer or algorithm designer the
opportunity to study the implementation of a new routine apart from the interactive windowing
system so that properties such as convergence and timing behavior can be accurately established.
\vspace{.15in}

\section{Overview:}

\noindent The complib\_test main program serves as a Level-2 interface routine to the propagation 
subsection of dstool;  see the dstool Reference Manual \cite{ref1} for more details on the organization
of the propagation routines collected together in the {\em complib.a} subroutine library for dstool.
The program complib\_test and dstool share the same computation engine, and
complib\_test executes precisely the same computation routines in exactly the same way as dstool.
It is composed of a main driver, {\em driver.c}, and a collection
of enumerated program files which specify individual tests which are used to exercise the integration
and iteration code. 
The distribution version of the complib\_test program has been pre-configured to include
eight problem testcases selected from a variety of sources in the literature;   however,
the real utility of complib\_test should become evident when the dstool user installs problem
files which pertain to the dynamical systems of their research interests.
\medskip

\noindent To create the complib\_test program, merely change the current directory to that which contains
the complib\_test source and invoke the UNIX make utility:
\begin{tabbing}
00000000000000000000\=00000000012345678\=00000123\=0123456789\=0123456789\=0123456789\=0123456789\=0123456789 \kill
\> cd \$\{DSTOOL\}/src/computation/complib/TEST\_DRIVER \\
\> make complib\_test
\end{tabbing}
at the UNIX prompt;  the file called Makefile contains a complete set of instructions for creating an executable
version from the source code.  Once this step is complete, complib\_test may be called to execute any one of
several pre-installed example testcases, selected using the following command-line arguments:
\bigskip

\hspace{.25in}\parbox[b]{.5in}{-p}
\parbox[t]{4.6in}{
Program identification number.  The next Section of this document provides 
a description of each problem that comes installed in the distribution version.
A particular problem is specified by typing its identification number following 
the -p option flag.  If no identification number is provided, complib\_test will 
execute the default problem,  the integration of a linear vector field. 
}
\bigskip

\hspace{.25in}\parbox[b]{.5in}{-m}
\parbox[t]{4.6in}{ 
Integration method. If the problem defined is the propagation of a flow for a
vector field, the integration method is selected using this command-line 
argument.  Any integration method installed in dstool may be specified;  for the
current distribution release, fixed-step $4^{th}$-order Runge-Kutta (option 0),
Euler's method (option 1), variable-step $4^{th}$-order Runge-Kutta (option 2) 
and Bulirsch-Stoer (option 3) are allowed choices.
}
\bigskip

\hspace{.25in}\parbox[b]{.5in}{-a}
\parbox[t]{4.6in}{  
Execute all allowed integration methods on the specified test problem.  This option 
has no meaning if the specified problem is an iterated mapping.
}
\bigskip
\bigskip

\noindent For example, the following command would execute the $4^{th}$ installed testcase
problem using the variable-step Runge-Kutta integration algorithm:
\begin{tabbing}
00000000000000000000\=00000000012345678\=00000123\=0123456789\=0123456789\=0123456789\=0123456789\=0123456789 \kill
\> complib\_test -p 4 -m 2
\end{tabbing}
while the command:
\begin{tabbing}
00000000000000000000\=00000000012345678\=00000123\=0123456789\=0123456789\=0123456789\=0123456789\=0123456789 \kill
\> complib\_test 
\end{tabbing}
would produce a sequence of integrate points for the default vector field using the fixed-step Runge-Kutta
technique, a trajectory for the differential equation $\dot{y} \! = \! -y$, as described below.


\input{problems}

\clearpage

\input{biblio}

\end{document}

