\documentstyle[psfig]{article}


% Definition for bitmap images to be included into LaTeX documents
%\def\sunbitmap#1#2#3#4{%
% \hfill \hbox to #1{%
%  \vbox to #2{
%   \vss
%   \special{pre: sunbitmap #3 #40}
%   \special{ps: sunbitmap #3 #40}
%  }%
% }%
% \hfill
%}

% set margins to 1 inch + specified quantity
\oddsidemargin 0.25in
\topmargin 0.25in
\headheight 0.25in

\textwidth 6in 
\headsep 0in
\textheight 8.25in

% set special fonts
\font\setfont=eufm10

\begin{document}


\begin{center}
{\LARGE \bf Dynamical System Parser Interface to dstool}  \\
\vspace{.15in}
{\large \bf Custom User Application Panel}
\end{center}

\vspace{.2in}
\begin{tabbing}
00000000000000000000\=00000000012345678\=00000123\=0123456789\=0123456789\=0123456789\=0123456789\=0123456789 \kill
\>{\bf Author: } \> Patrick A. Worfolk \\
\>	       \> Center for Applied Mathematics  \\
\>	       \> Cornell University \\
\>	       \> Ithaca, New York \hspace{.1in}  14853 \\
\>	       \> paw@macomb.tn.cornell.edu \\
\>	       \>   \\
\>{\bf Version: }\> 1.0 \hspace{.07in}  for dstool Version 1.1   \\
\>	       \>   \\
\>{\bf Bug Reports: } \> dstool\_bugs@macomb.tn.cornell.edu
\end{tabbing}
\vspace{.2in}


\noindent {\large \bf Purpose:}  
	This panel provides a text interface to dstool for inputting dynamical
	systems. The text is parsed allowing the creation of new dynamical
	systems without recompilation, but with a cost in performance.
	This is especially useful for experimentation and classroom
	exercises.
	The panel can produce C code from the textual dynamical
	system which may be compiled into dstool if greater
	efficiency in computation is needed for more
	substantial explorations.
\vspace{.15in}

\section{Overview}

We will describe the method for inputting dynamical systems
to a parser interface to dstool.  The parser allows the
user to define a vector field or mapping in a simple
textual format as opposed to C code language.  
This may be extended to a full description of the
dynamical system by defining initial conditions
and default ranges for the variables and parameters,
declaring variables periodic on a specified interval,
and defining auxiliary functions.

Once a dynamical system has been defined in a text window,
it may be interpreted and examined within dstool.  Computations
with the dynamical system will incur additional
overhead since the code for evaluation of the dynamical
system is not compiled.  
C code can be created from the panel for the dynamical
system which may be compiled into dstool for more
efficient exploration.

The capabilities of the parser will be described by considering
a number of examples.  These examples are included as text
files with the code for this panel and may be loaded into
the parser editor window.  This window is a standard XView 
Text Pane window and the basic command menu is accessed
by depressing the Menu button (usually right button)of
the mouse when the pointer is in the window.  These
examples can be loaded into the text window by selecting
the Load File option from the File option on the Text Pane
menu.

The parser cannot be used to define analytic
Jacobians.  Nor can it define explicit or approximate
inverses.  However, these can be added by hand into the automatically
generated C code.


\section{Basic Functionality}

The basic defining equations for a dynamical system are
entered in the following format:

\begin{verbatim}
# The Lorenz system (lorenz.p)
x' = sigma ( y - x ) 
y' = rho x - y - x z
z' = -beta z + x y

INITIAL sigma 10 rho 28 beta 2.6667
\end{verbatim}

