.TH DSTOOLTK 1 "9 September 1992"
.SH NAME
dstooltk \- dynamical systems analysis and exploration toolkit, Version 2.0
.SH SYNOPSIS
.B dstooltk
[
.B \-infile
.I filename
]
[
.B \-version
]
.B dstool_u
[
.B \-infile
.I filename
]
[
.B \-version
]
.SH DESCRIPTION
This manual page is mainly copied from the manual page for
dstool with an xview front end.  The bulk of the discussion
applies to dstooltk, which has a tk front end.  There is 
a user's manual written specifically for dstooltk, which is included
in the package 'dstooltk-doc'.  The other documents referred to 
below are included in the package 'dstool-doc' .

This manual page  sketches
.B DsTool
use. For more details, please see the 
.B DsTool Users Manual, DsTool Referance Manual, 
.B DsTool Installation Manual,
and the 
.B DsTool Tutorial.
.SS Environment Variables
The following environment variables are important for 
DsTool usage:

.RS
.B DSTOOL
\- location of the main DsTool 
distribution, for example /usr/local/dstool.

.B DSTOOL_COLOR_DIR
\- location of colormaps. When not set, $DSTOOL/colormaps is used.

.B DSTOOL_DATA_DIR
\- default directory for users to save their DsTool 
configuration and print files. When not set, the current working directory
is used.

.B DSTOOL_CONFIG
\- filename of configuration file which is loaded automatically on startup

.B OPENWINHOME
\- location of the standard Open Windows distribution

.B LD_LIBRARY_PATH
\- colon separated list of directories to be searched at runtime for
dynamic linking; should include $OPENWINHOME/lib.

.SS Command Window
The 
.I Command Window 
is the main control panel for the dynamical
system toolkit. It is opened at startup and contains: 

.RS
.B Model stack setting
\- select a model to study.

.B File menu button
\- open the 
.I Load 
or 
.I Save 
windows.

.B View menu button
\- open the 
.I Two Dimensional View 
window.

.B Panels menu button
\- open the 
.I Orbits, Fixed Point, Multiple
or other
.I User-Defined
windows.

.B Settings menu button
\- open the
.I Selected, Function, or Defaults
windows.
.SS Model
Users entering their own models should first create a 
.I user dstool configuration
by invoking the script $DSTOOL/bin/install_dsuser. The top directory of
this configuration contains two subdirectories, 
.I models 
and 
.I userlib,
as well as a Makefile for creating a user customized executable 
.I dstool_u.
A 
.I README 
in the models subdirectory describes the process for actually entering
a new model.
.SS Load
Files may be loaded in 
.I DsTool format 
to re-establish a user computational state
or 
.I unformatted
to allow importing into 
dstool data objects. Formats for importing unformatted data are described
in the
.B DsTool Reference Manual.
.SS Save
The 
.I Save Window
controls saving data to files. Formats are described in the
.B DsTool Reference Manual.
The options control which elements are saved. Available choices 
and the principal components they refer to are:

.RS
.B Current Settings 
\- basic data including initial conditions, parameter values, and 
default settings.

.B Configuration
\- positions and sizes of most windows, including the
options associated with view windows.

.B Trajectories
\- phase space coordinates of points on trajectories.

.B Fixed Points
\- equilibria for vector fields, periodic points for mappings,
and stable/unstable manifolds.

.B Continuation Data
\- continuation curves.

.B Parameter Data
\- points in parameter space.

.B Selected Points
\- points in the product of phase space with parameter space
specifically added to view windows as annotation.

.B Function Values
\- values of auxiliary functions, the corresponding phase space coordinates,
and parameters.

.SS 2-D Image
This window supports many viewing options. The coordinates of the 
pointer in the windows are displayed whenever the pointer is in the
canvas viewing area. The 
.I options
menu button contains entries to perform tasks including
.I refreshing windows,
.I setting or using default plotting ranges,
.I opening a view options panel,
and
.I opening a print panel.

Accelerator mouse buttons available include:

.RS
.B <SELECT> 
\- set two coordinates of the initial condition and set direction to forward. 

.B <ADJUST>
\- begin or continue orbit in the current direction.

