	One-D Strong Stable and Unstable Manifolds
	==========================================


Strong (Un)Stable Manifold 1D is a software package written by Hinke
Osinga and Reza Rokni for the computation of one-dimensional strong
stable or strong unstable manifolds of equilibria that may be
non-hyperbolic. Currently, the algorithm works for vector fields
only. 

======================================================================


The Strong (Un)Stable Manifold 1Dsoftware package can be used with the
software package DsTool, developed at the Center for Applied
Mathematics, Cornell University. In order to use it, you should first
download and install the Tcl/Tk version of DsTool; see the DsTool item
on DSWeb: 

	http://www.dynamicalsystems.org/sw/sw/detail?item=11

After installing DsTool, please follow the instructions below.


======================================================================


Instructions for installing the Strong (Un)Stable Manifold 1D code
======================================================================

Table of Contents:

I.    Motivation
II.   Adding the Strong (Un)Stable Manifold 1D code to DsTool
    A.  How to start 
    B.  Linking the Strong (Un)Stable Manifold 1D code to DsTool 
    C.  Linking ssman1d.tk to Tcl/Tk 
III.  Explanation of the parameters
IV.   Useful remarks


I. Motivation
-------------

DsTool offers the possibility to compute equilibria of a vector field
and the associated one-dimensional stable and unstable manifolds if
the equilibria are hyperbolic. However, an equilibrium that has an
eigenvalue 0 can still have one-dimensional strong stable or unstable
manifolds. 

The Strong (Un)Stable Manifolds code computes one-dimensional strong
stable and unstable manifolds of both hyperbolic and non-hyperbolic
equilibria up to a pre-specified arclength. It is merely an extension
module for existing DsTool software, as the computation of the
manifolds is essentially the same as the algorithm used for computing
one-dimensional manifolds of hyperbolic equilibria of vector
fields. However, the manifold may be represented using far fewer mesh
points than the number of integrated points (which can be extremely
high when starting very close to the equilibrium) by using the mesh
reduction by curvature. 


II.  Adding the Strong (Un)Stable Manifold1D code to DsTool
-----------------------------------------------------------

Custom analysis code may be added to DsTool on a model-by-model basis
or on a general purpose basis. The Strong (Un)Stable Manifold 1D code
works for vector fields only; a DsTool WARNING message appears when it
is used on a map. This text describes how to install the Strong
(Un)Stable Manifold 1D code on a general purpose basis. If you prefer to
have it on a model-by-model basis, check the README file in the
$DSTOOL/my_dstool directory. 

II.A. How to start
------------------
 
When downloading the Strong (Un)Stable Manifold 1D code, you got a
gzipped tar-file named SSMan1D.tgz. Place this file in your $MYDSTOOL
directory and type

	  tar xvfz SSMan1D.tgz 

A subdirectory called SSMan1D is created automatically containing the
files:
	COPYRIGHT
	Makefile
	README
	curvature_proc.c
	help_ssman1d.tk
	s1dman_compute.c
	ssman1d.c
	ssman1d.h
	ssman1d.tk
	ssman1d_help.txt
	ssman1d_init.c
	ssman1d_ode.c

The files ssman1d.tk and help_ssman1d.tk contain procedures called by
tcl_script. Both files must be moved to the directory $MY_DSTOOL/tcl/.

The file s1dman_compute.c uses an include file from DsTool that is not
in the $DSTOOL/include directory; on line 22 of s1dman_compute.c:  

	#include "$DSTOOL/src/fixed/fixed_local.h

Unfortunately, the compiler does not recognize the alias $DSTOOL, so
that you have to replace $DSTOOL with its full address.


II.B. Linking the Strong (Un)Stable Manifold 1D code to DsTool
--------------------------------------------------------------

The files in $MY_DSTOOL/SSMan1D compile into the library libssman1d.a
when you type "make" in this directory. DsTool can use this library
when it knows where to find it. The idea is to have a (permanent) new
option in the Panels list that, when chosen, causes a window to pop up
for the Strong (Un)Stable Manifold 1D code for vector fields.

