\chapter{Additional Topics}
\section{Defining Dynamical Systems Using the Parser Window}\label{def_ds_parser}\index{defining dynamical system}\index{defining dynamical system, using parser}

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.

The capabilities of the parser will be described by considering
a number of examples.  These examples are included as text
files in the directory \unix{\$DSTOOL/data/parser/}, and may be loaded into
the parser editor window.

While the parser is intended to be an easy-to-use general
purpose tool, for extensive and/or more sophisticated calculations with a
vector field or mapping, a full C-code model file should
be compiled into DsTool.   See section \ref{def_ds} for more 
information on this process.  This is primarily because:
\begin{enumerate}
\item Computations with the parsed dynamical system will incur additional
overhead since the code for evaluation of the dynamical system is not compiled.
\item Certain features cannot be defined by the parser.  In addition, 
they will not be included into the automatically generated C code, and 
have to be added by hand.  See section \ref{parser_limitations} on
limitations for more details.
\end{enumerate}

\subsection{Basic Functionality}\index{parsed dynamical system}

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

\begin{verbatim}
# The Lorenz system (lorenz.def)
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 setting to Vector field, and 
then select the ``Build model'' button on the Parser window in order to 
create the dynamical system from the text.


\subsection{Periodic Variables}\index{parsed dynamical system, 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=\real^2/\zed^2$:

\begin{verbatim}
# The Kim-Ostlund torus map (kotorus.def)
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
setting to Mapping before selecting ``Build model''.


\subsection{Initial Conditions and Default Ranges}\index{parsed dynamical system, initial conditions}\index{parsed dynamical system, 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.def)
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, the default
values as given in Table~\ref{parser_defaults} are used.


\subsection{Auxiliary Functions}\index{parsed dynamical system, 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.   RANGE may not be specified for 
auxiliary functions.  For example, in the Van der Pol system:

\begin{verbatim}
# The Van der Pol oscillator (vanderpol.def)
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}

\subsection{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.def)

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}


\subsection{Automatic C Code Generation}\label{automatic_c_code_generation}

For complicated dynamical systems or analyses which will require 
a large amount of computation, 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 command/window button.
This will generate C code\index{C code, automatically generated}
for the system, and open the C Code window.

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 subsection.  When the user is finished
making any modifications, 
the C code file may be saved and compiled into DsTool in the
standard way.  Section \ref{def_ds} contains a complete description
of this process.


%\newpage
\subsection{Default Values}\index{parsed dynamical system, default values}

Table \ref{parser_defaults} 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}[ht]
\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}

\subsection{Limitations and Bugs}\label{parser_limitations}\index{parsed dynamical system, limitations}

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

\item The parser cannot be used to define analytic Jacobians.  Nor can it define
explicit or approximate inverses.  These need to be added by hand into the automatically
generated C code.

\end{itemize}