.B <MENU> 
\- set two coordinates of the initial condition and set direction to backwards.

.B <CONTROL-ADJUST>
\- clear data. For details on which data is cleared, see the 
.B dstool Users Manual.

.B <SHIFT-SELECT>
\- dragging sets a zoom box for the window, and a notice allows one to
set the direction of zooming.

.B <CONTROL-SELECT>
\- select a two dimensional portion of a control box for the 
.I multiple
orbits window.
.SS 2-D View Options
Functions available here include:

.RS
Adding selected points or parameter data using a given 
symbol and size.

Changing background color of a view window.

Load a new colormap.

Changing colormap type of a view window. For trajectories, 
color can be set as:

.RS
.TP 4
.B Alternating
\- automatic advance when a new trajectory starts.
.TP 4
.B Pick Colors
\-  advance when a user selects a color by clicking <SELECT> on a colorbar.
.TP 4
.B Depth
\- using the value of a variable, parameter or function to select
color from the available colormap.
.SS Print
The 
.I Print Window
allows a user to output the contents of a viewing window in postscript
to either a file or printer.
.SS Orbits 
The 
.I Orbits Panel 
allows users to set conditions for orbit propagation. Available stopping 
conditions include:

.RS
.B Fixed Steps
\- stop after a fixed number of steps based on the integer in the
.I Stop
text field.

.B Event Stopping
\- stop when one of the variables or functions crosses a value.

.B Fixed Time
\- stop when time crosses a value.

.B Poincare Section
\- generate a Poincare section using a surface which is a union of level
sets of variables or auxiliary functions.
.SS Propagation
The 
.I Propagation Panel
allows users to set integrators/iterators and various parameters
relative to their use.
.SS Multiple Orbits
The
.I Multiple Orbits 
allows users to generate a set of trajectories starting from a 
(bounded part of) a lattice of initial conditions or using a 
lattice of parameter values.
.SS Fixed Point
The 
.I Fixed Point Panel 
allows users to find equilibria of vector fields, periodic points of mappings,
and compute one dimensional stable/unstable manifolds.
.SS Selected
The 
.I Selected Point Panel
allows users to examine and modify the current values of variables and
parameters.
.SS Function
The
.I Function Panel
displays the values of user defined functions.
.SS Defaults
The
.I Defaults Settings Window
allows the user to adjust default plotting ranges for variables,
parameters, and auxiliary functions, as well as setting a number of other
global flags and values. 
.SS Other User Panels
There is a mechanism for adding 
.I User Panels
which function on almost equal footing with other dstool
panels. Please refer to the 
.B DsTool Reference Manual
for details on this.

There are also contributed user panels in the directory 
$DSTOOL/contrib. These have man pages in 
subdirectories of $DSTOOL/man.
.SH OPTIONS
dstool
is an xview based program and accepts normal 
.I xview
display related command line arguments. See the
.B  xview (1)
man page for descriptions of these.


.B \-c filename
Use the named file to configure dstool. 
Configuration files are created with the dstool 
.I Save
panel.

.SH AUTHORS
J. Guckenheimer, M. R. Myers, F. J. Wicklin, P. A. Worfolk

Center for Applied Mathematics, Cornell University

Ithaca, New York 14853
.SH FILES
$DSTOOL, $DSTOOL/bin/dstool, $DSTOOL/bin/install_dsuser,
$DSTOOL/bin/install_dstool, $DSTOOL/src, $DSTOOL/include,
$DSTOOL/colormaps, $DSTOOL/site_specific
.SH SEE ALSO
.B install_dsuser(1), dstool_browser(l), dstool_parser(l), xview (1), install_dstool(8)

.B dstool Users Manual, dstool Tutorial, 
.B dstool Reference Manual, dstool Installation Manual
.SH BUGS

Please report these as well as other comments related to
DsTool to 
.I dstool_bugs@macomb.tn.cornell.edu.

If you would like to be included on a DsTool mailing list to 
receive
notices about DsTool updates, future releases, and bug 
fixes, please send your e-mail address to
.I dstool-list@macomb.tn.cornell.edu.