next up previous contents
Next: A Vector Field Example Up: Defining Dynamical Systems Previous: Numerical Algorithms   Contents


Installing a Defined Dynamical System

It is assumed that the reader has completed the steps in the preceeding sections of this chapter. In this section, we describe the installation of the dynamical system defined using the above steps. As an illustration, we continue with the bouncing ball example.

Our first task is to modify the file modellib_ds_def.h which should be found in the user's local models directory. There are two steps to this process:

During the execution of dstool, the user may select one of several installed dynamical systems. The program maintains a list of installed models, along with the procedures which initialize and define them. This list is maintained in the file modellib_ds_def.h. This file contains three blocks of C-code: the first block defines an array of categories used to collect dynamical systems into related classes; the second consists of several lines beginning with the declaration extern int; the last block is a C-language structure which contains titles for the models along with names of the models' initialization procedures. The modellib_ds_def.h delivered with dstool contains the following code:

/* This is a configuration file for dynamical systems */
#include <modellib.h>
struct  DS_DataS	DS_model;
char    *DS_Category[] = { "Standard Mappings",         /* category 0 */
                           "Standard Vector Fields",    /* category 1 */
                           "Special Dynamical Systems"};/* category 2 */

/* ------------------------------------------------------------------ */
/*   declare names of initialization routines                         */
/* ------------------------------------------------------------------ */
extern int      lorenz_init(), cubic_init(), vdpol_init();
extern int      standard_init(), ko_init(), henon_init();
extern int      hh_init(), d4_init(), pfork_init();

/* ------------------------------------------------------------------ */
/* fill structure according to: { category, title, init_routine }     */
/* ------------------------------------------------------------------ */
struct DS_DataS DS_Sel[] = {
       { 0, "Standard Map", standard_init },
       { 0, "Kim-Ostlund Torus Map", ko_init },
       { 0, "Complex Henon Map", henon_init },
       { 1, "Lorenz System", lorenz_init },
       { 1, "Planar Cubic Vector Field", cubic_init },
       { 1, "Forced Van der Pol Eqns", vdpol_init }, 
       { 2, "D4 Symmetric System", d4_init },
       { 2, "Hodgkin Huxley Equations", hh_init },
       { 2, "Pitchfork NF Vector Field", pfork_init }
     };

/* ------------------------------------------------------------------ */
/* do not edit beyond this line                                       */
/* ------------------------------------------------------------------ */
int     DEFAULT_SYSTEM = 0; 
int     N_DS = sizeof(DS_Sel) / sizeof(struct DS_DataS);
int     N_DS_Category = sizeof(DS_Category) / sizeof(char *);

To tell dstool the name of the initialization routine which defines our bouncing ball model, we need to add the line

extern int  bball_init();
to the second block of code in modellib_ds_def.h. To install our model, we add the line of code
{2, "Bouncing Ball", bball_init},
to the definition of the data structure DS_Sel within the third block of code. The variable DS_Sel is an array, each element of which is a data structure which defines a dynamical system. The first element of the structure is a number which specifies the category to which the dynamical system belongs. The category is used to group together systems which share similar properties. The default list of categories is defined by the lines in the first block of code:
char    *DS_Category[] = { "Standard Mappings",         /* category 0 */
                           "Standard Vector Fields",    /* category 1 */
                           "Special Dynamical Systems"};/* category 2 */
This array provides the title for each category. For our example, the category index is 2, so our bouncing ball model belongs to the category named ``Special Dynamical Systems.'' (Word to novice C programmers: remember that arrays in C are indexed from 0 so DS_Category[2] is not the second title, but is actually the third.) Every dynamical system must belong to a valid category.

The next element of the dynamical system data structure is the title of the system being defined. We have chosen ``Bouncing Ball'' as the title of our system. Any descriptive title will do, provided that the length of the title is not larger than the global constant MAX_LEN_DS_TITLE. The value of this constant is found in the file $DSTOOL/src/include/constants.h.

The last element is the name of the function which contains the initialization routine for the new dynamical system. For our example, the name is bball_init.

Notice that each dynamical system data structure is enclosed by braces and is followed by a comma. That is, all except the last. The last element in the array of dynamical systems (the system entitled ``Pitchfork NF Vector Field'' in our example code) does not require a trailing comma.

We are now ready to compile the source code we have written and to assemble the code into a library called modellib.a. To do this, edit the file Makefile in your models subdirectory. Add the file bball_def.c to the SOURCES_A list of files. In the example described above, the corresponding Makefile entry would be:

SOURCES_A =     \
                models.c \
                standard_def.c \
                kotorusmap_def.c \
                henon_def.c \
                lorenz_def.c \
                cubic_def.c \
                vdpol_def.c \
                bball_def.c  \
                d4_def.c  \
                hh_def.c \
                pitchfork_def.c
Now save and exit the Makefile. To build modellib.a, type make modellib.a. If the compiler reports errors, correct them by editing bball_def.c and attempt to build modellib.a again.

Once modellib.a is constructed without error, we can create a custom version of dstool called dstool_u. To do this, change to your local dstool directory and make a custom version of dstool with the command

make dstool_u
If the file dstool_u is made, then this local (user) version of dstool may be executed by the command
dstool_u
This version of dstool will include the bouncing ball equations among its installed dynamical systems.


next up previous contents
Next: A Vector Field Example Up: Defining Dynamical Systems Previous: Numerical Algorithms   Contents
root
1998-11-02