\newcommand{\TUTRESPATH}{/marcy/back/notes/tutorial/RAS}
\chapter{Tutorial}
\label{sec:tutorial}

\section{Preliminaries}
\label{sec:preliminaries}
This chapter is a tutorial for \xx{dstool}.  Its
purpose is to introduce the user to
\dstool\  quickly.
It is suggested that the user read this tutorial
while actually running \xx{dstool}.   The tutorial consists
of three sections: this brief overview and
two examples.  In the first example, we will use
\dstool\ to explore the Lorenz system; in the 
second, we will explore  maps of the two-dimensional
torus.  We
describe only basic features of \xx{dstool}.  This is
not a comprehensive description of the
capabilities of \xx{dstool}. More complete documentation
is presented in the \xx{Dstool Reference Manual} \cite{dsref:bib}
and the \xx{Dstool User's Manual} \cite{dsuser:bib}.
In particular the \xx{Dstool User's Manual} explains how
users can easily install their own dynamical systems in \xx{dstool}.


Running windowed working environments such as \xu{X11R4} (Release 4 of
\xu{X11} ), \xu{X11R5}, or \xu{Open Windows} on a workstation
generally involves invoking both a \xx{server} and a \xx{window manager}.
In this context, a \xx{server} is a program controlling one or more
displays. Client programs such as
\dstool\ make \xu{X protocol} requests to the server, and it is up to
the server to actually accomodate these requests. 
A \xx{window manager} is another client program, which is given special
authority to make decisions (using user and client
preferences) about issues such as window placement and 
user interaction style. Due to the relatively low level
of abstraction of some \xu{X11 services}, most applications, including
\dstool\ are built using an additional toolkit library layered on top
of \xu{X11}. 

\xx{Dstool} has been tested only on Sun workstations with the
\xu{X11R4} and \xu{X11R5} window systems. 
It may be run with
either the \xu{XNews} server standard on Sun systems or a generic
\xu{X11} server. \xx{Dstool}  uses the
\xu{XView} toolkit for building panels and other user interface
components. We believe that
availability of this toolkit on other hardware platforms  is the 
only major obstruction to using \dstool\ in other \xu{X11} environments.

We will assume that the program has already been 
installed  either by yourself or by a system manager.
If \dstool\ has not already been installed, please 
refer to the \dstool\ Installation Manual.
%move to the installation section now.


\xx{Dstool} uses three environment variables which will typically be
set in a users \xu{.cshrc} file. The variable \xx{DSTOOL} should point
to the root of the local \dstool\ distribution - possibly a directory
such as \xu{/usr/local/dstool}. With this choice, the users
\xu{.cshrc} file should contain the line ``setenv DSTOOL
/usr/local/dstool''.
If you are unsure of this location,
consult your system manager. The environment variable 
DSTOOL\_COLOR\_DIR gives the
location of colormaps used by the system, when color is available.
This directory will often be \$DSTOOL/colormaps. The variable 
DSTOOL\_DATA\_DIR specifies a default  location for data files to be
saved to and loaded from. 

Before accessing \xx{dstool},  start up your window system and 
window manager in the usual
way. On a Sun running \xu{Open Windows}, this might be done by using
the script \xu{openwin}. This will call \xu{xinit}, and in the course
of processing (or possibly creating) your \xu{.xinitrc} file, the
 default window manager \xu{olwm} will be started.

\xx{Dstool} is controlled by a collection of panels in separate
windows. Windows contain buttons, menus, text fields, and drawing
canvases.

To access \dstool\,
start the program by typing \dstool. If the \dstool\ executable has been
correctly installed and lies in a directory mentioned in your
\xu{path}, the \dstool\  \xx{command} window ({\it figure~\ref{cmd}}) pops up.



The top line of the window is a header containing a title such as
\xx{dstool (Version 1.0)}. On the left of the header line is a small
button with an inverted triangle ($\bigtriangledown$) --- this is an 
\xu{Open Look} convention for an \xu{abbreviated menu button}.
Clicking and holding the \xb{MENU} button of your mouse (usually the
rightmost) over this button will display a menu whose bottom entry is
\xx{Quit} --- selecting this is the easiest way to exit \dstool\ at any
time.

Below the header of the \xx{command} window is a control panel. 
The first line controls the selected model and the second line is a
series of menu buttons. By default, \dstool\ comes up with the Lorenz
system selected. You can use the abbreviated menu button between
\xx{Model:} and \xx{Lorenz System} to choose other pre-installed 
dynamical systems. We'll see how to do so later.

\section{The Lorenz Equations}
\label{sec:lorenzeqns}

In this section, we shall learn some of the basic
\dstool\ operations by examining the Lorenz equations.
The Lorenz equations\index{Lorenz equations}
are given by
\begin{eqnarray*}
\dot{x} & = & \sigma(y-x) \\
\dot{y} & = & \rho x - y - x z \\
\dot{z} & = & -\beta z + xy  \\
\end{eqnarray*}
These equations represent a truncation of a
partial differential equation which models 
two-dimensional fluid convection.  This system
was first studied by Lorenz in the early 1960's.
The reader is directed to \cite{guckenholmes:bib}, 
\cite{lorenz:bib}, or \cite{sparrow:bib} for more 
information regarding the nature and behavior of this 
system.

\subsection{Conventions}
\label{sec:conventions}
Throughout the tutorial,
mouse\index{mouse}\glossary{mouse}
operations are frequently used. In order to 
facilitate our subsequent discussion,
we introduce the following conventions. See
the \xu{Open Windows Users Guide} \cite{OpenWinRef:bib} for more information
on  \xu{Open Windows} interaction conventions.

\begin{enumerate}

   \item The three mouse buttons on the Sun mouse\index{mouse 
   buttons} will be denoted \xb{SELECT}, \xb{ADJUST}, 
   and \xb{MENU}.  By default, these are  the
   left, middle , and right mouse buttons respectively.

   \item {\em Shift-clicking} and {\em control-clicking}
   are defined as pressing a mouse button while \xx{Shift} 
   or \xx{Control} are also depressed.  We will use
   notations like \xb{Shift-MENU} and \xb{Control-MENU}
   to indicate these.

   \item Buttons are activated by clicking \xb{SELECT} on them.

   \item Menus generally are opened by pressing \xb{MENU}. Items 
   on pop-up menus are
   selected by holding this mouse button while the pointer is dragged
   to the menu entry being chosen.

   \item Text fields are edited by first clicking \xb{SELECT} 
   within the appropriate text field,  and then using keyboard
   keys including \xx{Delete} to change the entries.

   \item One of the features of the \xu{Open Look} environment
   is that menus may be opened for display without continuing to
   hold the mouse button. Clicking (without holding) \xb{MENU} on a 
   menu button is the procedure for doing this. One can then select
   a menu entry by clicking \xb{MENU} or \xb{SELECT} on it. The menu
   can also be dismissed by clicking \xb{MENU} again outside the menu.

   \item Windows are moved by clicking and holding \xb{SELECT} on
   the window header while moving the pointer. When the window is
   in a satisfactory location, simply release \xb{SELECT}.
\end{enumerate}

\subsection{Opening a View Window}
\label{sec:openview}

The first thing to do after starting \dstool\ is to open a view
window. Open the \xx{view} menu on the  \xx{command} window and
using \xb{MENU}, choose the \xx{2-D Image} entry. A window
with a title such as \xx{dstool:Lorenz System}
 ({\it figure~\ref{vw}}) appears. It may well obstruct 
some other important window -- using \xb{SELECT} on the header, drag the
window to a convenient location. The view window 
contains abbreviated menu buttons for selecting the horizontal and
vertical coordinates being displayed, as well as text fields
controlling the coordinate ranges of the viewport. (~These coordinate
ranges are expressed in the original world coordinates of the
dynamical system. ) Coordinates displayed in view windows can be
phase space coordinates of the original problem, auxiliary functions,
or parameters built into the dynamical system at creation.
For the Lorenz system, the default display is to project the
phase space coordinates $(x,y,z)$ to $(x,y)$ as horizontal and
vertical coordinates of the view window.



Move the mouse within the canvas below the view window control panel.
The canvas is the large boxed-in area where graphics are displayed.
Note that the horizontal and vertical coordinates of the mouse
position (in world coordinates) appear to the right of the 
\xx{options} menu button.

Within the limits of system resources, you can open as many view 
windows as you like. So it's possible to view a number of two
dimensional projections simultaneously. BY default, the same orbit 
in different
windows will be drawn in the same color. Different orbits will
generally be drawn in different colors. The use of color is
controllable as described in Section~\ref{sec:color}.

\subsection{How to Display Orbits}
\label{sec:orbitsdis}

\subsection{Using a Mouse to Generate Orbits}
\label{sec:mouse}

	Move your mouse into the view window and click \xb{SELECT}.
\xx{Dstool} will remember this selected point until you explicitly
choose another. Now click \xb{ADJUST} in the view window. 
{\it Figure~\ref{lorxy}}  shows a typical result. By default,
\dstool\ will compute 5000  points forward along the trajectory starting at the
previously selected point. The points will be equally spaced at time
intervals of .01. We'll see shortly how to change these parameters. To
the right of the \xx{Settings} button on the \xx{command} window,
you'll see the number of points currently stored by \dstool. Each time
you click \xb{ADJUST}  another 5000 points are computed and displayed.


	If you're using a color monitor, all points of this orbit will
be drawn in the first color of \xx{dstool's} palette. Now click 
\xb{SELECT} at another location in the canvas of the view window.
Clicking \xb{ADJUST} will plot 5000 points on the orbit from the newly
selected point. On a color monitor, this orbit will automatically be
displayed in the next color of \xx{dstool's} palette.

	You can choose initial conditions for backwards orbits by
clicking \xb{MENU} on a location in the view window canvas. This also
resets the current orbit direction from forward to backward. Now 
clicking \xb{ADJUST} within the canvas will cause up to 5000 points 
along the backward orbit to be displayed. Your backward orbit will
probably rapidly go off to infinity, so \dstool\ will display a message
and stop computing somewhat earlier. On a color monitor, this backward
orbit will automatically have been displayed in the next color of 
\xx{dstool's} palette.

	\xx{Dstool} only remembers one selected point and one orbit 
direction. So pressing \xb{SELECT} or \xb{MENU} within the canvas
both sets the orbit direction and replaces any previously selected
point. One of the menu entries under the \xx{Options} menu button of
the \xx{2-D Image} window is \xx{Display...} which will allow you to
mark this selected point before you change it. 
%We'll discuss this panel in more detail when discussing bifurcation diagrams.


\subsection{Reading Coordinate Values}
\label{sec:coordval}

	Numerical values of phase space variables can also be
inspected and adjusted directly. Going back to the \xx{Settings} menu
button in the \xx{command} window, click the \xb{MENU} mouse button on
the entry \xx{Selected...}. The \xx{Selected Point} panel which
appears will
then contain text fields with the coordinates of the last point you chose with
\xb{SELECT} or \xb{MENU} as well as the last point computed on the
current orbit. You can directly edit the values of the selected point
( in the column labeled \xx{Initial} ) in these text fields. Or click on
the \xx{Copy Final to Initial} menu button to replace the selected
point by the endpoint of the current orbit. 

\subsection{Changing the Plane of Projection}
\label{sec:changeplane}

Those familiar with the Lorenz system may have
noticed that the orbits which appear here do 
not look like the phase portrait normally associated
with the Lorenz attractor.  This is because \dstool\
is projecting this three dimensional system onto
the $xy$-plane.  To change the plane of projection,
locate the abbreviated menu button labeled \xx{Ver:}
on the view window control panel. Open this menu and
select the variable \xx{z} to replace \xx{y} as the
vertical coordinate. Then open the \xx{Options} menu 
button just below and select the \xx{Refresh} menu entry.
The screen will redraw each orbit as projected into the $xz$-plane.
{\it (See figure~\ref{lorxz})}.



	In the same way as above,
values of auxiliary user-defined functions can also be
displayed in \xx{2-D Image} windows. Or \xx{time} may be chosen
as one of the displayed coordinates to generate {\it time series.}
The \xx{Dstool Users Manual} explains how to add user-defined
functions to a particular \dstool\ system. 

\subsection{Changing the Scale}
\label{sec:rescaling}

To see fine structure, it is often desirable
to zoom in on a particular portion of the phase
space.  Conversely, sometimes a larger phase space
perspective is desired.  Changing the scale of 
the view window can be  accomplished by 
editing the \xx{Min:} and \xx{Max:} text fields to
the right of the horizontal and vertical variables.
Change the minimum \xx{z} value to \xu{-100} instead of \xu{-5}
and change the maximum to \xu{100}.
Be sure and enter a \xx{Carriage--Return} after you edit
each text field --- then select \xx{Refresh} from the \xx{Options}
menu button and the orbits will appear compressed and much further
away.
{\it (Figure~\ref{lorxzfar})}
This process can also be used to 
zoom in, or to view any
rectangular portion of the $xz$-plane.




It is also possible to rescale using a 
``rubber-band'' method.  This is often preferred
for zooming in, whereas the method described 
above is often preferred for zooming out.  
Position the mouse pointer in the view
window near the upper left corner of the 
Lorenz attractor.  Press \xb{Shift-SELECT}
and keep the \xb{SELECT} button depressed.
(You may release the \xx{Shift} key.) 
Now drag down and to the 
right until the attractor is enclosed in a 
rectangle called the \xx{rescaling box}.
\index{rescaling box}  When the attractor is
satisfactorily enclosed within the rescaling 
box, release \xb{SELECT}.  A notifier box offering the
options of \xx{zoom in}, \xx{zoom out}, or \xx{cancel} will
pop up. Click \xb{SELECT} on the button \xx{zoom in}. The attractor 
will be displayed larger than it was before. {\it (Figure~\ref{lorxznear})}



\subsection{Other Mouse Button Functions in View Windows}
\label{sec:omb}

Since \xx{Refresh} is the default choice of the \xx{Options} menu
button, instead of opening the  menu, you can simply click
\xb{SELECT} on the \xx{Options} button to refresh the view in the
window. Buttons in \dstool\  have their first menu entry
as default choice.

You can clear both the view window and the trajectory points in memory
by clicking \xb{Control-ADJUST} in a view window canvas. 

By holding and dragging \xb{Control-SELECT}, you can graphically
select a rectangle to evolve under the flow. See
Section~\ref{sec:multorb} below for a complete description.


\subsection{Quitting and Interrupting}

	Typing \xx{Control-C} in the original window from which
you invoked \dstool\  pops up a notifier box offering the options of
either interrupting the current computation, quitting \dstool, or
canceling. Try this now, and using \xb{SELECT}, choose the \xx{Cancel}
option.
	You can also quit \dstool\ by choosing the \xx{Quit} entry
after clicking \xb{MENU} in the header of the original \xx{command}
window.

\subsection{Orbits Panel}
\label{sec:orbitspan}

	Additional control of the computation of orbits can be obtained with
the \xx{Orbits} panel. With the mouse in the \dstool\ \xx{command} window and
using \xb{MENU}, select the \xx{Orbits...} entry from the \xx{Panels}
menu button. A new panel {\em (figure~\ref{orb})} will open. 




	The top two lines of the panel contain buttons \xx{Forwards},
\xx{Backwards}, \xx{Continue}, and \xx{Clear All} which correspond to
the mouse actions within the view window already described. 

	Below these are several text fields which control essential
parameters. Edit the \xx{Plot:} value to 100 and the \xx{Step Size:}
to \xu{.001}. Using \xb{SELECT}, click on \xx{Forwards}.  \xu{5000}
points  (the value in the \xx{Stop:} field) will
still be computed but now at time intervals of \xu{.001} with only every
hundredth point plotted or stored in memory. You can monitor this by
watching the \xx{Final time} entry in the \xx{Selected Point} panel,
and noting the number of points in memory displayed to the right of
the \xx{Settings} button in the main \xx{command} window. 

	Now restore the \xx{Plot:} field to \xu{1} and the \xx{Step
Size:} to \xu{.01}. Clear the view window by clicking
\xx{Clear All} inside the \xx{Orbits} panel.
Open the abbreviated menu button to the right of
\xx{Stopping Condition}. Replace the \xx{Fixed Steps} entry currently
chosen by \xx{Event Stopping}. Most of the text fields at the bottom
of the \xx{Orbits} panel now darken indicating that their  fields
are editable. Enter \xu{0} in the lines to the right of $\xx{x+y}$ and
$\xx{x-y}$ respectively. 

	Now click on the \xx{Forwards} button once to make sure the
direction is set, and then repeatedly \xx{Continue}. Orbits will 
be computed until either $x+y$ or $x-y$ reaches \xu{0} or \xu{5000}
points are computed. You'll be able to see the orbits wind around near
the attractor, as you repeatedly continue them.

	You can also select the \xx{Propagation...} panel to control
both the choice of integration algorithm and parameters for it. 

\subsection{How to Change Parameters}
\label{sec:param}

The Lorenz system contains three parameters,
denoted $\sigma$, $\beta$ and $\rho$.  
The default values for the parameters are 
$\sigma = 10$, $\beta = 8/3$, and $\rho = 28$.
These values appear in panel text items located on 
the main panel.  The default values correspond 
to the values originally studied by Lorenz.  
For the default value of $\rho = 28$, the Lorenz
system possesses a global attractor, but for other
parameter values different initial conditions
may end up in different attractors.  This exercise 
will help you to learn how to alter parameter values
and to control the initial conditions with a high
degree of accuracy.

One method of changing parameters is by editing text
fields in the \xx{Selected Point} panel. If it is not
already open, open it with \xb{MENU} from the menu entry \xx{Selected...}
under the  \xx{Settings} menu button of the 
\xx{command} window. {\it (Figure~\ref{sel})}
Change the text item \xx{rho} to the value \xu{19}.




Clear the \xx{view window} by \xb{Control-ADJUST} and make sure
the $xz$ plane is displayed. Restore the range of \xx{x} values
to the original \xu{-30} to \xu{30} and the \xx{z} to \xu{-5} to
\xu{50}. On the \xx{Selected Point} panel, set the value of the 
items \xx{x} and
\xx{z} to \xu{0.1},  and set the value of
\xx{y} to \xu{-0.1}. 

Now select the button item \xx{Forward} in the \xx{Orbits} panel.
The orbit starting at the point 
$(0.1, -0.1, 0.1)$ is   drawn in 
towards an attracting fixed point.  Select \xx{Continue} 
and watch the trajectory spiral in to the sink.

Now change the value of \xx{y} to \xu{-0.099},
and select \xx{Forward} again.  The orbit of the 
point $(0.1, -0.099, 0.1)$ is attracted to a 
second (different) attracting point! {\it (Figure~\ref{lorparam})}




You can also use the mouse to change parameters. By clicking
\xb{SELECT} on the \xx{View} menu button of the \xx{command}
window,
open a second \xx{2-D Image} window. Change the horizontal and
vertical variables being displayed to the parameters $\sigma$ and
$\rho$. Note that by clicking \xb{SELECT} on different locations
in this window, the values of $\sigma$ and $\rho$ in the \xx{Selected
Point} panel change accordingly. You can mark the selected point on
this window by selecting \xx{Display...} from the \xx{Options} menu
button on the view window. The popup box allows you to select various
symbols and sizes to mark locations in the \xx{view window}. Click
\xb{SELECT} on \xx{Add Point} to actually mark a location with the
symbol you have selected.

Being able to control the initial conditions
of a trajectory with a high degree of accuracy
is often  crucial in the exploration of dynamical 
systems, and in these cases it is often preferable
to input initial conditions as text items rather than
via a mouse.  

\subsection{Loading Other Dynamical Systems and Restoring Defaults}
\label{sec:otherdynsys}

	The abbreviated menu button to the right of \xx{Model:} in
the \xx{command} window can be used to load a new dynamical system
or reload the defaults of an old one. This button holds a 
\xx{pullright menu} where each of the entries \xx{Mapping Examples},
\xx{Vector Field Examples}, and \xx{Special Dynamical Systems} 
contains a submenu which may be displayed by moving right while
continuing to hold the \xb{MENU} button. 
	This can also be used to conveniently restore defaults for a
system. Follow the \xx{Vector Field Examples} entry to the right while
holding \xb{MENU} and select \xx{Lorenz System} again. Now the values
of parameters and variable ranges for graphing are as they originally were.
	
\subsection{Computing Equilibria}
\label{sec:equilibria}
\index{equilibria}

	If you have not already done so, use the procedure of 
Section~\ref{sec:otherdynsys} to restore the default \xx{Lorenz System}.
Adjust your view window to the $\xx{xz}$ plane. 
	
	We shall numerically compute the equilibria for
the Lorenz system. First using the \xx{Panels} menu button of the
\dstool\ \xx{command} window, click with  \xb{MENU} on the
\xx{Periodic...} entry. The \xx{Periodic Orbit} panel appears. {\it
(Figure~\ref{per})} The entry 0 in the \xx{Period to Find:} text field
in the upper left corner indicates to \dstool\ a wish to find
equilibria. Using \xb{SELECT}, press the \xx{Find} button in the fifth
line of the panel, and \dstool\ will use Newton's method starting at a
random point to search for equilibria. The number of tries (by default
10) is specified in the \xx{\# MC: } field, and the number of
equilibria found is reported in the \xx{\# Found:} field. \xx{Dstool}
marks saddles
in view windows with green plus signs, sinks as blue
triangles, and sources as red squares. After one or two
presses of \xx{Find}, you'll almost certainly have located the three
saddles of the \xx{Lorenz system}. {\it (Figure~\ref{eq})}
	





	To the right of \xx{Settings:} on the fourth line of the
\xx{Periodic Orbit} panel is the \xx{Hide/Show} choice box. Click
\xb{SELECT} on \xx{Show} and the panel will expand, with a number
of parameters accessible for editing. {\it (Figure~\ref{pershow})} 
You can also change the
\xx{Algorithm:} and \xx{Initial Guess: } methods via the abbreviated
menu buttons to the right of these labels.




\subsection{Computing Manifolds}
\label{sec:manifolds}
\index{manifolds}



Before beginning this section of the tutorial,
Section~\ref{sec:equilibria}
must be completed.
If the three equilibria have been found and marked,
then we may compute the stable and unstable 
manifolds of the hyperbolic saddle located at
the origin. At the moment, when these are of dimension greater
than \xu{1}, \dstool\ computes one dimensional pieces of these
tangent at the equilibrium to the eigen-directions of the
linearization, for those eigen-directions with real eigen-values.

First, in the \xx{Periodic Orbit} panel, click \xb{SELECT} on
the \xx{Show} choice box to the right of the \xx{Settings:}
entry. We will edit the \xx{1-D Manifold} entries to produce
longer, more detailed stable and unstable manifolds.
Select the input field to the panel text item 
\xx{Unstable Manifold Divisions per Step:}, and change the default value
of \xu{1} to \xu{3}. This
determines the number of interpolating 
points which we will use to ``fill in''
the space between two calculated points on the 
unstable manifold. Below this field, change the \xx{Number of Steps:}
default entry of \xu{200} to \xu{2500}. This 
basically determines the length of the unstable manifold: the bigger 
this value is, the longer the manifold will be.  


Above the entries for unstable manifolds are corresponding ones for 
stable manifolds. Edit the \xx{Stable Manifold Divisions per Step:}
text value to \xu{10}.


%See Section~\ref{sec:equilibriaandpo} 
%for more information 
%on the meaning of the text items in the \xx{Periodic
%Orbit}  panel.


After setting the above values, select the button 
item \xx{Add 1-D Manifold} in the \xx{Periodic Orbit}
panel. {\it (Figure~\ref{stable})} If you are on a color monitor,
\dstool\ draws the stable manifolds in red and
the unstable manifold in blue.



\subsection{Multiple Orbits}
\label{sec:multorb}

	\xx{Dstool} supports the convenient display of the evolution of
isoriented (edges parallel to coordinate axes) n-cubes  or their boundaries
under the flow of a dynamical system. 
%The current implementation
%of \dstool\  allows the cubes to have coordinate ranges only
%in phase space. 

	To see this feature, first reload the \xx{Lorenz} system defaults
using the procedure described in Section~\ref{sec:otherdynsys}.
Now open up the \xx{Multiple Orbits} window by selecting (with \xb{MENU})
the \xx{Multiple...} menu entry under the
\xx{panels} menu button of the \xx{command} window. The lengths of the
sides of the cube may be edited in the \xx{Size} column at the bottom of
the panel, and the number of division points along each edge in the
\xx{Number} column. In the \xx{Size} column, change the \xx{x} and \xx{y}
entries to \xu{5}. In the \xx{Number of Points} column, change these two
(\xx{x} and \xx{y}) entries to \xu{20}. By default, the \xx{Load:} choice box
should be set to \xx{Rectangle} indicating that only the boundary of the 
specified n-cube will be evolved; selecting \xx{Region} here would also
include a mesh of interior points of the specified n-cube. Click
\xb{SELECT} on the \xx{Load Points} button near the top of the \xx{Multiple
Orbits} panel. The message {\em 76 initial points loaded} will appear.
{\it (See figure~\ref{multpan}.)}


	
	Before actually evolving the rectangle, make sure you
have the \xx{Orbits} panel and a \xx{2-D Image} window 
open (with \xx{x} and \xx{y} as coordinates displayed.) Recall these
are summoned by menu entries of the \xx{Panels} and \xx{View} menu buttons
respectively on the main \xx{Command} window. On the \xx{Orbits} panel,
edit the \xx{Stop} text field (to the right on the third line) to \xu{1}
instead of the default \xu{5000}.

	Now back on the \xx{Multiple Orbits} panel, click \xb{SELECT} on
\xx{Forwards}. In the \xx{view} window, you will see the original rectangle
and its evolution one time step later. Click on \xx{Continue} several times
and you will see the rectangle evolve towards the line $x=y$. 
{\it (Figure~\ref{multorb})}





\subsection{How to Print}
\label{sec:howtoprint}
\index{printing}

The phase portraits and bifurcation diagrams produced
in \dstool\ may be printed on a  laser printer.
Choose the menu entry \xx{Print...} from the 
menu under the \xx{Options} menu button of a \xx{2-D Image} window.
A pop-up panel labeled 
\xx{Print} will appear.  
Near the bottom of this panel is the \xx{Destination:}
choice box. Using \xb{SELECT}, choose either \xx{Printer}
or \xx{File}. If \xx{Printer} is chosen, edit the 
\xx{Printer:} name to an appropriate local printer.
If \xx{File} is chosen, edit the \xx{Directory}
and \xx{File} text fields below in this panel to specify the file you
wish to create. 
Now clicking on the 
button \xx{Print}  will send a 
PostScript file to either the printer or file.




\subsection{Use of Color}
\label{sec:color}

	The use of the color palette in \xx{2-D Image} windows is
programmable. To adjust this, use \xb{MENU} to select the
\xx{Display...} menu entry from the \xx{Options} menu button
of this window. The \xx{2-D View Options} panel will appear.
Options supported include using the menu button to the right
of \xx{Colormap Type:} to change to the entry \xx{Pick Colors}. When this
option is selected, the user can click \xb{SELECT} on a color in the
palette directly above the drawing area.  This will then
set the chosen color as the color for drawing orbits.


\section{A Torus Diffeomorphism}
Despite the richness of the Lorenz system,
there are aspects of \dstool\ that we did not 
explore in the previous example.  This 
example is designed to explore some of the 
remaining elementary features of \dstool.  

This example
is a diffeomorphism of the two dimensional
torus ${\cal T}^2 = S^1 \times S^1$ onto itself.  
The map is given by a non-linear perturbation of 
translations of the torus:
\[
 {\bf f}({\bf x})= {\bf x} + {\bf \Omega}
  + {\bf g}({\bf x})
\]
where ${\bf x} = (x, y) \in {\cal T}^2$, 
${\bf \Omega} = (\omega_x, \omega_y) \in {\bf R}^2$,
and 
\[
{\bf g}({\bf x}) = \left(\frac{-ab}{2 \pi}\sin 2 \pi y, 
                   \frac{-a}{2 \pi b}\sin 2 \pi x \right).
\]
Because the map is from the torus to itself, the
phase space in this example is the unit square
with opposite edges identified.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\subsection{Choosing an Installed Dynamical System}
\label{sec:choosingds}
The first task is to load the torus diffeomorphism
into \dstool.  To do this, hold down \xb{MENU} on the 
abbreviated menu button to the right of \xx{Model:} in
the \xx{command} window and follow the pullright menu entry
\xx{Mapping Examples} to the entry \xx{Kim-Ostlund Torus Map}. 

	The parameter \xx{b} above is labeled in the \xx{2-D Image
window} as \xx{asymm}.

\subsection{Orbits of Maps}
\label{sec:obitsofmaps}
Forward orbits of maps are generated in the same
manner as  generating the forward orbit of a 
flow.  Position the pointer within 
the \xx{2-D Image} window; click \xb{SELECT} to 
set an initial point and \xb{ADJUST} to iterate 
the map forward. 
Continue the iteration with \xb{ADJUST}.  
You can also use the \xx{Orbits}
and \xx{Selected Point} panels as with vector fields. 
You will
see that for the default parameter values 
almost  every initial condition is
mapped asymptotically towards an invariant
curve which winds around the torus.     


Since this map is a diffeomorphism (for small
values of the nonlinearity $a$), the inverse
of the map exists, and therefore we can compute
backward orbits.  Click \xb{MENU} followed by
\xb{ADJUST} a few times and convince yourself that almost every 
initial condition is backwards asymptotic to a period
five orbit for the default parameter values. {\it (Figure~\ref{tororb})}



\subsection{More on Fixed Points}
\label{sec:morefp}
For the default parameter values, the torus map  
has two distinct sets of periodic points of period five. 
Open the \xx{Periodic Orbit} panel as described in 
Section~\ref{sec:equilibria}.  We 
want to find the periodic points of period five, so we
select the input field for the text item \xx{Period To Find:},
and set its value to \xu{5}.
Now click \xb{SELECT} on the \xx{Find} panel button item.
There are two orbits of period five.  One orbit is
attracting;  we saw this orbit in the previous 
section.  The other orbit consists of five saddle
points, so we did not observe this orbit when we 
computed random trajectories. 
It is almost always the case that \dstool\
finds both sets of period five points
on the first try.  If the text item \xx{\#~Found:}
does {\em not} read \xu{2} after selecting \xx{Find}, 
then try selecting \xx{Find} until it does.


        
\subsection{More on Manifolds}
\label{sec:moremanifolds}

Once the periodic points of period 5 are found,
we can compute the stable and unstable manifolds 
of these points.  In the periodic orbit panel, first
click \xb{SELECT} on the \xx{Show} choice box next
to the label \xx{Settings}. This will reveal a
large collection of parameters which can be adjusted.
Under \xx{1-D Manifold}, change the value
of \xx{Stable Manifold Divisions per Step} to \xu{3}.
This
determines the number of interpolating 
points which we will use to ``fill in''
the space between two calculated points on the 
unstable manifold.
Immediately below the \xx{Stable Manifold Divisions per Step}
entry, edit the
\xx{Number of Steps} text field to the value \xu{300}. 
This 
basically determines the length of the unstable manifold: the bigger 
this value is, the longer the manifold will be.  
Change the corresponding
\xx{Unstable Manifold} entries similarly.
Then select the button item \xx{Add 1-D Manifold}.
As we saw in the Lorenz system, on a color monitor
\dstool\ displays the stable manifolds in red and
the unstable manifolds in blue. {\it (Figure~\ref{torstab})}




An often discussed  phenomenon
in the study of nonlinear dynamics is the transverse
intersection of the stable and unstable manifolds
of a non-integrable system.  These intersections 
imply the existence of infinitely many saddle points 
and the presence of Smale Horseshoes.  The torus
map has a homoclinic orbit which intersects itself 
transversally for a certain parameter range, so our
goal in the next few paragraphs is to view this transverse
intersection.  As a word of warning, the computation 
involved is rather extensive, and may take a few
minutes.
% on relatively slow machines.  The calculations
%take less than a minute on a SPARCstation 1.

First we'll adjust the number of significant digits possible in
panel items. Going back to the \dstool\ \xx{command} window, open
the \xx{Settings} menu button to select the entry \xx{Defaults...}.
On the window which pops up, change the \xx{Window Precision:} entry
from \xu{6} to \xu{12}.

Now if it is not already open, use the \xx{Settings} menu button
to open the \xx{Selected Point} window. Select the input  
field of the text item \xx{wx:}
in this panel, and replace the old parameter value with
the value \xu{0.59547797038}.  
%Also select the input
%field of the text item \xx{wy:} and if necessary change
%its value to \xu{0.805}.  
Now clear the \xx{2-D Image } window
via \xb{Control-MIDDLE} and then create the periodic
orbit panel (if it is not already created)
as is detailed in section~\ref{sec:equilibria}.

First, in the \xx{Periodic Orbit} panel, click \xb{SELECT} on
the \xx{Show} choice box to the right of the \xx{Settings:}
entry. We will edit the \xx{1-D~Manifold} entries to produce
more complete stable and unstable manifolds.
As before, we want to modify how ``long'' the 
manifolds are and how ``fine'' they are.   Change
the input fields of the following text items on the
\xx{Periodic Orbit} panel:

\begin{itemize}

	\item Change \xx{Unstable Manifold Divisions per Step:} to \xu{20}. 

	\item Change \xx{Number of Steps:} immediately below this
	to \xu{600}.

	\item Change \xx{Stable Manifold Divisions per Step:} to
	\xu{10}. 

	\item Change \xx{Number of Steps:} immediately below to
	\xu{100}.  

	\item Change the text item \xx{Initial Distance Along
	Eigenvector:} so that it reads \xu{1e-07}.  

\end{itemize}
Lastly,
make  sure that the text item \xx{Period to Find:} is still
set to the value \xu{5}.

We are now ready to begin the computation of the 
stable and unstable manifolds.  First select
the button item \xx{Clear} in the \xx{Periodic Orbit}
panel.  This action resets the text item \xx{\# Found}
to the value~\xu{0}.  Now press
\xx{Find} in the 
panel.  If \dstool\ does not find 
two period orbits of period five, then continue to 
select \xx{Find}.  Once the periodic points are found,
choose the button item \xx{Add 1-D Manifold}.  When the 
manifolds have been computed, we want to blow up 
a region about a saddle point. 
%Note that
%computing periodic orbits after blowing up a region
%may not work.  
Using the text
items \xx{Min:} and \xx{Max:} located in the 
\xx{2-D Image} window, change the $x$-range to 
$[0.23897, 0.23902]$ and change the $y$-range
to $[0.65355, 0.65358]$.  Now select \xx{Refresh}
and the homoclinic tangle will appear.{\it (Figure~\ref{tortan})}




\subsection{Saving and Loading Data}\label{sec:saveload}

The Kim-Ostlund torus map undergoes many 
bifurcations as the parameters are changed 
\cite{bgkm:bib}, \cite{kimguc:bib}, \cite{kmg:bib}.
In investigating the behavior of  a complicated 
dynamical system, researchers often find it convenient
to save system information associated with interesting
dynamics.  In this section we will save information 
about the torus map to a file and then retrieve the
information. 



If necessary, open the \xx{Selected Point} panel using \xb{MENU}
on the \xx{Settings} menu button of the \dstool\ \xx{command} window.
Clear the \xx{2-D Image} window with \xb{Control-MIDDLE}.
Then change the value of  \xx{wx} to 
\xu{0.5} and change the value of \xx{wy} to \xu{0.8}.  
Generate a phase portrait for these parameter values. 
{\it (See figure~\ref{fig:phasepor} .)} 

Suppose that you wish to save this phase portrait.
With \dstool\, you have several options.  The first option
(the default) is to save only the information {\em about}
the phase portrait.  This includes the name of the 
dynamical system being studied, the parameter values, 
values of some tolerances used in numerical computations,
and a few lines worth of other 
information.  {\em The default option does not save any
data points.}  The advantage of this option is that it does
not require the storage of the large amount of data
which actually comprise the phase portrait -- yet the 
phase portrait may be fully reconstructed. 

Using \xb{MENU} on the \xx{File} menu button of the \xx{command}
window, select the menu entry \xx{Save...} to open the
\xx{Save} panel. Edit the \xx{Directory:} and \xx{Filename:}
fields appropriately to set the name of the data file in some
directory where you have write access.
Options specify exactly which data is saved. Use \xb{SELECT} to
toggle these choices on or off. Choices are boxed within darker
rectangles when they have been selected. In this case, \xb{SELECT} the
option \xx{Current Settings}. Now click \xb{SELECT} on the \xx{Save} 
button at the bottom of the panel to actually save the data.

To reload this data at some later point, open the \xx{Load} panel
by selecting with \xb{MENU} the \xx{Load...} menu entry button of
the \xx{File} menu button on the \xx{command} window. Edit the 
\xx{Directory:} and \xx{Filename:} fields to the same choices
you made before. Maintain the option \xx{dstool Format} right now.
( The \dstool\ Reference Manual  describes how to import 
unformatted data into a \dstool\ memory object.~) Clicking 
\xb{SELECT} on the \xx{Load} button will then restore the \dstool\
settings.

We remark that saving and loading trajectory data 
is significantly slower than merely saving the \xx{Current Settings}
values.  The length of time needed to save 
or load data depends on the number of data points,
the  dimension of the phase space, and the particular
machine running \dstool.  
%For more information about
%saving data, see Section~\ref{sec:savingdata}.
