next up previous contents
Next: A Vector Field Example: Up: Installing a New Dynamical Previous: Numerical Algorithms   Contents


Installing a Defined Dynamical System

It is assumed that the reader has completed the steps in the preceding 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 user.c. 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. The user-defined models are maintained in the file user.c of the user's local DsTool directory. This file contains three relevant 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 relevant pieces of the file user.c delivered with DsTool contain the following code:

/* ----------------------------------------------------------------
 * INCLUDE USER DYNAMICAL SYSTEMS CATEGORIES HERE
 *
 * ----------------------------------------------------------------
 */
char *USER_DS_Category[] = { "User models" /* Category 0 */
                           };
 
/* ----------------------------------------------------------------
 * INCLUDE USER DYNAMICAL SYSTEM NAMES HERE
 *
 * We have put in the Lorenz system as an example
 * ----------------------------------------------------------------
 */
 
/* declare the model initialization procedure here */
extern int lorenz_init();
 
 
/* list the category, a short model name, and the initialization proc here */
struct DS_DataS USER_DS_Sel[]= {
  { 0, "Lorenz system", lorenz_init }
};

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 user.c. To install our model, we replace the line of code
  { 0, "Lorenz system", lorenz_init }
with the line of code
  { 0, "Bouncing Ball", bball_init }
in the definition of the data structure USER_DS_Sel within the third block of code. The variable USER_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 user category to which the dynamical system belongs. The category is used to group together systems which share similar properties. These categories are defined in the first block of code. Users cannot add dynamical systems to the standard list of categories. However, they can create as many new categories as they wish, by modifying the category list like so:
char *USER_DS_Category[] = { "User models", /* Category 0 */
                             "Project with Bob", /* Category 1 */
                             "My favorite dynamical systems" /* Category 2 */
                           };
This array provides the title for each category. For our example, the category index is 0, so our bouncing ball model belongs to the category named ``User models.'' (Recall that arrays in C are indexed from 0 so DS_Category$[0]$ is not an invalid array index.) 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.

Note that each dynamical system data structure must be enclosed by braces and followed by a comma. That is, all except the last. The last element in the array of dynamical systems (our new dynamical system ``Bouncing Ball'' in our example code) should not have a trailing comma.

We are now ready to compile the source code we have written. To do this, edit the Makefile in your local DsTool directory. Add the file bball_def.c to the USER_SRCS list of files, and the file bball_def.o to the USER_OBJS list of files. In the example described above, the corresponding Makefile entry would be:

        USER_SRCS = user.c bball_def.c
        USER_OBJS = user.o bball_def.o
Now save and exit the Makefile.

If our model compiles without errors, we can create a custom version of DsTool called my_dstool. To do this, execute the command make in your local DsTool directory.

Once this is done, you can ensure that this version of DsTool is executed by settting the UNIX environmental variable MY_DSTOOL to your local DsTool directory. When the script dstool_tk is run from any directory, it will execute the binary $MY_DSTOOL/bin/$ARCH/my_dstool. A message will be printed confirming which binary is being executed. 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: Installing a New Dynamical Previous: Numerical Algorithms   Contents
2009-08-07