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.