This file outlines how to install a user-defined dynamical system.

We presume dstool is installed according to the instructions provided in
the installation section of the user's manual.  This procedure includes:

	1) Define UNIX environmental variables DSTOOL, DSTOOL_COLOR_DIR, and 
   	DSTOOL_DATA_DIR.
   	Make sure that the environment variables OPENWINHOME and 
	LD_LIBRARY_PATH are also defined. 
 
	2) Creating a local directory for dstool.  For this README file, 
	we will assume the local directory is $HOME/mydstool.

	3) Running the shellscript install_dsuser.  The normal location of
   	this script is the subdirectory $DSTOOL/bin.  After checking that 
	the environment variables above are defined, it prompts the user 
	for the name of the user dynamical system directory (the one 
	created in step (2) above) and copies the appropriate files into 
	this directory. If necessary the script creates two subdirectories of 
	$HOME/mydstool---"models" and "userlib". It then copies appropriate 
	files to each of the three directories $HOME/mydstool, 
	$HOME/mydstool/models and $HOME/mydstool/userlib.  Each of these 
	directories contains a Makefile in addition to C-language procedures.

Please be certain that these steps are complete before proceeding.  
For more information on installation, please refer to the user's manual.

The addition of a new dynamical system in dstool is a two-step process.  The
first step entails writing a few procedures which define the set of governing
equations for the dynamical system (be it a vector field or a mapping) and the
initial settings of variables and parameters.  If desired, additional procedures
may be written which define derivatives (with respect to space, time, and
parameters) and define an arbitrary number of auxillary scalar-valued functions.
The second step in the process is to install the procedures into the libraries
used to construct the executable version of dstool.  To help you complete the
necessary steps, we provide the following checklist:

1.   Define the dynamical system
	A.  Create a new file: Copy the template file GENERIC.c to the file 
		my_system_def.c. The name "my_system_def.c" may be replaced by 
		any meaningful name for a C-language file.  
	B.  Equations of motion: Begin to define the dynamical system by 
		editing the file my_system_def.c.  Write the C-language 
		procedure which defines the equations of motion. The 
		files "*_def.c" in this directory give examples of this 
		procedure. The function user_ds_func() must be edited to 
		describe the dynamical system you wish to study.
		Change the name of this function to something like 
		"my_sys_func". 
	C.  Derivatives, inverses, and auxillary equations: if desired, 
		write C-language procedures which define the jacobian, 
		explicit or approximate inverses (for mappings), and 
		auxillary equations.  All of these functions are optional.
	D.  Initialization procedure: You will also have to edit the 
		initialization procedure user_init(), changing it's name to 
		something like "my_sys_init". Within the body of my_sys_init(), 
		you must specify
		   i.   Names and default plotting ranges for variables;
		   ii.  Names and default plotting ranges for parameters;
		   iii. Names and default plotting ranges for auxillary 
			functions;
		   iv.  Which, if any, variables are periodic;
		   v.   Names of the user-defined functions defined in 2A and 2B.
			For example, identify the name of the dynamical system 
			function (e.g. "my_sys_func") by replacing the line
				int            (*def_name)()=NULL;
			with
				int            (*def_name)()=my_sys_func;
2. Install the dynamical system
	A.  Install initialization routine and system title:  The system 
		needs to be informed about the name you have chosen for 
		the initialization function. Edit the file 
		$HOME/mydstool/modellib_ds_def.h and, following the examples
		there, add a declaration line like
			extern int mysys_init();
		and also include a line such as
			{ 2, "My Dynamical System", my_sys_init },
		to modify the initialization of the structure "DS_Sel."
		The middle entry "My Dynamical System" will be the menu entry
		you need to select the system when dstool is running. With the
		choice "2" above of system type, it will appear on a submenu 
		of the entry "Special Dynamical Systems".
	B.  Edit the Makefile: Add the file "my_system_def.c" to the 
		list SOURCES_A in the file $HOME/mydstool/models/Makefile.
	C.  Compile: Change to the parent directory $HOME/mydstool and give the
		command "make dstool_u". This should produce the user customized
		executable "dstool_u".