1) In order for DsTool to know of the existence of libssman1d.a, fill
   out in $MY_DSTOOL/Makefile: 
 
        SUBDIRS = tcl SSMan1D

   and

        USER_LIBS = SSMan1D/libssman1d.a
 
   Once you are done (after II.C.), you can also use the command "make
   all" in $MY_DSTOOL, which first creates the library libssman1d.a
   and then compiles your personal version of DsTool. Note that if you
   prefer a different name, say MY_NAME, for the directory SSMan1D, you
   should replace SSMan1D with MY_NAME in $MY_DSTOOL/Makefile, and also
   in $MY_DSTOOL/MY_NAME/Makefile.
 
2) Edit the file $MY_DSTOOL/user.c to include the installation
   procedure for the Strong (Un)Stable Manifold 1D code. The
   appropriate lines in user.c should look something like:

	/* ------------------------------------------------------
 	 *
 	 * INCLUDE USER COMPUTATIONAL MODULES HERE
 	 *
 	 * ------------------------------------------------------
	 */
 
	extern void ssman1d_install();
	 
	typedef void (*PFV)();
	 
	PFV user_install_procs[] = {
	   ssman1d_install,
	  (PFV) NULL
	};

   Be sure not to remove the "(PFV) NULL" entry.  DsTool uses this to
   signal the end of the array.  The procedures in user_install_procs
   will be called when your custom version of DsTool starts up,
   installing the Strong (Un)Stable Manifolds code once and for all.


II.C. Linking ssman1d.tk to Tcl/Tk 
----------------------------------

When executing DsTool a new menu entry should appear in the Panels
list. This is done by using tcl_script.

1) You need to edit the Makefile in $MY_DSTOOL/tcl/ in order to let DsTool 
   know about the files ssman1d.tk and help_ssman1d.tk. In
   $MY_DSTOOL/tcl/Makefile, fill out: 
 
        TK_SRCS = ssman1d.tk help_ssman1d.tk
 

2) Edit the file $MY_DSTOOL/tcl/my_app_init.tcl to make the menu option 
   appear. This should look something like:

	proc my_app_init {} {
	    global COLOR FONT EXT
 
	    # Add changes to colors and fonts here

	    window(open) cmd

	    # Add new panel items here
    	    cmd(add_to_panels) "" ""
            cmd(add_to_panels) "Strong Manifolds One-D..." \
		"window(open) ssman1d"
	}

   This will cause a new option to appear in the Panels list. The
   option "Strong Manifolds One-D..." is separated from the other 
   options by a horizontal line (cmd(add_to_panels) "" ""). If you
   choose the new option, the command "window(open) ssman1d" is
   executed, which opens the window "ssman1d". Note that these commands
   must go after the line "window(open) cmd", since you are changing
   entries in the Command window. 

3) Recompile your personal version of DsTool with the command "make
   all" and see if it works!


III. Explanation of the parameters
----------------------------------

When you run DsTool and choose the "Strong Manifolds One-D..."
option in the Panels list, a window pops up that allows you to compute 
one-dimensional strong stable and strong unstable manifolds for
(non-)hyperbolic equilibria. Note that, essentially, the algorithm is
no different from the algorithm used by DsTool to compute
one-dimensional stable and unstable manifolds of hyperbolic
equilibria.  

1) The Stong (Un)Stable Manifold 1D code gives you the option to
   compute either "both sides," the "positive side," or the "negative
   side" of the manifolds. Which side is positive or negative depends
   on how DsTool computes the corresponding eigenvector of the fixed
   point.  

2) You should use the DsTool `Fixed points' window to find
   (non-)hyperbolic equilibria. The number of fixed points in the
   memory is shown for reference only.

3) The algorithm starts with a point on the respective eigendirection. 
   The initial step is specified in the next column

       initial step:			9.9999999999999995e-07
       arclength strong stable manifold:	10
       arclength strong unstable manifold:	10

   By default, the first point is found at distance 10^-6. The
   round-off is shown so that you see how DsTool treats this
   number. The algorithm computes a trajectory starting at this
   initial condition using the integration routines of DsTool with
   step size as specified in the `Orbits' window. The default
   integration routine is Runge-Kutta 4/5. If you want to use a
   different integrator, you need to click on `Propagation' in the
   `Orbits' window. 

   The total arclength of the computed trajectory is no less than the
   specified arclength (10 is the default). The length of the computed
   arclength, which is then slightly larger than what you specified,
   is reported in a message. 

