 This program is the property of:

	      Hinke Osinga and Reza Rokni Lamooki
	      School of Mathematical Sciences
	      University of Exeter
	      Laver Building, North Park Road
	      Exeter, EX4 4QE, United Kingdom

   email: H.M.Osinga@bristol.ac.uk, Rokni@tech.umz.ac.ir

 and may be used, modified and distributed freely, subject to the following
 restrictions:

1. A copy of the file (COPYRIGHT) must be distributed along with any
   copies that you redistribute; this includes copies that you have
   modified, or copies of programs or other software products that
   include this software.

2. The header must remain in all files. Modifications of the software
   must carry prominent notices in this header, stating who changed
   the files and the date of any change. 

3. Strong (Un)Stable Manifolds 1D is distributed in the hope that it 
   will be useful, but there is no warranty or other guarantee of
   fitness. The software is provided as is without any obligation on
   the part of the author to assist in its use, correction,
   modification or enhancement.

4. We would appreciate an email if you use or have used this software;
   this data will remain confidential and will not be disclosed to any
   third party.

 If you use a picture produced by this software in a publication,
 please give credit with a notice such as the following: 

	Figures 1, 2 and 4 were generated with DsTool [1,2].

where [1,2] refers to the following two papers:

[1] A. Back, J. Guckenheimer, M.R. Myers, F.J. Wicklin and P.A. Worfolk,
    "DsTool: Computer assisted exploration of dynamical systems",
    Notices Amer. Math. Soc. 39(4) (1992), pp. 303-309.

[2] H.M.Osinga and G.R. Rokni-Lamooki, 
    "One-dimensional strong stable and unstable manifolds code", 
    Software for use inside the Tcl/Tk version of DsTool, available via
    http://www.dynamicalsystems.org/sw/sw/detail=?item=26. 


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

Explanation of the parameters
------------------------------------

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).


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

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. 


