
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.


   * Overview
   * Basic Functionality
   * Periodic Variables
   * Initial Conditions and Default Ranges
   * Auxiliary Functions
   * Temporary Functions
   * Automatic C code generation
   * Default Values
   * The Dynamical System Parser Window
   * Limitations and Bugs



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.



Basic Functionality

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

# 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

We denote the time derivative of a variable by a prime, '. 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:

        constants: PI, pi, E
        operators: +, -, *, /, % (mod), ^
        special functions: sin, cos, tan, asin, acos, atan, sinh, cosh,
                tanh, log, ln, exp, abs, sqrt

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.



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,
[tex2html_wrap_inline80] :

# 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

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.



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:

# 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

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 are used.



Auxiliary Functions

Auxiliary functions may be declared by defining them 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:

# 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

Note: RANGE may not be specified for auxiliary functions.



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

# 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



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.



Default Values

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



         Item                                Vector Field  Mapping
         Variable Initial Value                   0.0        0.0
         Variable Range Minimum                  -10.0      -1.0
         Variable Range Maximum                  10.0        1.0
         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
         Parameter Initial Value                  1.0        1.0
         Parameter Range Minimum                 -10.0      -10.0
         Parameter Range Maximum                 10.0       10.0
         Auxiliary Function Range Minimum        -10.0      -10.0
         Auxiliary Function Range Maximum        10.0       10.0
                           Table: Default values.





The Dynamical System Parser Window


Figure:   The Dynamical System Parser Window.

Window title:
     Dynamical System Parser

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.

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.

Window type:
     pop-up

Window attributes:
     resizable, pinnable(in), fixed template

Panel items:
        o 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.
        o Type exclusive setting: This field defines whether the dynamical
          system should be interpreted as a vector field or a mapping.
        o 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.
        o 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.
        o 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.
        o 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.

Library name:
     parserlib.a

Models interface:

             extern int parser_open();

Models DS_DataS entry:

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



Limitations and Bugs

   * 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, , 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.
   * Ranges for auxiliary functions may not be set.
   * 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.
   * The same temporary functions are used for both the definition of the
     dynamical system and the auxiliary functions.



