--- name: "dstool" section: "1" platform: "linux" package: "dstool" version: "2.0-4" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/dstool" --- # dstool(1) dynamical systems analysis and exploration toolkit, Version 2.0 ## NAME dstool - dynamical systems analysis and exploration toolkit, Version 2.0 ## SYNOPSIS **dstool** \[ **-infile** *filename* \] \[ **-version** \] **dstool\_u** \[ **-infile** *filename* \] \[ **-version** \] ## DESCRIPTION This manual page sketches **DsTool** use. For more details, please see the **DsTool Users Manual, DsTool Referance Manual,** **DsTool Installation Manual,** and the **DsTool Tutorial.** ## DEBIAN INSTALLATION In the Debian installation, the environment variables below need not be set. They are set by a shell script when dstool is invoked. See documentation in the directory /usr/doc/dstool. ### Environment Variables The following environment variables are important for DsTool usage: **DSTOOL** - location of the main DsTool distribution, for example /usr/local/dstool. **DSTOOL\_COLOR\_DIR** - location of colormaps. When not set, $DSTOOL/colormaps is used. **DSTOOL\_DATA\_DIR** - default directory for users to save their DsTool configuration and print files. When not set, the current working directory is used. **DSTOOL\_CONFIG** - filename of configuration file which is loaded automatically on startup **OPENWINHOME** - location of the standard Open Windows distribution **LD\_LIBRARY\_PATH** - colon separated list of directories to be searched at runtime for dynamic linking; should include $OPENWINHOME/lib. ### Command Window The *Command Window* is the main control panel for the dynamical system toolkit. It is opened at startup and contains: **Model stack setting** - select a model to study. **File menu button** - open the *Load* or *Save* windows. **View menu button** - open the *Two Dimensional View* window. **Panels menu button** - open the *Orbits, Fixed Point, Multiple* or other *User-Defined* windows. **Settings menu button** - open the *Selected, Function, or Defaults* windows. ### Model Users entering their own models should first create a *user dstool configuration* by invoking the script $DSTOOL/bin/install\_dsuser. The top directory of this configuration contains two subdirectories, *models* and *userlib,* as well as a Makefile for creating a user customized executable *dstool\_u.* A *README* in the models subdirectory describes the process for actually entering a new model. ### Load Files may be loaded in *DsTool format* to re-establish a user computational state or *unformatted* to allow importing into dstool data objects. Formats for importing unformatted data are described in the **DsTool Reference Manual.** ### Save The *Save Window* controls saving data to files. Formats are described in the **DsTool Reference Manual.** The options control which elements are saved. Available choices and the principal components they refer to are: **Current Settings** - basic data including initial conditions, parameter values, and default settings. **Configuration** - positions and sizes of most windows, including the options associated with view windows. **Trajectories** - phase space coordinates of points on trajectories. **Fixed Points** - equilibria for vector fields, periodic points for mappings, and stable/unstable manifolds. **Continuation Data** - continuation curves. **Parameter Data** - points in parameter space. **Selected Points** - points in the product of phase space with parameter space specifically added to view windows as annotation. **Function Values** - values of auxiliary functions, the corresponding phase space coordinates, and parameters. ### 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 *options* menu button contains entries to perform tasks including *refreshing windows,* *setting or using default plotting ranges,* *opening a view options panel,* and *opening a print panel.* Accelerator mouse buttons available include: **\** - set two coordinates of the initial condition and set direction to forward. **\** - begin or continue orbit in the current direction. **\** - set two coordinates of the initial condition and set direction to backwards. **\** - clear data. For details on which data is cleared, see the **dstool Users Manual.** **\** - dragging sets a zoom box for the window, and a notice allows one to set the direction of zooming. **\** - select a two dimensional portion of a control box for the *multiple* orbits window. ### 2-D View Options Functions available here include: 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: - **Alternating** \- automatic advance when a new trajectory starts. - **Pick Colors** \- advance when a user selects a color by clicking \ on a colorbar. - **Depth** \- using the value of a variable, parameter or function to select color from the available colormap. ### Print The *Print Window* allows a user to output the contents of a viewing window in postscript to either a file or printer. ### Orbits The *Orbits Panel* allows users to set conditions for orbit propagation. Available stopping conditions include: **Fixed Steps** - stop after a fixed number of steps based on the integer in the *Stop* text field. **Event Stopping** - stop when one of the variables or functions crosses a value. **Fixed Time** - stop when time crosses a value. **Poincare Section** - generate a Poincare section using a surface which is a union of level sets of variables or auxiliary functions. ### Propagation The *Propagation Panel* allows users to set integrators/iterators and various parameters relative to their use. ### Multiple Orbits The *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. ### Fixed Point The *Fixed Point Panel* allows users to find equilibria of vector fields, periodic points of mappings, and compute one dimensional stable/unstable manifolds. ### Selected The *Selected Point Panel* allows users to examine and modify the current values of variables and parameters. ### Function The *Function Panel* displays the values of user defined functions. ### Defaults The *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. ### Other User Panels There is a mechanism for adding *User Panels* which function on almost equal footing with other dstool panels. Please refer to the **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. ## OPTIONS dstool is an xview based program and accepts normal *xview* display related command line arguments. See the **xview (1)** man page for descriptions of these. **-c filename** Use the named file to configure dstool. Configuration files are created with the dstool *Save* panel. ## AUTHORS J. Guckenheimer, M. R. Myers, F. J. Wicklin, P. A. Worfolk Center for Applied Mathematics, Cornell University Ithaca, New York 14853 ## FILES $DSTOOL, $DSTOOL/bin/dstool, $DSTOOL/bin/install\_dsuser, $DSTOOL/bin/install\_dstool, $DSTOOL/src, $DSTOOL/include, $DSTOOL/colormaps, $DSTOOL/site\_specific ## SEE ALSO **install\_dsuser(1), dstool\_browser(l), dstool\_parser(l), xview (1), install\_dstool(8)** **dstool Users Manual, dstool Tutorial,** **dstool Reference Manual, dstool Installation Manual** ## BUGS Please report these as well as other comments related to DsTool to *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 *dstool-list@macomb.tn.cornell.edu.*