We denote the time derivative of a variable by a prime, {\tt '}.  This is followed by
an equals sign and then the right hand side.  A mapping is input in the
same format using the prime to indicate the new point in phase space.
Variable and parameter names are alphanumeric strings beginning with an 
alphabetic character.
Any undefined string is understood to be a parameter in the system.   

Comments are allowed at the end of any line and must
begin with the pound character, \#.
As seen in the above example, multiplication is understood,
when no arithmetic operator is present, but it may be
explicitly indicated with an asterisk, *
The INITIAL declaration assigns initial values to the parameters.

The parser understands the following fundamental constants, operators, and
special functions:

\begin{verbatim}
	constants: PI, pi, E
	operators: +, -, *, /, % (mod), ^
	special functions: sin, cos, tan, asin, acos, atan, sinh, cosh, 
	        tanh, log, ln, exp, abs, sqrt
\end{verbatim}
The special functions all correspond to standard C math library functions.

If you try this example, set the dynamical system type to Vector field, and 
then select the Build button on the Dynamical System Parser Window in order to 
create the dynamical system from the text.


\section{Periodic Variables}

Phase space variables may be declared periodic on a fixed interval
by using the PERIODIC command.  We define the following map on the
torus, $T^2=R^2/Z^2$:

\begin{verbatim}
# The Kim-Ostlund torus map (kotorus.p)
x' = x + w1 - a / (2 PI) sin(2 PI y)
y' = y + w2 - a / (2 PI) sin(2 PI x)

INITIAL w1 0.6 w2 0.805 a 0.7
PERIODIC x 0 1 y 0 1
\end{verbatim}

The PERIODIC command should only be given once in the definition
and all periodic variables should be declared, but optionally may be placed
on separate lines.  
When trying this example, don't forget to set the dynamical system type
to Mapping before selecting Build.


\section{Initial Conditions and Default Ranges}

Initial conditions for the parameters and variables and their default
ranges may be declared using the INITIAL and RANGE commands.  These specify
specific initial values for the parameters and variables and the default ranges
for display purposes.  Any or all of the parameters and variables may
be specified in either case.  We look at Duffing's equation, for example:

\begin{verbatim}
# The Duffing oscillator (duffing.p)
x' = y
y' = - alpha y + (beta - x^2) x + gamma cos(omega t)
t' = 1

INITIAL alpha 0.5 beta 0 gamma 10 omega 1
        x -5 y 4 t 0
RANGE x -6 6 y -6 6
\end{verbatim}

Note that in this example, we explicitly augment the phase space
with the variable t (else the parser will think t is a parameter).
When initial conditions or ranges are not specified, then the default
values as given in Table~\ref{parser_defaults} are used.


\section{Auxiliary Functions}

Auxiliary functions may be declared by defining them {\em after} the dynamical system equations.
They should have the same format as the dynamical system, but do not use the prime
after the name of the auxiliary function.   For example, in the Van der Pol system:

\begin{verbatim}
# The Van der Pol oscillator (vanderpol.p)
x' = y 
y' = alpha (1 - x^2) y - x + beta cos(omega t)
t' = 1

Rsqr = x x + y y     # square of polar radial coordinate

INITIAL alpha 1.0 beta 0 omega 1.0
RANGE x 3 -3 y 3 -3
\end{verbatim}

Note: RANGE may not be specified for auxiliary functions.

\section{Temporary Functions}

In order to improve evaluation efficiency, it is often useful
to define temporary variables to be used in the definition of
vector fields or auxiliary functions.  This can be done by
defining a function {\em before} defining the dynamical system.
Here is an example where temporary variables are used
in both the vector field definition and in the auxiliary functions
definition.

\begin{verbatim}
# A D4 symmetric system (d4symm.p)

xsq = x x       # xsq and zsq are temporary functions
zsq = z z

x' = y        
y' = x (mu - (xsq+zsq)) + delta x zsq + 
     epsilon ((xsq+zsq) y + nu y + Axzw x (x y + z w) + Ayz2 y zsq
z' = w
w' = z (mu - (xsq+zsq)) + delta z xsq + 
     epsilon ((xsq+zsq) w + nu w + Axzw z (x y + z w) + Ayz2 w xsq

Energy = 0.5 (y y + w w - mu (xsq + zsq) + 0.5 (xsq + zsq) (xsq + zsq) - 
              delta xsq zsq)
AngMom = y z - x w

INITIAL mu 2 delta 0.95 epsilon 0 nu -3.52 Axzw 1 Ayz2 0
RANGE x -5 5 y -5 5 z -5 5 w -5 5
\end{verbatim}


\section{Automatic C code generation}

For complicated dynamical systems or analyses which will require 
a large amount of computation, then the user will wish to code
the dynamical system in C.  If the model is written for
the parser, then the parser may be able to do most of the
work of writing the C language procedures necessary to 
interface into dstool.  The system can be built and tested using
the parser and when the user has decided on a set of satisfactory initial
conditions and ranges, the user may fill in the Name field with a single
descriptive word and select the Write C code option.
This will produce a new Text Pane window with C code for
the system.  

The code may be immediately edited, if for example the user
wishes to add explicit Jacobian or inverse routines.  Additionally,
the C code may be made more efficient or functions may be
implemented which are unavailable in the parser.
Any information which was not supplied through the parser
will be assigned a default value.  These are listed in
the table in the following section.  When the user is finished
making any modifications, 
the C code file may be saved and compiled into dstool in the
standard way.  The dstool User's Manual contains a complete description
of this process.


\newpage
\section{Default Values}

The following table gives the defaults which are used
in defining the dynamical systems.  The items in {\bf bold}
are ones which may be specified explicitly by the user
within the textual description of the dynamical system.

\begin{table}[h]
\begin{center}
\begin{tabular}{|l|c|c|} \hline
Item & Vector Field & Mapping \\ \hline \hline
{\bf Variable Initial Value} 	& 0.0 	& 0.0 \\
{\bf Variable Range Minimum}	& -10.0	& -1.0 \\
{\bf Variable Range Maximum}	& 10.0 	& 1.0 \\ \hline
Independent Variable Name & time & iter \\
Independent Variable Initial Value & 0.0 & 0 \\
Independent Variable Range Minimum & 0.0 & 0 \\
Independent Variable Range Maximum & 10000.0 & 10000 \\ \hline
{\bf Parameter Initial Value}	& 1.0	& 1.0 \\
{\bf Parameter Range Minimum}	& -10.0	& -10.0 \\
{\bf Parameter Range Maximum}	& 10.0	& 10.0 \\ \hline
Auxiliary Function Range Minimum & -10.0 & -10.0 \\
Auxiliary Function Range Maximum & 10.0 & 10.0 \\ \hline
\end{tabular}
\end{center}
\caption{Default values.}
\label{parser_defaults}
\end{table}


\newpage
\section{The Dynamical System Parser Window}
%
%
%
\begin{figure}[h]
\vspace{.5in}
%\sunbitmap{3in}{1in}{parser.ras}{55}
\centerline{\psfig{figure=parser_fig.ps,height=1in,width=3in}}
\caption{\label{parser}
The Dynamical System Parser Window.
}
\end{figure}

%
%
%
\begin{description}

\item[Window title:] Dynamical System Parser

\item[Function:] This window is used to input a dynamical
	system into dstool which is parsed at runtime.  It can
	also write out the dynamical system in C code.
	
\item[Description:] The Dynamical System Parser Window is a user window
	and is optionally a part of the dstool executable.  It is opened
	by selecting the Parsed dynamical system in the Parser category
	of the Models menu on the Command Window.  The panel appears containing
	text describing the Lorenz system.

\item[Window type:] pop-up    

\item[Window attributes:] resizable, pinnable(in), fixed template

\item[Panel items:]\mbox{}
    \begin{itemize}
	\item Name read-write text field: This field is for giving a name
		to the dynamical system which is used in the C code procedure
		names.  This should be a single word of no more than 30 characters.
	\item Type exclusive setting: This field defines whether the dynamical
		system should be interpreted as a vector field or a mapping.
	\item Build command button: Selecting this button will convert the
		text from the scrolling text window into a dynamical
		system and then load this as a new model into dstool.
		Any errors encountered while parsing will be sent to the
		parent window and the previous dynamical system will remain active.
	\item Write C code window button: Selecting this button will open
		the Dynamical System Definition Editor window.  The text from 
		the scrolling text window will be converted into C code in
		dstool's model format.
	\item Scrolling text field: This portion of the window contains the text that
		the user types to define a dynamical system.  This
		is a standard XView text window widget and uses the 
		standard keyboard and mouse commands.  Use the Menu (usually, Right) 
		button on the mouse for a selection of various standard editing features.
	\item Dynamical System Definition Editor: This window is created by selecting
		the Write C code button on the Dynamical System Parser window.  It
		contains C code which attempts to define in dstool format the dynamical system
		entered by the user in the Dynamical System Parser scrolling text field.
		This is a standard XView text window widget so the code may be modified
		by the user and then saved as a file suitable for compilation into dstool.
    \end{itemize}

\item[Library name:] parserlib.a

\item[Models interface:] \mbox{}
	\begin{verbatim}
	extern int parser_open();
	\end{verbatim}

\item[Models DS\_DataS entry:] \begin{verbatim}

	/* Category 3 - Parser */
	{ 3, "Parsed dynamical system...", parserwin_open}
	\end{verbatim}

\end{description}


\section{Limitations and Bugs}

\begin{itemize}

\item The conversion to C code is weak.  Essentially, the input
must be written in C code format, with or without the multiplication
operator.  The exponentiation operator, $\hat{}$, will be translated directly,
but this is not a valid C command.  Parentheses need to be included with
the special operators for a correct translation to C.

\item Ranges for auxiliary functions may not be set.

\item The independent variable name, initial value, and default
range cannot be set.  Nonautonomous vector fields are not allowed;
they must be embedded in autonomous ones by augmenting the
phase space.

\item The same temporary functions are used for both the definition of the dynamical
system and the auxiliary functions.

\end{itemize}

\section{Acknowledgements}

The parser included here is the modification of one
given to the author by Swan Kim.

\end{document}