4) It may be that the total arclength of the manifold is actually
   shorter than the specified arclength. Hence, the computation also
   stops if the total number of integration steps reaches the
   specified

	maximal integration steps:	2000000

   If you do not obtain the required arclength, but you are convinced
   the manifold is that long, you probably need to increase this
   number.

5) The total number of mesh points for the computed manifold is
   actually NOT the total number of integration points. The number of
   mesh points is reduced using parameters that specify a required
   curvature accuracy. The meaning of these parameters is explained
   below. We stress here that the arclength of the piecewise smooth
   approximation resulting from the reduced mesh will typically be
   slightly different from (less than) the arclength of the integrated
   trajectory. 

   If you want the total number of integration points, you should set
   the menu item "reduce mesh points" to "do not reduce mesh points."
   Note that it may take a long time for DsTool to save the manifold
   if is contains a lot of points.

6) The parameters for the accuracy of the mesh point reduction are
   specified in the next column:

	  alpha_min:		0.20000000000000001
	  alpha_max:		0.29999999999999999
	  (Delta alpha)_min:		1.0000000000000001e-05
	  (Delta alpha)_max:		0.0001

   In fact, the numbers were meant to be alpha_min = 0.2, alpha_max =
   0.3, (Delta alpha)_min = 10^-5, and (Delta alpha)_max = 10^-4.
   Again, the round-offs are shown so that you see how DsTool treats
   these numbers. 

   The parameter alpha denotes an approximation of the angle between
   the lines given by three successive points. If the angle is very
   small, the three points almost lie on a straight line. On the other
   hand, if the angle is large, the three points should be thought of
   as being on a sharp fold, and more points are needed to approximate
   the manifold properly. The parameter Delta is the distance between
   two successive points. The value (Delta alpha) denotes the product
   of the distance between the last two points and the angle between
   the last three points. The algorithm selects a subset of the
   computed integration points such that for each three consecutive
   points the following is satisfied:

	     alpha_min < alpha < alpha_max,
	     (Delta alpha)_min < Delta alpha < (Delta alpha)_max.

   Note that the mesh selection is done using computed integration
   points only. This means that three successive integration steps may
   produce three points whose angle or distance violates any of the
   two above constraints. In this case, the computation stops and an
   accuracy violation is reported. Longer pieces of the manifold can
   be computed by reducing the integration step size in the `Orbits'
   window. 

   If the manifold folds sharply, it may happen that angle never gets
   smaller than alpha_max. Theoretically, this should be possible if
   the integration time is small enough, but this may not be feasible
   in practice. One could consider accepting such an accuracy
   violation, but this has not been implemented in this version.

   If you want to do a mesh reduction with higher accuracy, you
   typically decrease the choices for (Delta alpha)_min and (Delta
   alpha)_max. The values for alpha_min and alpha_max have less
   effect. The local interpolation error is of order (Delta alpha).


IV. Useful remarks
---------------------

The Strong (Un)Stable Manifold 1D code should work for any vector
field with one-dimensional (strong) stable or unstable manifolds. The
following remarks may help to enjoy the code.

1) The manifolds are saved in the same format as if they were
   computed with the original manifold computation of DsTool. This
   means that you can clear them by pressing "Clear manifolds" in
   either the SSMan1D window, or in the `Fixed points' window. 

2) As is also done in the original manifold computation of DsTool,
   the Strong (Un)Stable Manifold 1D code computes each branch of the 
   manifolds entirely before it is saved. Saving points may take a
   long time when a branch consists of a lot of points. 

3) DsTool does not draw lines between successive points on the
   manifold. However, you can port the manifolds to Geomview (for
   two-dimensional systems just take "0" for the z-coordinate) and 
   choose to connect the dots before sending them. 

