File: auto.tex

package info (click to toggle)
auto-07p 0.9.1%2Bdfsg-7
links: PTS, VCS
area: main
in suites: buster
size: 16,200 kB
sloc: fortran: 22,644; f90: 19,340; python: 19,045; ansic: 11,116; sh: 1,079; makefile: 618; perl: 339
file content (13727 lines) | stat: -rw-r--r-- 584,522 bytes
parent folder | download | duplicates (3)
%==============================================================================
%==============================================================================
\documentclass[12pt]{report}
\usepackage{epsfig}
\usepackage{hyperref}
\usepackage{graphicx}
\usepackage{include/harvard}
\usepackage{alltt}
\usepackage{longtable}
\usepackage{moreverb}
\usepackage{amsmath,amssymb}
\usepackage{url}
\usepackage{subfigure}
\usepackage{xspace}
\pagestyle{plain}
\topmargin=0pt
\textwidth=6.75in
\textheight=9in
\evensidemargin=-15pt
\oddsidemargin=-15pt
%==============================================================================
\input{macros}
%==============================================================================
\def\norm#1{\parallel#1\parallel}
\def\abs#1{\mid#1\mid}
\def\eps{\epsilon}
\def\R{{\rm R}}
\def\Rn{{\rm R}^n}
%==============================================================================
%==============================================================================
\begin{document}
\bibliographystyle{include/agsm} 
%
\title{
\LARGE {\cal AUTO}-07P :\\ 
\Large CONTINUATION AND BIFURCATION SOFTWARE \\
\Large FOR ORDINARY DIFFERENTIAL EQUATIONS\\ 
\author{
\Large Eusebius J. Doedel and Bart E. Oldeman\\
\Large Concordia University\\
\Large Montreal, Canada\\
\\
with major contributions by\\
\\
Alan R. Champneys (Bristol),
Fabio Dercole (Milano),
Thomas Fairgrieve (Toronto),
\\
Yuri Kuznetsov (Utrecht),
Randy Paffenroth (Pasadena),
\\
Bj\"orn Sandstede (Brown),
Xianjun Wang,
and
Chenghai Zhang.\\
}}
\date{January 2012}
\pagenumbering{alph}
\maketitle
\pagenumbering{arabic}
\setcounter{page}{1}
\tableofcontents
%
%
\newpage
~
\vskip.50truein
\subsection*{Preface}
This is a guide to the software package {\cal AUTO}
for continuation and bifurcation problems in ordinary differential 
equations.
Earlier versions of {\cal AUTO} were described in 
\citename{Do:81} \citeyear{Do:81},
\citename{DoKe:86} \citeyear{DoKe:86},
\citename{DoWa:95a} \citeyear{DoWa:95a},
\citename{WaDo:95b} \citeyear{WaDo:95b},
\citename{AUTO:97} \citeyear{AUTO:97},
\citename{AUTO:2000} \citeyear{AUTO:2000}.
For a description of the basic algorithms see
\citename{DoKeKe:91a} \citeyear{DoKeKe:91a},
\citename{DoKeKe:91b} \citeyear{DoKeKe:91b}.
{\cal AUTO} incorporates the {\cal HomCont} algorithms of
\citename{ChKu:94} \citeyear{ChKu:94},
\citename{ChKuSa:95} \citeyear{ChKuSa:95}
for the bifurcation analysis of homoclinic orbits, and
the BPcont algorithms of \citename{DercoleSMSC:08}
\citeyear{DercoleSMSC:08} for the continuation of
branch points in both symmetric and non-symmetric problems.
The Floquet multiplier algorithms were written by
\citename{Fa:94} \citeyear{Fa:94},
\citename{FaJe:91} \citeyear{FaJe:91}.
A GUI was written by
\citename{XJW:94} \citeyear{XJW:94}.
The Python CLUI is the work of Randy Paffenroth.

\vskip1.00truein
\subsection*{Acknowledgments}
The first author is much indebted to H.~B.~Keller 
of the California Institute of Technology for his inspiration,
encouragement and support.
He is also thankful to {\cal AUTO} users and research collaborators who have 
directly or indirectly contributed to its development,
in particular, 
Jean Pierre Kern\'evez, UTC, Compi\`egne, France;
Don Aronson, University of Minnesota, Minneapolis;
Hans Othmer, University of Utah; and
Frank Schilder, University of Surrey.
Some material in this document related to the computation of connecting orbits
was developed with Mark Friedman, University of Alabama, Huntsville.
Also acknowledged is the work of Nguyen Thanh Long,
Concordia University, Montreal, on the graphics program {\cal PLAUT}.
Special thanks are due to Sheila Shull, California Institute of Technology,
for her cheerful assistance in the distribution of {\cal AUTO} over a long period
of time.
Over the years, the development of {\cal AUTO} has been supported by
various agencies through the California Institute of Technology, and
by research grants from NSERC (Canada).

The development of {\cal HomCont} has benefitted from help and advice from, 
among others, 
W.-J. Beyn, Universit\"{a}t Bielefeld,
M.~J. Friedman, University of Alabama,
A. Rucklidge, University of Cambridge, 
M. Koper, University of Utrecht,
C.~J. Budd, University of Bath, and
Financial support for this collaboration was also received from the U.K.
Engineering and Physical Science Research Council and the Nuffield Foundation.

\newpage
~
\subsection*{License}
{\cal AUTO} is available under the terms of the BSD license:\\
\begin{footnotesize}
~\\
Copyright \copyright~1979--2007, E.~J.~Doedel, California Institute of
Technology, and Concordia University.  All rights reserved.\\
~\\
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
\begin{itemize}
\item Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer. 
  
\item Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer listed
  in this license in the documentation and/or other materials
  provided with the distribution.
  
\item Neither the name of the copyright holders nor the names of its
  contributors may be used to endorse or promote products derived from
  this software without specific prior written permission.
\end{itemize}
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT  
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT  
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
\end{footnotesize}

Note that the three-dimensional plotting tool {\cal PLAUT04} optionally
depends on libraries that are covered by the GNU General Public
License (GPL), in particular, Coin, SoQt and Qt. In that case the
{\cal PLAUT04} binaries are also covered by the GPL.

%==============================================================================
%==============================================================================
\chapter{Installing {\cal AUTO}.} \label{ch:Installing_AUTO}
%==============================================================================
%==============================================================================
\section{ Installation.} \label{sec:Installation}
%The {\cal AUTO} files {\filef auto.ps.gz, auto.tar.gz} and {\filef README} 
%are available via FTP from 
%directory {\filef pub/doedel/auto} at \url{ftp.cs.concordia.ca}.
The {\cal AUTO} file \filef{auto07p-0.9.1.tar.gz} is
available via \url{http://cmvl.cs.concordia.ca/auto}.
%The {\filef README} file contains the instructions for printing this manual.
Here it is assumed that you are using the Unix (e.g. \emph{bash}) shell 
and that the file \filef{auto07p-0.9.1.tar.gz} is in your main
directory. See below for OS-specific notes.

While in your main directory, enter the commands
\commandf{gunzip auto07p-0.9.1.tar.gz},
followed by \commandf{tar xvfo auto07p-0.9.1.tar}.
This will result in a directory \filef{auto}, 
with one subdirectory, \filef{auto/07p}. 
Type \commandf{cd auto/07p}
to change directory to \filef{auto/07p}.
Then type
\commandf{./configure}~,
to check your system for required compilers and libraries.
Once the \filef{configure} script has finished you 
may then type \commandf{make} to compile \AUTO
and its ancillary software.
The \filef{configure} script is designed to detect the details
of your system which \AUTO requires to compile successfully.
If either the \filef{configure} script or the \filef{make} command
should fail, you may assist the \filef{configure} script by giving
it various command line options.  Please type \commandf{./configure --help}
for more details.
Upon compilation, you may type 
\commandf{make clean}  
to remove unnecessary files.

To run \AUTO you need to set your environment variables correctly.
Assuming \AUTO is installed in your home directory, the following
commands set your environment variables so that you will be able to
run the \AUTO commands, and may be placed into your \filef{.login},
\filef{.profile}, or \filef{.cshrc} file, as appropriate.  If you are
using a \commandf{sh} compatible shell, such as \commandf{sh},
\commandf{bash}, \commandf{ksh}, or \commandf{ash} enter the command
\commandf{source~ {\rm \$}HOME/auto/07p/cmds/auto.env.sh}.  On the
other hand, if you are using a \commandf{csh} compatible shell, such
as \commandf{csh} or \commandf{tcsh}, enter the command \commandf{
source~ {\rm \$}HOME/auto/07p/cmds/auto.env}.

The Graphical User Interface (GUI94) requires the {\cal X-Window} system
and {\cal Motif} or {\cal LessTif}.
Note that the GUI is not strictly necessary, since {\cal AUTO} can be
run very effectively using the Unix Command Language User Interface (CLUI).
Moreover, long or complicated sequences of {\cal AUTO} calculations can
be programmed using the alternative Python CLUI. 
The GUI is not compiled by default. To compile
\AUTO with the GUI, type \commandf{./configure --enable-gui}
and then \commandf{make} in the directory \filef{auto/07p}.

To use the Python CLUI and the ``@pp'' {\cal PyPLAUT} plotter it
is strongly recommended to install NumPy
(\url{http://numpy.scipy.org}), TkInter, and
Matplotlib (\url{http://matplotlib.sourceforge.net/}).
Note that Matplotlib 0.99 or higher is recommended because it supports
3D plotting in addition to 2D plotting.
Python itself needs to be at least version 2.3 or higher, but 2.4 or
higher is strongly recommended and required for NumPy and Matplotlib.
As of this writing Python 3.x is not yet supported by
Matplotlib, and therefore not recommended.
For enhanced interactive use of the Python CLUI it is also worth
installing IPython (\url{http://ipython.scipy.org}).

The graphic tool for 3D \AUTO data visualization, {\cal PLAUT04}, is
compiled by default, but depends on a few libraries that may not be
in a standard installation of a typical Unix-like
system. These libraries may be available as optional packages,
though. In order of preference these are:
\begin{enumerate}
\item
Coin3D (version 2.2 or higher), SoQt (1.1.0 or higher), and simage
(1.6 or higher). With SoQt 1.5.0 or higher, simage is no longer required.
\item
Coin3D with the SoXt library, which interfaces with (Open)Motif or
LessTif (version 2.0 or higher) instead of Qt. The user interface has
a few problems with LessTif though, in particular it is likely to
crash on 64-bit machines, so the Qt version or (Open)Motif is
recommended.
\item
One can download SGI's implementation of the
Open Inventor libraries from:
\url{ftp://oss.sgi.com/projects/inventor/download/}
Because SGI's implementation for Linux cannot show text correctly, 
we recommend that Coin is used instead of SGI's implementation. 
\end{enumerate}

The \filef{configure} script checks
for these libraries and outputs a warning if any of these libraries
cannot be found. It first checks for SoQt, and then for SoXt, unless
you pass \texttt{\hyphenchar\font45\relax --disable-plaut04-qt}
as an option to \filef{configure}.
If the libraries are not available you can still compile
all other components of \AUTO using \filef{make}.

The Fortran code uses several routines that were not standardardized
prior to the Fortran 2003 standard, for timing, flushing output, and
accessing command-line arguments. The \filef{configure} script first looks if
the F2003 routines are supported (\filef{src/f2003.f90}), then checks
for a set of routines that are widely implemented across Unix
compilers (\filef{src/unix.f90}), and if that fails too, uses a set of
dummy replacement routines (\filef{src/compat.f90}), which could be
edited for some obscure installations.

The PostScript conversion command \commandf{@ps} is compiled by
default. Alternatively you can type \commandf{make} in the directory
\filef{auto/07p/tek2ps}.
To generate the on-line manual, type \commandf{make} in
\filef{auto/07p/doc}, which depends on the presence of xfig's
(transfig) fig2dev utility.

To prepare {\cal AUTO} for transfer to another machine,
type \commandf{make superclean}
in the directory \filef{auto/07p} before creating the \filef{tar}-file. 
This will remove all executable, object, and other non-essential files, and
thereby reduce the size of the package.

Some {\cal LAPACK} routines used by {\cal AUTO} for computing eigenvalues and
Floquet multipliers are included in the package
(\citename{LAPACK:99} \citeyear{LAPACK:99}).
The Python CLUI includes a slightly modified version of the Pointset
and Point classes from PyDSTool by R.~Clewley, M.D.~LaMar, and E.~Sherwood
(\url{http://pydstool.sourceforge.net})

\subsection{Installation on Linux/Unix}
A free Fortran 95 compiler, Gfortran, is shipped with most recent
Linux distributions, or can be obtained at 
\url{http://gcc.gnu.org/wiki/Gfortran}.
The following packages (and their dependencies) are recommended for
Fedora:
\begin{itemize}
\item Python: \filef{python-matplotlib-tk} and \filef{ipython}.
\item {\cal PLAUT04}: \filef{SoQt-devel}. For SoQt versions older than
1.5.0, to see pictures of stars, the earth
and the moon instead of white blobs, compile simage from
source (see \url{www.coin3d.org}; needs \filef{libjpeg-devel}).
\item {\cal PLAUT}: \filef{xterm}.
\item GUI94: \filef{lesstif-devel} or \filef{openmotif-devel}.
\item manual: \LaTeX (\filef{tetex} or \filef{texlive}) and \filef{transfig}.
\end{itemize}
and the following for Ubuntu and Debian:
\begin{itemize}
\item Python: \filef{python-matplotlib} and \filef{ipython}.
\item {\cal PLAUT04}: SoQt (\filef{libsoqt-dev} or \filef{libsoqt4-dev}) and
\filef{libsimage-dev}.
\item {\cal PLAUT}: \filef{xterm}
\item GUI94: \filef{lesstif2-dev} or \filef{libmotif-dev}.
\item manual: \LaTeX (\filef{tetex} or \filef{texlive}) and \filef{transfig}.
\end{itemize}
Other distributions may have packages with similar names.

If you need to compile and install one of the above {\cal PLAUT04} libraries
from the source code available at the above web site, and you
find that, after that, {\cal PLAUT04} still does not work then you might need to
adjust the environment variable {\tt LD\_LIBRARY\_PATH} to include
the location of these libraries, for instance {\tt /usr/local/lib}.

\subsection{Installation on Mac OS X}
\AUTO runs on Mac OS X using the above instructions provided that
you have the development tools
installed (see the Mac OS X Install DVD, Optional Installs, Xcode).
You do not need to start an X server to run AUTO.
Furthermore, the following packages are recommended:
\begin{itemize}
\item Gfortran: See \url{http://gcc.gnu.org/wiki/GFortranBinaries}.
Alternatively, see \url{hpc.sourceforge.net} or \url{r.research.att.com/tools/}.
At the time of writing the first of these is recommended to be able
to benefit from parallelization.
\item Python: you can install \textbf{32-bit} Python 2.7, NumPy, and
Matplotlib \filef{.dmg} files
from \url{www.python.org}, \url{numpy.scipy.org},
and \url{matplotlib.sf.net}, respectively.\\
For example, download from\\
\url{http://www.python.org/ftp/python/2.7.2/python-2.7.2-macosx10.3.dmg},\\
\url{http://sourceforge.net/projects/numpy/files/NumPy/1.6.1/numpy-1.6.1-py2.7-python.org-macosx10.3.dmg/download},\\
and 
\url{http://sourceforge.net/projects/matplotlib/files/matplotlib/matplotlib-1.1.0/matplotlib-1.1.0-py2.7-python.org-macosx10.3.dmg/download}

The default system Python in Mac OS X is usable, but may be too old for
Matplotlib and NumPy.
There are other alternatives, for instance the Enthought Python
Distribution at \url{www.enthought.com}. Fink should work but native
graphics provided by the previous alternatives seem to work better.\\
To be able to plot in the Python CLUI in some versions of OS X,
\AUTO uses \filef{pythonw} instead of \filef{python}.
This should happen automatically.
\item {\cal PLAUT04}: Get a Qt \filef{.dmg} from\\
\url{http://qt.nokia.com/downloads/qt-for-open-source-cpp-development-on-mac-os-x}.
Similarly, you can get a binary Coin package from \url{coin3d.org}.
After that you can compile SoQt (at least version 1.5.0)
from the source code at \url{coin3d.org}.
For example, download
\url{http://ftp.coin3d.org/coin/bin/macosx/all/Coin-3.1.3-gcc4.dmg},
\url{http://get.qt.nokia.com/qt/source/qt-mac-opensource-4.8.0.dmg}, and
\url{http://ftp.coin3d.org/coin/src/all/SoQt-1.5.0.tar.gz}.

Try to make sure that the native (Aqua) Qt
is used by setting {\tt \$QTDIR}, if you also have fink installed.
\item {\cal PLAUT}: In pre-Leopard OS X it appears that you do not see
fonts. To solve this issue you need to obtain a different
version of xterm; see
\url{http://sourceforge.net/project/showfiles.php?group_id=21781}.
\item GUI94: Perhaps possible using Fink but not attempted.
\item manual: \LaTeX\xspace and transfig (comes with xfig).
\end{itemize}

Notes for 64-bit Snow Leopard to be able to compile PLAUT04:
\begin{itemize}
\item
To compile and install SoQt, after installing Qt and Coin3D, run
\begin{verbatim}
./configure CFLAGS="-m32" CXXFLAGS="-m32" LDFLAGS="-m32" FFLAGS="-m32"
make
sudo make install
\end{verbatim}
\item
Then, in the AUTO-07p folder configure and compile AUTO as described above.
\end{itemize}

\subsection{Installation on Windows}
A native, light-weight solution for running AUTO on Windows is
to use GFortran, MSYS 1.0.11 or higher (see \url{http://www.mingw.org}),
combined with a native Win32 version of Python,
obtained at \url{http://www.python.org}. To install this setup:
\begin{itemize}
\item
Install Python (as of this writing, preferably version 2.7, not 3.2!)
from \url{www.python.org}, NumPy from \url{numpy.scipy.org},
and Matplotlib from \url{matplotlib.sf.net}, which all come
with installers.
\item
Install MinGW (make sure to include msys-base, gcc and fortran)
using the MinGW Graphical Installer at \url{http://www.mingw.org}.
\item
Start MSYS using the Start menu (Start $>$ All Programs $\to$ MinGW
$\to$ MinGW Shell) or by clicking on its desktop icon, which
puts you in a home directory, where you can unpack
\AUTO using \filef{gunzip} and \filef{tar}, as described above.
\item
Make sure that the {\tt gfortran} and {\tt python} binaries
are in your {\tt PATH}, and that their directories are at the front of it.
You can do this, for instance, using the shell command
\commandf{export PATH="/c/Python27:/bin:/c/Program Files/gfortran/bin:\$PATH" }.
You can also inspect, edit and then source the file
\filef{auto/07p/cmds/auto.env.sh} to achieve this.
\item
Now you should be able to run configure and make to compile \AUTO
as shown above.
\end{itemize}

You can use \AUTO using shell commands from the default MSYS shell
environment. You can also start the CLUI by double clicking on the file
\filef{auto.py} in the \filef{python} folder of \AUTO in Windows Explorer,
or by creating a shortcut to it.

Alternatively, \AUTO runs on Windows as above using the Unix-like
environment Cygwin (see \url{http://www.cygwin.com}), but the
non-Cygwin setup is more responsive and is much easier to setup for
Matplotlib. You can however use its X server and lesstif to compile
and run the old {\cal PLAUT} and GUI94, if you so desire.

With some effort it is possible to compile {\cal PLAUT04}
on Windows (without an X server) using Coin, SoQt, and Qt. You can
also find precompiled {\cal PLAUT04} binaries at
\url{http://sourceforge.net/projects/auto-07p/files}.

\section{ Restrictions on Problem Size.} \label{sec:Restrictions}
There are no size restrictions in the file \filef{
  auto/07p/include/auto.h} any more. This file now contains the
default effective number of equation parameters {\tt NPAR}, set to 36
upon installation. It can be overridden in constant files.
See also Section~\ref{sec:Restrictions_on_PAR}.
The default can be changed by editing {\tt auto.h}.
This must be followed by recompilation by typing \commandf{make} 
in the directory {\tt auto/07p/src}.

Note that in certain cases the {\it effective dimension} may be greater
than the user dimension.
For example, for the continuation of folds,
the effective dimension is 2{\tt NDIM}+1 for algebraic equations,
and 2{\tt NDIM} for ordinary differential equations, respectively.
Similarly, for the continuation of Hopf bifurcations,
the effective dimension is 3{\tt NDIM}+2.
 
 
\section{ Compatibility with Earlier Versions.} \label{sec:Compatibility}
Unlike earlier versions, \AUTO can no longer be compiled using a pure
Fortran 77 compiler, but you need at least a Fortran 90 compiler.
A free Fortran 95 compiler, GFortran, is shipped with most recent
Linux distributions, or can be obtained at
\url{http://gcc.gnu.org/wiki/GFortran}, which contains binaries for
Linux, Mac OS X and Windows. \AUTO was also tested with the free
compiler {\tt g95}, and there exist various commercial Fortran
9x compilers as well.

The {\cal AUTO} input files are now called 
{\tt c.xxx} (the constants file),
and
{\tt h.xxx} (the {\cal HomCont} constants file, only used with {\cal HomCont});
the output files are called
{\tt b.xxx} (the bifurcation-diagram-file),
{\tt s.xxx} (the solution-file),
and
{\tt d.xxx} (the diagnostics-file).
The command \commandf{@rn} can be used to rename all these files from
their old names.
There are also minor changes in the formatting of these files 
compared to recent versions of {\cal AUTO}, such as {\cal AUTO97} 
and {\cal AUTO2000}.
The main change compared to {\cal AUTO97} is that there is now a
programmable Python CLUI. The constants file can be written using
a completely new, more flexible syntax, but the old syntax is
still accepted, and files can be converted using the command
\commandf{@cnvc} (see Section~\ref{sec:command_mode}).

Due to the replacement of EISPACK routines by LAPACK routines for the
computation of eigenvalues and eigenvectors, the sign of the
eigenvectors may have flipped sometimes with respect to earlier
versions. This affects the sign of some {\cal HomCont}
test functions and the initial direction when using the homotopy
method (you may have to flip the sign of the starting distance
in the routine STPNT). Eigenvectors are now normalized to avoid
future problems and improve consistency.

Parameter derivatives in {\tt DFDP} are now significant when using {\cal
HomCont}. If only the derivatives with respect to phase space variables
are specified in {\tt DFDU}, please use the setting \parf{JAC=-1}.

When upgrading from {\cal AUTO2000}, you can continue to use
equations-files written in C. However, there is now a strict
difference between indexing of the array {\tt par[]} in the
C file and the references to it using {\tt PAR()} in constants
files and output, using {\tt par[i]=PAR(I+1)}. In practise this
means that you do not have to change the C file, but need to
add 1 to all parameter indices in the constant files, namely
{\tt ICP}, {\tt THL}, and {\tt UZR}. For example,
the period is referenced by {\tt par[10]} in the C file,
but by {\tt PAR(11)} in the constants file. Equation files
written in C are used in the homoclinic branch switching
demo in Chapter~\ref{ch:HomCont_hbs}.
 
A detailed list of user-visible changes can be found in the file
\filef{\$AUTO\_DIR/CHANGELOG}.

\section{ Parallel Version.} \label{sec:Parallel}
\AUTO contains code which allows
it to run in on parallel computers.  Namely,
it can use either OpenMP to run most of its code in parallel
on shared-memory multi-processors, or the MPI message passing
library.
When the \filef{configure} script is run it will try to
detect if the Fortran compiler supports OpenMP; examples
are Gfortran 4.2 or later and the Intel Fortran Compiler.
If it is successful the necessary compiler flags are used
to enable OpenMP in \AUTO.
To force the \filef{configure} script not to use OpenMP,
one may type \commandf{./configure --without-openmp},
and then type \commandf{make}.
On the other hand, unless there is some
particular difficulty, we recommend that that the 
\filef{configure} script be used without arguments, since the
parallel version of \AUTO may easily be controlled,
and even run in a serial mode,  
through the use of the environment variable {\tt OMP\_NUM\_THREADS}.

For example, to run the \AUTO executable \filef{auto.exe}
in serial mode you just type \commandf{export OMP\_NUM\_THREADS=1}.
To run the same command in parallel on 4 processors you type 
\commandf{export OMP\_NUM\_THREADS=4}. Without any {\tt OMP\_NUM\_THREADS}
set the number of processors that \AUTO will use can be equal to the
actual number of processors on the system, or can be equal to one;
this is system-dependent.

The MPI message passing library is not used by default. You can enable it
by typing  \commandf{./configure --with-mpi}. If OpenMP and MPI are
both used then \AUTO uses mixed mode, with MPI parallelisation
occurring at the top level.

Running the MPI version is somewhat more complex because of the fact
that MPI normally uses some external program for starting the
computational processes.  The exact name and command line options of
this external program depends on your MPI installation.  A common name
for this MPI external program is \filef{mpirun}, and a common command
line option which defines the number of computational processes is \filef{
-np}.  Accordingly, if you wanted to run the MPI version of \AUTO
on four processors, with the above external program, you would
type \filef{mpirun -np 4 file.exe}.  Please see your local MPI
documentation for more detail.

Both the Python CLUI and the commands in the \filef{ auto/07p/cmds}
directory described in Chapter~\ref{sec:command_mode} may be used with the
MPI version as well, by setting the \commandf{ AUTO\_COMMAND\_PREFIX}
environment variable.  For example, to run \AUTO in parallel using
the MPI library on 4 processors just type
\commandf{export AUTO\_COMMAND\_PREFIX='mpirun -np 4'}
before you run the Python CLUI \commandf{auto} or
the commands in \filef{ auto/07p/cmds} normally. 
The previous example
assumed you are using the \commandf{sh} shell or the \commandf{bash} shell; for
other shells you should modify the commands appropriately,
for example \commandf{setenv AUTO\_COMMAND\_PREFIX 'mpirun -np 4'}
for the \commandf{csh} and \commandf{tcsh} shells. Alternatively,
inside the Python
CLUI and scripts you can use \commandf{import os} followed by
\commandf{os.environ["AUTO\_COMMAND\_PREFIX"]="mpirun -np 4"}.

%==============================================================================
%==============================================================================
\chapter{ Overview of Capabilities.} \label{ch:Overview}
%==============================================================================
%==============================================================================
\section{ Summary.} \label{sec:Summary}
{\cal AUTO} can do a limited bifurcation analysis of algebraic systems
\begin{equation} \label{1} 
  f( u , p ) = 0 ,  \qquad  f(\cdot,\cdot) , u \in \Rn.
\end{equation}
The main algorithms in {\cal AUTO}, however, are aimed at the continuation
of solutions of systems of ordinary differential equation (ODEs) of the form
\begin{equation} \label{2} 
 u'(t) = f\bigl( u(t) , p \bigr) , 
  \qquad  f(\cdot,\cdot) , u(\cdot) \in \Rn,
\end{equation}
subject to boundary (including initial) conditions and integral constraints.
Above, $p$ denotes one or more free parameters.

These boundary value algorithms also allow {\cal AUTO} to do certain stationary 
solution and wave calculations for the partial differential equation (PDE)
\begin{equation} \label{3} 
  u_t = D u_{xx} + f( u , p ), 
  \qquad  f(\cdot,\cdot) , u(\cdot) \in \Rn,
\end{equation}
where $D$ denotes a diagonal matrix of diffusion constants.

The basic algorithms used in {\cal AUTO},
as well as related algorithms, can be found in 
\citename{HBK:77} \citeyear{HBK:77},
\citename{HBK:86} \citeyear{HBK:86},
\citename{DoKeKe:91a} \citeyear{DoKeKe:91a},
\citename{DoKeKe:91b} \citeyear{DoKeKe:91b}.

Below, the basic capabilities of {\cal AUTO} are specified in more detail.
Some representative demos are also indicated.
 
\section{ Algebraic Systems.} \label{sec:algebraic_systems}
Specifically, for (\ref{1}) {\cal AUTO} can~:~
 
\begin{itemize}
\item[-]
  Compute solution families.\\  (Demo {\tt ab}; Run~2.) 
\item[-]
  Locate branch points, continue these in two or three parameters,
  and automatically compute
  bifurcating families. \\ (Demos {\tt pp2}; Run~1, and {\tt apbp}.)
\item[-]
  Locate Hopf bifurcation points, continue these in two
  parameters, detect whether the Hopf bifurcation is sub- or
  supercritical, and detect zero-Hopf, Bogdanov-Takens, and 
  generalized Hopf (Bautin) bifurcations.\\ (Demos {\tt pp3} and
  {\tt ppp}.)
\item[-]
  Locate folds (limit points), continue these 
  in two parameters, and detect cusp, zero-Hopf, and Bogdanov-Takens
  bifurcations. \\
\item[-]
  Locate branch points, folds, period-doubling, and torus
  (Neimark-Sacker) bifurcations, continue these in two or three
  parameters, and switch branches at branch points and
  period-doubling bifurcations
  for fixed points of the discrete dynamical system
  $u^{(k+1)}= f( u^{(k)}, p )$ \\ (Demo {\tt dd2}.)
\item[-]
  Find extrema of an objective function along solution families
  and successively continue such extrema in more parameters.
  \\ (Demo {\tt opt}.)
\end{itemize}


\section{ Ordinary Differential Equations.} \label{sec:ODEs}
For the ODE (\ref{2}) the program can~:~
 
\begin{itemize}
\item[-]
  Compute families of stable and unstable periodic
  solutions and
  compute the Floquet multipliers, that determine stability, along
  these families.
  Starting data for the computation of periodic orbits are
  generated automatically at Hopf bifurcation points. \\
  (Demo {\tt ab}; Run~2.)
\item[-]
  Locate folds, branch points, period doubling bifurcations,
  and bifurcations to tori, along families of periodic solutions. 
  Branch switching is possible at branch points and at period 
  doubling bifurcations.  \\
  (Demos {\tt tor}, {\tt lor}.)
\item[-]  Continue folds, period-doubling bifurcations,
  and bifurcations to tori, in two parameters, detecting
  1:1, 1:2, 1:3 and 1:4 resonances. \\
  (Demos {\tt plp}, {\tt pp3}, {\tt tor}.)

  The continuation of orbits of fixed period is also
  possible. This is the simplest way to compute curves of
  homoclinic orbits, if the period is sufficiently large. \\
  (Demo {\tt pp2}.)

  The continuation of branch points in two parameters is only possible
  in non-generic problems, characterized by problem-specific symmetries.\\
  (Demo {\tt lcbp}, Run~2.)

  Generically, in non-symmetric problems, branch points are continued
  in three parameters.\\
  (Demos {\tt lcbp}, Run~3, and {\tt abcb}.)

\item[-]  Do each of the above for {\it rotations}, i.e., when some of the
  solution components are periodic modulo a phase gain of a
  multiple of $2 \pi$. \\
  (Demo {\tt pen}.)
\item[-]  Follow curves of homoclinic orbits and detect and continue
  various codimension-2 bifurcations, using the {\cal HomCont} algorithms of 
  \citename{ChKu:94} \citeyear{ChKu:94},
  \citename{ChKuSa:95} \citeyear{ChKuSa:95}.\\
  (Demos  {\tt san}, {\tt mnt}, {\tt kpr}, {\tt cir},
  {\tt she}, {\tt rev}.)
\item[-]  Locate extrema of an integral objective functional along a family 
  of periodic solutions and successively continue such extrema 
  in more parameters. \\
  (Demo {\tt ops}.)
\item[-]
  Compute curves of solutions to (\ref{2}) on $[0,1]$, subject to general
  nonlinear boundary and integral conditions.
  The boundary conditions need not be separated, i.e., they may
  involve both $u(0)$ and $u(1)$ simultaneously.
  The side conditions may also depend on parameters.
  The number of boundary conditions plus the number of integral
  conditions need not equal the dimension of the ODE, 
  provided there is a corresponding number of additional
  parameter variables. \\
  (Demos {\tt exp}, {\tt int}.)
\item[-]
  Determine folds and branch points along
  solution families to the above boundary value problem.
  Branch switching is possible at branch points.
  Curves of folds and branch points can be computed.\\
  (Demos {\tt bvp}, {\tt int}, {\tt sspg}.)
\end{itemize}
 


\section{ Parabolic PDEs.} \label{sec:Parabolic_PDEs}
For (\ref{3}) the program can~:~
 
\begin{itemize}
\item[-]
  Trace out families of spatially homogeneous solutions.
  This amounts to a bifurcation analysis of the algebraic
  system (\ref{1}). However, {\cal AUTO} uses a related system instead,
  in order to enable the detection of bifurcations to wave train
  solutions of given wave speed. More precisely, bifurcations
  to wave trains are detected as Hopf bifurcations along fixed
  point families of the related ODE
  \begin{equation} \label{4} \begin{array}{cl}
  & u'(z) = v(z) ,\\
  & v'(z) =-D^{-1}  \bigl[ c~v(z) + f\bigl( u(z) , p \bigr) \bigr], \\
  \end{array} \end{equation}
  where $z = x - ct$ , with the wave speed $c$ specified by the user.\\
  (Demo {\tt wav}; Run~2.) 
\item[-]
  Trace out families of periodic wave solutions to (\ref{3}) that emanate
  from a Hopf bifurcation point of Equation~\ref{4}.
  The wave speed $c$ is  fixed along such a family, but
  the wave length $L$, i.e., the period of periodic solutions 
  to (\ref{4}),
  will normally vary. If the wave length $L$ becomes large,
  i.e., if a homoclinic orbit of Equation~\ref{4} is approached,
  then the wave tends to a solitary wave solution of (\ref{3}). \\
  (Demo {\tt wav}; Run~3.) 
\item[-]
  Trace out families of waves of fixed wave length $L$ in two parameters. 
  The wave speed $c$ may be chosen as one of these parameters.
  If $L$ is large then such a continuation gives a family
  of approximate solitary wave solutions to (\ref{3}).\\
  (Demo {\tt wav}; Run~4.) 
\item[-]
  Do time evolution calculations for (\ref{3}), given periodic
  initial data on the interval $[0,L]$.
  The initial data must be specified on $[0,1]$ and
  $L$ must be set separately because of internal scaling.
  The initial data may be given analytically or
  obtained from a previous computation of wave trains, solitary
  waves, or from a previous evolution calculation.
  Conversely, if an evolution calculation results in a
  stationary wave then this wave can be used as starting data
  for a wave continuation calculation.\\
  (Demo {\tt wav}; Run~5.)
\item[-]
  Do time evolution calculations for (\ref{3}) subject to user-specified
  boundary conditions.
  As above, the initial data must be specified on $[0,1]$ and the space
  interval length $L$ must be specified separately.
  Time evolution computations of (\ref{3}) are adaptive in space and
  in time. Discretization in time is not very accurate~: only
  implicit Euler. Indeed, time integration of (\ref{3}) has only been
  included as a convenience and it is not very efficient.
  (Demos {\tt pd1}, {\tt pd2}.)
\item[-]
  Compute curves of stationary solutions to (\ref{3}) subject to user-specified
  boundary conditions.
  The initial data may be given analytically, obtained from a previous 
  stationary solution computation, or from a time evolution calculation.\\
  (Demos {\tt pd1}, {\tt pd2}.)
\end{itemize}
 
In connection with periodic waves,
note that (\ref{4}) is just a special case of (\ref{2}) and
that its fixed point analysis is a special case of (\ref{1}).
One advantage of the built-in capacity of {\cal AUTO} to deal with
problem (\ref{3}) is that the user need only specify $f$, $D$, and $c$.
Another advantage is the compatibility of output data for
restart purposes. This allows switching back and forth between
evolution calculations and wave computations.

\section{ Discretization.} \label{sec:Discretization}
  {\cal AUTO} discretizes ODE boundary value problems
  (which includes periodic solutions) by the method of orthogonal 
  collocation using piecewise polynomials with 2-7 collocation points 
  per mesh interval (\citename{dBSw:73} \citeyear{dBSw:73}).
  The mesh automatically adapts to the solution to equidistribute
  the local discretization error (\citename{RuCr:78} \citeyear{RuCr:78}).
  The number of mesh intervals and the number of collocation points
  remain constant during any given run, although they may be changed 
  at restart points.
  The implementation is {\cal AUTO}-specific. In particular, the choice of
  local polynomial basis
  and the algorithm for solving the linearized collocation systems
  were specifically designed for use in numerical bifurcation analysis.
  
%==============================================================================
%==============================================================================
\chapter{ User-Supplied Files.} \label{ch:User_supplied_files}
%==============================================================================
%==============================================================================
The user must prepare the two files described below.
This can be done with the GUI described in Chapter~\ref{ch:GUI}, 
or independently.

\section{ The Equations-File \texttt{xxx.f90}, or \texttt{xxx.f}, or \texttt{xxx.c}} 
A source file {\tt xxx.f90} containing the Fortran routines
{\tt FUNC}, {\tt STPNT}, {\tt BCND}, {\tt ICND}, {\tt FOPT}, and {\tt PVLS}.
Here {\tt xxx} stands for a user-selected name. 
If any of these routines is irrelevant 
to the problem then its body need not be completed.
Examples are in {\tt auto/07p/demos}, where, e.g.,
the file {\tt ab/ab.f90} defines a two-dimensional dynamical system,
and the file {\tt exp/exp.f90} defines a boundary value problem.
The simplest way to create a new equations-file is to copy 
an appropriate demo file.
For a fully documented equations-file see
{\tt auto/07p/demos/cusp/cusp.f90} or {\tt auto/07p/gui/aut.f90}.
In GUI mode, this file can be directly loaded with the GUI-button 
{\it Equations/New}; see Section~\ref{sec:GUI_Menu_bar}.
 
The equations-file can either be written in fixed-form (old-style)
Fortran (.f), free-form Fortran (.f90) or in C (.c).

\section{ The Constants-File \texttt{c.xxx}} 
{\cal AUTO}-constants for {\tt xxx.\{f,f90,c\}} are normally expected 
in a corresponding file {\tt c.xxx}.
Specific examples include {\tt ab/c.ab}
and {\tt exp/c.exp} in {\tt auto/07p/demos}.
See Chapter~\ref{ch:AUTO_constants}
for the significance of each constant.

\newpage
\section{ User-Supplied Routines.} \label{sec: User_supplied_routines}
The purpose of each of the user-supplied routines in
the file {\tt xxx.\{f90,f\}} is described below.
  
\begin{itemize}
\item[-] {\tt FUNC}~:~
  defines the function $f(u,p)$ in (\ref{1}), (\ref{2}), or (\ref{3}).
\item[-] {\tt STPNT}~:~
  This routine is called only if {\tt IRS}=0 
(see Section~\ref{sec:IRS} for {\tt IRS}),
  which typically is the case for the first run, or when a system
  is manually extended. A system is extended if {\tt NDIM} (see
  Section~\ref{sec:NDIM}) increases between runs.
  It defines a starting solution $(u,p)$ of (\ref{1}) or (\ref{2}).
  The starting solution should not be a branch point.\\
  (Demos {\tt ab}, {\tt exp}, {\tt frc}, {\tt lor}.)\\
  It extends an existing solution into higher dimensions in the demos
  {\tt p2c} and {\tt c2c}.
\item[-] {\tt BCND}~:~ 
  A routine {\tt BCND} that defines the boundary conditions. \\
  (Demo {\tt exp}, {\tt kar}.)
\item[-] {\tt ICND}~:~ 
  A routine {\tt ICND} that defines the integral conditions. \\ 
  (Demos {\tt int}, {\tt lin}.)  
\item[-] {\tt FOPT}~:~ 
  A routine {\tt FOPT} that defines the objective functional. \\ 
  (Demos {\tt opt}, {\tt ops}.)  
\item[-] {\tt PVLS}~:~
  A routine {\tt PVLS} for defining ``solution measures''.
  This routine, using a ``\texttt{LOGICAL, SAVE :: first = .TRUE.}''
  variable can also be used for initialization, as it is called
  first. \\
  (Demo {\tt pvl}.)
\end{itemize}

In a C language equation file, these routines are written using
lowercase letters; with Fortran you can use any case.
 
\section{ User-Supplied Derivatives.} \label{sec:derivatives}
If {\cal AUTO}-constant {\tt JAC} equals 0 
then derivatives need not be specified in 
{\tt FUNC}, {\tt BCND}, {\tt ICND}, and {\tt FOPT}; see Section~\ref{sec:JAC}.
If {\tt JAC=1} then derivatives must be given.
If {\tt JAC=-1} then the parameter derivatives may be omitted in 
{\tt FUNC}.
This may be necessary for sensitive 
problems, and is recommended for computations in which {\cal AUTO} 
generates an extended system.
Derivatives are specified as follows, where zero entries may be
omitted:
\begin{itemize}
\item[{\tt FUNC}]
\begin{itemize}
\item
 Derivatives with respect to phase space variables
  are specified in {\tt DFDU(1:NDIM, 1:NDIM)}.
\item
 Parameter derivatives go into {\tt DFDP(1:NDIM, 1:NPAR)}.
\end{itemize}
\item[{\tt BCND}]
\begin{itemize}
\item
Derivatives with respect to the two boundary conditions
are specified in {\tt DBC(1:NBC, 1:NBC)} and {\tt DBC(1:NBC, NBC+1:2*NBC)},
respectively.
\item
Parameter derivatives go into {\tt DBC(1:NBC, 2*NBC+1:2*NBC+NPAR)}.
\end{itemize}
\item[{\tt ICND}]
\begin{itemize}
\item
Derivatives with respect to the integral conditions
are specified in {\tt DINT(1:NINT, 1:NINT)}.
\item
Parameter derivatives go into {\tt DINT(1:NINT, NINT+1:NINT+NPAR)}.
\end{itemize}
\end{itemize}
Examples of user-supplied derivatives can be found in
demos  {\tt dd2}, {\tt int}, {\tt plp}, {\tt opt}, and {\tt ops}.

%==============================================================================
%==============================================================================
\chapter{ Running {\cal AUTO} using Python Commands.} \label{ch:python_mode}
%==============================================================================
%==============================================================================

 \section{ Typographical Conventions }
 This chapter uses the following conventions.
 All code examples will be in in the following font.

 {\small \begin{center} \begin{boxedverbatim}
 AUTO> copydemo("ab")
 Copying demo ab ... done 
 \end{boxedverbatim} 
 \end{center}
 }

 To distinguish commands which are typed to the Unix
 shell from those which are typed to the \AUTO
 command line user interface (CLUI) we will use the
 following two prompts.

 \begin{tabular}{|l|l|}
 \hline 
 \verb!>! & Commands which follow this prompt are for the Unix shell. \\ \hline
 \verb!AUTO>!   & Commands which follow this prompt are for the \AUTO CLUI. \\ \hline
 \end{tabular}

 \section{ General Overview.} \label{sec:CLUI_Overview}
 The \AUTO command line user interface (CLUI) is similar
 to the command language described in Section~\ref{sec:command_mode}
 in that it facilitates the interactive creating and editing of 
 equations-files and constants-files.
 It differs from the other command language in that it is based 
 on the object-oriented scripting language \python (see \citename{Lut:96} \citeyear{Lut:96})
 and provides extensive programming capabilities.
 This chapter will provide documentation for the \AUTO CLUI commands,
 but is not intended as a tutorial for the \python language.
 We will attempt to make this chapter self contained by describing
 all \python constructs that we use in the examples, but
 for more extensive documentation on the \python language,
 including tutorials and pointers to further documentation,
 please see \citename{Lut:96} \citeyear{Lut:96} or the
 web page \url{http://www.python.org} which contains
 an excellent tutorial at 
 \url{http://www.python.org/doc/current/tut/tut.html}.

 To use the CLUI for a new equation, change to an empty directory.
 For an existing equations-file, change to its directory.
 (\emp{Do not activate the CLUI in the directory \filef{auto/07p} 
 or in any of its subdirectories.})
 Then type 

 \centerline {\commandf{auto}.}

 If your command search path has been correctly set (see
 Section~\ref{sec:Installation}), this command will start the \AUTO CLUI
 interactive interpretor and provide you with the \AUTO CLUI prompt.

 \begin{figure}[htbp]
 {\small 
 \begin{center} \begin{boxedverbatim}
 > auto
 Python 2.5.2 (r252:60911, Nov 14 2008, 19:46:32) 
 [GCC 4.3.2] on linux2
 Type "help", "copyright", "credits" or "license" for more information.
 (AUTOInteractiveConsole)
 AUTO>
 \end{boxedverbatim}
 \end{center}
 }
 \caption[Starting the \AUTO CLUI.]
 {Typing \commandf{auto} at the Unix shell prompt starts the
 \AUTO CLUI.  }
 \label{exa:clui_starting}
 \end{figure}

 If you have IPython installed (\url{http://ipython.scipy.org}), then
 you can get a friendlier interface using the command
 \commandf{auto -i}, enabling TAB completion, persistent command-line
 history and other features.

 In addition to the examples in the following sections there are
 several example scripts which can be found in
 \filef{auto/07p/demos/python} and are listed in
 Table~\ref{tbl:demo_scripts}.  These scripts are fully annotated and
 provide good examples of how \AUTO CLUI scripts are written.  The
 scripts in \filef{auto/07p/demos/python/n-body} are especially lucid
 examples and perform various related parts of a calculation involving
 the gravitational N-body problem.  
 Scripts which end in the
 suffix \filef{.auto} are called ``basic'' scripts and can
 be run by typing \commandf{auto scriptname.auto}.
 The scripts shown in Section~\ref{sec:clui_first_example}
 and Section~\ref{sec:clui_complex_example} are examples
 of basic scripts.
 Scripts which end in the
 suffix \filef{.xauto} are called ``expert'' scripts and can
 be run by typing \commandf{autox scriptname.xauto}.
 More information on expert scripts can be 
 found in Section~\ref{sec:clui_extending}.
 See the \filef{README} file in that
 directory for more information.

 \begin{table}[htbp]
 \begin{center}
 \begin{tabular}{| l | l |}
 \hline
 Script & Description \\
 \hline
 demo1.auto & \begin{minipage}{3in}\smallskip The demo script from Section~\ref{sec:clui_first_example}.\smallskip\end{minipage} \\
 \hline
 demo2.auto, demo3.auto, and demo4.auto & \begin{minipage}{3in}\smallskip The demo scripts from Section~\ref{sec:clui_complex_example}.\smallskip\end{minipage} \\
 \hline
 userScript.xauto & \begin{minipage}{3in}\smallskip The expert demo script from Figure~\ref{exa:clui_complex_function}.\smallskip\end{minipage} \\
 \hline
 userScript.py & \begin{minipage}{3in}\smallskip The loadable expert demo script from Figure~\ref{exa:clui_complex_interactive}.\smallskip\end{minipage} \\
 \hline
 branches.auto & \begin{minipage}{3in}\smallskip The branch
   manipulating script from Figure~\ref{exa:clui branch management}.\smallskip\end{minipage}\\
 \hline
 fullTest.auto & \begin{minipage}{3in}\smallskip A script which uses the entire \AUTO command set, except for the plotting commands.\smallskip\end{minipage} \\
 \hline
 plotter.auto & \begin{minipage}{3in}\smallskip A demonstration of some of the plotting capabilities of \AUTO. \smallskip\end{minipage}\\
 \hline
 tutorial.auto & \begin{minipage}{3in}\smallskip A script which implements the tutorial from Section~\ref{sec:Demos_ab}. \smallskip\end{minipage}\\

 \hline n-body/compute\_lagrange\_points\_family.auto 
 & \begin{minipage}{3in}\smallskip A basic script which computes and plots all of the
 ``Lagrange points'' as a function of the ratio of the masses of
 the two planets.\smallskip\end{minipage}\\

 \hline n-body/compute\_lagrange\_points\_0.5.auto
 & \begin{minipage}{3in}\smallskip A basic script which computes all of the ``Lagrange
 points'' for the case where the masses of the two planets are
 equal, and saves the data.
 \smallskip\end{minipage}\\

 \hline n-body/compute\_periodic\_family.xauto
 & \begin{minipage}{3in}\smallskip An expert script which starts at a ``Lagrange
 point'' computed by compute\_lagrange\_points\_0.5.auto
 and continues in the ratio of the masses until
 a specified mass ratio is reached.  It then computes
 a family of periodic orbits for each pair of
 purely complex eigenvalues.
 \smallskip\end{minipage}\\

 \hline n-body/to\_matlab.xauto
 & \begin{minipage}{3in}\smallskip A script which takes a set of \AUTO data files and creates
 a set of files formatted for importing into Matlab
 for either plotting or further calculations.
 \smallskip\end{minipage}\\
 \hline
 \end{tabular}
 \caption[Available demo scripts.]
 {The various demonstration scripts for the \AUTO CLUI.}
 \label{tbl:demo_scripts}
 \end{center}
 \end{table}

 \section{ First Example } \label{sec:clui_first_example}

 We begin with a simple example of the \AUTO CLUI.  In this example we
 copy the \filef{ab} demo from the \AUTO installation directory and
 run it.  For more information on the \filef{ab} demo see
 Section~\ref{sec:Demos_ab}.
 The commands listed in Table~\ref{tbl:example_clui_1}
 will copy the demo files to your work directory and run
 the first part of the demo.
 The results of running these commands are shown in
 Figure~\ref{exa:clui_first_example}.


 \begin{table}[htbp]
 \begin{center}
 \begin{tabular}{| l | l |}
 \hline
   {\cal Unix}-COMMAND  & ACTION \\
 \hline
 %==============================================================================
   \commandf{auto}  & start the \AUTO CLUI\\ 
 \hline
   \AUTO CLUI COMMAND  & ACTION \\
 \hline
   \commandf{demo('ab')}  & copy the demo files to the work directory\\
   \commandf{ab = load(equation='ab')}  & load the filename \filef{ab.f90} into the variable ab\\
   \commandf{ab = load(ab, constants='ab.1')}  & load the contents of
   the file \filef{c.ab.1} into the variable ab\\
   \commandf{run(ab)}  & run \AUTO with the current set of files\\
 \hline
 %==============================================================================
 \end{tabular}
 \caption[Running the demo \filef{ab} files.]
 {Running the demo \filef{ab} files.}
 \label{tbl:example_clui_1}
 \end{center}
 \end{table}

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 > auto
 Python 2.5.2 (r252:60911, Nov 14 2008, 19:46:32) 
 [GCC 4.3.2] on linux2
 Type "help", "copyright", "credits" or "license" for more information.
 (AUTOInteractiveConsole)
 AUTO> demo('ab')
 Copying demo ab ... done
 Runner configured
 AUTO> ab = load(equation='ab')
 Runner configured
 AUTO> ab = load(ab,constants='ab.1')
 Runner configured
 AUTO> run(ab)
 gfortran -fopenmp -O -c ab.f90 -o ab.o
 gfortran -fopenmp -O ab.o -o ab.exe /home/bart/auto/07p/lib/*.o
 Starting ab ...
 
   BR    PT  TY  LAB    PAR(2)        L2-NORM         U(1)          U(2)     
    1     1  EP    1   8.00000E+00   0.00000E+00   0.00000E+00   0.00000E+00
    1    31  UZ    2   1.40000E+01   0.00000E+00   0.00000E+00   0.00000E+00
    1    36  UZ    3   1.50000E+01   0.00000E+00   0.00000E+00   0.00000E+00
    1    41  UZ    4   1.60000E+01   0.00000E+00   0.00000E+00   0.00000E+00
    1    46  UZ    5   1.70000E+01   0.00000E+00   0.00000E+00   0.00000E+00
    1    51  UZ    6   1.80000E+01   0.00000E+00   0.00000E+00   0.00000E+00

  Total Time    0.181E-01
 ab ... done
 <_=bifDiag instance at 0x0972198c>
 AUTO>
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[The first example of the \AUTO CLUI.]
 {Typing \commandf{auto} at the Unix shell prompt starts the
 \AUTO CLUI.  The rest of the commands are interpreted by
 the \AUTO CLUI.}
 \label{exa:clui_first_example}
 \end{figure}


 Let us examine more closely what action each of the commands 
 performs.  First, \commandf{demo('ab')} 
 (Section~\ref{sec:clui_ref_demo} in the reference) copies the files in 
 \filef{\$AUTO\_DIR/demo/ab} into the work directory.  

 Next, \commandf{ab = load(equation='ab')} 
 (Section~\ref{sec:clui_ref_basic} in the reference)
 informs the \AUTO CLUI that the name of
 the user defined function file is \filef{ab.f90}.  The commands
 \commandf{load}, and the closely related \commandf{run}, are
 two of the most commonly used commands in the
 \AUTO CLUI, since they read and parse the user files which are
 manipulated by other commands.  The \AUTO CLUI stores this setting in
 the variable {\tt ab} until it is changed by a command,
 such as another \commandf{load}
 command.  The idea of storing information is one of the ideas that
 sets the CLUI apart from the command language described in
 Section~\ref{sec:command_mode}.

 Next, \commandf{ab = load(ab, constants='ab.1')} parses the \AUTO
 constants file \filef{c.ab.1} and reads it into memory.  Note that
 \emp{changes to the file \filef{c.ab.1} after it has been loaded in
 will not be used by \AUTO unless it is loaded in again after the
 changes are made}.  

 Finally, \commandf{run(ab)} 
 (Section~\ref{sec:clui_ref_basic} in the reference)
 uses the user defined functions loaded
 by the \commandf{load(equation='ab')} command, and the \AUTO constants
 loaded by the \commandf{load(ab, constants = 'ab.1')} to run \AUTO.

 The \commandf{run} command returns a bifurcation diagram structure. It can
 be referenced using the special \commandf{\_} variable in interactive
 sessions, or assigned as \commandf{result=run(ab)}. The result
 can then be referred to in further calculations, plotted, and saved.

 Figure~\ref{exa:clui_first_example} showed two of 
 the file types that the 
 \commandf{load} command can read into memory, namely 
 the user defined function file and the \AUTO constants
 file (Section~\ref{ch:User_supplied_files}).  
 There are two other files types that can be read
 in using the \commandf{load} command, and they are
 the restart solution file (Section~\ref{ch:Output_files})
 and the {\cal HomCont} parameter
 file (Section~\ref{sec:HomCont_files}). The \commandf{load} command
 can also directly load AUTO constants.

 Note that the name given to the load
 command is not the same as the filename which is read
 in, for example \commandf{load(constants='ab.1')} reads in 
 the file \filef{c.ab.1}.  This difference is 
 a result of the automatic transformation of the
 filenames by the 
 \AUTO CLUI into the
 standard names used by \AUTO.  
 The standard filename
 transformations are shown in Table~\ref{tbl:clui_filename_translation}. 

 \begin{table}[htbp]
 \begin{center}
 \begin{tabular}{| l | l | l | l |}
 \hline
 Long name & Short name & Name entered & Transformed file name \\
 \hline
 equation  & e          & foo          &foo.f90/foo.f/foo.c \\
 \hline
 constants  & c          & foo          & c.foo \\
 \hline
 solution  & s          & foo          & s.foo \\
 \hline
 bifurcationDiagram  & b          & foo          &b.foo \\
 \hline
 diagnostics  & d          & foo          &d.foo \\
 \hline
 homcont  & h          & foo          &h.foo \\
 \hline
 \end{tabular}
 \caption[Standard \AUTO CLUI filename translations.]
 {This table shows the standard \AUTO CLUI filename
 translations.  In \filef{load} and \filef{run}
 commands either the long name or the short name may be
 used for loading the appropriate files.}
 \label{tbl:clui_filename_translation}
 \end{center}
 \end{table}

 Since the \commandf{load} command is so common, there are
 various shorthand versions of it.  First, there are short versions
 of the various arguments as shown in Table~\ref{tbl:clui_filename_translation}.
 For example, the command \commandf{load(constants='ab.1')} can 
 be shortened to \commandf{load(c='ab.1')}.
 Next, several different
 files may be loaded at once using the same \commandf{load} command.
 For example, the two commands in Figure~\ref{exa:clui_two_command}
 have the same effect as the single command in 
 Figure~\ref{exa:clui_one_command}.
 Last, you can bypass the \commandf{load} command, unless the
 intermediate result is needed, and use the \commandf{run} command
 directly on the \commandf{load} arguments, as in
 Figure~\ref{exa:clui_one_run_command}.

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 AUTO> ab = load(e='ab')
 Runner configured
 AUTO> ab = load(ab,c='ab.1)
 Runner configured
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[Loading two files individually]
 {Loading two files individually.}
 \label{exa:clui_two_command}
 \end{figure}

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 AUTO> ab = load(e='ab',c='ab.1')
 Runner configured
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[Loading two files at the same time]
 {Loading two files at the same time.}
 \label{exa:clui_one_command}
 \end{figure}

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 AUTO> runab1 = run(e='ab',c='ab.1')
 Runner configured
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[Loading two files at the same time and running]
 {Loading two files at the same time and run using them.}
 \label{exa:clui_one_run_command}
 \end{figure}

 Also, since it is common that several files will be loaded that
 have the same base name \commandf{load('ab')} performs the same 
 action as \commandf{load(e='ab', c='ab', s='ab', h='ab')}. 
 Note, for the command \commandf{load('ab')} it is not required that all
 of the files exist. Information from all existing files is used only
 if they exist, and no error message will be given for non-existing
 files. However, later \commandf{run} commands may cause \AUTO to err
 with incomplete information.

 \section{ Scripting }

 Section~\ref{sec:clui_first_example} showed commands
 being interactively entered at the \AUTO CLUI
 prompt, but since the \AUTO CLUI is based 
 on \python one has the ability to write
 scripts for performing sequences of commands
 automatically.  A \python script is very similar
 to the interactive mode shown in Section~\ref{sec:clui_first_example}
 except that the commands are placed in a file and
 read all at once.  For example, if the
 commands from Figure~\ref{exa:clui_first_example} where placed 
 into the file \filef{demo1.auto}, in the format shown in 
 Figure~\ref{exa:clui_first_script}, then the commands
 could be run all at once by typing \commandf{auto demo1.auto}.
 See Figure~\ref{exa:clui_run_first_script} for the
 full output.

 \begin{figure}[htb]
 {\small \begin{center} \begin{boxedverbatim}
 demo('ab')
 ab = load(equation='ab')
 ab = load(ab, constants='ab.1')
 run(ab)
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[First example of a \AUTO CLUI script.]
 {The commands from Figure~\ref{exa:clui_first_example}
 and they would appear in a \AUTO CLUI script file.
 The source for this script can be found in \filef{\$AUTO\_DIR/demos/python/demo1.auto}.
 }
 \label{exa:clui_first_script}
 \end{figure}

 \begin{figure}[htb]
 {\small \begin{center} \begin{boxedverbatim}
 > cat demo1.auto
 demo('ab')
 ab = load(equation='ab')
 ab = load(ab, constants='ab.1')
 run(ab)

 > auto demo1.auto 
 Copying demo ab ... done
 Runner configured
 Runner configured
 Runner configured
 gfortran -fopenmp -O -c ab.f90 -o ab.o
 gfortran -fopenmp -O ab.o -o ab.exe /home/bart/auto/07p/lib/*.o
 Starting ab ...

   BR    PT  TY  LAB    PAR(2)        L2-NORM         U(1)          U(2)     
    1     1  EP    1   8.00000E+00   0.00000E+00   0.00000E+00   0.00000E+00
    1    31  UZ    2   1.40000E+01   0.00000E+00   0.00000E+00   0.00000E+00
    1    36  UZ    3   1.50000E+01   0.00000E+00   0.00000E+00   0.00000E+00
    1    41  UZ    4   1.60000E+01   0.00000E+00   0.00000E+00   0.00000E+00
    1    46  UZ    5   1.70000E+01   0.00000E+00   0.00000E+00   0.00000E+00
    1    51  EP    6   1.80000E+01   0.00000E+00   0.00000E+00   0.00000E+00

  Total Time    0.193E-01
 ab ... done
 > 
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[Figure of running a simple \AUTO CLUI script.]
 {This Figure starts by listing the contents
 of the \filef{demo1.auto} file using the Unix
 \commandf{cat} command.  The file is then run through
 the \AUTO CLUI by typing {auto demo1.auto} 
 and the output is shown.}
 \label{exa:clui_run_first_script}
 \end{figure}


 \section{ Second Example } \label{sec:clui_complex_example}

 In Section~\ref{sec:clui_first_example} we showed a very simple
 \AUTO CLUI script, in this Section we will describe a more
 complex example, which introduces several new \AUTO CLUI
 commands as well as a basic \python construct for looping.
 We will not provide an exhaustive reference for
 the \python language, but only 
 the very basics.  For more extensive documentation we refer the
 reader to \citename{Lut:96} \citeyear{Lut:96} or the
 web page \url{http://www.python.org}.
 In this section we will describe each line of the script
 in detail, and the full text of the script is in
 Figure~\ref{exa:clui_complex_script}.

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 demo('bvp')

 bvp = run('bvp')
 branchpoints = bvp("BP")
 for solution in branchpoints:
     bp = load(solution, ISW=-1, NTST=50)
     # Compute forwards
     print "Solution label", bp["LAB"], "forwards"
     fw = run(bp)
     # Compute backwards
     print "Solution label", bp["LAB"], "backwards"
     bw = run(bp,DS='-')
     both = fw + bw
     merged = merge(both)
     bvp = bvp + merged

 bvp=relabel(bvp)
 save(bvp, 'bvp')
 plot(bvp)
 wait()
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[A complex example of a \AUTO CLUI script.]
 {This Figure shows a more complex \AUTO CLUI script.
 The source for this script can be found in \filef{\$AUTO\_DIR/demos/python/demo2.auto}.
 }
 \label{exa:clui_complex_script}
 \end{figure}

 The script begins with a section, extracted into 
 Figure~\ref{exa:clui_complex_first}, which performs a task 
 identical to that shown in Figure~\ref{exa:clui_first_example}
 except that the shorthand discussed in 
 Section~\ref{sec:clui_first_example} is used for the 
 \commandf{run} command.

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 demo('bvp')

 bvp = run('bvp')
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[The first part of the  complex \AUTO CLUI script.]
 {The first part of the  complex \AUTO CLUI script.}
 \label{exa:clui_complex_first}
 \end{figure}

 Up to this point all of the commands presented have had
 analogs in the command language discussed in 
 Section~\ref{sec:command_mode}, and the \AUTO CLUI has
 been designed in this way to make it easy for users to
 migrate from the old command language to the
 \AUTO CLUI.  The next section of the script extracted into
 Figure~\ref{exa:clui_complex_first}, introduces a new
 command, namely \commandf{branchpoints = bvp("BP")},
 which is the first command which has no analog in the 
 old command language.
 The command \commandf{bvp("BP")}, given the output variable \commandf{bvp}
 from the first run, returns a \python object which represents a list
 of all branchpoint solutions.
 Accordingly, this list is stored in the \python
 variable \commandf{branchpoints}.
 Note, variables in \python are different from those in languages
 such as {\cal C} in that their type does not have to be
 declared before they are created.

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 branchpoints = bvp("BP")
 for solution in branchpoints:
     bp = load(solution, ISW=-1, NTST=50)
     # Compute forwards
     print "Solution label", bp["LAB"], "forwards"
     fw = run(bp)
     # Compute backwards
     print "Solution label", bp["LAB"], "backwards"
     bw = run(bp,DS='-')
     both = fw + bw
     merged = merge(both)
     bvp = bvp + merged
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[The second part of the  complex \AUTO CLUI script.]
 {The second part of the  complex \AUTO CLUI script.}
 \label{exa:clui_complex_second}
 \end{figure}

 The next command, \commandf{for solution in branchpoints:} is
 the \python syntax for loops.  The \commandf{branchpoints} object
 is a list of the branch point solutions from the first run.
 The command 
 \commandf{for solution in branchpoints:} is used to loop
 over all solutions in the branchpoints variable by 
 setting the variable \commandf{solution} to
 be one of the solutions in \commandf{branchpoints}
 and then calling the rest of the code in the
 block.  

 \python differs from most other computer languages in that
 blocks of code are not defined by some delimiter, such
 as \commandf{END DO} in {\cal Fortran}, but by indentation.  
 In Figure~\ref{exa:clui_complex_script} the commands starting with
 \commandf{bvp=relabel(bvp)} are not
 part of the loop, because they are indented 
 differently.  This can be confusing first time users of \python,
 but it has the advantage that the code
 is forced to have a consistent indentation style.

 The next command in the script,
 \commandf{bp = load(solution, ISW=-1, NTST=50)}
 loads a solution with modified AUTO constants. All other constants are
 the same as they were in the first run.
 The \parf{ISW} value is changed to \parf{-1} (see
 Section~\ref{sec:ISW}), so that a branch switch is performed, and
 the \parf{NTST} value is changed to \parf{50} (see
 Section~\ref{sec:NTST}).
 Only ``in memory'' versions of the \AUTO constants are modified;
 the original file \filef{c.bvp} is \emp{not} modified.

 Some diagnostics are then printed to the screen using a standard \python
 \commandf{print} command: the label number of the branch point that
 we switch at can be found by using \commandf{bp["LAB"]}.
 In addition, as can be seen in Figure~\ref{exa:clui_complex_second},
 the \commandf{\#} character is the \python comment character.
 When the \python interpretor encounters a \commandf{\#} character
 it ignores everything from that character to the end of the line.

 We then use a \commandf{fw=run(bp)} command to perform the
 calculation of the bifurcating branch from solution \commandf{bp}.
 We print additional information and use the command
  \commandf{bw = run(bp,DS='-')} to change the
 \AUTO initial step size from positive to negative, which causes
 \AUTO to compute the bifurcating branch in the other direction
 (see Section~\ref{sec:DS}).
 This output is appended to the existing output in the
 \python variable \commandf{bvp} after some more processing.
 First the command
 \commandf{both = fw + bw} concatenates, using standard Python list
 syntax, the forwards and backwards branches. Subsequently
 \commandf{merged = merge(both)} merges the two branches into one
 continuous branch where the backwards branch is flipped.
 Finally, the command \commandf{bvp = bvp + merged} appends the
 merged branch to the existing results.

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 bvp=relabel(bvp)
 save(bvp, 'bvp')
 plot(bvp)
 wait()
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[The third part of the  complex \AUTO CLUI script.]
 {The third part of the  complex \AUTO CLUI script.}
 \label{exa:clui_complex_third}
 \end{figure}

 The last section of the script, extracted into 
 Figure~\ref{exa:clui_complex_third}, 
 does some postprocessing and
 plotting. First, the command \commandf{bvp=relabel(bvp)} relabels
 so all solutions in the \commandf{bvp} object have unique labels
 starting at 1. The command \commandf{save(bvp,'bvp')}
 (Section~\ref{sec:clui_ref_basic} in the reference)
 saves the results of the \AUTO runs into files using
 the base name \filef{bvp} and the filename extensions in
 Table~\ref{tbl:clui_filename_translation}.  For example,
 in this case the bifurcation diagram will be saved as \filef{b.bvp}, 
 the solution will be saved as \filef{s.bvp}, and  
 the diagnostics will be saved as \filef{d.bvp}.

 Now that the section of script shown in 
 Figure~\ref{exa:clui_complex_third} has finished computing the
 bifurcation diagram, the command \commandf{plot(bvp)}
 brings up a plotting window 
 (Section~\ref{sec:clui_ref_plot} in the reference),
 and the command \commandf{wait()} causes the \AUTO CLUI
 to wait for input.  You may now exit the \AUTO CLUI
 by pressing any key in the window in which you started
 the \AUTO CLUI.

 For convenience, some of these commands have shorter forms.
 For instance, the \commandf{load}, \commandf{run}, \commandf{merge},
 \commandf{relabel}, \commandf{save}, and \commandf{plot} commands
 have the shorter forms \commandf{ld}, \commandf{r}, \commandf{mb},
 \commandf{rl}, \commandf{sv}, and \commandf{pl}, respectively.
 All algebraic and functional expressions can be combined in the
 usual way. Combining these techniques, a shorter version of the complex \AUTO
  CLUI script is given in Figure~\ref{exa:clui_complex_fourth}.

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 demo('bvp')

 bvp=r('bvp')
 for solution in bvp('BP'):
     bp = ld(solution,NTST=50,ISW=-1)
     # Compute forwards and backwards
     bvp = bvp + mb(r(bp)+r(bp,DS='-'))

 bvp=rl(bvp)
 pl(bvp)
 sv(bvp,'bvp')
 wait()
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[A complex example of a \AUTO CLUI script.]
 {This Figure shows a shorter version of the more complex \AUTO CLUI
   script given above.
 The source for this script can be found in \filef{\$AUTO\_DIR/demos/python/demo3.auto}.
 }
 \label{exa:clui_complex_fourth}
 \end{figure}

 Even shorter forms are possible to save you typing using features
 borrowed from ipython, both in \commandf{auto -i} and in plain
 \commandf{auto}. Those forms use auto-parentheses and auto-quotes:
 for a command that does not assign to a variable you can skip the
 parentheses, and by using a ``,'' on the first character of a line
 you force all parameters to be quoted. For example, you can just
 type \commandf{pl bvp} to plot the bifurcation diagram and solutions
 in the object \commandf{bvp}.
 Beware that these extra short forms are only possible in
 normal auto scripts and at the AUTO CLUI prompt, and only if they
 start in the first column, but not in the
 ``expert'' scripts described in the next section.
 The even shorter version of the complex \AUTO
 CLUI script is given in Figure~\ref{exa:clui_complex_fifth}.
 It should be clear that these super-short forms save you typing
 at the command prompt but do not help readability in scripts.
 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 ,demo bvp

 bvp=r('bvp')
 for solution in bvp('BP'):
     bp = ld(solution,NTST=50,ISW=-1)
     # Compute forwards and backwards
     bvp = bvp + mb(r(bp)+r(bp,DS='-'))

 bvp=rl(bvp)
 pl bvp
 sv bvp, 'bvp'
 wait
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[Another complex example of a \AUTO CLUI script.]
 {This Figure shows an even shorter version of the more complex \AUTO CLUI
   script given above.
 The source for this script can be found in \filef{\$AUTO\_DIR/demos/python/demo4.auto}.
 }
 \label{exa:clui_complex_fifth}
 \end{figure}



 \section{ Extending the \AUTO CLUI } \label{sec:clui_extending}

 The code in Figure~\ref{exa:clui_complex_script}
 performed a very useful and common procedure, it started an \AUTO
 calculation and performed additional continuations
 at every point which \AUTO detected as a bifurcation.
 Unfortunately, the script as written can only be used
 for the \filef{bvp} demo.  In this section we will 
 generalize the script in Figure~\ref{exa:clui_complex_script}
 for use with any demo, and demonstrate how it
 can be imported back into the interactive
 mode to create a new command
 for the \AUTO CLUI.  Several examples of such
 ``expert'' scripts can be found in \filef{auto/07p/demos/python/n-body}.

 Just as loops and conditionals can be used in \python,
 one can also define functions.  For example,
 Figure~\ref{exa:clui_complex_function} is a
 functional version of script from 
 Figure~\ref{exa:clui_complex_script}.
 The changes are actually quite minor.  
 The first line, \commandf{from auto import *},
 includes the definitions of the \AUTO CLUI commands,
 and must be included in all \AUTO CLUI scripts
 which define functions.
 The next line, 
 \commandf{def myRun(demoname):},
 begins the function definition, and 
 creates a function named \commandf{myRun} which
 takes one argument \commandf{demoname}.  The
 rest of the script is the same except that it
 has been indented to indicate that it is
 part of the function definition, all occurrences
 of string \commandf{'bvp'} have been replaced
 with the variable \commandf{demoname}, and the variable
 \commandf{bvp} was replaced by the variable \commandf{r}.
 Finally we have added a line \commandf{myRun('bvp')}
 which actually calls the function we have 
 created and runs the same computation as
 the original script.

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 from auto import *

 def myRun(demoname):

     demo(demoname)

     r = run(demoname)
     branchpoints = r("BP")
     for solution in branchpoints:
         bp = load(solution, ISW=-1, NTST=50)
         # Compute forwards
         print "Solution label", bp["LAB"], "forwards"
         fw = run(bp)
         # Compute backwards
         print "Solution label", bp["LAB"], "backwards"
         bw = run(bp,DS='-')
         both = fw + bw
         merged = merge(both)
         r = r + merged

     r=relabel(r)
     save(r, demoname)
     plot(r)
     wait()

 myRun('bvp')

 \end{boxedverbatim}
 \end{center} 
 }
 \caption[A complex \AUTO CLUI script as a function.]
 {This Figure shows a complex \AUTO CLUI script
 written as a function.
 The source for this script can be found in \filef{\$AUTO\_DIR/demos/python/userScript.xauto}.
 }
 \label{exa:clui_complex_function}
 \end{figure}

 While the script in Figure~\ref{exa:clui_complex_function} is 
 only slightly different then the one showed in 
 Figure~\ref{exa:clui_complex_script} it is much more powerful.
 Not only can it be used as a script for running any demo
 by modifying the last line, it can be read back into
 the interactive mode of the \AUTO CLUI and
 used to create a new command, 
 as in Figure~\ref{exa:clui_complex_interactive}.
 First, we create a file called \filef{userScript.py}
 which contains the script from 
 Figure~\ref{exa:clui_complex_function}, with
 one minor modification.  We want the function only
 to run when we use it interactively, not when
 the file \filef{userScript.py} is read in, so we
 remove the last line where the function is called.
 We start the \AUTO CLUI with the Unix command
 \commandf{auto}, and once the \AUTO CLUI is running
 we use the command \commandf{from userScript import *},
 to import the file \filef{userScript.py} into the
 \AUTO CLUI.  The \commandf{import} command makes
 all functions in that file available for
 our use (in this case \commandf{myRun} is the only 
 one).  It is important to note that 
 \commandf{from userScript import *} does \emp{not}
 use the \filef{.py} extension on the file name. 
 After importing our new function, we may use it
 just like any other function in the \AUTO
 CLUI, for example by typing \commandf{myRun('bvp')}.

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 > cp \$AUTO\_DIR/python/demo/userScript.py .
 > ls
 userScript.py
 > cat userScript.py
 # This is an example script for the AUTO07p command line user
 # interface.  See the "Command Line User Interface" chapter in the
 # manual for more details.
 from auto import *

 def myRun(demoname):

     demo(demoname)

     r = run(demoname)
     branchpoints = r("BP")
     for solution in branchpoints:
         bp = load(solution, ISW=-1, NTST=50)
         # Compute forwards
         print "Solution label", bp["LAB"], "forwards"
         fw = run(bp)
         # Compute backwards
         print "Solution label", bp["LAB"], "backwards"
         bw = run(bp,DS='-')
         both = fw + bw
         merged = merge(both)
         r = r + merged

     r=relabel(r)
     save(r, demoname)
     plot(r)
     wait()

 > auto
 Python 2.5.2 (r252:60911, Nov 14 2008, 19:46:32) 
 [GCC 4.3.2] on linux2
 Type "help", "copyright", "credits" or "license" for more information.
 (AUTOInteractiveConsole)
 AUTO> from userScript import *
 AUTO> myRun('bvp')
 ...
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[An example of using a user created function interactively.]
 {This Figure shows the functional version of the
  \AUTO CLUI from Figure~\ref{exa:clui_complex_function} being 
 used as an extension to the \AUTO CLUI.  The source
 code for this script can be found in 
 \filef{\$AUTO\_DIR/python/demo/userScript.py }}
 \label{exa:clui_complex_interactive}
 \end{figure}

 \section{ Bifurcation Diagram Objects}
 The \commandf{run} and \commandf{loadbd} commands (see
 Section~\ref{sec:clui_ref_basic} in the reference for details)
 return a ~\python structure which we refer to as a \emph{bifurcation
 diagram object}. It represents the information that is also stored
 in \AUTO's output files (\filef{fort.7}, \filef{fort.8},
 and \filef{fort.9}, or \filef{b.*}, \filef{s.*}, and \filef{d.*}),
 and in \AUTO's constant files.
 For example, the command \commandf{loadbd('ab')}
 returns an object corresponding to the files \filef{b.ab},
 \filef{s.ab}, and \filef{d.ab}.
 (if you are using the standard
 filename translations from Table~\ref{tbl:clui_filename_translation}).
 The command \commandf{run('ab')} returns
 an object corresponding to the output of the run.

 The bifurcation diagram object encapsulates all this information in
 an easy to use form.
 This object is a list of all of the branches in the appropriate
 bifurcation diagram file, and each branch behaves like an array
 (a PyDSTool Pointset subclass, to be precise). This array can be
 viewed as a list of all of the points in the appropriate
 bifurcation diagram file, and each point is a \python
 dictionary with entries for each piece of data for the point.
 For example, the sequence of commands
 in Figure~\ref{exa:clui parse diagram}, prints out the
 label of the first point of a branch in a bifurcation diagram.
 The query-able parts of the object are listed in
 Table~\ref{tbl:clui parse diagram}.

 The individual elements of the array may be accessed 
 in a number of ways: by index of the point using the
 \commandf{[]} syntax, a column using \commandf{['columnname']} syntax,
 or by label number or type name plus one-based index using the
 \commandf{()} syntax.  For example, assume that the parsed object is contained
 in a variable \commandf{data}, and the first branch is in a variable
 \commandf{br=data[0]}.
 The first point may then be accessed 
 using the command \commandf{br[0]}, while the column
 with label \parf{PAR(1)} may be accessed using the command
 \commandf{br['PAR(1)']}.
 The point with label \commandf{57} may be accessed using the command
 \commandf{br(57)}, and the second Hopf bifurcation point using
 the command \commandf{br('HB2')}
 Using the \commandf{()} syntax you can also obtain new lists of
 points: \commandf{br('HB')} gives a list of all Hopf bifurcation
 points, \commandf{br([1,4])} gives the points with labels 1 and 4,
 and \commandf{br(['UZ',4])} gives all user defined points and label
 4.
 
 The \commandf{['columnname']} syntax is especially useful for
 plotting, as is illustrated in Figure~\ref{exa:bdplot}. Here the
 \python package matplotlib is directly used to plot a branch.
 Of course, the command \commandf{plot} may also be used, but
 sometimes more control may be needed.

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 AUTO> demo('lrz')
 Copying demo lrz ... done
 Runner configured
 AUTO> data=run('lrz')
 gfortran -fopenmp -O -c lrz.f -o lrz.o
 gfortran -fopenmp -O lrz.o -o lrz.exe /home/bart/auto/07p/lib/*.o
 Starting lrz ...
(...)
lrz ... done
 AUTO> print data

  BR    PT  TY  LAB    PAR(1)        L2-NORM         U(1)          U(2)          U(3)     
   1     1  EP    1   0.00000E+00   0.00000E+00   0.00000E+00   0.00000E+00   0.00000E+00
   1     5  BP    2   1.00000E+00   0.00000E+00   0.00000E+00   0.00000E+00   0.00000E+00
   1    13  EP    3   3.16000E+01   0.00000E+00   0.00000E+00   0.00000E+00   0.00000E+00

  BR    PT  TY  LAB    PAR(1)        L2-NORM         U(1)          U(2)          U(3)     
   2    42  HB    4   2.47368E+01   2.62685E+01   7.95602E+00   7.95602E+00   2.37368E+01
   2    45  EP    5   3.26008E+01   3.41635E+01   9.17980E+00   9.17980E+00   3.16008E+01

  BR    PT  TY  LAB    PAR(1)        L2-NORM         U(1)          U(2)          U(3)     
   2    42  HB    6   2.47368E+01   2.62685E+01  -7.95602E+00  -7.95602E+00   2.37368E+01
   2    45  EP    7   3.26008E+01   3.41635E+01  -9.17980E+00  -9.17980E+00   3.16008E+01

 AUTO> br=data[1]
 AUTO> print br
  BR    PT  TY  LAB    PAR(1)        L2-NORM         U(1)          U(2)          U(3)     
   2    42  HB    4   2.47368E+01   2.62685E+01   7.95602E+00   7.95602E+00   2.37368E+01
   2    45  EP    5   3.26008E+01   3.41635E+01   9.17980E+00   9.17980E+00   3.16008E+01
 AUTO> print br[0]
 {'TY number': 0, 'PT': -1, 'index': 0, 'section': 0, 'LAB': 0, 'BR': 2,
  'data': [0.99999994000000003, 0.0, 0.0, 0.0, 0.0], 'TY name': 'No Label'}
 AUTO> print br['PAR(1)']
 [  0.99999994   1.001875     1.00747645   1.01786791   1.03426011
    1.05801491   1.08738983   1.12195713   1.16544975   1.21923418
(...)
   13.69994168  15.15715248  16.76398367  18.53533839  20.48761501
   22.63885621  24.73684367  27.10974373  29.72303281  32.60076345]
 AUTO> print br(4)
 {'TY number': 3, 'PT': 42, 'index': 41, 'section': 0, 'LAB': 4, 'BR': 2, 
  'data': [24.736843667999999, 26.268502943000001, 7.9560197197999996,
   7.9560197197999996, 23.736843667999999], 'TY name': 'HB'}
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[An example of processing a bifurcation diagram of a run.]
 {This figure shows an example of parsing a bifurcation diagram.
 First the demo involving the Lorenz equations named 'lrz' is copied
 and we perform its first run. We then print
 the result, its second branch, the first point on this branch,
 the column corresponding to 'PAR(1)', and the point with
 label 4 on this branch.
 }
 \label{exa:clui parse diagram}
 \end{figure}

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 AUTO> import pylab
 AUTO> pylab.plot(br['PAR(1)'],br['U(1)'])
 [<matplotlib.lines.Line2D object at 0x9b1356c>]
 AUTO> pylab.show()
 \end{boxedverbatim}
 \end{center} 
 }
 \caption{Following the example in Figure~\ref{exa:clui parse diagram} 
  we can plot a subset of the bifurcation diagram, that is, the second
  branch, directly using matplotlib.}
 \label{exa:bdplot}
 \end{figure}

 \begin{table}[htbp]
 \begin{center}
 \begin{tabular}{| l | l |}
 \hline
 Query string & Meaning \\
 \hline
 TY name &  The short name for the solution type (see Table~\ref{tbl:clui type translation}). \\
 \hline
 TY number &  The number of the solution type (see Table~\ref{tbl:clui type translation}). \\
 \hline
 BR  &  The branch number. \\
 \hline
 PT  &  The point number. \\
 \hline
 LAB  &  The solution label, if any. \\
 \hline
 section  &  A unique identifier for each branch in a file with multiple branches. \\
 \hline
 data  &  An array which contains the \AUTO output. \\
 \hline
 \end{tabular}
 \caption[Contents of a bifurcation diagram object.]
 {This table shows the strings that can be used to
 query a bifurcation diagram object and their
 meanings.}
 \label{tbl:clui parse diagram}
 \end{center}
 \end{table}

 \begin{table}[htbp]
 \begin{center}
 \begin{tabular}{| l | l | l |}
 \hline
 Type & Short Name & Number \\
 \hline
 No Label & No Label &  \\
 \hline
 Branch point (algebraic problem) & BP & 1 \\
 \hline
 Fold (algebraic problem) & LP & 2 \\
 \hline
 Hopf bifurcation (algebraic problem) & HB & 3 \\
 \hline
 Regular point (every NPR steps) & RG & 4 \\
 \hline
 User requested point & UZ & -4 \\
 \hline
 Fold (ODE) & LP & 5 \\
 \hline
 Bifurcation point (ODE) & BP & 6 \\
 \hline
 Period doubling bifurcation (ODE) & PD & 7 \\
 \hline
 Bifurcation to invariant torus (ODE) & TR & 8 \\
 \hline
 Normal begin or end & EP & 9 \\
 \hline
 Abnormal termination & MX & -9 \\
 \hline
 \end{tabular}
 \caption[Type translations.]
 {This table shows the various types of points
 that can be in solution and bifurcation diagram
 files, with their short names and numbers.}
 \label{tbl:clui type translation}
 \end{center}
 \end{table}

 \begin{table}[htbp]
 \begin{center}
 \begin{tabular}{| l | l | l |}
 \hline
 Type & Short Name & Number \\
\hline
 Bogdanov-Takens bifurcation (algebraic problem) & BT & -21, -31 \\
 \hline
 Cusp (algebraic problem) & CP & -22 \\
\hline
 Generalized Hopf bifurcation (algebraic problem) & GH & -32 \\
\hline
 Zero-Hopf bifurcation (algebraic problem) & ZH & -13, -23, -33 \\
\hline
 1:1 Resonance bifurcation (ODE, maps) & R1 & -25, -55, -85 \\
\hline
 1:2 Resonance bifurcation (ODE, maps) & R2 & -76, -86 \\
\hline
 1:3 Resonance bifurcation (ODE, maps) & R3 & -87 \\
\hline
 1:4 Resonance bifurcation (ODE, maps) & R4 & -88 \\
\hline
 Fold-flip bifurcation (maps) & LPD & 28, 78 \\
\hline
 Fold-torus bifurcation (maps) & LTR & 23, 83 \\
\hline
 Flip-torus bifurcation (maps) & PTR & 77, 87 \\
\hline
 Torus-torus bifurcation (maps) & TTR & 88 \\
\hline
 \end{tabular}
 \caption[Codimension-two type translations.]
 {This table shows the various types of codimension-two points
 as in Table~\ref{tbl:clui type translation}. The absolute value
 of the number divided by 10 gives the type of the branch on which
 the codimension-two bifurcation occurs.}
 \label{tbl:clui codim2 type translation}
 \end{center}
 \end{table}

 Additionally three special keys can be used to query a branch: use
 \commandf{br['BR']} to obtain the branch number, \commandf{br['TY']}
 for the branch type, and \commandf{br['TY number']} for the
 corresponding number. These keys are also useful to change
 bifurcation diagram files, as is illustrated in
 Figure~\ref{exa:clui branch management}. Note that you can
 interactively change branch numbers, solution numbers and delete
 branches and solutions using the \commandf{@lb} command
 (see Chapter~\ref{sec:command_mode}).

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 # get and run the ab demo
 demo('ab')
 auto('ab.auto')
 # load data from b.ab, s.ab, and d.ab
 ab = loadbd('ab')
 # change the branch number to either 1 or 2 depending on IPS
 for branch in ab:
     branch['BR'] = branch.c['IPS']
 # delete the last branch
 del ab[-1]
 # subtract the first branch from all other branches with respect to PAR(1)
 ab = subtract(ab, ab, 'PAR(1)')
 # plot the branches, coloring by branch number
 plot(ab, coloring_method='branch', color_list='black red')
 wait()
 # save data to b.abnew, s.abnew, and d.abnew
 save(ab, 'abnew')
 \end{boxedverbatim}
 \end{center} 
 }
 \caption{This example shows how to change branch numbers and delete a
 branch in the 'ab' demo output file. Using
 the \parf{coloring\_method='branch'} setting you can then give one
 color to all branches of fixed points and one other color to all
 branches of periodic orbits.
 The source for this script can be found in
 \filef{\$AUTO\_DIR/demos/python/branches.auto}.}
 \label{exa:clui branch management}
 \end{figure}

 \subsection{ Solutions}
 You can also obtain solutions from a bifurcation diagram structure,
 by using the \commandf{()} syntax directly on the diagram instead of
 on individual branches.
 For example, in the above example the command
 \commandf{s=data()}
 returns an object which encapsulates
 all solutions in a easy to use form.

 The object returned in this way
 is a list of all of the solutions in the appropriate
 bifurcation solution file, and each solution is a Python
 dictionary with entries for each  piece of
 data for the solution.  For example, the sequence of commands
 in Figure~\ref{exa:clui parse solution}, prints out the
 label of the first solution in a bifurcation solution.
 The query-able parts of the object are listed in
 Table~\ref{tbl:clui parse solution}.

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim}
 AUTO> s=data()
 AUTO> sol=s[3] #or s(4), data(4), s('HB1'), or data('HB1')
 AUTO> print sol 
   BR    PT  TY  LAB ISW NTST NCOL NDIM IPS IPRIV
    2    42  HB    4   1    1    0    3   1     0
 Pointset lrz (parameterized)
 Independent variable:
 t:  [ 0.]
 Coordinates:
 U(1):  [ 7.95601972]
 U(2):  [ 7.95601972]
 U(3):  [ 23.73684367]
 Labels by index: Empty
 Active ICP: [1]
 rldot: [0.69738311435]
 udotps: Pointset lrz (non-parameterized)
 Coordinates:
 UDOT(1):  [ 0.11686228]
 UDOT(2):  [ 0.11686228]
 UDOT(3):  [ 0.69738311]
 Labels by index: Empty
 PAR(1:5):      2.4736843668E+01   2.6666666667E+00   1.0000000000E+01   0   0
 PAR(6:10):     0.0000000000E+00   0.0000000000E+00   0.0000000000E+00   0   0
 PAR(11:11):    6.5283032822E-01
 AUTO> print sol['LAB']
 4
 AUTO> print sol['L2-NORM'] # or sol.b['L2-NORM']
 26.268502943
 AUTO> sol[0]
 {'u': [7.9560197197999996, 7.9560197197999996, 23.736843667999999],
   't': 0.0, 'u dot': [0.11686227712, 0.11686227712, 0.69738311435]}
 AUTO> sol['t']
 array([ 0.])
 AUTO> sol['U(1)']
 array([ 7.95601972])
 AUTO> sol.PAR(1) # or sol['PAR(1)']
 24.736843667999999
 AUTO> pylab.plot(sol['U(1)'],sol['U(2)'],'+')
 [<matplotlib.lines.Line2D object at 0x9c3348c>]
 AUTO> pylab.show()
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[An example of parsing solutions.]
 {This figure shows an example of parsing solutions.
 The first command, \commandf{s=data()}, extracts a list of all solutions
 stored in the bifurcation diagram object \commandf{data} from the
 'lrz' demo in Figure~\ref{exa:clui parse diagram}
 and puts it into the variable \commandf{s}.
 The command \commandf{sol=s[3]} obtains the fourth solution.
 Next, \commandf{print sol} displays it.
 The last commands illustrate how to extract components from
 this fourth solution: its label, its first point, its time array, its first
 coordinate array, its first parameter, and a plot of the first two
 coordinates.
 }
 \label{exa:clui parse solution}
 \end{figure}

 \begin{table}[htbp]
 \begin{center}
 \begin{tabular}{| l | l |}
 \hline
 Query string & Meaning \\
 \hline
 data  & \begin{minipage}{4in} \smallskip An array which contains the
 \AUTO output. Each array entry is a Python dictionary with a scalar
 entry 't' denoting time,
 and sub-arrays for the solution vector 'u' and the solution
 direction vector 'u dot'.\\
 Other syntax: \commandf{s[0]}, \commandf{s['t']}, \commandf{s['U(1)']}.
  \smallskip \end{minipage} \\
 \hline
 BR & \begin{minipage}{4in} \smallskip The number of the branch to which the solution belongs. \smallskip \end{minipage} \\ 
 \hline
 IPRIV & \begin{minipage}{4in} \smallskip A private field for use by
   toolboxes. \smallskip \end{minipage} \\ 
 \hline
 IPS & \begin{minipage}{4in} \smallskip The user-specified problem type.  See Section~\ref{sec:IPS}. \smallskip \end{minipage} \\ 
 \hline
 ISW & \begin{minipage}{4in} \smallskip  The ISW value used to start the calculation.  See Section~\ref{sec:ISW}. \smallskip \end{minipage} \\ 
 \hline
 LAB & \begin{minipage}{4in} \smallskip The label of the solution.   \smallskip \end{minipage} \\ 
 \hline
 NCOL & \begin{minipage}{4in} \smallskip The number of collocation points used to compute the solution.  See Section~\ref{sec:NCOL}. \smallskip \end{minipage} \\ 
 \hline
 NDIM & \begin{minipage}{4in} \smallskip The user-specified number of dimensions. See Section~\ref{sec:NDIM}. \smallskip \end{minipage} \\ 
 \hline
 NTST & \begin{minipage}{4in} \smallskip The number of mesh intervals used to compute the solution.  See Section~\ref{sec:NTST}. \smallskip \end{minipage} \\ 
 \hline
 Parameters & \begin{minipage}{4in} \smallskip The value of all of the parameters for the solution. \smallskip \end{minipage} \\ 
 parameters & \begin{minipage}{4in} \smallskip 'p' and 'parameters' are aliases.\end{minipage} \\ 
 p & \begin{minipage}{4in} \smallskip Other syntax: \commandf{s.PAR(1)}, \commandf{s['PAR(1)']} \smallskip \end{minipage} \\ 
 \hline
 PT & \begin{minipage}{4in} \smallskip The number of the point in the given branch.  \smallskip \end{minipage} \\  
 \hline
 TY & \begin{minipage}{4in} \smallskip A short string which describes the type of the solution (see Table~\ref{tbl:clui type translation}). \smallskip \end{minipage} \\  
 \hline
 TY number & \begin{minipage}{4in} \smallskip A number which describes the type of the solution (see Table~\ref{tbl:clui type translation}).  \smallskip \end{minipage} \\  
 \hline
 Active ICP & \begin{minipage}{4in} \smallskip
 The values of the (one-based) indices of the free parameters.
 \smallskip \end{minipage} \\  
 \hline
 rldot & \begin{minipage}{4in} \smallskip The values
 of the parameter direction vector.\smallskip \end{minipage} \\  
 \hline
 \end{tabular}
 \caption[Contents of a solution object.]
 {This table shows the strings that can be used to
 query a solution object and their
 meanings.}
 \label{tbl:clui parse solution}
 \end{center}
 \end{table}

 The individual elements of the list may, again, be accessed 
 in two ways, either by the index of the solution using the
 \commandf{[]} syntax or by label number or type name using the
 \commandf{()} syntax.  For example, assume that the parsed object is contained
 in a variable \commandf{s=data()}.
 The first solution may be accessed 
 using the command \commandf{s[0]}, while the solution with
 label \commandf{57} may be accessed using the command \commandf{s(57)}.

 Individual solutions can be also be obtained directly from the
 bifurcation diagram object \commandf{data} in the same way as for
 individual points above, by using \commandf{s=data(label)}.
 For example, the solution with label \commandf{57} may be accessed
 using the command
 \commandf{data(57)}, and the second Hopf bifurcation solution using
 the command \commandf{data('HB2')}.
 All individual solutions can then be used as a starting point for a new run.

 Similarly, using the \commandf{()} syntax you can also obtain new lists of
 solutions: \commandf{data('HB')} gives a list of all Hopf bifurcation
 solutions, \commandf{data([1,4])} gives the solutions with labels 1 and 4,
 and \commandf{data(['UZ',4])} gives all user defined solutions and
 label 4. A for loop can then iterate through the list and provide new
 starting solutions.

 Solutions can be deleted using the commands \commandf{dlb},
 \commandf{dsp}, \commandf{klb}, and \commandf{ksp}, described in
 the reference, Section~\ref{sec:clui_ref_filemaint}. The command
 \commandf{relabel}, as described before, gives each solution a unique
 label starting at 1. Finally, you can change individual solution
 labels using the \commandf{relabel} \emph{method}:
 \commandf{data.relabel(9, 57)} relabels label 9 to label 57, making
 sure that the label changes both in the bifurcation diagram and in
 the solution.

 \subsection{Summary and reference}
 We have defined the following objects:
 \begin{description}
   \item[Bifurcation diagram object]:
    \commandf{bd=run(...)}, \commandf{bd=loadbd(...)}.
   \item[Branch]:
    \commandf{bd[0], bd[1], bd[2], ...}.
   \item[Branch AUTO constants]:
    \commandf{bd[0].c, bd[1].c, bd[2].c, ...}.\\
    \commandf{bd.c} refers to \commandf{bd[0].c}.
   \item[Branch column]:
    \commandf{bd['PAR(1')], bd[0]['PAR(1)'], bd[1]['L2-NORM'], ...}.\\
    Here \commandf{bd['PAR(1)']} is a shortcut for \commandf{bd[0]['PAR(1)']}.
   \item[Point]:
    \commandf{bd[0][0], bd[1](5), bd[1]('UZ1'), bd(1).b, bd('UZ1').b, ...}.
   \item[Point list]:
    \commandf{bd[0]('UZ'), bd[0]([1,2]), bd[0](['UZ','HB1',7]), ...}.
   \item[Solution]:
    \commandf{bd(5), bd('UZ1'), bd()[0], ...}.
   \item[Solution list]:
    \commandf{s=bd(), s('UZ'), bd('UZ'), bd([1,2]), bd(['UZ','HB1',7]), ...}.
   \item[Solution column]:
    \commandf{bd('UZ1')['t'], bd('UZ1')['U(1)'], ...}.
   \item[Solution measures]:
    \commandf{bd('UZ1')['L2-NORM'], ...}.\\
    This example is a shortcut for \commandf{bd('UZ1').b['L2-NORM']}: here you
    can use any column name from the bifurcation diagram.
   \item[Solution point]:
    \commandf{bd('UZ1')(0), bd('UZ1')[0], ...}.\\
    Here the \commandf{bd('UZ1')(t)} notation gives the point at
    time \commandf{t}.
   \item[Solution AUTO constants]:
    \commandf{bd(5).c, bd('UZ1').c, bd()[0].c, ...}.\\
    These constants are copied from the corresponding branch
    constants, removing the constants \parf{IRS}, \parf{PAR}, \parf{U},
    \parf{sv}, \parf{s}, and \parf{dat}, because those constants need
    to change between runs. The AUTO constant
    \parf{IRS} is automatically set to the solution label.
 \end{description}

 \section{ Importing data from Python or external tools.} \label{sec:clui_importing}
 A solution can be created from a Python list or Numerical Python
 array using the \commandf{load} command. The syntax is slightly
 different depending on whether you create a point or an orbit.

 Use \commandf{ s = load(u,PAR=p)} where \commandf{u} is a Python list
 or a numpy array representing a solution. For a point
 such an array is just the point itself, for example,
 \commandf{u = [x, y, z]} or
 \commandf{u = [0, 0, 0]}. For an orbit such an array must be given
 column-wise, as \commandf{u = [[t0, ..., tn], [x0, ..., xn], [y0,
   ..., yn], ...]}.
 The \commandf{PAR=p} keyword argument takes a dictionary \commandf{p}
 as described in Section~\ref{sec:PAR}, for instance, \commandf{PAR=\{1:5.0,
 2:0.0\}} to set \parf{PAR(1)=5.0} and \parf{PAR(2)=0.0}.

 You can check your new solution using the command \commandf{print s}.

 An external orbit from an ASCII file can be directly imported by
 AUTO via the \parf{dat} AUTO constant, see Section~\ref{sec:dat}.

 \section{ Exporting output data for use by Python or external
   visualization tools.} \label{sec:clui_exporting}

 The bifurcation and solution file classes have three methods that are 
 particularily useful for creating data which can be used in other
 programs.  First, there is a method called \commandf{toArray} which
 takes a bifurcation diagram or solution and
 returns a Python array (a list of lists). Second, the method
 \commandf{toarray} returns a Numerical Python (numpy) array,
 which works for
 branches, points and solutions (but not for lists of branches).
 Third, there is a method called
 \commandf{writeRawFilename} which will create a standard ASCII file
 which contains the bifurcation diagram or the solution. 
 In the solution ASCII file, the first element of each row will be
 the 't' value and the following elements will be the
 values of the components at that 't' value. Such ASCII files
 can be readily parsed and plotted by external tools such as
 Gnuplot and MATLAB.

 For example, we assume
 that a bifurcation diagram object is contained in a variable
 \commandf{bd}, for instance, using \commandf{bd=loadbd('ab')}.  If
 one wanted to have the bifurcation diagram returned as a Python list
 one would type \commandf{bd.toArray()}.  Similarily, if one wanted
 to write out the bifurcation diagram to the file \commandf{outputfile}
 one would type \commandf{bd.writeRawFilename('outputfile')}.

 To get the solution with label \commandf{57} returned as a numpy
 array one would type \commandf{bd(57).toarray()}.
 Similarily, if one wanted to write out the solution
 to the file \commandf{outputfile} one would type
 \commandf{bd(57).writeRawFilename('outputfile')}.

 \section{ The \filef{.autorc} or \filef{autorc} File }

 Much of the default behavior of the \AUTO CLUI
 can be controlled by the \filef{.autorc} file.
 The \filef{.autorc} file can exist in
 either the main \AUTO directory, the users
 home directory, or the current directory. In the current directory
 it can also have the name \filef{autorc}, that is, without the dot.
 For any
 option which is defined in more then one file, 
 the \filef{.autorc} file
 in the current directory (if it exists) takes precedence, 
 followed by the \filef{.autorc} file
 in the users home directory (if it exists), and then the
 \filef{.autorc} file in the main \AUTO directory.  Hence, 
 options may be defined on either a per directory, per
 user, or global basis.  

 The first section of the \filef{.autorc} file
 begins with the line \commandf{[AUTO\_command\_aliases]}
 and this section defines short names, or aliases,
 for the \AUTO CLUI commands.  
 Each line thereafter is a definition of
 a command, similiar to 
 \commandf{branchPoint     =commandQueryBranchPoint}.
 The right hand side of the assignment
 is the internal \AUTO CLUI name for the command,
 while the left hand side is the desired alias.  
 Aliases and
 internal names may be used interchangably, but the
 intention is that the aliases will be more commonly
 used.  A default set of aliases is provided, and
 these aliases will be used in the examples in the
 rest of this Chapter.  The default aliases
 are listed in the reference in Section~\ref{sec:clui reference}.

 %FIXME:  Fix the documentation here
 {\em NOTE:  Defaults for the plotting tool may be included in
 the .autorc file as well.}

 \section{ Plotting Tool}\label{clui:plotting}

 The plotting tool can be run by using the command
 \commandf{plot(bd)} to plot a bifurcation diagram object \parf{bd}
 after a calculation has been run, or using the command
 \commandf{plot()} to plot the files \filef{fort.7} and \filef{fort.8},
 or using the command \commandf{plot('foo')} to plote the data in the
 files \filef{s.foo} and \filef{b.foo}.  

 The menu bar provides two buttons.  The \commandf{File}
 button brings up a menu which allows the user to save
 the current plot as a Postscript file or
 to quit the plotting tool.
 The \commandf{Options} button allows the plotter
 configuration options to be modified.
 The available options are decribed in
 Table~\ref{tbl:clui plotter specific options}.  In addition, the options can 
 be set and figures can be saved from within the CLUI.  For example,
 the set of commands in Figure~\ref{exa:plotter_example} shows how to
 create a plot, change its background color to black, and save it.  The
 demo script \filef{auto/07p/demo/python/plotter.py} contains several
 examples of changing options in plotters. 
 The special argument 
 \commandf{hide=True} to \commandf{plot} does not produce an on-screen
 plot, which is useful for quick automatic generation of saved figure files.

 If you are using matplotlib, then you will find seven icons that allow
 you to use various zoom functions: a home button to go back to the
 original plot, back and forward buttons to go back and forwards
 between zooms, a button to select pan/zoom mode, a button to select
 rectangular zoom mode, a button to which brings up sliders that
 adjust margins, and a floppy disk button that you can use
 to save the plot to a file. 
 In ``zoom to rect'' mode, the left mouse button may be held down to create
 a box in the plot.  When the left button is released the plot will
 zoom to the selected portion of the diagram. Similarly, the right
 mouse button can be used to zoom out. In ``pan/zoom'' mode, dragging
 with the left mouse button pressed pans (shifts) the graph, whereas
 dragging with the right mouse button zooms in and out.

 If you are \emph{not} using matplotlib, then
 pressing the right mouse button in the plotting window brings
 up a menu of buttons which control several aspects
 of the plotting window.  The top two toggle buttons
 control what function the left button performs.  
 The \commandf{print value} button causes the
 left button to print out the numerical value underneath
 the pointer when it is clicked.
 When \commandf{zoom} button is checked the left
 mouse button may be held down to create
 a box in the plot.  When the left button
 is released the plot will zoom to the selected
 portion of the diagram.
 The \commandf{unzoom} button returns the
 diagram to the default zoom. 
 The \commandf{Postscript} button allows the user
 to save the plot as a Postscript file.
 The \commandf{Configure...} button brings up
 the dialog for setting configuration options.

 \begin{figure}[htbp]
 {\small \begin{center} \begin{boxedverbatim} 
 AUTO> p=plot()
 Created plot
 AUTO> p.config(bg="black")
 AUTO> p.savefig("black.eps")
 AUTO> p=plot(hide=True)
 Created plot
 AUTO> p.savefig("white.eps")
 \end{boxedverbatim}
 \end{center} 
 }
 \caption[Configuring a plotter.]
 {This example shows how a plotter is created,
 how the background color may be changed to black,
 how a figure is saved, and how an invisible plot is
 saved to a file.
 All other configuration options are set similarily.
 Note, the above commands assume that the files
 fort.7 and fort.8 exist in the current directory.
 }
 \label{exa:plotter_example}
 \end{figure}

 \begin{longtable}{| l | l |}
 \hline
 Query string & Meaning \\
 \hline
 1\_1\_resonance\_symbol & The symbol to use for 1:1 resonance points. \\
 \hline
 1\_2\_resonance\_symbol & The symbol to use for 1:2 resonance points. \\
 \hline
 1\_3\_resonance\_symbol & The symbol to use for 1:3 resonance points. \\
 \hline
 1\_4\_resonance\_symbol & The symbol to use for 1:4 resonance points. \\
 \hline
 azimuth  &  Azimuth of the axes in 3D plots. \\
 \hline
 background  &  The background color of the plot. \\
 \hline
 bifurcation\_column\_defaults  & A set of bifurcation columns the user is likely to use. \\
 \hline
 bifurcation\_coordnames & Names to use instead of PAR(1),... for bifurcation diagrams. \\
 \hline
 bifurcation\_diagram  &  A parsed bifurcation diagram file to plot. \\
 \hline
 bifurcation\_diagram\_filename  & The filename of the bifurcation diagram to plot. \\
 \hline
 bifurcation\_symbol  &  The symbol to use for bifurcation points. \\ 
 \hline
 bifurcation\_x  & The column to plot along the X-axis for bifurcation diagrams. \\
 \hline
 bifurcation\_y  & The column to plot along the Y-axis for bifurcation diagrams. \\
 \hline
 bifurcation\_z  & The column to plot along the Z-axis for bifurcation diagrams. \\
 \hline
 bogdanov\_takens\_symbol & The symbol to use for Bogdanov-Takens points. \\
 \hline
 bottom\_margin  & The margin between the graph and the bottom edge. \\
 \hline
 color\_list  &  A list of colors to use for multiple plots. \\
 \hline
 coloring\_method  & color\_list index: 'branch' (BR), 'type' (TY), or 'curve' (seq.). \\
 \hline
 cusp\_symbol & The symbol to use for Cusp points. \\
 \hline
 d0, d1, d2, d3, d4 & Redefine d0, d1, d2, etc. setting to use with
 {\cal PyPLAUT} (\commandf{@pp}). \\
 \hline
 dashes  &    List of dash, no-dash lengths for dashed lines. \\ 
 \hline
 decorations  & Turn on or off the axis, tick marks, etc. \\
 \hline
 default\_option & Default d0, d1, d2, etc. setting to use with {\cal
   PyPLAUT} (\commandf{@pp}). \\
 \hline
 elevation &  Elevation of the axes in 3D plots. \\
 \hline
 error\_symbol  &    The symbol to use for error points. \\ 
 \hline
 even\_tick\_length  & The length of the even tick marks. \\
 \hline
 flip\_torus\_symbol & The symbol to use for flip-torus points. \\
 \hline
 fold\_flip\_symbol & The symbol to use for fold-flip points. \\
 \hline
 fold\_torus\_symbol & The symbol to use for fold-torus points. \\
 \hline
 foreground  &  The background color of the plot. \\
 \hline
 generalized\_hopf\_symbol & The symbol to use for Generalized Hopf points. \\
 \hline
 grid  &  Turn on or off the grid. \\
 \hline
 height  & Height of the graph. \\
 \hline
 hopf\_symbol  &    The symbol to use for Hopf bifurcation points. \\ 
 \hline
 index  & An array of indices to plot.\\
 \hline
 label  & An array of labels to plot, or 'all' for all labels.\\
 \hline
 labelnames  & A dictionary mapping names in \filef{fort.7} to axis labels.\\
 \hline
 label\_defaults  & A set of labels that the user is likely to use. \\
 \hline
 left\_margin  & The margin between the graph and the left edge. \\
 \hline
 letter\_symbols  & Whether to use letter (True) or symbols (False) for special points. \\
 \hline
 limit\_point\_symbol  &    The symbol to use for limit points. \\ 
 \hline
 line\_width & Width to use for lines and curves. \\
 \hline
 mark\_t  &  The t value to marker with a small ball. \\      
 \hline
 maxx  & The upper bound for the x-axis of the plot. \\
 \hline
 maxy  & The upper bound for the y-axis of the plot. \\
 \hline
 maxz  & The upper bound for the z-axis of the plot. \\
 \hline
 minx  &  The lower bound for the x-axis of the plot. \\
 \hline
 miny  & The lower bound for the y-axis of the plot. \\
 \hline
 minz  & The lower bound for the z-axis of the plot. \\
 \hline
 odd\_tick\_length  & The length of the odd tick marks. \\
 \hline
 period\_doubling\_symbol  &   The symbol to use for period doubling bifurcation points. \\ 
 \hline
 ps\_colormode  & The PostScript output mode: 'color', 'gray' or 'monochrome'. \\ 
 \hline
 right\_margin  & The margin between the graph and the left edge. \\
 \hline
 runner  &  The runner object from which to get data. \\       
 \hline
 smart\_label  & Whether to use a smart but slower label placement algorithm. \\ 
 \hline
 special\_point\_colors  &    An array of colors used to mark special points. \\ 
 \hline
 special\_point\_radius  &    The radius of the spheres used to mark special points. \\ 
 \hline
 solution  &  A parsed solution file to plot. \\
 \hline
 solution\_column\_defaults  & A set of solution columns the user is likely to use.\\
 \hline
 solution\_coordnames & Variable names to use instead of U(1),... for solutions. \\
 \hline
 solution\_filename  & The filename of the solution to plot. \\
 \hline
 solution\_indepvarname & Variable name to use instead of 't' for solutions. \\
 \hline
 solution\_x  &  The column to plot along the X-axis for solutions. \\
 \hline
 solution\_y  & The column to plot along the Y-axis for solutions. \\
 \hline
 solution\_z  & The column to plot along the Z-axis for solutions. \\
 \hline
 stability  & Turn on or off stability information using dashed curves. \\
 \hline
 symbol\_font  &  The font to use for marker symbols. \\
 \hline
 symbol\_color  & The color to use for the marker symbols. \\
 \hline
 tick\_label\_template  & A string which defines the format of the tick labels. \\
 \hline
 tick\_length  &  The length of the tick marks. \\
 \hline
 top\_margin  & The margin between the graph and the top edge. \\
 \hline
 top\_title  &    The label for the top title. \\ 
 \hline
 top\_title\_fontsize  & The font size for the top title. \\ 
 \hline
 torus\_symbol  &    The symbol to use for torus bifurcation points. \\ 
 \hline
 torus\_torus\_symbol & The symbol to use for torus-torus points. \\
 \hline
 type  & The type of the plot, either ``solution'' or ``bifurcation''. \\  
 \hline
 use\_labels &   Whether or not to display label numbers in the graph. \\ 
 \hline
 use\_symbols  & Whether or not to display bifurcation symbols in the graph. \\
 \hline
 user\_point\_symbol  &   The symbol to use for user defined output points. \\ 
 \hline
 width  & Width of the graph. \\
 \hline
 xlabel  & The label for the x-axis. \\
 \hline
 xlabel\_fontsize  & The font size for the x-axis label. \\
 \hline
 xticks  & The number of ticks on the x-axis. \\
 \hline
 ylabel  & The label for the y-axis. \\
 \hline
 ylabel\_fontsize  & The font size for the y-axis label. \\
 \hline
 yticks  & The number of ticks on the y-axis. \\
 \hline
 zero\_hopf\_symbol & The symbol to use for zero-Hopf points. \\
 \hline
 zlabel  & The label for the z-axis. \\
 \hline
 zlabel\_fontsize  & The font size for the z-axis label. \\
 \hline
 zticks  & The number of ticks on the z-axis. \\
 \hline
 \caption[The options for the PyPLAUT plotting window.]
 {This table shows the options that
 can be set for the PyPLAUT plotting window and their meanings.}
 \label{tbl:clui plotter specific options}
 \end{longtable}

 \section{ The Plotting Tool PLAUT04}

 The \AUTO plotting tool {\cal PLAUT04} as described
 in Chapter~\ref{ch:PLAUT04}, can be run from the Python CLUI
 using the command
 \commandf{plot3} or \commandf{commandPlotter3D}, in a similar
 fashion to \commandf{plot}. It does not use the options that
 are used for the plotting window produced by \commandf{plot}.

 \section{ Quick Reference } \label{sec:clui quick reference}

 In this section we have created a table of all of the \AUTO CLUI
 commands, their abbreviations, and a one line description of what
 function they perform.  Each command may be entered using 
 its full name or any of its aliases.

\begin{longtable}{|p{1.1in}|l|p{2.5in}|}
\hline 
Command, Aliases & Long name & Description\\ \hline 
append ap & commandAppend & Append data files.\\ \hline 
cat & commandCat & Print the contents of a file\\ \hline 
cd & commandCd & Change directories.\\ \hline 
clean cl & commandClean & Clean the current directory.\\ \hline 
demo dm & commandCopyAndLoadDemo & Copy a demo into the current directory and load it.\\ \hline 
copy cp & commandCopyDataFiles & Copy data files.\\ \hline 
copydemo & commandCopyDemo & Copy a demo into the current directory.\\ \hline 
save sv & commandCopyFortFiles & Save data files.\\ \hline 
gui & commandCreateGUI & Show AUTOs graphical user interface.\\ \hline 
delete, dl & commandDeleteDataFiles & Delete data files.\\ \hline 
df deletefort & commandDeleteFortFiles & Clear the current directory of fort files.\\ \hline 
dlb & commandDeleteLabels & Delete special labels.\\ \hline 
dsp & commandDeleteSpecialPoints & Delete special points.\\ \hline 
double & commandDouble & Double a solution.\\ \hline 
man & commandInteractiveHelp & Get help on the AUTO commands.\\ \hline 
klb & commandKeepLabels & Keep special labels.\\ \hline 
ksp & commandKeepSpecialPoints & Keep special points.\\ \hline 
ls & commandLs & List the current directory.\\ \hline 
merge mb & commandMergeBranches & Merge branches in data files. \\ \hline
move mv & commandMoveFiles & Move data-files to a new name.\\ \hline 
cn constantsget & commandParseConstantsFile & Get the current continuation constants.\\ \hline 
bt diagramandsolutionget & commandParseDiagramAndSolutionFile & Parse both bifurcation diagram and solution.\\ \hline 
dg diagramget & commandParseDiagramFile & Parse a bifurcation diagram.\\ \hline 
sl solutionget & commandParseSolutionFile & Parse solution file:\\ \hline 
plot p2 pl & commandPlotter & plotting of data.\\ \hline 
plot3 p3 & commandPlotter3D & PLAUT04 plotting of data.\\ \hline 
branchpoint br bp & commandQueryBranchPoint & Print the ``branch-point function''.\\ \hline 
eigenvalue ev eg & commandQueryEigenvalue & Print eigenvalues of Jacobian (algebraic case).\\ \hline 
floquet fl & commandQueryFloquet & Print the Floquet multipliers.\\ \hline 
hopf hb hp & commandQueryHopf & Print the value of the ``Hopf function''.\\ \hline 
iterations it & commandQueryIterations & Print the number of Newton interations.\\ \hline 
limitpoint lm lp & commandQueryLimitpoint & Print the value of the ``limit point function''.\\ \hline 
note nt & commandQueryNote & Print notes in info file.\\ \hline 
secondaryperiod sc sp & commandQuerySecondaryPeriod & Print value of ``secondary-periodic bif. fcn''.\\ \hline 
stepsize ss st & commandQueryStepsize & Print continuation step sizes.\\ \hline 
quit q & commandQuit & Quit the AUTO CLUI.\\ \hline 
relabel rl & commandRelabel & Relabel data files.\\ \hline
run r rn & commandRun & Run AUTO.\\ \hline 
ch changeconstant cc & commandRunnerConfigFort2 & Modify continuation constants.\\ \hline 
hch & commandRunnerConfigFort12 & Modify HomCont continuation constants.\\ \hline 
load ld & commandRunnerLoadName & Load files into the AUTO runner.\\ \hline 
printconstant pc pr & commandRunnerPrintFort2 & Print continuation parameters.\\ \hline 
hpr & commandRunnerPrintFort12 & Print HomCont continuation parameters.\\ \hline 
shell & commandShell & Run a shell command.\\ \hline 
splabs & commandSpecialPointLabels & Return special labels.\\ \hline
subtract sb & commandSubtractBranches & Subtract branches in data files.\\ \hline
triple tr & commandTriple & Triple a solution.\\ \hline 
us userdata & commandUserData & Covert user-supplied data files.\\ \hline 
wait & commandWait & Wait for the user to enter a key.\\ \hline 
auto execfile ex & & Execute an AUTO CLUI script.\\ \hline
demofile dmf & & Execute an AUTO CLUI script, line by line (demo
mode). \\ \hline
\end{longtable}
For convenience, you can use ``!'' to run a shell command. Moreover
the common shell commands \commandf{clear}, \commandf{less},
\commandf{mkdir}, \commandf{rmdir},
\commandf{cp}, \commandf{mv}, \commandf{rm}, \commandf{ls},
\commandf{cd}, and \commandf{cat}, and all \AUTO Unix commands that are described
in Chapter~\ref{sec:command_mode} and start with an ``@''-sign can be
entered directly, without the ``!''.
\pagebreak
\section{ Reference }  \label{sec:clui reference}
\subsection{Basic commands.} \label{sec:clui_ref_basic}
\begin{description}
\item[run]
Run \AUTO.

    Type \commandf{r=run([data],[options])} to run \AUTO from solution data with the given
    \AUTO constants or file keyword options.
    
    The results are stored in the bifurcation diagram r which you can
    later print with \commandf{print r}, obtain branches from via r[0], r[1], ...,
    and obtain solutions from via r(3), r(5), r('LP2'), where 3 and 5
    are label numbers, and 'LP2' refers to the second LP label.

    \commandf{run(data)} runs \AUTO in the following way for different types of \parf{data}:
    \begin{itemize}
    \item
      A solution: \AUTO starts from solution \parf{data}, with \AUTO constants \parf{data.c}.
    \item
      A bifurcation diagram: \AUTO start from the solution specified by
      the \AUTO constant \parf{IRS}, or if \parf{IRS} is not specified, the last solution
      in \parf{data}, \parf{data()[-1]}, with \AUTO constants \parf{data()[-1].c}.
    \item
      A string: \AUTO uses the solution in the file \filef{s.data} together with the
      constants in the files \filef{c.data}, and \filef{h.data}. Not all of these
      files need to be present.
    \end{itemize}

    If no solution \parf{data} is specified, then the global values from the
    \commandf{load} command (below) are used instead, where
    options which are not explicitly set retain their previous value.

    Keyword argument options can be \AUTO constants, such as \parf{DS=0.05},
    or \parf{ISW=-1}, or specify a constant or solution file. These override
    the constants in \filef{s.c}, where applicable. See \commandf{load}:\\
    \commandf{run(s,options)} is equivalent to \commandf{run(load(s,options))}

    Example: given a bifurcation diagram bd, with a branch point
    solution, switch branches and stop at the first Hopf bifurcation:\\
    \commandf{hb = run(bd('BP1'),ISW=-1,STOP='HB1')}
    
    Special keyword arguments are \parf{sv} and \parf{ap}; \parf{sv} is also an \AUTO
    constant:\\
    \commandf{run(bd('BP1'),ISW=-1,STOP='HB1',sv='hb',ap='all')}\\
    saves to the files \filef{b.hb}, \filef{s.hb} and \filef{d.hb},
    and appends to \filef{b.all}, \filef{s.all}, and \filef{d.all}.

    \textbf{Aliases:} r rn commandRun

\item[load]
Load files into the \AUTO runner or return modified solution data.

    Type \commandf{result=load([options])} to modify the \AUTO runner.\\
    Type \commandf{result=load(data,[options])} to return possibly
    modified solution data.\\

    The type of the result is a solution object.

    \commandf{load(data,[options])} returns a solution in the following way for
    different types of data:
    \begin{itemize}
    \item
      A solution: load returns the solution data, with \AUTO constants
      modified by options.
    \item
      A bifurcation diagram or a solution list:
      returns the solution specified by
      the \AUTO constant \parf{IRS}, or if \parf{IRS} is not specified, the last solution
      in \parf{s}.
    \item
      A string: \AUTO uses the solution in the file 's.s' together with the
      constants in the files 'c.s', and 'h.s'. Not all of these
      files need to be present.
    \item
      A Python list array or a numpy array representing a solution,
      returns a solution with the given contents. Such an array must be given
      column-wise, as [[t0, ..., tn], [x0, ..., xn], [y0, ..., yn],
      ...], or for a point solution as [x, y, z, ...].
    \end{itemize}

    There are many possible options:
    \begin{verbatim}
    Long name   Short name    Description
    -------------------------------------------
    equation    e             The equations file
    constants   c             The AUTO constants file
    homcont     h             The Homcont parameter file
    solution    s             The restart solution file
                NDIM,IPS,etc  AUTO constants.
                BR,PT,TY,LAB  Solution constants.
    \end{verbatim}
    If data is not specified or data is a string then options which
    are not explicitly set retain their previous value.
    For example one may type: \commandf{s=load(e='ab',c='ab.1')} to
    use \filef{ab.f90}, \filef{ab.f}, or \filef{ab.c} as
    the equations file and \filef{c.ab.1} as the constants file.

    Type \commandf{s=load('name')} to load all files with base 'name'.
    This does the same thing as running
    \commandf{s=load(e='name',c='name,h='name',s='name')}.
 
    You can also specify \AUTO Constants, e.g., \parf{DS=0.05}, or \parf{IRS=2}.
    Special values for \parf{DS} are \parf{'+'} (forwards) and \parf{'-'} (backwards).\\
    Example: \commandf{s = load(s,DS='-')} changes \parf{s.c['DS']} to \parf{-s.c['DS']}.

    \textbf{Aliases:} ld commandRunnerLoadName

\item[loadbd]
    Load bifurcation diagram files.

    Type \commandf{b=loadbd([options])} to load output files or output data.
    There are three possible options:
    \begin{verbatim}
    Long name   Short name    Description
    -------------------------------------------
    bifurcationdiagram   b    The bifurcation diagram file
    solution    s             The solution file or list of solutions
    diagnostics d             The diagnostics file
    \end{verbatim}

    Type \commandf{loadbd('name')} to load all files with base 'name'.
    This does the same thing as running\\
    \commandf{loadbd(b='name',s='name,d='name')}.\\
    \commandf{plot(b)} will then plot the 'b' and 's' components.

    Returns a bifurcation diagram object representing the files in b.

    \textbf{Aliases:} bd commandParseOutputFiles

\item[save]
Save data files.

    Type \commandf{save(x,'xxx')} to save bifurcation diagram \parf{x}
    to the files \filef{b.xxx}, \filef{s.xxx}, \filef{d.xxx}. 
    Existing files with these names will be overwritten.
    If \parf{x} is a solution, a list of solutions, or does not contain any
    bifurcation diagram or diagnostics data, then only the file \filef{s.xxx}
    is saved to.

    Type \commandf{save('xxx')} to save the output-files \filef{fort.7},
    \filef{fort.8}, \filef{fort.9}, to \filef{b.xxx}, \filef{s.xxx},
    \filef{d.xxx}. Existing files with these names will be overwritten.

\textbf{Aliases:} commandCopyFortFiles

\item[append]

Append data files.

    Type \commandf{append(x,'xxx')} to append bifurcation diagram x
    to the data-files \filef{b.xxx}, \filef{s.xxx}, and \filef{d.xxx}. This is equivalent to
    the command\\
    \commandf{save(x+load('xxx'),'xxx')}

    Type \commandf{append('xxx',xxx)} to append existing data-files \filef{s.xxx}, \filef{b.xxx},
    and \filef{d.xxx} to bifurcation diagram x. This is equivalent to
    the command\\
    \commandf{x=load('xxx')+x}

    Type \commandf{append('xxx')} to append the output-files \filef{fort.7}, \filef{fort.8},
    \filef{fort.9}, to existing data-files \filef{s.xxx}, \filef{b.xxx}, and \filef{d.xxx}.

    Type \commandf{append('xxx','yyy')} to append existing data-files \filef{s.xxx}, \filef{b.xxx},
    and \filef{d.xxx} to data-files \filef{s.yyy}, \filef{b.yyy}, and
    \filef{d.yyy}.

    \textbf{Aliases:} ap commandAppend
\end{description}

\subsection{Plotting commands.} \label{sec:clui_ref_plot}

\begin{description}
\item[plot]
Plotting of data.

    Type \commandf{plot(x)} to run the graphics program PyPLAUT for the graphical
    inspection of bifurcation diagram or solution data in x.

    Type \commandf{plot('xxx')} to run the graphics program PyPLAUT for the graphical
    inspection of the data-files \filef{b.xxx} and \filef{s.xxx}.

    Type \commandf{plot()} to run the graphics program for the graphical
    inspection of the output-files \filef{fort.7} and \filef{fort.8}.

    Values also present in the file \filef{autorc}, such as
    \commandf{color\_list = "black green red blue orange"} can be provided as
    keyword arguments, as well as \commandf{hide=True} which hides the
    on-screen plot.

    The return value, for instance, \commandf{p} for
    \commandf{p=plot(x)} will be the handle for the graphics window.
    It has p.config() and p.savefig() methods that allow you to configure
    and save the plot. When plotting, see \commandf{help(p.config)}
    and \commandf{help(p.savefig)} for details.

\textbf{Aliases:} p2 pl commandPlotter

\item[plot3]
Plotting of data using PLAUT04.

    Type \commandf{plot3(x)} to run the graphics program PLAUT04 for the graphical
    inspection of bifurcation diagram or solution data in x.

    Type \commandf{plot3('xxx')} to run the graphics program PLAUT04 for the graphical
    inspection of the data-files \filef{b.xxx} and \filef{s.xxx}.

    Type \commandf{plot3()} to run the graphics program PLAUT04 for the graphical
    inspection of the output-files \filef{fort.7} and \filef{fort.8}.

    Type \commandf{plot3(...,r3b=True)} to run PLAUT04 in restricted three body
    problem mode.
    
\textbf{Aliases:} p3 commandPlotter3D
\end{description}

\subsection{File-manipulation.} \label{sec:clui_ref_files}
\begin{description}
\item[copy]
Copy data files.

    Type \commandf{copy(name1, name2)}, or \commandf{copy(name1,
      name2, name3)}, or  \commandf{copy(name1, name2, name3, name4)} to
    copy the data-files \filef{dir1/c.xxx}, \filef{dir1/b.xxx},
    \filef{dir1/s.xxx}, and \filef{dir1/d.xxx}, to \filef{dir2/c.yyy},
    \filef{dir2/b.yyy}, \filef{dir2/s.yyy}, and \filef{dir2/d.yyy}.

    Type \commandf{copy('xxx','yyy')} to copy the data-files \filef{c.xxx},
    \filef{d.xxx}, \filef{b.xxx}, and \filef{h.xxx} to \filef{c.yyy},
    \filef{d.yyy}, \filef{b.yyy}, and \filef{h.yyy}.
    
    The values of \filef{dir1/?.xxx} and \filef{dir2/?.yyy} are as
    follows, depending on whether \filef{name1} is a directory or
    \filef{name2} is a directory:

    \commandf{copy(name1, name2)}\\
    no directory names: \filef{./?.name1} and \filef{./?.name2}\\
    \filef{name1} is a directory: \filef{name1/?.name2} and \filef{./?.name2}\\
    \filef{name2} is a directory: \filef{./?.name1} and \filef{name2/?.name1}

    \commandf{copy(name1, name2, name3)}\\
    \filef{name1} is a directory: \filef{name1/?.name2} and \filef{./?.name3}\\
    \filef{name2} is a directory: \filef{./?.name1} and \filef{name2/?.name3}

    \commandf{copy(name1, name2, name3, name4)}\\
    \filef{name1/?.name2} and \filef{name3/?.name4}

\textbf{Aliases:} cp commandCopyDataFiles

\item[move]
Move data-files to a new name.

    Type \commandf{move(name1, name2)}, or \commandf{move(name1,
      name2, name3)}, or  \commandf{move(name1, name2, name3, name4)} to
    move the data-files \filef{dir1/b.xxx}, \filef{dir1/s.xxx}, and
    \filef{dir1/d.xxx}, to \filef{dir2/b.yyy}, \filef{dir2/s.yyy}, and
    \filef{dir2/d.yyy}, and copy the constants
    file \filef{dir1/c.xxx} to \filef{dir2/c.yyy}.

    The values of \filef{dir1/?.xxx} and \filef{dir2/?.yyy} are determined
    in the same way as for \commandf{copy} above.

\textbf{Aliases:} mv commandMoveFiles

\item[df]
Clear the current directory of fort files.

    Type \commandf{df()} to clean the current directory.  This command will
    delete all files of the form \filef{fort.*}.
    
\textbf{Aliases:} deletefort commandDeleteFortFiles

\item[clean]
Clean the current directory.

    Type \commandf{clean()} to clean the current directory.  This command will
    delete all files of the form \filef{fort.*}, \filef{*.*\~{}},
    \filef{*.o}, and \filef{*.exe}.
    
\textbf{Aliases:}
cl commandClean

\item[delete]
Delete data files.

    Type \commandf{delete('xxx')} to delete the data-files \filef{d.xxx},
    \filef{b.xxx}, and \filef{s.xxx} (if you are using the default
    filename templates).
    
\textbf{Aliases:} dl commandDeleteDataFiles
\end{description}

\subsection{Diagnostics.} \label{sec:clui_ref_diagnostics}

\begin{description}
\item[limitpoint]
Print the value of the ``limit point function''.

    Type \commandf{limitpoint(x)} to list the value of the ``limit point function'' 
    in the diagnostics of the bifurcation diagram object \parf{x}.
    This function vanishes at a limit point (fold).

    Type \commandf{limitpoint()} to list the value of the ``limit point function'' 
    in the output-file \filef{fort.9}.

    Type \commandf{limitpoint('xxx')} to list the value of the ``limit point function'' 
    in the info file \filef{d.xxx}.
    
\textbf{Aliases:} lm lp commandQueryLimitpoint

\item[branchpoint]
Print the ``branch-point function''.
    
    Type \commandf{branchpoint(x)} to list the value of the ``branch-point function'' 
    in the diagnostics of the bifurcation diagram object \parf{x}.
    This function vanishes at a branch point.

    Type \commandf{branchpoint()} to list the value of the ``branch-point function'' 
    in the output-file \filef{fort.9}.
    
    Type \commandf{branchpoint('xxx')} to list the value of the ``branch-point function''
    in the info file \filef{d.xxx}.
    
\textbf{Aliases:} br bp commandQueryBranchPoint

\item[hopf]
Print the value of the ``Hopf function''.

    Type \commandf{hopf(x)} to list the value of the ``Hopf function'' 
    in the diagnostics of the bifurcation diagram object \parf{x}.
    This function vanishes at a Hopf bifurcation point.

    Type \commandf{hopf()} to list the value of the ``Hopf function'' 
    in the output-file \filef{fort.9}.

    Type \commandf{hopf('xxx')} to list the value of the ``Hopf function''
    in the info file \filef{d.xxx}.
    
\textbf{Aliases:} hb hp commandQueryHopf

\item[secondaryperiod]
Print value of ``secondary-periodic bif. fcn''.

    Type \commandf{secondaryperiod(x)} to list the value of the
    ``secondary-periodic bifurcation function'' 
    in the diagnostics of the bifurcation diagram object \parf{x}.
    This function vanishes at period-doubling and torus bifurcations.

    Type \commandf{secondaryperiod()}  to list the value of the
    ``secondary-periodic bifurcation function'' 
    in the output-file \filef{fort.9}.

    Type \commandf{secondaryperiod('xxx')} to list the value of the
    ``secondary-periodic bifurcation function''
    in the info file \filef{d.xxx}.
    
\textbf{Aliases:} sc sp commandQuerySecondaryPeriod

\item[iterations]
Print the number of Newton interations.

    Type \commandf{iterations(x)} to list the number of Newton iterations per
    continuation step in the diagnostics of the bifurcation diagram
    object \parf{x}.

    Type \commandf{iterations()} to list the number of Newton iterations per
    continuation step in \filef{fort.9}. 

    Type \commandf{iterations('xxx')} to list the number of Newton iterations per
    continuation step in the info file \filef{d.xxx}.
    
\textbf{Aliases:} it commandQueryIterations

\item[note]
Print notes in info file.

    Type \commandf{note(x)} to show any notes 
    in the diagnostics of the bifurcation diagram
    object \parf{x}.

    Type \commandf{note()} to show any notes in the output-file \filef{fort.9}.

    Type \commandf{note('xxx')} to show any notes  in the info file \filef{d.xxx}.
    
\textbf{Aliases:} nt commandQueryNote

\item[stepsize]
Print continuation step sizes.

    Type \commandf{stepsize(x)} to list the continuation step size for each
    continuation step in the diagnostics of the bifurcation diagram
    object \parf{x}.

    Type \commandf{stepsize()} to list the continuation step size for each
    continuation step in  \filef{fort.9}. 

    Type \commandf{stepsize('xxx')} to list the continuation step size for each
    continuation step in the info file \filef{d.xxx}.
    
\textbf{Aliases:} ss st commandQueryStepsize

\item[eigenvalue]
Print eigenvalues of Jacobian (algebraic case).

    Type \commandf{eigenvalue(x)} to list the eigenvalues of the Jacobian 
    in the diagnostics of the bifurcation diagram object \parf{x}.
    (Algebraic problems.)

    Type \commandf{eigenvalue()} to list the eigenvalues of the Jacobian 
    in \filef{fort.9}. 

    Type \commandf{eigenvalue('xxx')} to list the eigenvalues of the Jacobian 
    in the info file \filef{d.xxx}.
    
\textbf{Aliases:} ev eg commandQueryEigenvalue

\item[floquet]
Print the Floquet multipliers.

    Type \commandf{floquet(x)} to list the Floquet multipliers
    in the diagnostics of the bifurcation diagram object \parf{x}.
    (Differential equations.)

    Type \commandf{floquet()} to list the 
    in the output-file \filef{fort.9}. 

    Type \commandf{floquet('xxx')} to list the Floquet multipliers 
    in the info file \filef{d.xxx}.
    
\textbf{Aliases:} fl commandQueryFloquet
\end{description}

\subsection{File-maintenance.} \label{sec:clui_ref_filemaint}

\begin{description}
\item[relabel]
Relabel data files.

    Type \commandf{y=relabel(x)} to return the python object x, with the solution
    labels sequentially relabelled starting at 1, as a new object y.

    Type \commandf{relabel('xxx')} to relabel \filef{s.xxx} and
    \filef{b.xxx}. Backups of the
    original files are saved.

    Type \commandf{relabel('xxx','yyy')} to relabel the existing data-files
    \filef{s.xxx} and \filef{b.xxx} and save then to \filef{s.yyy} and
    \filef{b.yyy}; \filef{d.xxx} is copied to \filef{d.yyy}.

\textbf{Aliases:} rl commandRelabel

\item[double]
Double a solution.

    Type \commandf{double()} to double the solution in \filef{fort.8}.

    Type \commandf{double('xxx')} to double the solution in
    \filef{s.xxx}.
    
\textbf{Aliases:} db commandDouble

\item[triple]
Triple a solution.

    Type \commandf{triple()} to triple the solution in \filef{fort.8}.

    Type \commandf{triple('xxx')} to triple the solution in
    \filef{s.xxx}.
    
\textbf{Aliases:} tr commandTriple

\item[us]
Convert user-supplied data files.

    Type \commandf{us('xxx')} to convert a user-supplied data file 'xxx.dat' to
    \AUTO format. The converted file is called 's.dat'.  The original
    file is left unchanged.  \AUTO automatically sets the period in
    {\tt PAR(11)}.  Other parameter values must be set in 'STPNT'. (When
    necessary, {\tt PAR(11)} may also be redefined there.)  The
    constants-file file 'c.xxx' must be present, as the \AUTO-constants
    'NTST' and 'NCOL' are used to define the new mesh.

    Note: this technique has been obsoleted by the 'dat' \AUTO constant
    in Section~\ref{sec:dat}.
    
\textbf{Aliases:} userdata commandUserData

\item[dlb]
Delete special labels.

    Type \commandf{dlb(x,list)} to delete the special points in list from
    the Python object x, which must be a solution list or a bifurcation diagram.

    Type \commandf{dlb(list,'xxx')} to delete from the data-files 
    \filef{b.xxx} and \filef{s.xxx}.\\
    Type \commandf{dlb(list,'xxx','yyy')} to save to \filef{b.yyy} and
      \filef{s.yyy} instead of \filef{?.xxx}.\\
    Type \commandf{dlb(list)} to delete from \filef{fort.7} and \filef{fort.8}.

    \commandf{list} is a label number or type name code, or a list of those,
    such as 1, or [2, 3], or 'UZ' or ['BP', 'LP'], or it can be None or
    omitted to mean the special points ['BP', 'LP', 'HB', 'PD', 'TR',
    'EP', 'MX']

    Alternatively a boolean user-defined function \commandf{f} that
    takes a solution can be specified for \commandf{list}, such as
\begin{verbatim}
        def f(s):
            return s["PAR(9)"]<0
\end{verbatim}
    where all solutions are deleted that satisfy the given condition, or
\begin{verbatim}
        def f(s1,s2):
            return abs(s1["L2-NORM"] - s2["L2-NORM"]) < 1e-4
\end{verbatim}
    where all solutions are compared with each other and \commandf{s2}
    is deleted if the given condition is satisfied, which causes
    pruning of solutions that are close to each other.

    Type information is kept in the bifurcation diagram for plotting.

\textbf{Alias:} commandDeleteLabels

\item[klb]
Keep special labels.

    Type \commandf{klb(x,list)} to only keep the special points in list in
    the Python object x, which must be a solution list or a bifurcation diagram.

    Type \commandf{klb(list,'xxx')} to keep them in the data-files
    \filef{b.xxx} and \filef{s.xxx}.\\
    Type \commandf{klb(list,'xxx','yyy')} to save to \filef{b.yyy} and
      \filef{s.yyy} instead of \filef{?.xxx}.\\
    Type \commandf{klb(list)} to keep them in \filef{fort.7} and \filef{fort.8}.

    \commandf{list} is a label number or type name code, or a list of those,
    such as 1, or [2, 3], or 'UZ' or ['BP', 'LP'], or it can be None or
    omitted to mean ['BP', 'LP', 'HB', 'PD', 'TR', 'EP', 'MX'], deleting 'UZ' and
    regular points.

    Alternatively a boolean user-defined function \commandf{f} that
    takes a solution can be specified for \commandf{list}, such as
\begin{verbatim}
        def f(s):
            return s["PAR(9)"]<0
\end{verbatim}
    where only solutions are kept that satisfy the given condition.

    Type information is kept in the bifurcation diagram for plotting.

\textbf{Alias:} commandKeepLabels

\item[dsp]
Delete special points.

    Type \commandf{dsp(x,list)} to delete the special points in list from
    the Python object x, which must be a solution list or a bifurcation diagram.

    Type \commandf{dsp(list,'xxx')} to delete from the data-files
    \filef{b.xxx}, and \filef{s.xxx}.\\
    Type \commandf{dsp(list,'xxx','yyy')} to save to \filef{b.yyy} and
    \filef{s.yyy} instead of \filef{?.xxx}.\\
    Type \commandf{dsp(list)} to delete from \filef{fort.7} and \filef{fort.8}.

    \commandf{list} is a label number or type name code, or a list of those,
    such as 1, or [2, 3], or 'UZ' or ['BP', 'LP'], or it can be None or
    omitted to mean the special points ['BP', 'LP', 'HB', 'PD', 'TR', 'EP',
    'MX']\\
    Alternatively a boolean user-defined function \commandf{f} that
    takes a solution can be specified for \commandf{list}, such as
\begin{verbatim}
        def f(s):
            return s["PAR(9)"]<0
\end{verbatim}
    where all solutions are deleted that satisfy the given condition, or
\begin{verbatim}
        def f(s1,s2):
            return abs(s1["L2-NORM"] - s2["L2-NORM"]) < 1e-4
\end{verbatim}
    where all solutions are compared with each other and \commandf{s2}
    is deleted if the given condition is satisfied, which causes
    pruning of solutions that are close to each other.

    Type information is \emph{not} kept in the bifurcation diagram.

\textbf{Alias:} commandDeleteSpecialPoints

\item[ksp]
Keep special points.

    Type \commandf{ksp(x,list)} to only keep the special points in list in
    the Python object x, which must be a solution list or a bifurcation diagram.

    Type \commandf{ksp(list,'xxx')} to keep them in the data-files
    \filef{b.xxx}, and \filef{s.xxx}.\\
    Type \commandf{ksp(list,'xxx','yyy')} to save to \filef{b.yyy} and
    \filef{s.yyy} instead of \filef{?.xxx}.\\
    Type \commandf{ksp(list)} to keep them in \filef{fort.7} and \filef{fort.8}.

    \commandf{list} is a label number or type name code, or a list of those,
    such as 1, or [2, 3], or 'UZ' or ['BP', 'LP'], or it can be None or
    omitted to mean ['BP', 'LP', 'HB', 'PD', 'TR', 'EP', 'MX'], deleting 'UZ' and
    regular points.\\
    Alternatively a boolean user-defined function \commandf{f} that
    takes a solution can be specified for \commandf{list}, such as
\begin{verbatim}
        def f(s):
            return s["PAR(9)"]<0
\end{verbatim}
    where only solutions are kept that satisfy the given condition.

    Type information is \emph{not} kept in the bifurcation diagram.

\textbf{Alias:} commandKeepSpecialPoints

\item[merge]
Merge branches in data files.

    Type \commandf{y=merge(x)} to return the python object x, with its branches
    merged into continuous curves, as a new object y.

    Type \commandf{merge('xxx')} to merge branches in \filef{s.xxx},
    \filef{b.xxx}, and \filef{d.xxx}.  Backups of the
    original files are saved.

    Type \commandf{merge('xxx','yyy')} to merge branches in the existing data-files
    \filef{s.xxx}, \filef{b.xxx}, and \filef{d.xxx} and save them to 
    \filef{s.yyy}, \filef{b.yyy}, and \filef{d.yyy}.

\textbf{Aliases:} mb commandMergeBranches

\item[subtract]
Subtract branches in data files.

    Type \commandf{z=subtract(x,y,ref)} to return the python object x, where,
    using interpolation, the first branch in y is subtracted from all
    branches in x, as a new object z.
    Use 'ref' (e.g., 'PAR(1)')  as the reference column in y
    (only the first monotonically increasing or decreasing part is used).

    Type \commandf{subtract('xxx','yyy','ref')} to subtract, using interpolation, the first
    branch in \filef{b.yyy} from all branches in \filef{b.xxx},
    and save the result in \filef{b.xxx}.
    A Backup of the original file is saved.

    Use optional arguments branch=m, and point=n, to denote the branch and
    first point on that branch within y or \filef{b.yyy}, where m,n are in
    {1,2,3,...}.

\textbf{Aliases:} sb commandSubtractBranches

\end{description}

\subsection{Copying a demo.}
\label{sec:clui_ref_demo}
\begin{description}
\item[demo]
Copy a demo into the current directory and load it.

    Type \commandf{demo('xxx')} to copy all files from auto/07p/demos/xxx to the
    current user directory.  Here 'xxx' denotes a demo name; e.g.,
    'abc'.  To avoid the overwriting of existing files, always run
    demos in a clean work directory.  NOTE: This command automatically
    performs the \commandf{load} command as well.
    
\textbf{Aliases:} dm commandCopyAndLoadDemo

\item[copydemo]
Copy a demo into the current directory.

    Type \commandf{copydemo('xxx')} to copy all files from auto/07p/demos/xxx to the
    current user directory.  Here 'xxx' denotes a demo name; e.g.,
    'abc'.  To avoid the overwriting of existing
    files, always run demos in a clean work directory.
    
\textbf{Aliases:} copydemo commandCopyDemo
\end{description}

\subsection{Python data structure manipulation functions.}
\label{sec:clui_ref_python}
All commands here, except for 'man', 'gui', and 'wait' are only
provided for backwards compatibility. Alternatives are given.
\begin{description}
\item[man]
Get help on the \AUTO commands.
    
    Type \commandf{man} to list all commands with a online help.
    Type \commandf{man xxx} or \commandf{help xxx} to get help for command \commandf{xxx}.

\textbf{Aliases:} commandInteractiveHelp

\item[cn]
Get the current continuation constants.

    Type \commandf{cn('xxx')} to get a parsed version of the constants file
    \filef{c.xxx}. This is equivalent to the command\\
    \commandf{loadbd('xxx').c}
    
\textbf{Aliases:} constantsget commandParseConstantsFile

\item[dg]
Parse a bifurcation diagram.

    Type \commandf{dg('xxx')} to get a parsed version of the diagram file \filef{b.xxx}.
    This is equivalent to the command \commandf{loadbd('xxx')} but without the
    solutions in \filef{s.xxx} and without the diagnostics in \filef{d.xxx}.
    
\textbf{Aliases:} diagramget commandParseDiagramFile

\item[sl]
Parse solution file:

    Type \commandf{sl('xxx')} to get a parsed version of the solution file
    \filef{s.xxx}. This is equivalent to the command\\
    \commandf{loadbd('xxx')()}
    
\textbf{Aliases:} solutionget commandParseSolutionFile

\item[bt]
Parse both bifurcation diagram and solution.

    Type \commandf{bt('xxx')} to get a parsed version of the diagram file \filef{b.xxx}
    and solution file \filef{s.xxx}.
    This is equivalent to the command \commandf{loadbd('xxx')} but without the
    diagnostics in \filef{d.xxx}.
    
\textbf{Aliases:} diagramandsolutionget commandParseDiagramAndSolutionFile

\item[ch]
Modify continuation constants.

    Type \commandf{ch('xxx',yyy)} to change the constant \parf{'xxx'} to have
    value \parf{yyy}.
    This is equivalent to the command\\
    \commandf{s=load(s,xxx=yyy)}\\
    where \parf{s} is a solution.

\textbf{Aliases:} changeconstant cc commandRunnerConfigFort2

\item[hch]
Modify HomCont continuation constants.

    Type \commandf{hch('xxx',yyy)} to change the HomCont constant \parf{'xxx'} to have
    value \parf{yyy}.
    This is equivalent to the command\\
    \commandf{s=load(s,xxx=yyy)}\\
    where \parf{s} is a solution.
    
\textbf{Aliases:} commandRunnerConfigFort12

\item[pr]
Print continuation parameters.

    Type \commandf{pr()} to print all the parameters.
    Type \commandf{pr('xxx')} to return the parameter 'xxx'.
    These commands are equivalent to the commands\\
    \commandf{print s.c}\\
    \commandf{print s.c['xxx']}\\
    where \parf{s} is a solution.
    
\textbf{Aliases:} pc pr printconstant commandRunnerPrintFort2

\item[hpr]
Print HomCont continuation parameters.

    Type \commandf{hpr()} to print all the HomCont parameters.
    Type \commandf{hpr('xxx')} to return the HomCont parameter 'xxx'.
    These commands are equivalent to the commands\\
    \commandf{print s.c}\\
    \commandf{print s.c['xxx']}\\
    where \parf{s} is a solution.
    
\textbf{Aliases:} commandRunnerPrintFort12

\item[splabs]
Return special labels.
        
    Type \commandf{splabs('xxx',typename)} to get a list of labels with the specified
    typename, where typename can be one of
    'EP', 'MX', 'BP', 'LP', 'UZ', 'HB', 'PD', 'TR', or 'RG'.
    This is equivalent to the command\\
    \commandf{load('xxx')(typename)}\\
    which gives a list of the solutions themselves;
    \commandf{load('xxx')(typename).getLabels()}\\
    returns the list of labels.

    Or use \commandf{splabs(s,typename)} where \parf{s} is a parsed
    solution from \commandf{sl()}.
    This is equivalent to the command\\
    \commandf{s(typename).getLabels()}

\textbf{Aliases:} commandSpecialPointLabels

\item[wait]
Wait for the user to enter a key.

    Type \commandf{wait()} to have the \AUTO interface wait
    until the user hits any key (mainly used in scripts).

\textbf{Aliases:} commandWait

\item[quit]
Quits the \AUTO CLUI

\textbf{Aliases:} q commandQuit

\item[gui]
Show \AUTO's graphical user interface.

    Type \commandf{gui()} to start \AUTO's graphical user interface.
    
    NOTE: This command is not implemented yet.
    
\textbf{Aliases:} commandCreateGUI

\end{description}

\subsection{Shell Commands.} \label{sec:clui_ref_shell}

\begin{description}
\item[cat]
Print the contents of a file

    Type \commandf{cat xxx} to list the contents of the file \filef{xxx}.
    
\textbf{Aliases:} commandCat

\item[cd]
Change directories.
    
    Type \commandf{cd xxx} to change to the directory \filef{xxx}.  This command
    understands both shell variables and home directory expansion.
    
\textbf{Aliases:} commandCd 

\item[ls]
List the current directory.
    
    Type \commandf{ls} to run the system \commandf{ls} command in the
    current directory.
    This command will accept whatever arguments are accepted by the Unix command
    \commandf{ls}.
    
\textbf{Aliases:} commandLs

\item[shell]
Run a shell command.
        
    Type \commandf{shell('xxx')} to run the command \commandf{xxx}
    in the Unix shell and display
    the results in the \AUTO command line user interface.
    
\textbf{Aliases:} commandShell
\end{description}


%==============================================================================
%==============================================================================
\chapter{ Running {\cal AUTO} using Unix Commands.} \label{sec:command_mode}
%==============================================================================
%==============================================================================
Apart from the Python commands described in the previous chapter,
{\cal AUTO} can also be run with the GUI described in Chapter~\ref{ch:GUI},
or using the Unix commands described below. These Unix commands run both
directly in the shell and at the {\tt AUTO} Python prompt.
The {\cal AUTO} aliases must have been activated; see Section~\ref{sec:Installation}; 
and an equations-file {\tt xxx.f90} 
and a corresponding constants-file {\tt c.xxx} 
(see Section~\ref{ch:User_supplied_files})
must be in the current user directory.
\\
{\it Do not run {\cal AUTO} in the directory {\tt auto/07p} 
or in any of its subdirectories.}

Most commands only need a plain Unix shell but some use \python: the
commands that depend on \python are \commandf{@cnvc},
\commandf{@dlb}, \commandf{@dsp}, \commandf{@klb}, \commandf{@ksp},
\commandf{@lbf}, \commandf{@ll}, \commandf{@ls}, \commandf{@mb},
\commandf{@pp}, and \commandf{@sb}.

\section{ Basic commands.} 

\begin{itemize}
\item[\tt @r]:
  Type \commandf{@r xxx} to run {\cal AUTO}.
  Restart data, if needed, are expected in {\tt s.xxx},
  and {\cal AUTO}-constants in {\tt c.xxx}.
  This is the simplest way to run {\cal AUTO}.
\item[-]
  Type \commandf{@r xxx yyy} to run {\cal AUTO}
  with equations-file {\tt xxx.f90} and restart data-file {\tt s.yyy}.
  {\cal AUTO}-constants must be in {\tt c.xxx}.
\item[-]
  Type \commandf{@r xxx yyy zzz} to run {\cal AUTO}
  with equations-file {\tt xxx.f90}, restart data-file {\tt s.yyy}
  and constants-file {\tt c.zzz}.

\item[\tt @R]~:
  The command \commandf{@R xxx} is equivalent to the command \commandf{@r xxx} above.
\item[-]
  Type \commandf{@R xxx i}  to run {\cal AUTO} with equations-file {\tt xxx.f90},
  constants-file {\tt c.xxx.i}
  and, if needed, restart data-file {\tt s.xxx}. 
\item[-]
  Type \commandf{@R xxx i yyy} to run {\cal AUTO}
  with equations-file {\tt xxx.f90}, 
  constants-file {\tt c.xxx.i}
  and restart data-file {\tt s.yyy}.
\item[-]
  Use \commandf{@@R} on case-insensitive file systems.

\item[\tt @sv]~:
  Type \commandf{@sv xxx} to save the output-files 
  {\tt fort.7}, {\tt fort.8}, {\tt fort.9},
  as {\tt b.xxx}, {\tt s.xxx}, {\tt d.xxx}, respectively.
  Existing files by these names will be deleted.

\item[\tt @ap]~:
  Type \commandf{@ap xxx} to append the output-files 
  {\tt fort.7}, {\tt fort.8}, {\tt fort.9}, 
  to existing data-files 
  {\tt b.xxx}, {\tt s.xxx}, {\tt d.xxx}, resp.
\item[-]
  Type \commandf{@ap xxx yyy} 
  to append 
  {\tt b.xxx}, {\tt s.xxx}, {\tt d.xxx}, to
  {\tt b.yyy}, {\tt s.yyy}, {\tt d.yyy}, resp.

\item[\tt @ll]~:
  Type \commandf{@ll} to list all solutions in \filef{fort.8}.\\
  Type \commandf{@ll xxx} to list all solutions in \filef{s.xxx}.

\item[\tt @ls]~:
  Type \commandf{@ls} to list the abbreviated contents of \filef{fort.7}.\\
  Type \commandf{@ls xxx} to list the abbreviated contents of \filef{b.xxx}.\\
  The contents are shown in a similar format as the screen output of
  AUTO runs.

\item[\tt @lbf]~:
  Type \commandf{@lbf} to list the contents of \filef{fort.7}.\\
  Type \commandf{@lbf xxx} to list the contents of \filef{b.xxx}.\\
  The contents are shown with less accuracy (6 instead of 11
  significant figures) than in the actual file for easier viewing.


\end{itemize}

\section{ Plotting commands.} 

\begin{itemize}

\item[\tt @pp]~:
  Type \commandf{@pp xxx} to run the graphics program {\cal PyPLAUT}
  (See Chapter~\ref{ch:PLAUT})
  for the graphical inspection of the data-files 
  {\tt b.xxx} and {\tt s.xxx}. 
\item[-]
  Type \commandf{@pp} to run the graphics program {\cal PyPLAUT}
  for the graphical inspection of the output-files 
  {\tt fort.7} and {\tt fort.8}.

\item[\tt @pl]~:
  The command \commandf{@pl} is equivalent to {\tt @pp} but runs
  the graphics program {\cal PLAUT04} instead.
  (See Chapter~\ref{ch:PLAUT04})

\item[\tt @r3b]~:
  The command \commandf{@r3b} is equivalent to {\tt @pp} but runs
  the graphics program {\cal PLAUT04} instead in R3B mode.
  (See Chapter~\ref{ch:PLAUT04})

\item[\tt @p]~:
  The command \commandf{@p} is equivalent to {\tt @pp} but runs
  the graphics program {\cal PLAUT} instead.
  (See Chapter~\ref{ch:PLAUT})

\item[\tt @ps]~:
  Type \commandf{@ps fig.x} to convert a saved {\cal PLAUT} figure {\tt fig.x}
  from compact {\cal PLOT10} format to {\cal PostScript} format.
  The converted file is called {\tt fig.x.ps}. 
  The original file is left unchanged.

\end{itemize}

\section{ File-manipulation.} 

\begin{itemize}

\item[\tt @cp]~:
  Type \commandf{@cp name1 name2}, or \commandf{@cp name1
   name2 name3}, or  \commandf{@cp name1 name2 name3 name4} to
  copy the data-files \filef{dir1/c.xxx}, \filef{dir1/b.xxx},
  \filef{dir1/s.xxx}, and \filef{dir1/d.xxx}, to \filef{dir2/c.yyy},
  \filef{dir2/b.yyy}, \filef{dir2/s.yyy}, and \filef{dir2/d.yyy}.

  The values of \filef{dir1/?.xxx} and \filef{dir2/?.yyy} are as
  follows, depending on whether \filef{name1} is a directory or
  \filef{name2} is a directory:

  \commandf{@cp name1 name2}\\
  no directory names: \filef{./?.name1} and \filef{./?.name2}\\
  \filef{name1} is a directory: \filef{name1/?.name2} and \filef{./?.name2}\\
  \filef{name2} is a directory: \filef{./?.name1} and \filef{name2/?.name1}

  \commandf{@cp name1 name2 name3}\\
  \filef{name1} is a directory: \filef{name1/?.name2} and \filef{./?.name3}\\
  \filef{name2} is a directory: \filef{./?.name1} and \filef{name2/?.name3}

  \commandf{@cp name1 name2 name3 name4}\\
  \filef{name1/?.name2} and \filef{name3/?.name4}

\item[\tt @mv]~:
   Type \commandf{@mv name1 name2}, or \commandf{@mv name1 name2
     name3)}, or  \commandf{@mv name1 name2 name3 name4} to
   move the data-files \filef{dir1/b.xxx}, \filef{dir1/s.xxx}, and
   \filef{dir1/d.xxx}, to \filef{dir2/b.yyy}, \filef{dir2/s.yyy}, and
   \filef{dir2/d.yyy}, and copy the constants
   file \filef{dir1/c.xxx} to \filef{dir2/c.yyy}.

   The values of \filef{dir1/?.xxx} and \filef{dir2/?.yyy} are determined
   in the same way as for \commandf{@cp} above.

\item[\tt @df]~:
  Type \commandf{@df} 
  to delete the output-files 
  {\tt fort.7}, {\tt fort.8}, {\tt fort.9}.

\item[\tt @cl]~:
  Type \commandf{@cl} 
  to clean the current directory.
  This command will delete  all files of the form
  {\tt fort.*}, {\tt *.o}, {\tt *.*\~{}}, and {\tt *.exe}.

\item[\tt @dl]~:
  Type \commandf{@dl xxx} 
 to delete the data-files 
  {\tt b.xxx}, {\tt s.xxx}, {\tt d.xxx}.

\item[\tt @cnvc]~:
  Type \commandf{@cnvc xxx yyy} to convert old-format constants files
\filef{c.xxx} and \filef{h.xxx} to a new-format constant file
\filef{c.yyy}.\\
  The command \commandf{@cnvc xxx} overwrites the file \filef{c.xxx}
  with the new style file and deletes \filef{h.xxx} if it exists.

\item[\tt @rn]~:
  Type \commandf{@rn} to rename, within the current directory, all
  old-named constants, HomCont, bifurcation
  diagram, and solution files starting with \filef{r.}, \filef{s.},
  \filef{p.}, and \filef{q.} to files with the new prefixes
  \filef{c.}, \filef{h.}, \filef{b.}, and \filef{s.}.

\item[\tt @rc]~:
  Type \commandf{@rc} to do a recovery by swapping the backup files
  \filef{fort.7\~{}} and \filef{fort.8\~{}} with the files
  \filef{fort.7} and \filef{fort.8}.\\
  Type \commandf{@rc xxx} to do a recovery by swapping the backup files
  \filef{b.xxx} and \filef{s.xxx} with the files
  \filef{b.xxx\~{}} and \filef{s.xxx\~{}}.

\item[\tt @gz]~:
  Type \commandf{@gz} to compress, using \commandf{gzip} all output
  files in the current directory.

\item[\tt @uz]~:
  Type \commandf{@uz} to decompress, using \commandf{unzip} all output
  files in the current directory.

\item[\tt @sr]~:
  Type \commandf{@sr xxx y} to copy \filef{c.xxx} to \filef{c.xxx.y}.

\end{itemize}

\section{ Diagnostics.} 

\begin{itemize}
\item[\tt @lp]~:
  Type \commandf{@lp} to list the value of the ``limit point function'' 
  in the output-file {\tt fort.9}. This function
  vanishes at a limit point (fold).
  \item[-]
  Type \commandf{@lp xxx} to list the value of the ``limit point function'' 
  in the data-file {\tt d.xxx}. This function
  vanishes at a limit point (fold).
\item[\tt @bp]~:
  Type \commandf{@bp} to list the value of the ``branch-point function'' 
  in the output-file {\tt fort.9}. This function
  vanishes at a branch point.
  \item[-]
  Type \commandf{@bp xxx} to list the value of the ``branch-point function''
  in the data-file {\tt d.xxx}. This function
  vanishes at a branch point.
\item[\tt @hb]~:
  Type \commandf{@hb} to list the value of the ``Hopf function'' 
  in the output-file {\tt fort.9}. This function
  vanishes at a Hopf bifurcation point.
  \item[-]
  Type \commandf{@hb xxx} to list the value of the ``Hopf function''
  in the data-file {\tt d.xxx}. This function
  vanishes at a  Hopf bifurcation point.
\item[\tt @ho]~:
  The command \commandf{@ho} is an alias to \commandf{@hb} above.
\item[\tt @sp]~:
  Type \commandf{@sp} to list the value of the 
  ``secondary-periodic bifurcation function'' 
  in the output-file {\tt fort.9}. This function
  vanishes at period-doubling and torus bifurcations.
  \item[-]
  Type \commandf{@sp xxx} to list the value of the
   ``secondary-periodic bifurcation function''
  in the data-file {\tt d.xxx}. This function
  vanishes at period-doubling and torus bifurcations.
\item[\tt @it]~:
  Type \commandf{@it} to list the number of Newton iterations per
  continuation step in {\tt fort.9}. 
  \item[-]
   Type \commandf{@it xxx} to list the number of Newton iterations per
  continuation step in {\tt d.xxx}. 
\item[\tt @st]~:
  Type \commandf{@st} to list the number of stable eigenvalues or stable
  Floquet multipliers per continuation step in  {\tt fort.9}. 
\item[\tt @ss]~:
  Type \commandf{@st} to list the continuation step size for each
  continuation step in  {\tt fort.9}. 
  \item[-]
   Type \commandf{@st xxx} to list the continuation step size for each
  continuation step in {\tt d.xxx}. 
\item[\tt @ev]~:
  Type \commandf{@ev} to list the eigenvalues of the Jacobian 
  in {\tt fort.9}. 
  (Algebraic problems.)
  \item[-]
   Type \commandf{@ev xxx} to list the eigenvalues of the Jacobian 
  in {\tt d.xxx}. 
  (Algebraic problems.)
\item[\tt @fl]~:
  Type \commandf{@fl} to list the Floquet multipliers
  in the output-file {\tt fort.9}. 
  (Differential equations.)
  \item[-]
   Type \commandf{@fl xxx} to list the Floquet multipliers 
  in the data-file {\tt d.xxx}. 
  (Differential equations.)
\item[\tt @no]~:
  Type \commandf{@no} to show any notes in {\tt fort.9}.
  \item[-]
  Type \commandf{@no xxx} to show any notes in {\tt d.xxx}.
\end{itemize}

\section{ File-editing.} 

\begin{itemize}

\item[\tt @e7]~:
  To use the vi editor to edit the output-file {\tt fort.7}.
\item[\tt @e8]~:
  To use the vi editor to edit the output-file {\tt fort.8}.
\item[\tt @e9]~:
  To use the vi editor to edit the output-file {\tt fort.9}.
\item[\tt @j7]~:
  To use the SGI jot editor to edit the output-file {\tt fort.7}.
\item[\tt @j8]~:
  To use the SGI jot editor to edit the output-file {\tt fort.8}.
\item[\tt @j9]~:
  To use the SGI jot editor to edit the output-file {\tt fort.9}.
  
\end{itemize}

\section{ File-maintenance.} 

\begin{itemize}
\item[\tt @rl]~:
  Type \commandf{@rl} to sequentially relabel solutions with the numbers $1,2,3,\ldots$
  in the output-files {\tt fort.7} and {\tt fort.8}.
  The original files are backed up as
{\tt fort.7$\sim$} and {\tt fort.8$\sim$}. 
  \item[-]
  Type \commandf{@rl xxx} to relabel solutions
  in the data-files {\tt b.xxx} and {\tt s.xxx}.
  The original files are backed up as {\tt b.xxx$\sim$} and {\tt s.xxx$\sim$}. 
\item[-]
  Type \commandf{@rl xxx yyy} to relabel solutions
  in the data-files {\tt b.xxx} and {\tt s.xxx}.
  The modified files are written as {\tt b.yyy} and {\tt s.yyy}. 

\item[\tt @lb]~:
  Type \commandf{@lb} to run an interactive utility program
  for listing, deleting and relabeling solutions and branches
  in the output-files {\tt fort.7} and {\tt fort.8}.
  The original files are backed up as
{\tt fort.7$\sim$} and {\tt fort.8$\sim$}. 
  \item[-]
  Type \commandf{@lb xxx} to list, delete and relabel solutions and branches
  in the data-files {\tt b.xxx} and {\tt s.xxx}.
  The original files are backed up as {\tt b.xxx$\sim$} and {\tt s.xxx$\sim$}. 
\item[-]
  Type \commandf{@lb xxx yyy} to list, delete and relabel solutions
  in the data-files {\tt b.xxx} and {\tt s.xxx}.
  The modified files are written as {\tt b.yyy} and {\tt s.yyy}. 

\item[\tt @LB]~:
  Type \commandf{@LB} or \commandf{@@LB} on case-insensitive file
  systems is equivalent to \commandf{@lb} above but moves instead of
  copies files so that it is much quicker but interrupts may be harmful.

\item[\tt @fc]~:
  Type \commandf{@fc xxx} to convert a user-supplied data file {\tt xxx.dat}
  to {\cal AUTO} format. The converted file is called {\tt s.dat}.
  The original file is left unchanged.
  {\cal AUTO} automatically sets the period in {\tt PAR(11)}.
  Other parameter values must be set in {\tt STPNT}. (When necessary,
  {\tt PAR(11)} may also be redefined there.) 
  The constants-file file {\tt c.xxx} must be present, as the 
  {\cal AUTO}-constants {\tt NTST} and {\tt NCOL} 
  (Sections~\ref{sec:NTST} and \ref{sec:NCOL}) are used to define the new mesh.
  
  Note: this technique has been obsoleted by the 'dat' AUTO constant
  in Section~\ref{sec:dat}.

\item[\tt @db]~:
  Type \commandf{@db} to double the solution in \filef{fort.8}.
  Type \commandf{@db xxx} to double the solution in \filef{s.xxx}.

\item[\tt @tr]~:
  Type \commandf{@tr} to triple the solution in \filef{fort.8}.
  Type \commandf{@tr xxx} to triple the solution in \filef{s.xxx}.

\item[\tt @dlb]~:
  Type \commandf{@dlb} to delete all special labels in \filef{fort.7} and
  \filef{fort.8}. Backups are made.\\
  Type \commandf{@dlb xxx} to delete all special labels in \filef{b.xxx} and
  \filef{s.xxx}. Backups are made.\\
  Type \commandf{@dlb xxx yyy} to delete all special labels in \filef{b.xxx} and
  \filef{s.xxx}. The output is written to \filef{b.yyy} and
  \filef{s.yyy}.\\
  Optionally, give an argument of the form
  \commandf{-UZ}, \commandf{-HB}, \commandf{-LP}, \commandf{-EP}, \commandf{-PD},
  \commandf{-TR}, \commandf{-BP}, \commandf{-MX}, or \commandf{-RG} to
  remove all labels with the given type, as in
  \commandf{@dlb -UZ xxx}; otherwise only labels with type UZ and
  regular labels are kept.\\
  Type information is kept in the bifurcation diagram for plotting.

\item[\tt @klb]~:
  Type \commandf{@klb} to keep all special labels in \filef{fort.7} and
  \filef{fort.8}. Backups are made.\\
  Type \commandf{@klb xxx} to keep all special labels in \filef{b.xxx} and
  \filef{s.xxx}. Backups are made.\\
  Type \commandf{@klb xxx yyy} to keep all special labels in \filef{b.xxx} and
  \filef{s.xxx}. The output is written to \filef{b.yyy} and
  \filef{s.yyy}.\\
  Optionally, give an argument of the form
  \commandf{-UZ}, \commandf{-HB}, \commandf{-LP}, \commandf{-EP}, \commandf{-PD},
  \commandf{-TR}, \commandf{-BP}, \commandf{-MX}, or \commandf{-RG} to
  keep all labels with the given type, as in
  \commandf{@klb -UZ xxx} and remove all others;
  otherwise all labels are kept except for labels with type UZ and regular labels.\\
  Type information is kept in the bifurcation diagram for plotting.

\item[\tt @dsp]~:
  The command \commandf{@dsp} is equivalent to the command \commandf{@dlb}
  above, except that
  type information is \emph{not} kept in the bifurcation diagram for plotting.

\item[\tt @ksp]~:
  The command \commandf{@ksp} is equivalent to the command \commandf{@klb}
  above, except that
  type information is \emph{not} kept in the bifurcation diagram for plotting.

\item[\tt @dlp]~:
  The command \commandf{@dlp} is equivalent to the command \commandf{@dsp -LP}
  above.

\item[\tt @kbp]~:
  The command \commandf{@kbp} is equivalent to the command \commandf{@ksp -BP}
  above.

\item[\tt @klp]~:
  The command \commandf{@klp} is equivalent to the command \commandf{@ksp -LP}
  above.

\item[\tt @kuz]~:
  The command \commandf{@kuz} is equivalent to the command \commandf{@ksp -UZ}
  above.

\item[\tt @rd]~:
  Type \commandf{@rd} to reduce the solution in \filef{fort.7}
  and \filef{fort.8}.\\
  Type \commandf{@rd xxx} to reduce the solution in \filef{b.xxx} and
  \filef{s.xxx}.\\
  Reducing means that all even regular point solutions
  (from \parf{NPR}: the 2nd, 4th, 6th,  etc.) are deleted from the files.

\item[\tt @RD]~:
  The commands \commandf{@RD} and \commandf{@@RD} (for
  case-insensitive file systems) are equivalent to \commandf{@rd}
  above but are faster, though not reliable when interrupting,
  by using moves instead of copies.

\item[\tt @mb]~:
  Type \commandf{@mb} to merge branches into continuous curves
  in \filef{fort.7}, \filef{fort.8}, and \filef{fort.9}.  Backups of the
  original files are saved.\\
  Type \commandf{@mb xxx} to merge branches in \filef{s.xxx},
  \filef{b.xxx}, and \filef{d.xxx}.  Backups of the
  original files are saved.\\
  Type \commandf{@mb xxx yyy} to merge branches in \filef{s.xxx},
  \filef{b.xxx}, and \filef{d.xxx},
  and save them to \filef{s.yyy}, \filef{b.yyy}, and \filef{d.yyy}.

\item[\tt @sb]~:
  Type \commandf{@sb xxx yyy ref} to subtract, using interpolation, the first
  branch in \filef{b.yyy} from all branches in \filef{b.xxx},
  and save the result in \filef{b.xxx}.
  Use \commandf{ref} (e.g., \commandf{PAR(1)}) as the reference
  column in \filef{b.yyy}.
  (only the first monotonically increasing or decreasing part is used).
  A Backup of the original file is saved.

  Use optional fourth and fifth arguments \commandf{m}, and
  \commandf{n}, to denote the
  branch $m$ and first point $n$ on that branch within \filef{b.yyy},
  where $m,n$ are in $\{1,2,3,\ldots\}$.

\item[\tt @zr]~:
  Type \commandf{@zr xxx} to zero all small numbers, with absolute
  value less than $10^{-16}$ in \filef{s.xxx}. A backup file is made.

\end{itemize}

\section{ HomCont commands.} 

Note that the \commandf{@h} and \commandf{@H} are obsolete with
new-style constants files, where HomCont constants can be included in
the main constant file with a {\tt c.} prefix.
\begin{itemize}
\item[\tt @h]~:
  Use {\tt @h} instead of {\tt @r} when using {\cal HomCont}, i.e., when {\tt IPS}=9
  (see Chapter~\ref{ch:HomCont}).
  Type \commandf{@h xxx} to run {\cal AUTO}/{\cal HomCont}.
  Restart data, if needed, are expected in {\tt s.xxx},
  {\cal AUTO}-constants in {\tt c.xxx} and {\cal HomCont}-constants in {\tt h.xxx}.
\item[-]
  Type \commandf{@h xxx yyy} to run {\cal AUTO}/{\cal HomCont}
  with equations-file {\tt xxx.f90} and restart data-file {\tt s.yyy}.
  {\cal AUTO}-constants must be in {\tt c.xxx} and {\cal HomCont}-constants in {\tt h.xxx}.
\item[-]
  Type \commandf{@h xxx yyy zzz} to run {\cal AUTO}/{\cal HomCont}
  with equations-file {\tt xxx.f90}, restart data-file {\tt s.yyy}
  and constants-files {\tt c.zzz} and {\tt h.zzz}.

\item[\tt @H]~:
  The command \commandf{@H xxx} is equivalent to the command \commandf{@h xxx} above.
\item[-]
  Type \commandf{@H xxx i} to run {\cal AUTO}/{\cal HomCont} with equations-file {\tt xxx.f90}
  and constants-files {\tt c.xxx.i} and {\tt h.xxx.i}
  and, if needed, restart data-file {\tt s.xxx}. 
\item[-]
  Type \commandf{@H xxx i yyy} to run {\cal AUTO}/{\cal HomCont}
  with equations-file {\tt xxx.f90}, 
  constants-files {\tt c.xxx.i} and {\tt h.xxx.i},
  and restart data-file {\tt s.yyy}.
\item[-]
  Use \commandf{@@H} on case-insensitive file systems.
\end{itemize}

\section{ Copying a demo.} 

\begin{itemize}

\item[\tt @dm]~:
  Type \commandf{@dm xxx} 
  to copy all files 
  from {\tt auto/07p/demos/xxx}
  to the current user directory.
  Here {\tt xxx} denotes a demo name; e.g., {\tt abc}.
  Note that the \commandf{@dm} command also copies \filef{.auto} files
  to the current user directory. To avoid the overwriting of
  existing files, always run demos in a clean work directory.
\end{itemize}

\section{ Viewing the manual.} 

\begin{itemize}

\item[\tt @mn]~: Use {\cal gv} or {\cal evince} to view the PDF version of this manual.
\end{itemize}

\newpage

%==============================================================================
%==============================================================================
\chapter{ Output Files.} \label{ch:Output_files}
%==============================================================================
%==============================================================================
{\cal AUTO} writes to standard output and three output-files~:
\begin{itemize}
\item[-] standard output:~
  A summary of the computation is written to standard output, which usually
  corresponds to the window in which {\cal AUTO} is run. 
  Only special, labeled solution points are noted, namely those listed
  in Tables~\ref{tbl:Solution_Types} and \ref{tbl:Codim2_Solution_Types}
  The letter codes in the Table are used in the screen output.
  The numerical codes are used internally and in
  the {\tt fort.7} and {\tt fort.8} output-files described below.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | r | l |}
\hline
 BP & (1)  & Branch point (algebraic systems) \\
\hline
 LP & (2)  & Fold (algebraic systems) \\
\hline
 HB & (3)  & Hopf bifurcation \\
\hline
  & (4)  & User-specified regular output point \\
\hline
 UZ & (-4)  & Output at user-specified parameter value \\
\hline
 LP & (5)  & Fold (differential equations) \\
\hline
 BP & (6)  & Branch point (differential equations) \\
\hline
 PD & (7)  & Period doubling bifurcation \\
\hline
 TR & (8)  & Torus bifurcation \\
\hline
 EP & (9)  & End point of family; normal termination \\
\hline
 MX & (-9)  & Abnormal termination; no convergence \\
\hline
\end{tabular}
\caption{Solution Types.}
\label{tbl:Solution_Types}
\end{center}
\end{table}
 
\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | r | l |}
\hline
 BT & (-21) & Bogdanov-Takens bifurcation on fold curve (algebraic systems)\\
\hline
 BT & (-31) & Bogdanov-Takens bifurcation on Hopf curve \\
\hline
 CP & (-22) & Cusp bifurcation on fold curve (algebraic systems)\\
\hline
 GH & (-32) & Generalized Hopf bifurcation on Hopf curve \\
\hline
 ZH & (-13) & Zero-Hopf on BP curve (algebraic systems)\\
\hline
 ZH & (-23) & Zero-Hopf on Fold curve (algebraic systems)\\
\hline
 ZH & (-33) & Zero-Hopf on Hopf curve \\
\hline
 R1 & (-25) & 1:1 resonance on Fold (maps) \\
\hline
 R1 & (-55) & 1:1 resonance on Fold (periodic solutions) \\
\hline
 R1 & (-85) & 1:1 resonance on Torus (periodic solutions, maps) \\
\hline
 R2 & (-76) & 1:2 resonance on PD (periodic solutions, maps) \\
\hline
 R2 & (-86) & 1:2 resonance on Torus (periodic solutions, maps) \\
\hline
 R3 & (-87) & 1:3 resonance on Torus (periodic solutions, maps) \\
\hline
 R4 & (-88) & 1:4 resonance on Torus (periodic solutions, maps) \\
\hline
 LPD & (28) & Fold-flip bifurcation on Fold (maps) \\
\hline
 LPD & (78) & Fold-flip bifurcation on PD (maps) \\
\hline
 LTR & (23) & Fold-torus bifurcation on Fold (maps) \\
\hline
 LTR & (83) & Fold-torus bifurcation on Torus (maps) \\
\hline
 PTR & (77) & Flip-torus bifurcation on PD (maps) \\
\hline
 PTR & (87) & Flip-torus bifurcation on Torus (maps) \\
\hline
 TTR & (88) & Torus-torus bifurcation on Torus (maps) \\
\hline
\end{tabular}
\caption{Codimension-two solution types.
Note that the absolute value of the numerical code divided by 10
gives the type of the curve on which the special point occurs.}
\label{tbl:Codim2_Solution_Types}
\end{center}
\end{table}

\item[-] {\tt fort.7}~:~ 
  The {\tt fort.7} output-file contains the bifurcation diagram.
  Its format is the same as the {\tt fort.6} (screen) output, 
  but the {\tt fort.7} output is more extensive, as every solution point has 
  an output line printed.
\item[-] {\tt fort.8}~:~ 
  The {\tt fort.8} output-file contains complete graphics and restart data
  for selected, labeled solutions. 
  The information per solution is generally much more extensive than
  that in {\tt fort.7}. 
  The {\tt fort.8} output should normally be kept to a minimum.
\item[-] {\tt fort.9}~:~
  Diagnostic messages, convergence history, eigenvalues, and 
  Floquet multipliers are written in {\tt fort.9}.
  It is strongly recommended that this output be habitually inspected.
  The amount of diagnostic data can be controlled via the {\cal AUTO}-constant {\tt IID};
  see Section~\ref{sec:IID}.
\end{itemize}

The user has some control over the {\tt fort.6} (screen) and {\tt fort.7} output 
via the {\cal AUTO}-constant {\tt IPLT} (Section~\ref{sec:IPLT}).
Furthermore, the routine {\tt PVLS} can be used to define ``solution measures''
which can then be printed by ``parameter overspecification'';
see Section~\ref{sec:Parameter_over_specification}.
For an example see demo {\tt pvl}.

The {\cal AUTO}-commands \commandf{@sv}(\commandf{sv}), \commandf{@ap}(\commandf{ap}),
 and \commandf{@df}(\commandf{df}) can be used 
to manipulate  the output-files {\tt fort.7}, {\tt fort.8},
and {\tt fort.9}.
Furthermore, the {\cal AUTO}-command \commandf{@lb}(\commandf{rl}) can be
used to delete and
relabel solutions and branches simultaneously in {\tt fort.7} and {\tt fort.8}.
For details see Section~\ref{sec:command_mode}.

The graphics programs {\cal PLAUT}, {\cal PLAUT04}, and the Python
CLUI command \commandf{plot} can be used to graphically inspect 
the data in {\tt fort.7} and {\tt fort.8}; see Chapters~\ref{ch:PLAUT},
~\ref{ch:PLAUT04}, and ~\ref{ch:python_mode}.
 
%==============================================================================
%==============================================================================
\chapter{ The Graphics Programs PLAUT and PyPLAUT.} \label{ch:PLAUT}
%==============================================================================
%==============================================================================
{\cal PLAUT} and {\cal PyPLAUT} can be used to extract graphical
information from the {\cal AUTO} output-files {\tt fort.7} and {\tt fort.8},
or from the corresponding data-files {\tt b.xxx} and {\tt s.xxx}.
To invoke {\cal PLAUT}, use the \commandf{@p} command defined in 
Section~\ref{sec:command_mode}.
The {\cal PLAUT} window (a Tektronix window) will appear, in which {\cal PLAUT}
commands can be entered.
To invoke {\cal PyPLAUT}, use the \commandf{@pp} command. The same
plotting window as you get by using \commandf{plot} in the \python interface
appears (see Section~\ref{clui:plotting}), 
but you can also manipulate it by typing {\cal PLAUT}
commands in the terminal in which you typed \commandf{@pp}.
For examples of using {\cal PLAUT} and {\cal PyPLAUT} see the tutorial demos {\tt pp2}
and {\tt pp3} in sections~\ref{sec:Demos_pp2} and \ref{sec:Demos_pp3},
respectively.

The files \filef{.autorc} and \filef{autorc}, as explained in
Section~\ref{clui:plotting}, can be used to customize
{\cal PyPLAUT}'s behaviour and appearance.

\section{ Basic {\cal PLAUT}-Commands.} \label{sec:main_PLAUT_commands}
The principal {\cal PLAUT}-commands are 
\begin{itemize}
\item[\tt bd0]~:
  This command is useful for an initial overview of the bifurcation
  diagram as stored in {\tt fort.7}.
  If you have not previously selected one of the default options 
  {\it d0, d1, d2, d3}, or {\it d4} described below then you will be asked
  whether you want solution labels, grid lines, titles, or labeled axes.

\item[\tt bd]~:
  This command is the same as the {\it bd0} command, except that you will be
  asked to enter the minimum and the maximum of the horizontal and 
  vertical axes.
  This is useful for blowing up portions of a previously displayed
  bifurcation diagram.

\item[\tt ax]~:
  With the {\it ax} command you can select any pair of columns of real
  numbers from {\tt fort.7} as horizontal and vertical axis in the
  bifurcation diagram. (The default is columns 1 and 2).
  To determine what these columns represent, one can look at the
  screen ouput of the corresponding {\cal AUTO} run, or one can inspect the
  column headings in {\tt fort.7}.
  
\item[\tt 2d]~:
  Upon entering the {\it 2d} command, the labels of all solutions stored 
  in {\tt fort.8} will be listed and you can select one or more of these 
  for display. The number of solution components is also listed
  and you will be prompted to select two of these as horizontal and
  vertical axis in the display.
  Note that the first component is typically the independent 
  time or space variable scaled to the interval [0,1].

\item[\tt sav]~:
  To save the displayed plot in a file. You will be asked to enter
  a file name. Each plot must be stored in a separate new file.
  The plot is stored in compact {\cal PLOT10} format, which can be converted to 
  {\cal PostScript} format with the {\cal AUTO}-commands {\tt @ps};
  see Section~\ref{sec:Printing_PLAUT_files}.

\item[\tt cl]~:  To clear the graphics window.

\item[\tt lab]~:
  To list the labels of all solutions stored in {\tt fort.8}.
  Note that {\cal PLAUT} requires all labels to be distinct.
  In case of multiple labels you can use the {\cal AUTO}
  command \commandf{@lb} to relabel solutions in
  {\tt fort.7} and {\tt fort.8}.

\item[\tt end]~:  To end execution of {\cal PLAUT}.
\end{itemize}


\section{ Default Options.} \label{sec:PLAUT_default}
After entering the commands {\it bd0, bd}, or {\it 2d}, you will be asked whether you 
want solution labels, grid lines, titles, or axes labels.
For quick plotting it is convenient to bypass these selections.
This can be done by the default commands {\it d0, d1, d2, d3}, or {\it d4} below.
These can be entered as a single command 
or they can be entered as prefixes in the {\it bd0} and {\it bd} commands. 
Thus, for example, one can enter the command {\it d1bd0}.  

\begin{itemize}
\item[\tt d0]~:  Use solid curves, showing symbols, but no solution labels. 
\item[\tt d1]~:  Use solid curves, except use dashed curves for unstable
  solutions and for solutions of unknown stability.
  Show solution labels and symbols.
\item[\tt d2]~:  As {\it d1}, but without solution labels.
\item[\tt d3]~:  As {\it d1}, but with grid lines.
\item[\tt d4]~:  As {\it d2}, but with grid lines.
\end{itemize}

If no default option {\it d0, d1, d2, d3}, or {\it d4} has been selected 
or if you want to override a default feature,
then the following commands can be used.
These can be entered as individual commands or as prefixes.
For example, one can enter the command {\it sydpbd0}.

\begin{itemize}
\item[\tt sy]~:  Use symbols for special solution points, for example,
  open square = branch point,
  solid square = Hopf bifurcation.
\item[\tt dp]~:  ``Differential Plot'', i.e., show stability of the 
  solutions. Solid curves represent stable solutions.
  Dashed curves are used for unstable
  solutions and for solutions of unknown stability.
  For periodic solutions use solid/open circles
  to indicate stability/instability (or unknown
  stability).
\item[\tt st]~:  Set up titles and axes labels. 
\item[\tt nu]~:  Normal usage (reset special options). 
\end{itemize}


\section{ Other {\cal PLAUT}-Commands.} \label{sec:Other_PLAUT_commands}
The full {\cal PLAUT} program has several other capabilities, for example,

\begin{itemize}
\item[\tt scr]~:  To change the diagram size.
\item[\tt rss]~:  To change the size of special solution point symbols.
\end{itemize}

These commands are not available in {\cal PyPLAUT}.

\section{ Printing {\cal PLAUT} Files.} \label{sec:Printing_PLAUT_files}
\begin{itemize}
\item[\tt @ps]~:
  Type \commandf{@ps fig.1} to convert a saved {\cal PLAUT} file {\tt fig.1} 
  to {\cal PostScript} format
  in {\tt fig.1.ps}.

\item[\tt @eps]~:
  Type \commandf{@eps fig.1} to convert a saved {\cal PLAUT} file {\tt fig.1} 
  to encapsulated {\cal PostScript} format
  in {\tt fig.1.eps}.
\end{itemize}
In {\cal PyPLAUT} you can directly save to a variety of file
formats, including \filef{.eps} and \filef{.png}.

 
%==============================================================================
%==============================================================================
\chapter{ The Graphics Program PLAUT04.} \label{ch:PLAUT04}
%==============================================================================
%==============================================================================

% This tex file is also used by the stand-alone user guide you get
% when you ask for help in PLAUT04
\newcommand{\PLAUT} {\textsc{Plaut04}}
\newcommand{\ETC} {\textit{etc.}}
\input{plaut04_user_guide.tex}

%==============================================================================
%==============================================================================
\chapter{ The Graphical User Interface GUI94.} \label{ch:GUI}
%==============================================================================
%==============================================================================
\section{ General Overview.} \label{sec:GUI_Overview}
The {\cal AUTO} graphical user interface (GUI) is a tool
for creating and editing equations-files and constants-files;
see Section~\ref{ch:User_supplied_files}
 for a description of these files.
The GUI can also be used to run {\cal AUTO} and to manipulate and plot
output-files and data-files; 
see Section~\ref{sec:command_mode} for corresponding commands.
To use the GUI for a new equation, change to an empty work directory.
For an existing equations-file, change to its directory.
({\it Do not activate the GUI in the directory {\tt auto/07p} 
or in any of its subdirectories.})
Then type 

\centerline { @{\it auto}, }

or its abbreviation @{\it a}.
Here we assume that the {\cal AUTO} aliases have been activated; 
see Section~\ref{sec:Installation}.
The GUI includes a window for editing the equations-file,
and four groups of buttons, namely,
the {\it Menu Bar} at the top of the GUI,
the {\it Define Constants}-buttons at the center-left,
the {\it Load Constants}-buttons at the lower left,
and the {\it Stop- and Exit}-buttons.

{\bf Note :}~
Most GUI buttons are activated by point-and-click action with 
the {\it left} mouse button. 
If a beep sound results then the {\it right} mouse button must be used. 

\subsection{ The Menu bar.}
It contains the main buttons for running {\cal AUTO}
and for manipulating the equations-file, the constants-file,
the output-files, and the data-files.
In a typical application, these buttons are used from left to right.
First the {\it Equations} are defined and, if necessary, {\it Edited},
before being {\it Written}.
Then the {\cal AUTO}-constants are {\it Defined}.
This is followed by the actual {\it Run} of {\cal AUTO}.
The resulting output-files can be {\it Saved} as data-files,
or they can be {\it Appended} to existing data-files.
Data-files can be {\it Plotted} with the graphics program {\cal PLAUT},
and various file operations can be done with the {\it Files}-button.
Auxiliary functions are provided by the {\it Demos-}, {\it Misc-},
and {\it Help}-buttons.
The Menu Bar buttons are described in more detail 
in Section~\ref{sec:GUI_Menu_bar}.


\subsection{ The Define-Constants-buttons.}
These have the same function as
the {\it Define}-button on the  Menu Bar, namely to set and change
{\cal AUTO}-constants.
However, 
for the {\it Define}-button all constants appear in one panel, 
while 
for the Define Constants-buttons they
are grouped by function, 
as in Chapter~\ref{ch:AUTO_constants}, namely
{\it Problem} definition constants,
{\it Discretization} constants,
convergence {\it Tolerances},
continuation {\it Step Size},
diagram {\it Limits},
designation of free {\it Parameters},
constants defining the {\it Computation},
and
constants that specify {\it Output} options.


\subsection{ The Load-Constants-buttons.}
The {\it Previous}-button can be used to load an existing {\cal AUTO}-constants file.
Such a file is also loaded, if it exists,
by the {\it Equations}-button on the {\it Menu Bar}.
The {\it Default}-button can be used
to load  default values of all {\cal AUTO}-constants. 
Custom editing is normally necessary.


\subsection{ The Stop- and Exit-buttons.}
The {\it Stop}-button can be used to abort execution of an {\cal AUTO}-run.
This should be done only in exceptional circumstances.
Output-files, if any, will normally be incomplete and should be deleted.
Use the {\it Exit}-button to end a session.


\section{ The Menu Bar.} \label{sec:GUI_Menu_bar}
\subsection{ Equations-button.}
This pull-down menu contains the items
{\it Old}, to load an existing equations-file,
{\it New}, to load a model equations-file,
and
{\it Demo}, to load a selected demo equations-file.
Equations-file names are of the form {\tt xxx.f90}.
The corresponding constants-file {\tt c.xxx} is also loaded if it exists.
The equation name {\tt xxx} remains active until redefined.

\subsection{ Edit-button.}
This pull-down menu contains the items
{\it Cut} and {\it Copy}, 
to be performed on text in the GUI window
highlighted by click-and-drag action of the mouse,
and the item {\it Paste}, which places editor buffer text at the
location of the cursor.



\subsection{ Write-button.}
This pull-down menu contains the item
{\it Write},
to write the loaded files {\tt xxx.f90} and {\tt c.xxx},
by the active equation name,
and the item
{\it Write As}
to write these files by a selected new name, which then becomes the active name.


\subsection{ Define-button.}
Clicking this button will display the full {\cal AUTO}-constants panel.
Most of its text fields can be edited,
but some have restricted input values that can be selected with
the right mouse button.
Some text fields will display a subpanel for entering data.
To actually apply changes made in the panel, click the
{\it OK-} or {\it Apply}-button at the bottom of the panel.



\subsection{ Run-button.}
Clicking this button will write the constants-file {\tt c.xxx} and run {\cal AUTO}.
If the equations-file has been edited then it should first be rewritten 
with the {\it Write}-button. 


\subsection{ Save-button.}
This pull-down menu contains the item
{\it Save},
to save the output-files {\tt fort.7}, {\tt fort.8}, {\tt fort.9},
as {\tt b.xxx}, {\tt s.xxx}, {\tt d.xxx}, respectively.
Here {\tt xxx} is the active equation name.
It also contains the item
{\it Save As}, 
to save the output-files under another name. 
Existing data-files with the selected name, if any, will be overwritten.


\subsection{ Append-button.}
This pull-down menu contains the item
{\it Append},
to append the output-files {\tt fort.7}, {\tt fort.8}, {\tt fort.9},
to existing data-files {\tt b.xxx}, {\tt s.xxx}, {\tt d.xxx}, respectively.
Here {\tt xxx} is the active equation name.
It also contains the item
{\it Append To}, 
to append the output-files to other existing data-files.

\subsection{ Plot-button.}
This pull-down menu contains the items
{\it Plot},
to run the plotting program {\cal PLAUT} for the data-files 
{\tt b.xxx} and {\tt s.xxx},
where {\tt xxx} is the active equation name,
and the item
{\it Name}, 
to run {\cal PLAUT} with other data-files.


\subsection{ Files-button.}
This pull-down menu contains 
the item 
{\it Restart}, to redefine the restart file.
Normally, when restarting from a previously computed solution,
the restart data is expected in the file {\tt s.xxx},
where {\tt xxx} is the active equation name.
Use the {\it Restart}-button to read the restart data from another data-file
in the immediately following run.  
The pull-down menu also contains the following items~:
\begin{itemize}
\item[-]{\it Copy},~ to copy  
  {\tt b.xxx}, {\tt s.xxx}, {\tt d.xxx}, {\tt c.xxx},
  to
  {\tt b.yyy}, {\tt s.yyy}, {\tt d.yyy}, {\tt c.yyy}, resp.;

\item[-]{\it Append},~ to append data-files
  {\tt b.xxx}, {\tt s.xxx}, {\tt d.xxx},
  to
  {\tt b.yyy}, {\tt s.yyy}, {\tt d.yyy}, resp.;

\item[-]{\it Move},~ to move 
  {\tt b.xxx}, {\tt s.xxx}, {\tt d.xxx}, {\tt c.xxx},
  to
  {\tt b.yyy}, {\tt s.yyy}, {\tt d.yyy}, {\tt c.yyy}, resp.;

\item[-]{\it Delete},~ to delete data-files
  {\tt b.xxx}, {\tt s.xxx}, {\tt d.xxx};  

\item[-]{\it Clean}, to delete all files of the form 
  {\tt fort.*}, {\tt *.o}, and {\tt *.exe}.  
\end{itemize}


\subsection{ Demos-button.}
This pulldown menu contains the items
{\it Select},
to view and run a selected {\cal AUTO} demo in the demo directory,
and
{\it Reset},
to restore the demo directory to its original state.
Note that demo files can be copied to the user work directory
with the {\it Equations/Demo}-button.


\subsection{ Misc.-button.}
This pulldown menu contains the items
{\it Tek Window}
and
{\it VT102 Window},
for opening windows;
{\it Emacs}
and
{\it Xedit},
for editing files,
and
{\it Print}, for printing the active equations-file {\tt xxx.f90}.


\subsection{ Help-button.}
This pulldown menu contains the items
{\it {\cal AUTO}-constants}, for help on {\cal AUTO}-constants,
and
{\it User Manual}, for viewing the user manual; i.e., this document.


\section{ Using the GUI.} \label{sec:Using_the_GUI}
{\cal AUTO}-commands are described in Section~\ref{sec:command_mode} and
illustrated in the demos.
In Table~\ref{tbl:CM_GUI} we list the main {\cal AUTO}-commands 
together with the corresponding GUI button.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
\commandf{@r }  & {\it Run} \\  
\hline
\commandf{@sv }  & {\it Save}  \\ 
\hline
\commandf{@ap }  & {\it Append} \\ 
\hline
\commandf{@p }  & {\it Plot}  \\ 
\hline
\commandf{@cp }  & {\it Files/Copy}  \\ 
\hline
\commandf{@mv }  & {\it Files/Move}  \\ 
\hline
\commandf{@cl }  & {\it Files/Clean} \\ 
\hline
\commandf{@dl }  & {\it Files/Delete} \\  
\hline
\commandf{@dm }  & {\it Equations/Demo} \\  
\hline
\end{tabular}
\caption{Command Mode - GUI correspondences.}
\label{tbl:CM_GUI}
\end{center}
\end{table}


The {\cal AUTO}-command \commandf{@r xxx yyy} is given in the GUI as follows~:
click {\it Files/Restart} and enter {\it yyy} as data.
Then click {\it Run}.
As noted in Section~\ref{sec:command_mode}, 
this will run {\cal AUTO} with the current equations-file
{\tt xxx.f90} and the current constants-file {\tt c.xxx}, 
while expecting restart data in {\tt s.yyy}.
The {\cal AUTO}-command \commandf{@ap xxx yyy} is given in the GUI by
clicking {\it Files/Append}.

\section{ Customizing the GUI.} \label{sec:Customizing_the_GUI}
\subsection{ Print-button.}
The {\it Misc/Print}-button on the Menu Bar can be customized 
by editing the file {\tt GuiConsts.h} in directory {\tt auto/07p/include}.

\subsection{ GUI colors.}
GUI colors can be customized by creating an X resource file.
Two model files can be found in directory {\tt auto/07p/gui}, namely,
{\tt Xdefaults.1} and {\tt Xdefaults.2}.
To become effective, edit one of these, if desired,
and copy it to {\tt .Xdefaults} in your home directory.
Color names can often be found in the system file {\tt /usr/lib/X11/rgb.txt}.

\subsection{ On-line help.}
The file {\tt auto/07p/include/GuiGlobal.h}
contains on-line help on {\cal AUTO}-constants and demos.
The text can be updated, subject to a modifiable maximum length.
On SGI machines this is 10240 bytes,
which can be increased, for example, to 20480 bytes, 
by replacing the line
{\it CC = cc -Wf, -XNl10240 -O}
in {\tt auto/07p/gui/Makefile} by
{\it CC = cc -Wf, -XNl20480 -O}
On other machines, the maximum message length is the system defined maximum
string literal length.


%==============================================================================
%==============================================================================
\chapter{ Description of {\cal AUTO}-Constants.} \label{ch:AUTO_constants}
%==============================================================================
%==============================================================================
\section{ The {\cal AUTO}-Constants File.} \label{sec:The_AUTO_constants_file}
As described in Section~\ref{ch:User_supplied_files}, 
if the equations-file is {\tt xxx.f90} 
then the constants that define the computation 
are normally expected in the file  {\tt c.xxx}.
The format of this file is free, with constant=value pairs separated
by commas or spaces. Comments start with one of the characters  ``\#''
and ``!'', and run to the end of a line.
An example, with default values, is listed below. In real constant
files you only need to specify those values that are different from
these, but listing all of them allows for easier editing.

Note that this file is not strictly necessary when using the \python
interface: you can define all constants inside the scripts if you so wish.

\begin{verbatim}
# Default AUTO Constants file
e = '', s='', dat='', sv=''
unames = {}, parnames = {}
U = {}, PAR = {}
NDIM=   2, IPS =   1, IRS =   0, ILP =   1
ICP =  [1]
NTST=  20, NCOL=   4, IAD =   3, ISP =   2, ISW = 1, IPLT= 0, NBC= 0, NINT= 0
NMX=    0, NPR=    0, MXBF=  10, IID =   2, ITMX= 9, ITNW= 5, NWTN= 3, JAC= 0
EPSL= 1e-07, EPSU = 1e-07, EPSS = 1e-05
DS  =  0.01, DSMIN= 0.005, DSMAX=   0.1, IADS=   1
NPAR=  36, THL =  {}, THU =  {}
RL0=-1.7976e+308, RL1=1.7976e+308, A0=-1.7976e+308, A1=1.7976e+308,
UZR = {}, UZSTOP = {}, SP = [], STOP = []
IIS = 3, IBR=0, LAB=0, TY=''
NUNSTAB = -1, NSTAB = -1, IEQUIB = 1, ITWIST = 0, ISTART = 5
IREV = [], IFIXED = [], IPSI = []
\end{verbatim}

The significance of the {\cal AUTO}-constants, grouped by function, is 
described in the sections below. The HomCont constants \texttt{NUNSTAB},
\texttt{NSTAB}, \texttt{IEQUIB}, \texttt{ITWIST}, \texttt{ISTART},
\texttt{IREV}, \texttt{IFIXED}, and \texttt{IPSI} are explained in
Chapter~\ref{ch:HomCont}.
Representative demos that illustrate use of the {\cal AUTO}-constants
are also mentioned.

%=====================================================================
\section{ Problem Constants.} \label{sec:Problem_constants}
\subsection{\texttt{NDIM}} \label{sec:NDIM}
 Dimension of the system of equations as specified in the user-supplied
 routine {\tt FUNC}.

\subsection{\texttt{NBC}}  \label{sec:NBC}
 The number of boundary conditions as specified in the user-supplied
 routine {\tt BCND}. \\
(Demos {\tt exp}, {\tt kar}.)

\subsection{\texttt{NINT}}  \label{sec:NINT}
 The number of integral conditions as specified in the user-supplied
 routine {\tt ICND}. \\ 
(Demos {\tt int}, {\tt lin}, {\tt obv}.)

\subsection{\texttt{NPAR}} \label{sec:NPAR}
 Maximum parameter number that can be used in all user-supplied
 routines.

\subsection{\texttt{JAC}}  \label{sec:JAC}
 Used to indicate whether derivatives are supplied by the user
 or to be obtained by differencing~:
\begin{itemize}
\item[-] {\tt JAC=0}~: 
  No derivatives are given by the user. (Most demos use {\tt JAC}=0.)
\item[-] {\tt JAC=1}~:  
  Derivatives with respect to state- and problem-parameters are given 
  in the user-supplied routines 
  {\tt FUNC}, {\tt BCND}, {\tt ICND} and {\tt FOPT}, where 
  applicable.  This may be necessary for sensitive problems. 
  It is also recommended for computations in which {\cal AUTO} generates 
  an extended system, for example, when {\tt ISW}=2.
  (For {\tt ISW} see Section~\ref{sec:ISW}.) \\
(Demos {\tt int}, {\tt dd2}, {\tt obt}, {\tt plp}, {\tt ops}.)
\item[-] {\tt JAC=-1}~:
  As for {\tt JAC=1}, but derivatives with respect to
  problem-parameters may be omitted in {\tt FUNC}. \\
(Demo {\tt san}.)
\end{itemize}
%=====================================================================
\section{ Discretization Constants.} \label{sec:Discretization_constants}
\subsection{\texttt{NTST}}  \label{sec:NTST}
 The number of mesh intervals used for discretization.
 {\tt NTST} remains fixed during any particular run, but can be changed
 when restarting. 
 (For mesh adaption see {\tt IAD} in Section~\ref{sec:IAD}.)
 Recommended value of {\tt NTST} : As small as possible to maintain convergence. \\ 
 (Demos {\tt exp}, {\tt ab}, {\tt spb}.)


\subsection{\texttt{NCOL}}  \label{sec:NCOL}
 The number of Gauss collocation points per mesh interval,
 (2 $\le$ {\tt NCOL} $\le$ 7).
 {\tt NCOL} remains fixed during any given run, but can be changed
 when restarting at a previously computed solution.
 The choice {\tt NCOL}=4, used in most demos, is recommended.
 If {\tt NDIM} is ``large'' and the solutions ``very smooth'' then
 {\tt NCOL}=2 may be appropriate.

\subsection{\texttt{IAD}} \label{sec:IAD}
This constant controls the mesh adaption~: 
\begin{itemize}
\item[-] {\tt IAD=0}~:
  Fixed mesh. Normally, this choice should never be used, as it may result
  in spurious solutions. (Demo {\tt ext}.)
\item[-] {\tt IAD$>$0}~:  
  Adapt the mesh every {\tt IAD} steps along the family.
  Most demos use {\tt IAD=3}, which is the strongly recommended value.
\end{itemize}

When computing  ``trivial'' solutions to a boundary value problem,
for example, when all solution components are constant, then the
mesh adaption may fail under certain circumstances, and overflow may
occur. In such case, try recomputing the solution family with a fixed
mesh {\tt (IAD=0)}. Be sure to set  {\tt IAD} back to {\tt IAD=3} 
for computing eventual non-trivial bifurcating solution families.
%=====================================================================
\section{ Tolerances.} \label{sec:Tolerances}
\subsection{\texttt{EPSL}}  \label{sec:EPSL}
 Relative convergence criterion for equation parameters in the Newton/Chord 
 method. Most demos use {\tt EPSL}=$10^{-6}$ or {\tt EPSL}=$10^{-7}$,
 which is the recommended value range.

\subsection{\texttt{EPSU}}  \label{sec:EPSU}
 Relative convergence criterion for solution components in the Newton/Chord 
 method. Most demos use {\tt EPSU}=$10^{-6}$ or {\tt EPSU}=$10^{-7}$,
 which is the recommended value range.

\subsection{\texttt{EPSS}}  \label{sec:EPSS}
 Relative arclength convergence criterion for the detection of special solutions. 
 Most demos use {\tt EPSS}=$10^{-4}$ or  {\tt EPSS}=$10^{-5}$,
 which is the recommended value range.
 Generally, {\tt EPSS} should be approximately 100 to 1000 times the value
 of {\tt EPSL}, {\tt EPSU}.
 
\subsection{\texttt{ITMX}}  \label{sec:ITMX}
 The maximum number of iterations allowed in the accurate
 location of special solutions, such as bifurcations, folds, 
 and user output points, by M\"uller's method with bracketing.
 The recommended value is {\tt ITMX}=8, used in most demos.

\subsection{\texttt{NWTN}}  \label{sec:NWTN}
 After {\tt NWTN} Newton iterations the Jacobian is frozen, i.e.,
 {\cal AUTO} uses full Newton for the first {\tt NWTN} iterations
 and the Chord method for iterations {\tt NWTN}+1 to {\tt ITNW}.
 The choice {\tt NWTN}=3 is strongly recommended and used in most demos.
 Note that this constant is only effective for ODEs, i.e., for solving
 the piecewise polynomial collocation equations.
 For algebraic systems {\cal AUTO} always uses full Newton.

\subsection{\texttt{ITNW}}  \label{sec:ITNW}
 The maximum number of combined Newton-Chord iterations.
 When this maximum is reached, the step will be retried with 
 half the stepsize.
 This is repeated until convergence, or until the minimum
 stepsize is reached. In the latter case the computation of
 the family is discontinued and a message printed in {\tt fort.9}.
 The recommended value is {\tt ITNW}=5, but {\tt ITNW}=7 may be used for 
 ``difficult'' problems, for example, 
 demos {\tt spb}, {\tt chu}, {\tt plp}, etc.

%=====================================================================
\section{ Continuation Step Size.} \label{sec:step_size}
\subsection{\texttt{DS}}  \label{sec:DS}
 {\cal AUTO} uses pseudo-arclength continuation for following solution families.
 The pseudo-arclength stepsize is the distance between
 the current solution and the next solution on a family.
 By default, this distance includes all state variables
 (or state functions) and all free parameters.
 The constant {\tt DS} defines the pseudo-arclength stepsize to be used for the
 first attempted step along any family. 
 (Note that if {\tt IADS}$>$0 then {\tt DS} will automatically be adapted
 for subsequent steps and for failed steps.)
 {\tt DS} may be chosen positive or negative; changing its sign 
 reverses the direction of computation.
 The relation {\tt DSMIN} $\le$ $\abs {\tt DS}$ $\le$ {\tt DSMAX} must be satisfied.
 The precise choice of {\tt DS} is problem-dependent; the demos use a value 
 that was found appropriate after some experimentation.
 

\subsection{\texttt{DSMIN}}  \label{sec:DSMIN}
 This is minimum allowable absolute value of the pseudo-arclength 
 stepsize. {\tt DSMIN} must be positive.
 It is only effective if the pseudo-arclength step is adaptive,
 i.e., if {\tt IADS}$>$0.
 The choice of {\tt DSMIN} is highly problem-dependent;
 most demos use a value that was found appropriate after some
 experimentation.
 See also the discussion in Section~\ref{sec:Efficiency}.

\subsection{\texttt{DSMAX}}  \label{sec:DSMAX}
 The maximum allowable absolute value of the pseudo-arclength stepsize.
 {\tt DSMAX} must be positive.
 It is only effective if the pseudo-arclength step is adaptive,
 i.e., if {\tt IADS}$>$0.
 The choice of {\tt DSMAX} is highly problem-dependent; 
 most demos use a value that was found appropriate after some
 experimentation.
 See also the discussion in Section~\ref{sec:Efficiency}.

\subsection{\texttt{IADS}}  \label{sec:IADS}
This constant controls the frequency of adaption of the 
pseudo-arclength stepsize.
\begin{itemize}
\item[-] {\tt IADS=0}~: 
  Use fixed pseudo-arclength stepsize, i.e., the stepsize will
  be equal to the specified value of {\tt DS} for every step.
  The computation of a family will be discontinued as soon as
  the maximum number of iterations {\tt ITNW} is reached.
  This choice is not recommended. \\(Demo {\tt tim}.)
\item[-] {\tt IADS$>$0}~:  
 Adapt the pseudo-arclength stepsize after every {\tt IADS} steps.
  If the Newton/Chord iteration converges rapidly then 
  $\abs{\tt DS}$ will be increased, but never beyond {\tt DSMAX}.
  If a step fails then it will be retried with half
  the stepsize. This will be done repeatedly until the
  step is successful or until $\abs{\tt DS}$ reaches {\tt DSMIN}. 
  In the latter case nonconvergence will be signalled.
  The strongly recommended value is {\tt IADS}=1, which is used in 
  almost all demos.
\end{itemize}
  
\subsection{\texttt{THL}}  \label{sec:THL}
By default, the pseudo-arclength stepsize includes all state variables
(or state functions) and all free parameters.
Under certain circumstances one may want to modify the weight accorded 
to individual parameters in the definition of stepsize.
For this purpose, {\tt THL} defines the parameters whose weight 
is to be modified.
If {\tt THL=\{\}} then all weights will have default value 1.0,
else one must enter pairs,
             ~\{{\it Parameter Index} : {\it Weight}, ...\}~.

For example, for the computation of periodic solutions it is 
recommended that the period not be included in the pseudo-arclength 
continuation stepsize, in order to avoid period-induced limitations 
on the stepsize near orbits of infinite period. 
This exclusion can be accomplished by setting {\tt THL=\{11:0.0\}}.
If {\tt THL} is not specified this is the default for computing
periodic solutions ({\tt IPS=2}).
Most demos that compute periodic solutions use this option;
see for example demo {\tt ab}.

\subsection{\texttt{THU}}  \label{sec:THU}
Under certain circumstances one may want to modify the weight accorded 
to individual state variables (or state functions) in the definition 
of stepsize.
For this purpose, {\tt THU} defines the number of states whose weight 
is to be modified.
If {\tt THU}=\{\} then all weights will have default value 1.0,
else one must enter pairs,
             ~\{{\it State Index} : {\it Weight}, ...\}~.
At present none of the demos use this option.
%=====================================================================
\section{ Diagram Limits.} \label{sec:Diagram_limits}

There are five ways to limit the computation of a family~:

\begin{itemize}
\item[-]
By specifying a stopping condition in the list associated 
with the constant {\tt STOP}; see Section~\ref{sec:STOP}. 

\item[-]
By specifying parameters and parameter values in the list associated 
with the constant {\tt UZSTOP}; see Section~\ref{sec:UZSTOP}.

\item[-]
By specifying the maximum number of steps, {\tt NMX}.

\item[-]
By specifying a negative parameter index in the list associated 
with the constant {\tt UZR}; see Section~\ref{sec:UZR}. 

\item[-]
By appropriate choice of the computational window 
defined by the constants {\tt RL0}, {\tt RL1}, {\tt A0}, and {\tt A1}.
One should always check that the starting solution lies within
this computational window, otherwise the computation will stop immediately
at the starting point. Most demos do not specify these constants, and
use an unbounded window.
\end{itemize}

\subsection{\texttt{STOP}}  \label{sec:STOP}
This constant adds stopping conditions. It is specified as a list of
bifurcation type strings followed by a number $n$ greater than zero.
These strings specify that the contination should stop as soon as the $n$th
bifurcation of the associated type has been reached.
Example:\\
\begin{description}
\item[\parf{STOP=['HB3','UZ3']}]
Stop at the third Hopf bifurcation or third user defined point (see
Section~\ref{sec:UZR}), whichever comes first.
\end{description}

\subsection{\texttt{NMX}} \label{sec:NMX}
The maximum number of steps to be taken along any family.

\subsection{\texttt{RL0}}  \label{sec:RL0}
 The lower bound on the principal continuation parameter.
 (This is the parameter which appears first in the {\tt ICP} list;
 see Section~\ref{sec:ICP}.). 

\subsection{\texttt{RL1}}  \label{sec:RL1}
 The upper bound on the principal continuation parameter. 

\subsection{\texttt{A0}}  \label{sec:A0}
 The lower bound on the principal solution measure.
 (By default, if {\tt IPLT}=0, the principal solution measure
 is the $L_2$-norm of the state vector or state vector function.
 See the {\cal AUTO}-constant {\tt IPLT} in Section~\ref{sec:IPLT} 
 for choosing another principal solution measure.)

\subsection{\texttt{A1}}  \label{sec:A1}
 The upper bound on the principal solution measure.

%=====================================================================
%=====================================================================
\section{ Free Parameters.} \label{sec:Free_parameters}


\subsection{\texttt{ICP}}  \label{sec:ICP}
For each equation type and for each continuation calculation there is
a typical (``generic'') number of problem parameters that must be 
allowed to vary, in order for the calculations to be properly posed.
The array {\tt ICP} designates these free parameters.
The parameter that appears first in the {\tt ICP} list is called the 
``principal continuation parameter''.
Specific examples and special cases are described below.

%=====================================================================
\subsection{ Fixed points.}
The simplest case is the continuation of a solution family to the system
$ f( u , p ) = 0$,  where $f(\cdot,\cdot), u \in \Rn$, cf. Equation~(\ref{1}).
Such a system arises in the continuation of ODE stationary solutions and 
in the continuation of fixed points of discrete dynamical systems.
There is only one free parameter here.

As a concrete example, consider Run~1 of demo {\tt ab},
where {\tt ICP=[1]}. 
Thus, in this run {\tt PAR(1)} is designated as the free parameter.

%=====================================================================
\subsection{ Periodic solutions and rotations.}
The continuation of periodic solutions and rotations generically requires 
two parameters, namely, one problem parameter and the period.
For example, in Run~2 of demo {\tt ab} we have {\tt ICP=[1,11]}.
Thus, in this run, the free parameters are {\tt PAR(1)} and {\tt PAR(11)}.
(Note that {\cal AUTO} reserves {\tt PAR(11)} for the period.)

Actually, for periodic solutions, it is sufficient to only specify 
the index of the free problem parameter, as {\cal AUTO} will automatically 
add {\tt PAR(11)}.
However, in this case the period will not appear in the screen output 
and in the {\tt fort.7} output-file. 

For fixed period orbits one must specify two free problem 
parameters.
For example, in Run~7 of demo {\tt pp2}, we have {\tt ICP=[1,2]}, with 
{\tt PAR(1)} and {\tt PAR(2)}
specified as free problem parameters.
The period {\tt PAR(11)} is fixed in this run.
If the period is large then such a continuation provides a simple and 
effective method for computing a locus of homoclinic orbits.
%=====================================================================
\subsection{ Folds and Hopf bifurcations.}
The continuation of folds for algebraic problems and the continuation of
Hopf bifurcations requires two free problem parameters.
For example, to continue a fold in Run~3 of demo {\tt ab}, we have {\tt ICP=[1,3]}, 
with {\tt PAR(1)} and {\tt PAR(3)} specified as free parameters.
Note that one must set {\tt ISW}=2 for computing such loci of special solutions.
Also note that in the continuation of folds the principal continuation parameter
must be the one with respect to which the fold was located.

%=====================================================================
\subsection{ Folds and period-doublings.}
The continuation of folds, for periodic orbits and rotations,
and the continuation of period-doubling and torus bifurcations require two free 
problem parameters plus the free period. Thus, one would normally
specify three parameters.
For example, in Run~6 of demo {\tt pen}, where a locus of period-doubling
bifurcations is computed for rotations, we have {\tt ICP=[2,3,11]}, 
with {\tt PAR(2)}, {\tt PAR(3)}, and {\tt PAR(11)} specified as free parameters. 
Note that one must set {\tt ISW}=2 for computing such loci of special solutions.
Also note that in the continuation of folds the principal continuation parameter
must be the one with respect to which the fold was located.

Actually, one may only specify the problem parameters,
as {\cal AUTO} will automatically add the period.
For example, in Run~3 of demo {\tt plp}, where a locus of folds is computed 
for periodic orbits, we have {\tt ICP=[4,1]}, with {\tt PAR(4)} and {\tt PAR(1)} specified
as free parameters. 
However, in this case the period will not appear in the screen output 
and in the {\tt fort.7} output-file. 

To continue a locus of folds, period-doubling or torus bifurcations
with fixed period, simply
specify three problem parameters, not including {\tt PAR(11)}.
For torus bifurcations it is also possible to specify
four problem parameters (possibly including {\tt PAR(11)}). In that
case the angle of the torus ({\tt PAR(12)}) stays fixed.

%=====================================================================
\subsection{ Boundary value problems.}
The simplest case is that of boundary value problems where 
{\tt NDIM}={\tt NBC} 
and where {\tt NINT}=0.
Then, generically, one free problem parameter is required for computing 
a solution family.
For example, in demo {\tt exp}, we have {\tt NDIM}={\tt NBC}=2, {\tt NINT}=0. 
Thus, in this demo one free parameter is designated,
namely {\tt PAR(1)}.

More generally, for boundary value problems with integral constraints,
the generic number of free parameters is {\tt NBC} + {\tt NINT}$-${\tt NDIM} +1.
For example, in demo {\tt lin}, we have {\tt NDIM}=2, {\tt NBC}=2, and {\tt NINT}=1.
Thus {\tt ICP=[1,3]}. 
Indeed, in this demo two free parameters are designated,
namely {\tt PAR(1)} and {\tt PAR(3)}.

%=====================================================================
\subsection{ Boundary value folds.}
To continue a locus of folds for a general boundary value problem
with integral constraints, set {\tt \#ICP}={\tt NBC}+{\tt NINT}$-${\tt NDIM}+2, 
and specify this number of parameter indices to designate the free parameters.

%=====================================================================
\subsection{ Optimization problems.}
In algebraic optimization problems one must set {\tt ICP}(1)=10, 
as {\cal AUTO} uses {\tt PAR(10)} as principal continuation parameter
to monitor the value of the objective function.
Furthermore, one must designate one free equation parameter in {\tt ICP}(2). 
Thus, {\tt ICP=[10,2]} in the first run.

Folds with respect to {\tt PAR(10)} correspond to extrema of the objective function.
In a second run one can restart at such a fold, with an additional
free equation parameter specified in {\tt ICP}(3).
Thus, {\tt ICP=[10,2,3]} in the second run.

The above procedure can be repeated.
For example, folds from the second run can be continued in a third run
with three equation parameters specified in addition to {\tt PAR(10)}.
Thus, {\tt \#ICP=4} in the third run.

For a simple example see demo {\tt opt}, where a four-parameter extremum
is located.
Note that {\tt \#ICP=5} in each of the four constants-files of this demo, 
with the indices of {\tt PAR(10)} and {\tt PAR(1)-PAR(4)} specified in {\tt ICP}.
Thus, in the first three runs, there are overspecified parameters.
However, {\cal AUTO} will always use the correct number of parameters.
Although the overspecified parameters will be printed, their values will
remain fixed. 

%=====================================================================
\subsection{ Internal free parameters.}
The actual continuation scheme in {\cal AUTO} may use additional free
parameters that are automatically added.
The simplest example is the computation of periodic solutions and rotations,
where {\cal AUTO} automatically puts the period, if not specified, in
\parf{PAR(11)}.
The computation of loci of folds, Hopf bifurcations, and period-doublings
also requires additional internal continuation parameters.
These will be automatically added, and their indices will be greater
than \parf{NPAR}.
Other use depends on \parf{IPS}: see Section~\ref{sec:Restrictions_on_PAR}.

%=====================================================================
\subsection{ Parameter overspecification.} \label{sec:Parameter_over_specification}
The number of specified parameter indices is allowed to be be greater 
than the generic number.
In such case there will be ``overspecified'' parameters, whose values
will appear in the screen and {\tt fort.7} output, but which are not
part of the continuation process.
A simple example is provided by demo {\tt opt}, where the first three runs
have overspecified parameters whose values, although constant, are printed.

There is, however, a more useful application of parameter overspecification.
In the user-supplied routine {\tt PVLS} one can define solution measures
and assign these to otherwise unused parameters.
Such parameters can then be overspecified, in order to print them
on the screen and in the {\tt fort.7} output.
It is important to note that such overspecified parameters must appear
at the end of the {\tt ICP} list, as they cannot be used as true continuation
parameters.

For an example of using parameter overspecification for printing user-defined
solution measures, see demo {\tt pvl}.
This is a boundary value problem (Bratu's equation) which has
only one true continuation parameter, namely {\tt PAR(1)}.
Three solution measures are defined in the routine {\tt PVLS}, namely,
the $L_2$-norm of the first solution component,
the minimum of the second component, and
the left boundary value of the second component.
These solution measures are assigned to {\tt PAR(2), PAR(3), PAR(4)},
and {\tt PAR(5)}, respectively.
In the constants-file {\tt c.pvl} we have {\tt \#ICP=5},
with {\tt PAR(1)-PAR(5)} specified as parameters.
Thus, in this example, {\tt PAR(2)-PAR(5)} are overspecified.
Note that {\tt PAR(1)} must appear first in the {\tt ICP} list;
the other parameters cannot be used as true continuation parameters.
%=====================================================================
%=====================================================================
\section{ Computation Constants.} \label{sec:Computation_constants}
\subsection{\texttt{ILP}}  \label{sec:ILP}
\begin{itemize}
\item[-] {\tt ILP=0}~: 
  No detection of folds. This choice is recommended.
\item[-] {\tt ILP=1}~: 
  Detection of folds. To be used if subsequent fold continuation is intended.
\end{itemize}

\subsection{\texttt{SP}}  \label{sec:SP}
This constant controls the detection of bifurcations and adds stopping
conditions. It is specified as a list of bifurcation type strings
followed by an optional number. If this number is 0, then the detection
of this bifurcation is turned off, and if it is missing
then the detection is turned on. A number $n$ greater than zero
specifies that the contination should stop as soon as the $n$th
bifurcation of this type has been reached.
Examples:\\
\begin{itemize}
\item[-] {\tt SP=['LP0']}\\
turn off detection of folds.
\item[-] {\tt SP=['LP','HB3','BP0','UZ3']}\\
turn on the detection of folds and Hopf bifurcations,
turn off detection of branch points and stop at the third Hopf
bifurcation or third user defined point, whichever comes first.
\end{itemize}
 
\subsection{\texttt{ISP}}  \label{sec:ISP}
This constant controls the detection of Hopf bifurcations,
branch points, period-doubling bifurcations, and torus bifurcations. 
\begin{itemize}
\item[-] {\tt ISP=0}~:  
  This setting disables the detection of Hopf bifurcations,
  branch points, period-doubling 
  bifurcations, and torus bifurcations and the computation of 
  Floquet multipliers.
\item[-] {\tt ISP=1}~:  
  Branch points and Hopf bifurcations are detected for algebraic
  equations. Branch points, period-doubling bifurcations and torus
  bifurcations are not detected for periodic solutions and boundary
  value problems. However, Floquet multipliers are computed.
\item[-] {\tt ISP=2}~: This setting enables the detection of all special 
 solutions.
 For periodic solutions and rotations, the choice {\tt ISP}=2 should be used with
 care, due to potential inaccuracy in the computation of the
 linearized Poincar\'e map and possible rapid variation of the
 Floquet multipliers.
 The linearized Poincar\'e map always has a multiplier $z=1$.
 If this multiplier becomes inaccurate
 then the automatic detection of secondary periodic
 bifurcations will be discontinued and a
 warning message will be printed in {\tt fort.9}.
 See also Section~\ref{sec:Bifurcations}.
\item[-] {\tt ISP=3}~:  
  Hopf bifurcations will not be detected. 
  Branch points will be detected, and {\cal AUTO} will monitor the 
  Floquet multipliers. Period-doubling and torus bifurcations will go undetected. 
  This option is useful for certain problems with non-generic Floquet behavior.
\item[-] {\tt ISP=4}~:  
  Branch points and Hopf bifurcations are detected for algebraic
  equations. Branch points are not detected for
  periodic solutions and boundary value problems.
  {\cal AUTO} will monitor the Floquet multipliers, and period-doubling
  and torus bifurcations will be detected.
\end{itemize}

\subsection{\texttt{ISW}}  \label{sec:ISW}
 This constant controls branch switching at branch points for the case
 of differential equations.
 Note that branch switching is automatic for algebraic equations.
\begin{itemize}
\item[-] {\tt ISW=1}~: This is the normal value of {\tt ISW}.
\item[-] {\tt ISW=$-$1}~:
  If {\tt IRS} is the label of a branch point or a period-doubling
  bifurcation then branch switching will be done.
  For period doubling bifurcations it is recommended that {\tt NTST} be increased.
  For examples see Run~2 and Run~3 of demo {\tt lor}, where branch switching
  is done at period-doubling bifurcations, and Run~2 and Run~3 of demo {\tt bvp},
  where branch switching is done at a transcritical branch point.
\item[-] {\tt ISW=2}~:
  If {\tt IRS} is the label of a fold, a Hopf bifurcation point, 
  a period-doubling, a torus bifurcation, or, in a non-generic
  (symmetric) system, a branch point then a locus of such points will be
  computed. An additional free parameter must be specified for such 
  continuations; see also Section~\ref{sec:Free_parameters}.
\item[-] {\tt ISW=3}~:
  If {\tt IRS} is the label of a branch point in a generic
  (non-symmetric) system then a locus of such points will be
  computed. Two additional free parameters must be specified for such 
  continuations; see also Section~\ref{sec:Free_parameters}.
\end{itemize}

\subsection{\texttt{MXBF}}  \label{sec:MXBF}
 This constant, which is effective for algebraic problems only,
 sets the maximum number of bifurcations to be treated.
 Additional branch points will be noted, but the corresponding bifurcating
 families will not be computed.
 If {\tt MXBF} is positive then the bifurcating families of the first {\tt MXBF}
  branch points will be traced out in both directions.
 If {\tt MXBF} is negative then the bifurcating families of the first 
 $\abs{{\tt MXBF}}$ branch points will be traced out in only one direction. 

\subsection{\texttt{s}}  \label{sec:s}
This constant sets the name of the solution file from which the computation
is to be restarted, instead of \filef{fort.3}: if {\tt s='xxx'} then the
name of the restart file is \filef{s.xxx}.

\subsection{\texttt{dat}}  \label{sec:dat}
This constant, where {\tt dat='xxx'}, sets the name of a user-supplied ASCII
data file {\tt xxx.dat}, from which the contination is to be restarted.
{\cal AUTO} automatically sets the period in {\tt PAR(11)}.
Other parameter values must be set in {\tt STPNT}. (When necessary,
{\tt PAR(11)} may also be redefined there.) 

The first column in the data file denotes the time, which does
\emph{not} need to be rescaled to the interval $[0,1]$, and further
columns the coordinates of the solution. The constant {\tt IRS} must
be set to 0.

(Demos {\tt lor}, {\tt pen}.)

\subsection{\texttt{U}}  \label{sec:U}
This constant, where {\tt U=\{i1:x1,i2:x2\}}, changes the value of
{\tt U(i1)} to {\tt x1}, {\tt U(i2)} to {\tt x2}, and so on,
with respect to the solution to start from. This is only
valid for restarting from algebraic problems or a constant-in-time
solution.

\subsection{\texttt{PAR}}  \label{sec:PAR}
This constant, where {\tt PAR=\{i1:x1,i2:x2\}}, changes the value of
{\tt PAR(i1)}  to {\tt x1}, {\tt PAR(i2)} to
{\tt x2}, and so on, with respect to the solution to start from.

\subsection{\texttt{IRS}}  \label{sec:IRS}
This constant sets the label of the solution where the computation
is to be restarted.
\begin{itemize}
\item[-] {\tt IRS=0}~:  
  This setting is typically used in the first run of a new problem.
  In this case a starting solution must be defined in the user-supplied
  routine {\tt STPNT}.
  For representative examples of analytical starting solutions 
  see demos {\tt ab} and {\tt frc}.
  For starting from unlabeled numerical data see the {\tt dat} command
  above, and demos {\tt lor} and {\tt pen}.
  
\item[-] {\tt IRS$>$0}~: 
  Restart the computation at the previously computed solution with label {\tt IRS}. 
  This solution is normally expected to be in the current data-file 
 {\tt s.xxx}; see also the \commandf{@r} and \commandf{@R} commands in 
 Section~\ref{sec:command_mode}.
 Various {\cal AUTO}-constants can be modified when restarting.

\item[-] {\tt IRS$<$0}~:
  Restart the computation at the -IRSth computed solution in the
  restart file. This is especially useful if you do not want to look
  up label numbers and know for sure that the solution to continue
  from is at a fixed position.
\item[-] {\tt IRS='XYn'}~:
  Restart the computation at the nth label of type XY in the
  restart file, for instance 'HB12' to restart at the twelfth Hopf
  bifurcation.
\end{itemize}

\subsection{\texttt{TY}} \label{sec:TY} 
 This constant modifies the type from the restart solution.
 This is sometimes useful in conservative or extended systems,
 declaring a regular point to be a Hopf bifurcation point ({\tt TY='HB'}) or a
 branch point ({\tt TY='BP'}). Use {\tt TY='HB4'} to copy the period
 of the emanating periodic orbit from {\tt PAR(4)} (for example set in
 the routine {\tt PVLS} in the equations file) to {\tt PAR(11)}.
 (Demo {\tt r3b}.)

\subsection{\texttt{IPS}}  \label{sec:IPS}
This constant defines the problem type~:
\begin{itemize}
%=====================================================================
\item[-] {\tt IPS=0}~: 
  An algebraic bifurcation problem.
  Hopf bifurcations will not be detected and stability
  properties will not be indicated in the {\tt fort.7} output-file.
%=====================================================================
\item[-] {\tt IPS=1}~: 
  Stationary solutions of ODEs with detection of Hopf bifurcations.
  The sign of PT, the point number, in {\tt fort.7} is used 
  to indicate stability~: $-$ is stable , + is unstable.\\
 (Demo {\tt ab}.)
%=====================================================================
\item[-] {\tt IPS=$-$1}~:  
  Fixed points of the discrete dynamical system
  $u^{(k+1)}=f(u^{(k)},p ),$ with detection of Hopf bifurcations.
  The sign of PT in {\tt fort.7} indicates stability~: 
  $-$ is stable , + is unstable.  
 (Demo {\tt dd2}.)
%=====================================================================
\item[-] {\tt IPS=$-$2}~: 
  Time integration using implicit Euler. 
  The {\cal AUTO}-constants {\tt DS}, {\tt DSMIN}, {\tt DSMAX}, and {\tt ITNW}, {\tt NWTN} control 
  the stepsize.
  In fact, pseudo-arclength is used for ``continuation in time''. 
  Note that the time discretization is only first order accurate, 
  so that results should be carefully interpreted. 
  Indeed, this option has been included primarily for the detection 
  of stationary solutions, which can then be entered in the user-supplied
  routine {\tt STPNT}.  \\  
 (Demo {\tt ivp}.)
%=====================================================================
\item[-]  {\tt IPS=2}~:
  Computation of periodic solutions. Starting data can be
  a Hopf bifurcation point (Run~2 of demo {\tt ab}),
  a periodic orbit from a previous run (Run~4 of demo {\tt pp2}),
  an analytically known periodic orbit (Run~1 of demo {\tt frc}),
  or a numerically known periodic orbit (Demo {\tt lor}).
  The sign of PT in {\tt fort.7} is used to indicate
  stability~: $-$ is stable , + is unstable or unknown.
%=====================================================================
\item[-] {\tt IPS=4}~: 
  A boundary value problem. Boundary conditions must be
  specified in the user-supplied routine {\tt BCND}
  and integral constraints in {\tt ICND}. The {\cal AUTO}-constants
  {\tt NBC} and {\tt NINT} must be given correct values.
 (Demos {\tt exp}, {\tt int}, {\tt kar}.)
%=====================================================================
\item[-] {\tt IPS=5}~:
  Algebraic optimization problems. The objective function
  must be specified in the user-supplied routine {\tt FOPT}. 
 (Demo {\tt opt}.)
%=====================================================================
\item[-] {\tt IPS=7}~:
  A boundary value problem with computation of Floquet multipliers. 
  This is a very special option; for most boundary value problems 
  one should use {\tt IPS=4}.
  Boundary conditions must be
  specified in the user-supplied routine {\tt BCND}
  and integral constraints in {\tt ICND}. The {\cal AUTO}-constants
  {\tt NBC} and {\tt NINT} must be given correct values.
%=====================================================================
\item[-] {\tt IPS=9}~:
  This option is used in connection with the {\cal HomCont} algorithms
  described in 
  Chapters~\ref{ch:HomCont}-\ref{ch:HomCont_rev}
  for the  detection and continuation of homoclinic bifurcations.\\  
 (Demos {\tt san}, {\tt mtn}, {\tt kpr}, {\tt cir}, {\tt she},
  {\tt rev}.)
%=====================================================================
\item[-] {\tt IPS=11}~: 
  Spatially uniform solutions of a system of parabolic PDEs,
  with detection of traveling wave bifurcations.
  The user need only define the nonlinearity (in routine {\tt FUNC}),
  initialize the wave speed in {\tt PAR(10)}, initialize the diffusion 
  constants in {\tt PAR(15,16,$\cdots$)}, and set a free equation parameter 
  in {\tt ICP}(1).
  (Run~2 of demo {\tt wav}.)
%=====================================================================
\item[-] {\tt IPS=12}~: 
  Continuation of traveling wave solutions to a system of parabolic PDEs.
  Starting data can be a Hopf bifurcation point from a previous run 
  with {\tt IPS}=11, or a traveling wave from a previous run with {\tt IPS}=12.
  (Run~3  and Run~4 of demo {\tt wav}.)
%=====================================================================
\item[-] {\tt IPS=14}~:  
  Time evolution for a system of parabolic PDEs subject to periodic 
  boundary conditions. 
  Starting data may be solutions from a previous run with {\tt IPS}=12 or 14. 
  Starting data can also be specified in {\tt STPNT}, in which case
  the wave length must be specified in {\tt PAR(11)}, and the diffusion
  constants in {\tt PAR(15,16,$\cdots$)}.
  {\cal AUTO} uses {\tt PAR(14)} for the time variable.
  {\tt DS}, {\tt DSMIN}, and {\tt DSMAX} govern the pseudo-arclength continuation 
  in the space-time variables.
  Note that the time discretization is only first order accurate, 
  so that results should be carefully interpreted. 
  Indeed, this option is mainly intended for the detection of stationary 
  waves.
  (Run~5 of demo {\tt wav}.)
%=====================================================================
\item[-] {\tt IPS=15}~:   
  Optimization of periodic solutions. The integrand of the
  objective functional must be specified in the user supplied
  routine {\tt FOPT}. Only {\tt PAR(1-9)} should be used for
  problem parameters. {\tt PAR(10)} is the value of the objective
  functional, {\tt PAR(11)} the period, {\tt PAR(12)} the norm of the
  adjoint variables, {\tt PAR(14)} and {\tt PAR(15)} are internal optimality
  variables. {\tt PAR(21-29)} and {\tt PAR(31)} are used to monitor the 
  optimality functionals associated with the problem parameters 
  and the period. 
  Computations can be started at a solution computed with {\tt IPS}=2
  or {\tt IPS}=15.
  For a detailed example see demo {\tt ops}.
%=====================================================================
\item[-] {\tt IPS=16}~:
  This option is similar to {\tt IPS}=14, except that the user supplies the
  boundary conditions. Thus this option can be used for 
  time-integration of parabolic systems subject to 
  user-defined boundary conditions. For examples see the first runs
  of demos {\tt pd1}, {\tt pd2}, and {\tt bru}. Note that
  the space-derivatives of the initial conditions must
  also be supplied in the user supplied routine {\tt STPNT}. 
  The initial conditions must satisfy the boundary conditions.
  This option is mainly intended for the detecting stationary solutions.
%=====================================================================
 \item[-] {\tt IPS=17}~: 
  This option can be used to continue stationary solutions
  of parabolic systems obtained from an evolution run with {\tt IPS}=16.
  For examples see the second runs of demos {\tt pd1} and {\tt pd2}.
\end{itemize}
%=====================================================================


\section{ Output Control.} \label{sec:Output_control}
\subsection{\texttt{unames}}  \label{sec:unames}
This constant, where {\tt unames=\{i1:s1,i2:s2\}}, changes the names in all
output from {\tt U(i1)} to {\tt s1}, from {\tt U(i2)} to {\tt s2}, and so on.
You can also refer to these strings, instead of the corresponding indices,
in the constants \texttt{U} and \texttt{THU}.

\subsection{\texttt{parnames}}  \label{sec:parnames}
This constant, where {\tt parnames=\{i1:s1,i2:s2\}}, changes the names in all
output from {\tt PAR(i1)} to {\tt s1}, from {\tt PAR(i2)} to {\tt s2},
and so on.
You can also refer to these strings, instead of the corresponding indices,
in the constants \texttt{ICP}, \texttt{THL}, and \texttt{UZR}.

\subsection{\texttt{e}}  \label{sec:e}
This constant, where {\tt e='xxx'}, is only for use by post-processors:
it denotes the name of the equations file and is stored
in the bifurcation diagram file (\filef{fort.7}), so restarts in the
Python interface are possible without needing to specify the equations
file.

\subsection{\texttt{sv}} \label{sec:sv}
This constant specifies a string to write the output to instead of
{\tt fort.7}, {\tt fort.8}, and {\tt fort.9}: if {\tt sv='xxx'}, then
the output files are
{\tt b.xxx}, {\tt s.xxx}, and {\tt d.xxx}.

\subsection{\texttt{NPR}}  \label{sec:NPR}
 This constant can be used to regularly write {\tt fort.8} plotting and restart 
 data.  
 IF {\tt NPR}$>$0 then such output is written every {\tt NPR} steps.
 IF {\tt NPR}$=$0 or if {\tt NPR}$\ge${\tt NMX} then no such output is written.
 Note that special solutions, such as branch points, folds, end points, etc., 
 are always written in {\tt fort.8}.
 Furthermore, one can specify parameter values where plotting and restart 
 data is to be written; see Section~\ref{sec:UZR}.
 For these reasons, and to limit the output volume, it is recommended that
 {\tt NPR} output be kept to a minimum.

\subsection{\texttt{IBR}} \label{sec:IBR} 
 This constant specifies the initial branch number {\tt BR} that is
 used. The default {\tt IBR=0} means that that this number is
 determined automatically.

\subsection{\texttt{LAB}} \label{sec:LAB} 
 This constant specifies the initial label number {\tt LAB} that is
 used. The default {\tt LAB=0} means that that this number is
 determined automatically. Using {\tt LAB=1} means you do not need
 to relabel after a non-appended continuation if this is desired.

\subsection{\texttt{IIS}} \label{sec:IIS} 
 This constant controls the amount of information printed in {\tt fort.8}~:
 the greater {\tt IIS} the more solutions contain the corresponding
 vector giving the direction of the branch. The direction of the
 branch is necessary for restart points when switching branches, but
 make the solution file almost two times bigger than necessary when
 switching branches is never performed from solutions in this file.

\begin{itemize}
\item[-] {\tt IIS=0}~:
  The direction of the branch is never provided.
\item[-] {\tt IIS=1}~:
  The direction of the branch is only provided at special points from
  which branch switching can be performed (types LP (boundary value
  problems only), BP, PD, TR).
\item[-] {\tt IIS=2}~:
  The direction of the branch is provided at all special points but
  not at regular points without a type label.
\item[-] {\tt IIS=3}~:
  The direction of the branch is always provided. This is the default
  setting.
\end{itemize}

\subsection{\texttt{IID}} \label{sec:IID} 
 This constant controls the amount of diagnostic output printed in {\tt fort.9}~:
 the greater {\tt IID} the more detailed the diagnostic output.
\begin{itemize}
\item[-] {\tt IID=0}~:  
  No diagnostic output.
\item[-] {\tt IID=1}~:  
  Minimal diagnostic output. This setting is not recommended.
\item[-] {\tt IID=2}~: 
  Regular diagnostic output. This is the recommended value of {\tt IID}.
\item[-] {\tt IID=3}~: 
  This setting gives additional diagnostic output for algebraic equations,
  namely the Jacobian and the residual vector at the starting point.
  This information, which is printed at the beginning of {\tt fort.9},
  is useful for verifying whether the starting solution in {\tt STPNT} is indeed 
  a solution.
\item[-] {\tt IID=4}~: 
  This setting gives additional diagnostic output for differential equations,
  namely the reduced system and the associated residual vector. 
  This information is printed for every step and for every Newton iteration,
  and should normally be suppressed.
  In particular it can be used to verify whether the starting solution
  is indeed a solution. For this purpose, the stepsize {\tt DS} should
  be small, and one should look at the residuals printed in the {\tt fort.9}
  output-file. (Note that the first residual vector printed in {\tt fort.9} may
  be identically zero, as it may correspond to the computation of the starting
  direction. Look at the second residual vector in such case.)
  This residual vector has dimension 
  {\tt NDIM}+{\tt NBC}+{\tt NINT}+1, which accounts for the {\tt NDIM}
  differential equations, the {\tt NBC} boundary conditions, the {\tt NINT} user-defined
  integral constraints, and the pseudo-arclength equation.
  For proper interpretations of these data one may want to refer to the solution
  algorithm for solving the collocation system, as described in
  \citename{DoKeKe:91b} \citeyear{DoKeKe:91b}.
\item[-] {\tt IID=5}~:
  This setting gives very extensive diagnostic output for differential equations,
  namely, debug output from the linear equation solver.
  This setting should not normally be used as it may result
  in a huge {\tt fort.9} file. It gives incomplete results when
  used in combination with MPI parallellization.
\end{itemize}

\subsection{\texttt{IPLT}}  \label{sec:IPLT}
 This constant allows redefinition of the principal solution measure, which is
 printed as the second (real) column in the screen output and in the {\tt fort.7}
 output-file~:
 
\begin{itemize}
\item[-]
  If {\tt IPLT} = 0 then the $L_2$-norm is printed. Most demos use this setting.
  For algebraic problems, the standard definition of $L_2$-norm is used.
  For differential equations, the $L_2$-norm is defined as 
  $$ \sqrt{ \int_0^1 \sum_{k=1}^{NDIM} U_k(x)^2 ~ dx}~.$$
  Note that the interval of integration is $[0,1]$, the standard interval
 used by AUTO. For periodic solutions the independent variable is transformed
 to range from 0 to 1, before the norm is computed. The AUTO-constants THL(*) 
 and THU(*) (see Section~\ref{sec:THL} and Section~\ref{sec:THU})
 affect the definition of the $L_2$-norm.
\item[-]
  If 0 $<$ {\tt IPLT} $\le$ {\tt NDIM} then the maximum of the {\tt IPLT}'th solution component 
  is printed.
\item[-]
  If $-${\tt NDIM} $\le$ {\tt IPLT} $<$0 then the minimum of the {\tt IPLT}'th solution component
  is printed.  (Demo {\tt fsh}.)
\item[-]
  If {\tt NDIM} $<$ {\tt IPLT} $\le$ 2*{\tt NDIM} then the integral 
  of the ({\tt IPLT}$-${\tt NDIM})'th 
  solution component is printed. (Demos {\tt exp}, {\tt lor}.)
\item[-]
  If 2*{\tt NDIM} $<$ {\tt IPLT} $\le$ 3*{\tt NDIM} 
  then the $L_2$-norm of the ({\tt IPLT}$-${\tt NDIM})'th 
  solution component is printed. (Demo {\tt frc}.)
\end{itemize}

Note that for algebraic problems the maximum and the minimum are identical.
Also, for ODEs the maximum and the minimum of a solution component are generally
much less accurate than the $L_2$-norm and component integrals.
Note also that the routine {\tt PVLS} provides a second, more general way
of defining solution measures; see Section~\ref{sec:Parameter_over_specification}.


\subsection{\texttt{UZR}} \label{sec:UZR} 
 This constant allows the setting of parameter values at which labeled plotting 
 and restart information is to be written in the {\tt fort.8} output-file.
 Optionally, it also allows the computation to terminate at such a point.

\begin{itemize}
\item[-]
 Set {\tt UZR=\{\}} if no such output is needed. Many demos use this setting.
\item[-]
 Else one must enter pairs,
            ~\{{\it Parameter-Index} : {\it Parameter-Value}, ...\}~,\\
 or indices with lists of values,
            ~\{{\it Parameter-Index} : \[{\it Parameter-Value}, ...\], ...\}~,
 to designate the parameters and the parameter
 values at which output is to be written.
 For examples see demos {\tt exp}, {\tt int}, and {\tt fsh}.
\item[-]
 If such a parameter index is preceded by a minus sign then the computation will
 terminate at such a solution point. See also \texttt{STOP} in
 Section~\ref{sec:STOP} above and \texttt{UZSTOP} in
 Section~\ref{sec:UZSTOP} below for alternative termination methods.
 (Demos {\tt pen} and {\tt bru}.)
\end{itemize}

Note that {\tt fort.8} output can also be written at selected values of 
overspecified parameters. For an example see demo {\tt pvl}.
For details on overspecified parameters see 
Section~\ref{sec:Parameter_over_specification}.

\subsection{\texttt{UZSTOP}} \label{sec:UZSTOP}
 This constant specifies parameter values in the same way as
 \texttt{UZR} in Section~\ref{sec:UZR} above, but the computation
 will always terminate if any solution point that is specified is
 encountered.

%=====================================================================

\section{ Quick reference}
\vspace{-2.5mm}
\begin{tabular}{|l|l|}
\hline
{\tt e}, {\tt s}, {\tt dat}, {\tt sv} & Define file names: equation
prefix (.f,.f90,.c), restart solution suffix (s.), \\
& user data prefix (.dat), output suffix (b.,s.,d.)\\
\hline
{\tt unames}, {\tt parnames} & Dictionary (mapping) of U(*) and PAR(*)
to user-defined names\\
\hline
{\tt NDIM} & Problem dimension \\
{\tt IPS}  & Problem type; 0=AE, 1=FP(ODEs), -1=FP(maps), 2=PO,
           -2=IVP,\\
           & 4=BVP, 7=BVP with Floquet multipliers, 5=algebraic
           optimization \\
 	   & problem, 15=optimization of periodic solutions \\
{\tt IRS}, {\tt TY}  & Start solution label, start solution type\\
{\tt ILP}  & Fold detection; 1=on, 0=off \\
\hline
{\tt ICP}  & Continuation parameters \\
\hline
{\tt NTST} & \# mesh intervals \\
{\tt NCOL} & \# collocation points \\
{\tt IAD} & Mesh adaption every IAD steps; 0=off \\
{\tt ISP} & Bifurcation detection; 0=off, 1=BP(FP), 3=BP(PO,BVP), 2=all \\
{\tt ISW} & Branch switching; 1=normal, -1=switch branch (BP, HB, PD),\\
          & 2=switch to two-parameter continuation (LP, BP, HB, TR) \\
          & 3=switch to three-parameter continuation (BP) \\
{\tt IPLT} & Select principal solution measure \\
{\tt NBC} & \# boundary conditions \\
{\tt NINT} & \# integral conditions \\
\hline
{\tt NMX} & Maximum number of steps \\
{\tt RL0, RL1} & Parameter interval $ RL0 \leq \lambda \leq RL1$ \\
{\tt A0, A1} & Interval of principal solution measure $ A0 \leq
\Vert\cdot\Vert \leq A1$ \\
\hline
{\tt NPR} & Print and save restart data every NPR steps \\
{\tt MXBF} & Automatic branch switching for the first MXBF bifurcation \\
 	  & points if IPS=0, 1 	 \\
{\tt IBR}, {\tt LAB} & Set initial branch and label number; 0=automatic \\
{\tt IIS} & Control solution output of branch direction vector; 0=never, 3=always \\
{\tt IID} & Control diagnostic output; 0=none, 1=little, 2=normal, 4=extensive \\
{\tt ITMX} & Maximum \# of iterations for locating special solutions/points \\
{\tt ITNW} & Maximum \# of correction steps \\
{\tt NWTN} & Corrector uses full newton for NWTN steps \\
{\tt JAC}  & User defines derivatives; 0=no, 1=yes \\
\hline
{\tt EPSL}, {\tt EPSU}, {\tt EPSS} & Convergence criterion:
parameters, solution components, special points\\
\hline
{\tt DS}  & Start step size \\
{\tt DSMIN, DSMAX} & Step size interval $\mathtt{DSMIN} \leq h \leq \mathtt{DSMAX}$ \\
{\tt IADS} & Step size adaption every IADS steps; 0=off \\
\hline
{\tt NPAR} & Maximum number of parameters \\
{\tt THL, THU} & list of parameter and solution weights \\
\hline
{\tt UZR}, {\tt UZSTOP} & list of values for user defined output\\
{\tt SP}, {\tt STOP} & list of bifurcations to check and bifurcation stop
conditions\\
\hline
{\tt NUNSTAB}, {\tt NSTAB} & HomCont: unstable and stable manifold dimensions\\
{\tt IEQUIB}, {\tt ITWIST}, {\tt ISTART} & HomCont: control solution types
adjoint, starting\\
{\tt IREV}, {\tt IFIXED}, {\tt IPSI} & HomCont: control reversibility, fixed
parameters, test functions\\
\hline
\end{tabular}

 

%==============================================================================
%==============================================================================
\chapter{ Notes on Using {\cal AUTO}.}  \label{ch:Notes_on_Using_AUTO}
%==============================================================================
%==============================================================================
\section{ Restrictions on the Use of \texttt{PAR}.} \label{sec:Restrictions_on_PAR}
The array {\tt PAR} in the user-supplied routines is available
for equation parameters that the user wants to vary at some point
in the computations.
In any particular computation the free parameter(s) must be designated
in {\tt ICP}; see Section~\ref{sec:Free_parameters}.
The following restrictions apply~:

\begin{itemize}
\item[-]
  The default maximum number of parameters, \parf{NPAR} has a
  pre-defined value in \filef{auto/07p/ include/auto.h},
  of \parf{NPARX}=36.
  Any change \parf{NPARX} must be followed by recompilation of {\cal AUTO}.
\item[-]
  Generally one should avoid certain parameters for equation parameters,
  as {\cal AUTO} may need those internally, as follows:
\begin{description}
\item[\parf{IPS}=0,4:]
  No additional parameters with indices less than or equal
  to \parf{NPAR} are reserved.
\item[\parf{IPS}=$-$1,1,2,7:]
  \AUTO reserves \parf{PAR(11)} to store the period for stationary
  solutions at Hopf bifurcations only and continuously for periodic
  orbits. For \parf{IPS}=2 and \parf{IPS}=7, \AUTO also
  reserves \parf{PAR(12)} to store the angle of the torus
  at torus bifurcations.
\item[\parf{IPS}=$-$2:]
  The integration time is stored in \parf{PAR(14)}.
\item[\parf{IPS}=5:]
  The value of the objective functional is stored in \parf{PAR(10)}.
\item[\parf{IPS}=9:]
  The length in time of the truncated homoclinic or heteroclinic orbit
  is stored in \parf{PAR(11)}. For the adjoint variational equations,
  \parf{PAR(10)} is used. The equilibria are stored
  in \parf{PAR(11)} to \parf{PAR(11+NDIM-1)}/\parf{PAR(11+2*NDIM-1)}
  (homoclinic/heteroclinic). Test function values may be stored in
  \parf{PAR(21)} to \parf{PAR(36)}. Homoclinic branch switching uses
  \parf{PAR(20)} and higher to store time intervals and gap sizes.
\item[\parf{IPS}=11,12:]
  The wave speed is in \parf{PAR(10)}, and the diffusion 
  constants in \parf{PAR(15,16,$\cdots$)}. The period (for periodic
  solutions and at Hopf bifurcations) is stored in \parf{PAR(11)}.
\item[\parf{IPS}=14,16:]
  \AUTO uses \parf{PAR(14)} for the time variable, and the diffusion 
  constants are in \parf{PAR(15,16,$\cdots$)}. The period is stored in
  \parf{PAR(11)}. The previous time for each step is stored in \parf{PAR(12)}.
\item[\parf{IPS}=17:]
  The diffusion constants are in \parf{PAR(15,16,$\cdots$)}.
  The period is stored in \parf{PAR(11)}.
\item[\parf{IPS}=15:]
  Only \parf{PAR(1-9)} should be used for problem parameters.
  \parf{PAR(10)} is the value of the objective
  functional, \parf{PAR(11)} the period, \parf{PAR(12)} the norm of the
  adjoint variables, \parf{PAR(14)} and \parf{PAR(15)} are internal optimality
  variables. \parf{PAR(21-29)} and \parf{PAR(31)} are used to monitor the 
  optimality functionals associated with the problem parameters and
  the period.
\end{description}
\end{itemize}

\section{ Efficiency.} \label{sec:Efficiency}
In {\cal AUTO}, efficiency has at times been sacrificed for generality of programming.
This applies in particular to computations in which {\cal AUTO} generates
an extended system, for example, computations with {\tt ISW}=2.
However, the user has significant control over computational efficiency,
in particular through judicious choice of the {\cal AUTO}-constants  
{\tt DS}, {\tt DSMIN}, and {\tt DSMAX}, and, for ODEs, {\tt NTST} and {\tt NCOL}.
Initial experimentation normally suggests appropriate values.

Slowly varying solutions to ODEs can often 
be computed with remarkably small values of {\tt NTST} and {\tt NCOL}, 
for example, {\tt NTST}=5,  {\tt NCOL}=2.
Generally, however, it is recommended to set {\tt NCOL}=4,
and then to use the ``smallest'' value of {\tt NTST} that maintains convergence.

The choice of the pseudo-arclength stepsize parameters
{\tt DS}, {\tt DSMIN}, and {\tt DSMAX}
is highly problem dependent.
Generally, {\tt DSMIN} should not be taken too small,
in order to prevent excessive step refinement in case of non-convergence.
It should also not be too large, in order to avoid instant non-convergence.
{\tt DSMAX} should be sufficiently large, in order to reduce computation time
and amount of output data.
On the other hand, it should be sufficiently small, in order to prevent
stepping over bifurcations without detecting them.
For a given equation, appropriate values of these constants 
can normally be found after some initial experimentation.

The constants {\tt ITNW}, {\tt NWTN}, {\tt THL}, {\tt EPSU}, {\tt EPSL}, {\tt EPSS} 
also affect efficiency.
Understanding their significance is therefore useful; 
see Section~\ref{sec:Tolerances} and Section~\ref{sec:step_size}.
Finally, it is recommended that initial computations be done with 
{\tt ILP=0}; no fold detection;
and {\tt ISP}=1; no bifurcation detection for ODEs.
 
\section{ Correctness of Results.} \label{sec:Correctness}
{\cal AUTO}-computed solutions to ODEs are almost always structurally correct,
because the mesh adaption strategy, if {\tt IAD}$>$0, safeguards to some extent
against spurious solutions.
If these do occur, possibly near infinite-period orbits,
the unusual appearance of the solution family typically serves as a warning.
Repeating the computation with increased {\tt NTST} is then recommended.

\section{ Bifurcation Points and Folds.} \label{sec:Bifurcations}
It is recommended that the detection of folds 
and bifurcation points be initially disabled.
For example, if an equation has a ``vertical'' solution family
then {\cal AUTO} may try to locate one fold after another.

Generally, degenerate bifurcations cannot be detected.
Furthermore, bifurcations that are close to each other may not
be noticed when the pseudo-arclength step size is not sufficiently small.
Hopf bifurcation points may go unnoticed if no clear crossing of
the imaginary axis takes place. This may happen when there are other
real or complex eigenvalues near the imaginary axis and when 
the pseudo-arclength step is large compared to the rate
of change of the critical eigenvalue pair.
A typical  case is a Hopf bifurcation close to a fold.
Similarly, Hopf bifurcations may go undetected if switching from
real to complex conjugate, followed by crossing of the imaginary
axis, occurs rapidly with respect to the pseudo-arclength step size.
Secondary periodic bifurcations may not be detected for similar reasons.
In case of doubt, carefully inspect the contents of the diagnostics file
{\tt fort.9}.
 
\section{ Floquet Multipliers.} \label{sec:Floquet_multipliers}

{\cal AUTO} extracts an approximation to the linearized Poincar\'e map from 
the Jacobian of the linearized collocation system that arises in Newton's method.
This procedure is very efficient; the map is computed at negligible extra cost.
The linear equations solver of {\cal AUTO} is described in 
\citename{DoKeKe:91b} \citeyear{DoKeKe:91b}.
The actual Floquet multiplier solver was written by
\citename{Fa:94} \citeyear{Fa:94}.
For a detailed description of the algorithm see 
\citename{FaJe:91} \citeyear{FaJe:91}.

For periodic solutions, the exact linearized Poincar\'e map always has 
a multiplier $z=1$.
A good accuracy check is to inspect this 
multiplier in the diagnostics output-file {\tt fort.9}.
If this multiplier becomes inaccurate then the automatic detection 
of potential secondary periodic bifurcations (if {\tt ISP}=2) is discontinued 
and a warning is printed in {\tt fort.9}.
It is strongly recommended that the contents of this file be
habitually inspected,
in particular to verify whether solutions labeled as BP or TR 
(cf.~Table~\ref{tbl:Solution_Types}) have indeed  been correctly classified.
 
\section{ Memory Requirements.} \label{sec:Memory_requirements}
The run-time memory requirements depend on the values the user set in
the constants file and are roughly proportional to the value
${\tt NTST}\times({\tt NDIM}\times({\tt NCOL}+1)+{\tt NBC})\times
({\tt NDIM}\times{\tt NCOL}+{\tt NINT}+1)$.

%==============================================================================
%==============================================================================
\chapter{ \AUTO Demos : Tutorial.} \label{ch:Demos:_Tutorial}
%==============================================================================
%==============================================================================
\newpage
\section{ Introduction.} \label{sec:Tutorial_Introduction}
The directory {\tt auto/07p/demos} has a large number of subdirectories,
for example {\tt ab}, {\tt pp2}, {\tt exp}, etc.,
each containing all necessary files for certain illustrative calculations.
Each subdirectory, say {\tt xxx}, corresponds to a particular equation
and contains one equations-file \filef{xxx.\{f90,f,c\}}
and one or more constants-files \filef{c.xxx.i}, 
one for each successive run of the demo.
You also find \python script files \filef{xxx.auto} and
\filef{clean.auto}: the command \filef{auto xxx.auto} runs the demo,
and the command \filef{auto clean.auto} deletes all generated files.
To see how the equations have been programmed, inspect the equations-file. 
To understand in detail how {\cal AUTO} is instructed to carry out a 
particular task, inspect the appropriate constants-file and \python
script.
In this chapter we describe the tutorial demo {\tt cusp} in detail.
A brief description of other demos is given in later chapters.


\section{ cusp : A Tutorial Demo.} \label{sec:Demos_cusp}
This demo illustrates the computation of 
stationary solutions, locating saddle-node bifurcations of these
solutions, and the continuation of a saddle-node bifurcation in two
parameters.\\
The cusp normal form equation is given by
\begin{equation}
  \dot x = \mu + \lambda x - x^3.
\end{equation}

\section{ Copying the Demo Files.}  \label{sec:Tutorial_copying}
The commands listed in Table~\ref{tbl:demo_cusp_1}
will copy the demo files to your work directory.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  {\cal Unix}-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{auto}  & start the AUTO-07p Command Line User Interface\\ 
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
  \commandf{cd } & go to main directory (or other directory).\\
  \commandf{mkdir cusp}  & \parbox[t]{3in}{create an empty work directory.  
                            Note:  the '!' is used to signify a command 
                            which is sent to the shell.\vspace{0.2cm}}\\ 
  \commandf{cd cusp}  & change to the work directory.\\

  \commandf{demo('cusp')}  & copy the demo files to the work directory.\\
\hline
%==============================================================================
\end{tabular}
\caption{Copying the demo \filef{cusp} files.}
\label{tbl:demo_cusp_1}
\end{center}
\end{table}

Typing \commandf{ls} reveals the existence of 5 files:
\begin{enumerate}
\item
\commandf{cusp.f90}: This file contains the differential equations
and the initial values. If you inspect it, you will see that only two
routines are used. The subroutine {\tt FUNC} specifies the actual
differential equation. The routine {\tt STPNT} gives {\cal AUTO}
the initial values of {\tt PAR(1)}$=\lambda$ and
{\tt PAR(2)}$=\mu$, which
are $1.0$ and $0.0$, and the initial value of $x$, which is $0$.
For your own models you would generally copy another equation file
and then only change the pieces that actually define the equation.

\item
\commandf{c.cusp}: The initial computational constants are stored
in this file. Most importantly, you see that the dimension of the
problem (\parf{NDIM}) is set to 1, and the problem type \parf{IPS}
is set to 1 to specify continuation of a stationary solution.
The constants given by \parf{ICP} specify the parameters that are
used for the continuation. In this case these are 'mu' for $\mu$ and
'lambda' for $\lambda$, which correspond to the indices 2 and 1,
respectively, using the constant \parf{parnames}.
Since initially we only really continue in one parameter ($\mu$),
the second parameter $\lambda$ is \emph{overspecified}.
Another important constant is the initial step size {\tt DS}: as it is
positive, we initally continue in the positive $\mu$ direction.

\item
\commandf{cusp.auto}: A script with Python CLUI commands that steer
the calculation.

\item
\commandf{clean.auto}: A script that cleans the directory of all
generated files.

\item
\commandf{autorc}: A file that contains default settings for
the 2-dimensional plotting tool {\cal PyPLAUT}.

\item
\commandf{plaut04.rc}: A file that contains default settings for
the 3-dimensional plotting tool {\cal PLAUT04}.

\end{enumerate}

\section{ Executing all Runs Automatically.} \label{sec:Tutorial_all_runs}
To execute all prepared runs of demo \filef{cusp},
simply type the command given in Table~\ref{tbl:demo_cusp_2}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{demofile('cusp.auto')}  & \parbox[t]{3in}{execute all runs of demo \filef{cusp} interactively\vspace{0.2cm}}\\ 
\hline
%==============================================================================
\end{tabular}
\caption{Executing all runs of demo \filef{cusp}.}
\label{tbl:demo_cusp_2}
\end{center}
\end{table}

The command in Table~\ref{tbl:demo_cusp_2} begins
a tutorial which will proceed one step each time
the user presses a key.  Each step consists of a
single \AUTO command preceded by instructions as
to what action the command performs.
The tutorial script \filef{cusp.auto} performs the
demo by reading in a single \AUTO constants file
and then interactively modifying it to perform
each of the demo. The essential commands in \filef{cusp.auto}
are given in Table~\ref{tbl:demo_cusp_4a}.

Note that there are four separate runs, where each \commandf{run}
command performs a run.
In the first run, a branch of stationary solutions is traced out.
Along it, one fold (LP) (limit point, or in this case, a saddle-node
bifurcation) is located. The free parameter is $\mu$.
The other parameter $\lambda$ remains fixed in this run.
Note also that only special, labeled solution points are printed on the screen.
Detailed results are saved in the \python variable \parf{mu}.

The second run does the same thing but now in the negative direction
of $\mu$, i.e., backwards instead of forwards. The backwards
continuation is appended to the forwards continuation in the
data-files. Afterwards we perform a relabelling to make sure that we have
unique labels for each special solution. Next the relabelled result is saved
to the data-files \filef{b.mu}, \filef{s.mu}, and \filef{d.mu}.

The results are then plotted on the screen. Pressing the enter key
at the command line causes an automatic $\mu$ vs. $x$ display that
shows the two fold points at labels 2 and 7.

In the third run, the fold detected in the first run is followed in
the two parameters $\mu$ and $\lambda$.
We know that label 2, with solution \parf{mu(2)} is the right
solution to start from. However, we did not know this number in
advance, and moreover, in sensitive cases, it can be different on
different computer types. Another way to specify the starting label
is to use the notation \parf{mu('LP1')}: this specifies the first
LP-labelled solution of all solutions in \parf{mu}.

Furthermore the command that accomplishes
this must change the constant {\tt ISW} of the constants file: 
it must be set to 2 to cause a two-parameter continuation.

The fourth run continues this branch in opposite direction.
The detailed results of these continuations are saved
in the data-files \filef{b.cusp}, \filef{s.cusp}, and \filef{
d.cusp}. Finally, a plot of the cusp is produced.

The numerical results are given below
in somewhat abbreviated form.
Some differences in output are to be expected on different machines.
This does not mean that the results have different accuracy, but simply
that arithmetic differences have accumulated from step to step, possibly
leading to different step size decisions.

Next, reset the work directory, by typing the command given
in Table~\ref{tbl:demo_cusp_3}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{clean()}  & remove temporary files of demo \filef{cusp} \\ 
  \commandf{delete('mu')}  & remove 'mu' data-files of demo \filef{cusp} \\ 
  \commandf{delete('cusp')}  & remove 'cusp' data-files of demo \filef{cusp} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Cleaning the demo \filef{cusp} work directory.}
\label{tbl:demo_cusp_3}
\end{center}
\end{table}

\begin{center}
\vspace{-0.2in}
\begin{verbatim}
# Run forwards
 
  BR    PT  TY  LAB       mu         L2-NORM          x           lambda    
   1     1  EP    1   0.00000E+00   0.00000E+00   0.00000E+00   1.00000E+00
   1    14  LP    2   3.84900E-01   5.77360E-01  -5.77360E-01   1.00000E+00
   1    20        3   1.26582E-01   9.29410E-01  -9.29410E-01   1.00000E+00
   1    40        4  -1.38347E+00   1.40803E+00  -1.40803E+00   1.00000E+00
   1    47  UZ    5  -1.99999E+00   1.52138E+00  -1.52138E+00   1.00000E+00

# Run backwards
 
  BR    PT  TY  LAB       mu         L2-NORM          x           lambda    
   1     1  EP    1   0.00000E+00   0.00000E+00   0.00000E+00   1.00000E+00
   1    14  LP    2  -3.84900E-01   5.77360E-01   5.77360E-01   1.00000E+00
   1    20        3  -1.26582E-01   9.29410E-01   9.29410E-01   1.00000E+00
   1    40        4   1.38347E+00   1.40803E+00   1.40803E+00   1.00000E+00
   1    47  UZ    5   1.99999E+00   1.52138E+00   1.52138E+00   1.00000E+00

# Forward continuation of the first fold in two parameters
 
  BR    PT  TY  LAB       mu         L2-NORM          x           lambda    
   2    20       11   1.09209E+00   8.17354E-01  -8.17354E-01   2.00420E+00
   2    34  UZ   12   1.99995E+00   9.99991E-01  -9.99991E-01   2.99995E+00

# Backward continuation of the fold in two parameters

  BR    PT  TY  LAB       mu         L2-NORM          x           lambda    
   2    20       11   5.42543E-02   3.00470E-01  -3.00470E-01   2.70847E-01
   2    29  CP   12  -2.02768E-12   1.00472E-04   1.00472E-04   3.02837E-08
   2    40       13  -9.09414E-02   3.56925E-01   3.56925E-01   3.82187E-01
   2    60       14  -5.73716E-01   6.59512E-01   6.59512E-01   1.30487E+00
   2    80       15  -1.68023E+00   9.43582E-01   9.43582E-01   2.67104E+00
   2    85  UZ   16  -1.99995E+00   9.99992E-01   9.99992E-01   2.99995E+00

\end{verbatim}
\end{center}

The CLUI was used to generate the constants
file at runtime.  In the example below, the constant file \filef{c.cusp}
will be read in, and the CLUI will be used to make the appropriate
changes to perform the calculation.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{cusp = load('cusp')}  & load the problem definition  \filef{cusp} \\ 
  \commandf{mu = run(cusp)}  & execute the run \\
  \commandf{mu = mu + run(cusp,DS='-')}  & execute the run backwards and \\
    & append the results to \parf{mu}\\ 
  \commandf{mu = rl(mu) } & relabel solutions in mu \\
  \commandf{save(mu, 'mu')} & save the results
                   in the files \filef{b.mu}, \filef{s.mu}, and \filef{d.mu}\\ 
  \commandf{lp1 = load(mu('LP1'), ISW=2)} & use the first fold (LP) in
    \parf{mu} as the restart solution,\\
  & and change ISW to 2.\\
  \commandf{cusp = run(lp1) } & execute the third run of demo \filef{cusp} \\ 
  \commandf{cusp = cusp + run(lp1,DS='-') } & execute the fourth run
  of demo \filef{cusp} \\ 
  \commandf{save(cusp,'cusp')} & save the results
                   in the files \filef{b.cusp}, \filef{s.cusp}, and \filef{d.cusp}\\ 
\hline
%==============================================================================
\end{tabular}
\caption{Selected runs of demo \filef{cusp}.}
\label{tbl:demo_cusp_4a}
\end{center}
\end{table}

\section{ Plotting the Results with \AUTO.} \label{sec:Tutorial_plotting}
The bifurcation diagram computed in the runs above
was stored in the files \filef{b.mu} and \filef{b.cusp},
while each labeled solution is fully stored in \filef{s.mu} and
\filef{s.cusp}.
To use \AUTO to graphically inspect these data-files.
type the \AUTO-command given in Table~\ref{tbl:demo_cusp_7}.
The saved plots are shown in Figure~\ref{fig:cusp_1}
and in Figure~\ref{fig:cusp_2}.

Figure~\ref{fig:cusp_1} shows the bifurcation diagrams for the first
run, and Figure~\ref{fig:cusp_2} for the second run.

The plotting window consists of a menubar at the top, a plotting area,
and a control panel with four control widgets at the bottom.  By
default the first two columns in the bifurcation diagram output
are plotted against each other. To obtain a $\mu$ versus $x$
bifurcation diagram you need to plot column 'mu' versus column 'x'.
You can do that by changing the ``Y'' box to say ``[x]'', either by
typing it there, by using the menu obtained by clicking the
downwards facing triangle or by using a scripted command as used
in \filef{cusp.auto}.
You can also change the mode of
the plotting tool from ``bifurcation'' to ``solution''.  This is
accomplished by clicking on the widget marked ``Type'' on the bottom
control panel and setting it from ``bifurcation'' to ``solution''.  In
the plotting window will appear a plot of the first labeled solution,
in this case just a point. You can plot all points by changing
the ``Label'' to ``[1,2,3,4,5,6,7,8,9,10]''.

The plotting tool can also be used to create Postscript files from
plots by selecting the ``File'' on the menubar and then selecting the
``Save Postscript...'' from the drop down menu.
This will bring up
a dialog into which the user can enter the filename of the postscript
file to save the plot in.  
When using matplotlib
you can also click on the floppy disk icon to save using a variety of
file formats.
Further information on the plotting tool can be found in
Section~\ref{clui:plotting}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{plot(mu)} & run \AUTO to graph the contents of \parf{mu}\\
  \commandf{plot("mu")} & run \AUTO to graph the contents of
  \filef{b.mu} and \filef{s.mu}; \\  
  & (this is the same as \commandf{plot(loadbd("mu"))})\\
%==============================================================================
\hline
\end{tabular}
\caption{Commands for plotting 
   or the bifurcation diagram and solutions of the \python variable \parf{mu},
and the files \filef{b.mu} and \filef{s.mu}}
\label{tbl:demo_cusp_7}
\end{center}
\end{table}

\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/cusp1}}
\caption{The first bifurcation diagram of demo \filef{cusp}.}
\label{fig:cusp_1}
\end{figure}
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/cusp2}}
\caption{The second bifurcation diagram of demo \filef{cusp}.}
\label{fig:cusp_2}
\end{figure}

\section{ Plotting the Results with \AUTO in 3D.}
Whilst not very useful for this simple example, you can also plot
your results in 3D, using the \commandf{plot3} command ({\cal PLAUT04}), for example
\commandf{plot3('mu')}. Unlike the PyPLAUT tool by default, this shows
the stable and unstable parts: blue is stable, and red is unstable. You can also
spin the bifurcation diagram around and zoom in using the mouse.

\section{ Exporting the Results for different plotters.}
It is often useful to use other plotting programs or general-purpose
tools to work with AUTO's data. The ``writeRawFilename'' method (see
also Section~\ref{sec:clui_exporting}) can be used for this.
In this tutorial we can for
instance export the bifurcation diagram using\\
\commandf{cusp.writeRawFilename('cusp.dat') }, and then use
the command \commandf{plot 'cusp.dat' using 1:4 wi li } to plot
the bifurcation diagram in GNUPlot.

\newpage
\section{ ab : A Programmed Demo.} \label{sec:Demos_ab}
%==============================================================================
%DEMO=ab=======================================================================
%==============================================================================
This demo illustrates the computation of 
stationary solutions,
Hopf bifurcations and 
periodic solutions.
The equations, that model an A $\to$ B  reaction, are those from
\citename{URP:74} \citeyear{URP:74}, namely
\begin{equation} \begin{array}{cl}
  u_1 ' &=  -u_1 + p_1 (1-u_1) e^{u_2}, \\
  u_2 ' &=  -u_2 +  p_1 p_2 ( 1-u_1) e^{u_2} - p_3 u_2.\\
\end{array} \end{equation}
This demo is fully scripted, see Table~\ref{tbl:demo_ab}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir ab} & create an empty work directory \\ 
  \commandf{cd ab} & change directory \\
  \commandf{demo('ab')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{auto('ab.auto')} & run the demo \\
\hline
\end{tabular}
\caption{Commands for running demo \filef{ab}.}
\label{tbl:demo_ab}
\end{center}
\end{table}

If you look at the file \filef{ab.auto } you see that the script
computes a stationary solution family for certain values of $p_2$,
and that a periodic orbit family is computed for each Hopf bifurcation
that was found in the stationary solution families.

%==============================================================================
%==============================================================================
\chapter{ \AUTO Demos : Fixed points.} \label{ch:Demos_Fixed_points}
%==============================================================================
%==============================================================================

%==============================================================================
%DEMO=enz======================================================================
%==============================================================================
\section{ enz : Stationary Solutions of an Enzyme Model.} \label{sec:Demos_enz}
The equations, that model a two-compartment enzyme system 
(\citename{JPK:80} \citeyear{JPK:80}),
are given by
\begin{equation} \label{2'} \begin{array}{cl}
 s_1 '&=
 (s_0 - s_1) + (s_2 - s_1) - \rho R (s_1), \\
 s_2 '&=
 (s_0 +\mu - s_2) + (s_1 - s_2) - \rho R (s_2), \\\end{array} \end{equation}
where
$$ R (s)=\frac{s}{1+s+ \kappa s^{2} }.$$
The free parameter is $s_0$. Other parameters are fixed.
This equation is also considered in 
\citename{DoKeKe:91a} \citeyear{DoKeKe:91a}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir enz} & create an empty work directory \\ 
  \commandf{cd enz} & change directory \\
  \commandf{demo('enz')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{run('enz')} & compute stationary solution families \\ 
  \commandf{save('enz')} & save output-files as \filef{b.enz, s.enz, d.enz} \\ 
\hline
\end{tabular}
\caption{Python commands for running demo \filef{enz}.}
\label{tbl:demo_enz}
\end{center}
\end{table}

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir enz} & create an empty work directory \\ 
  \commandf{cd enz} & change directory \\
  \commandf{@dm enz} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{@r enz} & compute stationary solution families \\ 
  \commandf{@sv enz} & save output-files as \filef{b.enz, s.enz, d.enz} \\ 
\hline
\end{tabular}
\caption{Shell commands for running demo \filef{enz}.}
\label{tbl:demo_enz2}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=dd2======================================================================
%==============================================================================
\section{ dd2 : Fixed Points of a Discrete Dynamical System.} \label{sec:Demos_dd2}
This demo illustrates the computation of a solution family and
its bifurcating families for a discrete dynamical system.
Also illustrated are the continuation of 
period-doubling bifurcations, and branch switching at such
points.
The equations, a discrete predator-prey system, are
\begin{equation} \begin{array}{cl}
 u_1^{k+1} &=p_1
 u_1^{k}(1-u_1^{k})-p_2u_1^{k} u_2^{k},\\
 u_2^{k+1}&=(1-p_3)u_2^{k}+p_2u_1^{k}u_2^{k}.\\
\end{array} \end{equation}
In the first, third, and fourth run $p_1$ is free.
In the second run, both $p_1$ and $p_2$ are free.
The remaining equation parameter, $p_3$, is fixed in both runs.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir dd2 } & create an empty work directory \\ 
  \commandf{cd dd2 } & change directory \\
  \commandf{demo('dd2') } & copy the demo files to the work directory \\
\hline
%==============================================================================
 
  \commandf{r1=run(e='dd2',c='dd2')} & 1st run; fixed point solution branches \\ 
  \commandf{save('dd2')} & save output-files as \filef{b.dd2, s.dd2, d.dd2} \\ 
\hline
%==============================================================================
  \commandf{run(r1("PD1"),ICP=["p1","p2"],ISW=2)} & \parbox[t]{3in}{2nd run; a locus of period-doubling bifurcations.  \vspace{0.2cm}}\\ 
  \commandf{save('pd')} & save output-files as \filef{b.pd, s.pd, d.pd} \\ 
\hline
%==============================================================================
  \commandf{r3=run(r1("PD1"),ISW=-1)} & \parbox[t]{3in}{3rd run;
    the bifurcating period-2 orbit.  \vspace{0.2cm}}\\ 
  \commandf{append('dd2')} & append output-files to \filef{b.dd2, s.dd2, d.dd2} \\ 
\hline
%==============================================================================
  \commandf{run(r3("PD1"))} & \parbox[t]{3in}{4th run; the
    bifurcation period-4 orbit.  \vspace{0.2cm}}\\ 
  \commandf{append('dd2')} & append output-files to \filef{b.dd2, s.dd2, d.dd2} \\ 
\hline
\end{tabular}
\caption{Commands for running demo \filef{dd2}.}
\label{tbl:demo_dd2}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=log======================================================================
%==============================================================================
\section{ log : The Logistic Map.} \label{sec:Demos_log}
This demo shows 5 subsequent periodic doublings in the logistic map
\begin{equation} \begin{array}{cl}
 x^{k+1} &= \mu x (1-x),\\
\end{array} \end{equation}
and approximates the Feigenbaum constant. The script
\filef{log.auto} shows a Python loop in which values
of $\mu$ for subsequent period-doubling bifurcations are compared.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir log } & create an empty work directory \\ 
  \commandf{cd log } & change directory \\
  \commandf{demo('log') } & copy the demo files to the work directory \\
  \commandf{auto('log.auto') } & run the script log.auto \\
  \commandf{plot('log') } & plot the bifurcation diagram \\
\hline
\end{tabular}
\caption{Commands for running demo \filef{log}.}
\label{tbl:demo_log}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=hen======================================================================
%==============================================================================
\section{ hen: The H\'enon Map.} \label{sec:Demos_hen}
In this demo, a two-parameter bifurcation analysis of the H\'enon map
\begin{equation} \begin{array}{cl}
 x^{k+1} &= y,\\
 y^{k+1} &= \alpha-\beta x - y^2,\\
\end{array} \end{equation}
is performed. This demo features the detection and continuation
of Naimark-Sacker, period-doubling, and fold bifurcations in two
parameters. On these codimension-one bifurcation curves
certain codimension-two bifurcations are detected:
the 1:1 (R1), 1:2 (R2), 1:3 (R3), and 1:4 (R4) resonance and fold-flip (LPD)
bifurcation points. After running the script \filef{hen.auto}, the
results can be plotted using \commandf{plot('hen')} or \commandf{@pp hen}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir hen } & create an empty work directory \\ 
  \commandf{cd hen } & change directory \\
  \commandf{demo('hen') } & copy the demo files to the work directory \\
  \commandf{r1 = run('hen')} & \parbox[t]{3in}{
    fixed point solution branch for $\beta$
    ($\alpha=1$) (detects a period-doubling (PD)
    and a Naimark-Sacker (TR) bifurcation)\vspace{0.1cm}} \\
  \commandf{save('beta')} & save output-files as \filef{b.beta, s.beta,
      d.beta} \\
\hline
\parbox[t]{3in}{
  \commandf{run(r1("TR1"),ICP=['alpha','beta'], ISW=2,ILP=0,STOP=['R11','R21'])}\vspace{0.1cm}}&
\parbox[t]{3in}{
  continue the TR bifurcation in two parameters until a 1:1 or 1:2
  resonance is found\vspace{0.1cm}}\\
  \commandf{save('hen')} & save output-files as \filef{b.hen, s.hen, d.hen} \\
  \commandf{run(DS='-')} & compute last continuation the opposite way\\
  \commandf{append('hen')} & append output-files to \filef{b.hen, s.hen, d.hen} \\
\hline
\parbox[t]{3in}{
  \commandf{run(r1("PD1"),ICP=['alpha','beta'], ISW=2,ILP=0)}\vspace{0.1cm}}&
\parbox[t]{3in}{
  continue the PD bifurcation in two parameters\vspace{0.1cm}}\\
  \commandf{append('hen')} & append output-files as \filef{b.hen, s.hen, d.hen} \\
  \commandf{run(DS='-')} & compute last continuation the opposite way\\
  \commandf{append('hen')} & append output-files to \filef{b.hen, s.hen, d.hen} \\
\hline
\parbox[t]{3in}{
  \commandf{r4=run(c='hen',ICP=['alpha'], DS='-',STOP=['LP1'])}\vspace{0.1cm}}&
  \parbox[t]{3in}{
    fixed point solution branch for $\alpha$
    ($\beta=1$) (detects and stops at a fold (LP))\vspace{0.1cm}} \\
  \commandf{save('alpha')} & save output-files as \filef{b.alpha, s.alpha,
      d.alpha} \\
\hline
\parbox[t]{3in}{
  \commandf{run(r4("LP1"),ICP=['alpha','beta'], ISW=2,ILP=0)}\vspace{0.1cm}}&
\parbox[t]{3in}{
  continue the LP bifurcation in two parameters}\\
  \commandf{append('hen')} & append output-files as \filef{b.hen, s.hen, d.hen} \\
  \commandf{run(DS='-')} & compute last continuation the opposite way\\
  \commandf{append('hen')} & append output-files to \filef{b.hen, s.hen, d.hen} \\
\hline
\commandf{merge('hen')} & 
\parbox[t]{3in}{
join all forward and backward branches into
single branches\vspace{0.1cm}}\\
\commandf{relabel('hen')} & make all labels unique\\
\hline
\end{tabular}
\caption{Commands for running demo \filef{hen}.}
\label{tbl:demo_hen}
\end{center}
\end{table}

%merge('hen')
%relabel('hen')



%==============================================================================
%==============================================================================
\chapter{ {\cal AUTO} Demos : Periodic solutions.} \label{ch:Demos_Periodic}
%==============================================================================
%==============================================================================

%==============================================================================
%DEMO=lrz======================================================================
%==============================================================================
\newpage
\section{ lrz : The Lorenz Equations.} \label{sec:Demos_lrz}
This demo computes two symmetric homoclinic orbits in the Lorenz equations
\begin{equation} \begin{array}{cl}
  x' &=  \sigma (y - x), \\
  y' &=  \rho x - y - x z,  \\
  z' &=  x y - \beta z. \\ \end{array} \end{equation}
Here $\rho$ is the free parameter, and $\beta=8/3$, $\sigma=10$.
The two homoclinic orbits correspond to the final, large period orbits 
on the two periodic solution families.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================

  \commandf{mkdir lrz} & create an empty work directory \\ 
  \commandf{cd lrz} & change directory \\
  \commandf{demo('lrz')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{lrz=run(e='lrz',c='lrz')} & compute stationary solutions \\ 
  \commandf{save('lrz')} & save all output to \filef{b.lrz, s.lrz, d.lrz} \\ \hline
%==============================================================================
\parbox[t]{3in}{
  \commandf{run(lrz('HB1'),IPS=2,ICP=['rho',
    'PERIOD'],NMX=35,NPR=2,DS=0.5)}\vspace{0.2cm}}
& \parbox[t]{3in}{
 compute periodic solutions; the final orbit is near-homoclinic.
 \vspace{0.2cm}}\\
 \commandf{append('lrz')} & append all output to \filef{b.lrz, s.lrz, d.lrz} \\ 
\hline
%==============================================================================
\parbox[t]{3in}{
  \commandf{run(lrz('HB2'),IPS=2,ICP=['rho',
    'PERIOD'],NMX=35,NPR=2,DS=0.5)}
\vspace{0.2cm}} & compute the symmetric periodic solution family \\ 
  \commandf{append('lrz')} & append all output to \filef{b.lrz, s.lrz, d.lrz} \\ 
\hline
\end{tabular}
\caption{Commands for running demo \filef{lrz}.}
\label{tbl:demo_lrz}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=abc======================================================================
%==============================================================================
\section{ abc : The A \texorpdfstring{$\to$}{to} B 
\texorpdfstring{$\to$}{to} C Reaction.} \label{sec:Demos_abc}
This demo illustrates the computation of 
stationary solutions,
Hopf bifurcations 
and
periodic solutions
in the A $\to$ B $\to$ C reaction 
(\citename{DoHe:83} \citeyear{DoHe:83}).
\begin{equation} \begin{array}{cl}
  u_1 ' &=  -u_1 + p_1 (1-u_1) e^{u_3}, \\
  u_2 ' &=  -u_2 +  p_1 e^{u_3} ( 1-u_1 - p_5 u_2 ),\\
  u_3 ' &=  -u_3 - p_3 u_3 + p_1 p_4 e^{u_3}  
  ( 1-u_1 + p_2 p_5 u_2 ),\\ \end{array} \end{equation}
with $p_2=1$, $p_3=1.55$, $p_4=8$, and $p_5=0.04$. 
The free parameter is $p_1$.

The equations, as programmed in the equations-file {\tt abc.f90},
appear in Table~\ref{tbl:demo_abcE1}.
The starting point, an equilibrium of the equations,
is also defined in  the equations-file {\tt abc.f90},
as shown in  Table~\ref{tbl:demo_abcE2}.
(The equations-file {\tt abc.f90} also contains the skeletons
of some other routines, which must be supplied, but which 
are not used in this application.)

A more advanced version, that continues branch points in three
parameters is provided by the demo {\tt abcb}.

In the constants-file ({\tt c.abc.1}) for the first run, as shown in 
Table~\ref{tbl:demo_abcC1}, we note the following:

\begin{itemize}
\item[-] {\tt IPS=1}~: a family of stationary solutions is computed.

\item[-] {\tt IRS=0}~: the starting point defined in {\tt STPNT} 
	 is to be used (see  Table~\ref{tbl:demo_abcE2}). 

\item[-] {\tt ICP=[1]}~: the continuation parameter is PAR(1) 

\item[-] {\tt UZR=\{-1:0.4\}}~: there is one user output point, namely at
	 {\tt PAR(1)=0.4}. Moreover, since the index ("{\tt -1}") in
	 the last line of the constants-file {\tt c.abc.1} is negative, 
	 the calculation will terminate when the calculation reaches
	 the value {\tt PAR(1)=0.4}..
\end{itemize}

In the constants-file ({\tt c.abc.2}) for the second run, as shown in 
Table~\ref{tbl:demo_abcC2}, we note that:

\begin{itemize}
\item[-] {\tt IPS=2}~: a family of periodic solutions is computed.

\item[-] {\tt IRS=2}~: the starting point is the solution with label 2,
         (a Hopf bifurcation point), to be read from the solutions-file 
	 (here {\tt s.abc}).

\item[-] {\tt ICP=[1,11]}~: there are two continuation parameters
	 (namely {\tt PAR(1)}, and the period, {\tt PAR(11)}). 

\item[-] {\tt UZR=\{-1:0.25\}}~: there is one user output point, now at
	 {\tt PAR(1)=0.25}, where the calculation is to terminate,
	 since the index ("{\tt -1}") is negative.
\end{itemize}

%------------------------------------------------------
\begin{table}[htbp]
{\small
\begin{center}
\begin{boxedverbatim}
      SUBROUTINE FUNC(NDIM,U,ICP,PAR,IJAC,F,DFDU,DFDP) 
!     ---------- ---- 

      IMPLICIT NONE
      INTEGER, INTENT(IN) :: NDIM, ICP(*), IJAC
      DOUBLE PRECISION, INTENT(IN) :: U(NDIM), PAR(*)
      DOUBLE PRECISION, INTENT(OUT) :: F(NDIM)
      DOUBLE PRECISION, INTENT(INOUT) :: DFDU(NDIM,NDIM), DFDP(NDIM,*)

      DOUBLE PRECISION X1,X2,X3,D,ALPHA,BETA,B,S,E,X1C

       X1=U(1)
       X2=U(2)
       X3=U(3)

       D=PAR(1)
       ALPHA=PAR(2)
       BETA=PAR(3)
       B=PAR(4)
       S=PAR(5)

       E=DEXP(X3)
       X1C=1-X1

       F(1)=-X1 + D*X1C*E
       F(2)=-X2 + D*E*(X1C - S*X2)
       F(3)=-X3 - BETA*X3 + D*B*E*(X1C + ALPHA*S*X2)

      END SUBROUTINE FUNC
\end{boxedverbatim}
\end{center}
}
\caption{The equations for demo {\tt abc}, 
as defined in the equations-file {\tt abc.f90}.}
\label{tbl:demo_abcE1}
\end{table}
%------------------------------------------------------


%------------------------------------------------------
\begin{table}[htbp]
{\small
\begin{center}
\begin{boxedverbatim}
      SUBROUTINE STPNT(NDIM,U,PAR,T) 
!     ---------- ----- 

      IMPLICIT NONE
      INTEGER, INTENT(IN) :: NDIM
      DOUBLE PRECISION, INTENT(INOUT) :: U(NDIM),PAR(*)
      DOUBLE PRECISION, INTENT(IN) :: T

       PAR(1)=0.0
       PAR(2)=1.0
       PAR(3)=1.55
       PAR(4)=8.
       PAR(5)=0.04

       U(1)=0.
       U(2)=0.
       U(3)=0.

      END SUBROUTINE STPNT
\end{boxedverbatim}
\end{center}
}
\caption{The starting solution for demo {\tt abc}, 
as defined in the equations-file {\tt abc.f90}.}
\label{tbl:demo_abcE2}
\end{table}
%------------------------------------------------------

%------------------------------------------------------
\begin{table}[htbp]
{\small
\begin{center}
\begin{boxedverbatim}
NDIM=   3, IPS =   1, IRS =   0, ILP =   1
ICP =  [1]
NTST=  15, NCOL=   4, IAD =   3, ISP =   1, ISW = 1, IPLT= 0, NBC= 0, NINT= 0
NMX=  130, NPR=  200, MXBF=  10, IID =   2, ITMX= 8, ITNW= 5, NWTN= 3, JAC= 0
EPSL= 1e-07, EPSU = 1e-07, EPSS =0.0001
DS  =  0.02, DSMIN= 0.001, DSMAX=   0.1, IADS=   1
NPAR = 5, THL =  {11: 0.0}, THU =  {}
UZR =  {1: 0.4}, STOP = ['UZ1']
\end{boxedverbatim}
\end{center}
}
\caption{The constants-file {\tt c.abc.1} for Run 1 (stationary solutions)
of demo {\tt abc}.}
\label{tbl:demo_abcC1}
\end{table}
%------------------------------------------------------


%------------------------------------------------------
\begin{table}[htbp]
{\small
\begin{center}
\begin{boxedverbatim}
NDIM=   3, IPS =   2, IRS =   2, ILP =   1
ICP =  [1, 11]
NTST=  25, NCOL=   4, IAD =   3, ISP =   1, ISW = 1, IPLT= 0, NBC= 0, NINT= 0
NMX=  200, NPR=  200, MXBF=  10, IID =   2, ITMX= 8, ITNW= 5, NWTN= 3, JAC= 0
EPSL= 1e-07, EPSU = 1e-07, EPSS =0.0001
DS  =  0.02, DSMIN= 0.001, DSMAX=   0.1, IADS=   1
NPAR = 5, THL =  {11: 0.0}, THU =  {}
UZR =  {1: 0.25}, STOP = ['UZ1']
\end{boxedverbatim}
\end{center}
}
\caption{The constants-file {\tt c.abc.2} for Run 2 (periodic orbits) 
of demo {\tt abc}.}
\label{tbl:demo_abcC2}
\end{table}
%------------------------------------------------------


\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  COMMAND  & ACTION \\ 
\hline
%==============================================================================
  \commandf{mkdir abc} & create an empty work directory \\ 
  \commandf{cd abc} & change directory \\
  \commandf{@dm abc} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{@R abc 1} & compute the stationary solution family 
						with four Hopf bifurcations \\ 
  \commandf{@sv abc} & save output-files as {\tt b.abc, s.abc, d.abc} \\ 
\hline
%==============================================================================
  \commandf{@R abc 2} & compute a family of periodic solutions from the first Hopf point \\ 
  \commandf{@ap abc} & append the output-files to {\tt b.abc, s.abc, d.abc} \\ 
\hline
%==============================================================================
  \commandf{@R abc 3} & compute a family of periodic solutions from the second Hopf point \\ 
  \commandf{@ap abc} & append the output-files to {\tt b.abc, s.abc, d.abc} \\ 
\hline
%==============================================================================
  \commandf{@R abc 4} & compute a family of periodic solutions from the third Hopf point \\ 
  \commandf{@ap abc} & append the output-files to {\tt b.abc, s.abc, d.abc} \\ 
\hline
%==============================================================================
  \commandf{@R abc 5} & compute a family of periodic solutions from the fourth Hopf point \\ 
  \commandf{@ap abc} & append the output-files to {\tt b.abc, s.abc, d.abc} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Unix Commands for running demo {\tt abc}.}
\label{tbl:demo_abcL}
\end{center}
\end{table}

%------------------------------------------------------
\begin{table}[htbp]
{\small 
\begin{center} 
\begin{boxedverbatim}
abc=run(e='abc',c='abc.1')
abc=abc+run(abc('HB1'),c='abc.2')
abc=abc+run(abc('HB2'),c='abc.3')
abc=abc+run(abc('HB3'),c='abc.4')
abc=abc+run(abc('HB4'),c='abc.5')
save(abc,'abc')
\end{boxedverbatim}
\end{center}
}
\caption{Python Commands for running demo {\tt abc}.}
\label{tbl:demo_abcP1}
\end{table}
%------------------------------------------------------

%------------------------------------------------------
\begin{table}[htbp]
{\small
\begin{center}
\begin{boxedverbatim}
abc=run(e='abc',c='abc.1')
for solution in abc('HB'):
    abc=abc+run(solution,c='abc.2')
abc=rl(abc)
save(abc,'abc')
\end{boxedverbatim}
\end{center}
}
\caption{Python Program for running demo {\tt abc}.}
\label{tbl:demo_abcP2}
\end{table}
%------------------------------------------------------


\newpage
%==============================================================================
%DEMO=pp2======================================================================
%==============================================================================
\section{ pp2 : A 2D Predator-Prey Model.} \label{sec:Demos_pp2}
This demo illustrates the computation of families of stationary
solutions, including bifurcating stationary families, as well as
the detection of a Hopf bifurcation.
The first run computes the families of stationary solutions, bounded
by $0\le p_1\le 1$ and $u_1 \ge -0.25$. Then the script \filef{pp2.auto}
scans the first run for Hopf bifurcations, finds one, and computes
the family of periodic solutions that emanates
from the Hopf bifurcation. This family terminates in
a heteroclinic orbit. The continuation is configured to stop if the period
\parf{PAR(11)}$=36$, when the heteroclinic orbit is very close.

The equations, which model a predator-prey system with harvesting, are
\begin{equation} \begin{array}{cl}
  u_1 ' &= p_2 u_1 (1 - u_1 ) - u_1 u_2 - p_1 (1-e^{-p_3 u_1}) ,\\
  u_2 ' &= -u_2  + p_4 u_1 u_2  .\end{array} \end{equation}
Here $p_1$ (quota) is the principal continuation parameter,
while $p_2=p_4=3$ and $p_3=5$, are fixed. The variables $u_1$ and
$u_2$ denote prey and predator, for instance fish and sharks.
The use of {\cal PLAUT} is also illustrated. The saved plots are shown
in Figure~\ref{fig:pp2_1} and  Figure~\ref{fig:pp2_2}.
You can obtain similar figures using the Python CLUI's plot
command and using {\cal PLAUT04}.
\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir pp2} & create an empty work directory \\ 
  \commandf{cd pp2} & change directory \\ 
  \commandf{@dm pp2} & copy the demo files to the work directory \\ 
\hline
%============================================================================== 
  \commandf{auto pp2.auto } or & Run the script pp2.auto\\
  \commandf{auto('pp2.auto') } & \\
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo {\tt pp2}.}
\label{tbl:demo_pp2_1}
\end{center}
\end{table}

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  {\cal AUTO}-COMMAND  & ACTION \\
\hline
  \commandf{@p pp2} or \commandf{@pp pp2} & 
  \begin{minipage}{10cm}~\\
  run {\cal PLAUT} or {\cal
    PyPLAUT} to graph the contents of {\tt b.pp2} and {\tt s.pp2};\\
  \end{minipage}
  \\ 
\hline
  {\cal PLAUT/PyPLAUT}-COMMAND  & ACTION \\
\hline
  \commandf{d2}  & set convenient defaults\\ 
  \commandf{ax}  & select axes \\ 
  \commandf{1 3}  & select real columns 1 and 3 in {\tt b.pp2} \\ 
  \commandf{bd0}  & plot the bifurcation diagram; $max~u_1$ versus $p_1$ \\
\hline
  \commandf{d1}  & choose other default settings \\ 
  \commandf{bd}  & get blow-up of current bifurcation diagram \\ 
  \commandf{0~ 1 ~-0.25~ 1} & enter diagram limits  \\
  \commandf{sav}  & save plot (see Figure~\ref{fig:pp2_1})\\
  \commandf{fig.1} or \commandf{fig1.eps} & upon prompt, enter a new
  file name, e.g., {\tt fig.1} or {\tt fig.eps}\\
  \commandf{cl}  & clear the screen  \\
\hline
  \commandf{2d}  & enter 2D mode, for plotting labeled solutions\\ 
  \commandf{11 15 19 23}  & select these labeled orbits in {\tt s.pp2}\\ 
  \commandf{d}  & default orbit display; $u_1$ versus time\\
\hline
  \commandf{1 3}  & select columns 1 and 3 in {\tt s.pp2} \\
  \commandf{d}  & display the orbits; $u_2$ versus time\\
\hline
  \commandf{2 3}  & select columns 2 and 3 in {\tt s.pp2} \\
  \commandf{d}  & phase plane display; $u_2$ versus $u_1$\\
  \commandf{sav}  & save plot  (see Figure~\ref{fig:pp2_2})\\
  \commandf{fig.2} or \commandf{fig2.eps} & upon prompt, enter a new file name \\
  \commandf{ex}  & exit from 2D mode  \\
\hline
  \commandf{end}  & exit from {\cal PLAUT/PyPLAUT} \\
\hline
%==============================================================================
\end{tabular}
\caption{Plotting commands for demo {\tt pp2}.}
\label{tbl:demo_pp2_2}
\end{center}
\end{table}

%------------------------------------------------------
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/pp21}}
\caption{The bifurcation diagram of demo {\tt pp2}.}
\label{fig:pp2_1}
\end{figure}
%------------------------------------------------------

%------------------------------------------------------
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/pp22}}
\caption{The phase plot of solutions 11, 15, 19, and 23 in demo {\tt pp2}.}
\label{fig:pp2_2}
\end{figure}
%------------------------------------------------------


\newpage
%==============================================================================
%DEMO=lor======================================================================
%==============================================================================
\section{ lor : Starting an Orbit from Numerical Data.} \label{sec:Demos_lor}
This demo illustrates how to start the computation of a family of
periodic solutions from numerical data obtained, for example, from an
initial value solver.
As an illustrative application we consider the Lorenz equations
\begin{equation} \begin{array}{cl}
  x' &=  \sigma (y - x), \\
  y' &=  \rho x - y - x z,  \\
  z' &=  x y - \beta z. \\\end{array} \end{equation}
Numerical simulations with a simple initial value solver show the
existence of a stable periodic orbit when $\rho=280$, $\beta=8/3$, $\sigma=10$.
Numerical data representing one complete periodic oscillation are
contained in the file \filef{lor.dat}. 
Each row in \filef{lor.dat} contains four real numbers, namely,
the time variable $t$, $x$, $y$ and $z$.
The correponding parameter values are defined in the user-supplied subroutine
\filef{STPNT}.
The \AUTO constant \parf{dat='lor'} then allows for using
the data in \filef{lor.dat} where we also specify \parf{IRS=0}.
The mesh will be suitably adapted to the solution, using the number of
mesh intervals \parf{NTST} and the number of collocation point per mesh
interval \parf{NCOL} specified in the constants-file \filef{c.lor.1}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir lor} & create an empty work directory \\ 
  \commandf{cd lor} & change directory \\
  \commandf{demo('lor')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{lor=run('lor',c='lor.1')} & compute a solution family, restart from \filef{lor.dat} \\ 
  & save to bifurcation diagram object \parf{lor} \\ 
\hline
%==============================================================================
  \commandf{pd=run(lor('PD1'),c='lor.2')} & \parbox[t]{3in}{ switch branches at a period-doubling detected in the first run.  Constants changed : {\tt IRS, ISW, NTST} \vspace{0.2cm}} \\ 
  \commandf{save(lor+pd,'lor')} & save the two runs to \filef{b.lor, s.lor, d.lor} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{lor}.}
\label{tbl:demo_lor}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=frc======================================================================
%==============================================================================
\section{ frc : A Periodically Forced System.} \label{sec:Demos_frc}
This demo illustrates the computation of periodic solutions
to a periodically forced system.
In \AUTO this can be done by adding a nonlinear oscillator with
the desired periodic forcing as one of the solution components.
An example of such an oscillator is
\begin{equation} \begin{array}{cl}
 x'&=x + \beta y - x (x^{2} + y^{2}),  \\
 y'&=-\beta x + y - y (x^{2} + y^{2}), \\\end{array} \end{equation}
which has the asymptotically stable solution $x=sin (\beta t)$,
$y=cos (\beta t)$.
We couple this oscillator to the Fitzhugh-Nagumo equations~:
\begin{equation} \begin{array}{cl}
 v'&=\bigl( F(v) - w \bigr) / \eps,  \\
 w'&=v - dw - \bigl( b + r \sin(\beta t) \bigr) ,
\end{array} \end{equation}
by replacing $\sin(\beta t)$ by $x$.
Above, $F(v) = v (v-a) (1-v)$ and $a,b,\eps$ and $d$ are fixed.
The first run is a homotopy from $r=0$, where a solution is known analytically,
to $r=0.2$.
Part of the solution family with $r=0.2$ and varying $\beta$ 
is computed in the second run.
For detailed results see 
\citename{AlDoOt:90} \citeyear{AlDoOt:90}.


\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir frc} & create an empty work directory \\ 
  \commandf{cd frc} & change directory \\
  \commandf{demo('frc')} & copy the demo files to the work directory \\
\hline
%============================================================================== 
  \commandf{r1=run(e='frc',c='frc')} & homotopy to $r=0.2$ \\ 
  \commandf{save(r1,'0')} & save output-files as \filef{b.0, s.0, d.0} \\ 
\hline
%==============================================================================
\parbox[t]{3in}{
  \commandf{r2=run(r1('UZ1'),ICP=[5,11],
    NMX=20,DS=-0.5,DSMAX=5.0)}\vspace{0.2cm}} & 
  \parbox[t]{3in}{ compute solution family; restart from \parf{r1}. \vspace{0.2cm}} \\ 
  \commandf{save(r2,'frc')} & save output-files as \filef{b.frc, s.frc, d.frc} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{frc}.}
\label{tbl:demo_frc}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=ppp======================================================================
%==============================================================================
\section{ ppp :  Continuation of Hopf Bifurcations.} \label{sec:Demos_ppp}
This demo illustrates the continuation of Hopf bifurcations in a 3-dimensional 
predator prey model (\citename{Do:84} \citeyear{Do:84}).
This curve contain branch points, where one locus of Hopf points
bifurcates from another locus of Hopf points, and generalized Hopf (Bautin)
bifurcations (GH), where the Hopf bifurcation changes from sub- to
supercritical. The diagnostics file \filef{d.hb} can be inspected to
see where the Hopf bifurcation is subcritical and where it is supercritical.
The equations are
\begin{equation} \begin{array}{cl}
  u_1 ' &= u_1(1-u_1) - p_4 u_1 u_2  ,  \\
  u_2 ' &= -p_2 u_2 + p_4 u_1 u_2 - p_5 u_2 u_3
  -p_1(1-e^{-p_6 u_2}) \\
  u_3 ' &= -p_3 u_3  + p_5 u_2 u_3  .  \\  
\end{array} \end{equation}
Here $p_2=1/4$,  $p_3=1/2$,  $p_4=3$,  $p_5=3$,  $p_6=5$,
and $p_1$ is the free parameter.
In the continuation of Hopf points the parameter $p_4$
is also free.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir ppp} & create an empty work directory \\ 
  \commandf{cd ppp} & change directory \\
  \commandf{demo('ppp')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{ppp=run(e='ppp',c='ppp')} & 
  \parbox[t]{3in}{
  compute stationary solutions; detect Hopf bifurcations
  \vspace{0.2cm}}\\ 
\hline
%==============================================================================
  \parbox[t]{3.4in}{
    \commandf{ppp=ppp+run(ppp("HB2"),IPS=2,ICP=[1,11],
      ILP=0,NMX=15,NPR=50,DS=0.1,DSMAX=0.5)}\vspace{0.2cm}} & 
  compute a family of periodic solutions\\
  \commandf{save(ppp,'ppp')} & save the output to \filef{b.ppp, s.ppp, d.ppp} \\ 
\hline
%==============================================================================
  \parbox[t]{3.4in}{
  \commandf{hb =
    run(ppp("HB2"),ICP=[1,4],ILP=0,
    ISW=2,NMX=100,RL1=0.58,DSMAX=0.1)\vspace{0.2cm}}} & 
    compute Hopf bifurcation curves \\ 
  \commandf{save(hb,'hb')} & save the output-files as \filef{b.hb, s.hb, d.hb} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{ppp}.}
\label{tbl:demo_ppp_1}
\end{center}
\end{table}


\newpage
%==============================================================================
%DEMO=plp======================================================================
%==============================================================================
\section{ plp : Fold Continuation for Periodic Solutions.} \label{sec:Demos_plp}
This demo, which corresponds to computations in 
\citename{DoKeKe:91a} \citeyear{DoKeKe:91a}, shows how one can
continue folds on a family of periodic solutions in two parameters.
The calculation of a locus of Hopf bifurcations is also included.
The equations, that model a one-compartment activator-inhibitor system 
(\citename{JPK:80} \citeyear{JPK:80}),
are given by
\begin{equation} \begin{array}{cl}
 s' &= (s_{0} - s) - \rho R (s,a), \\
 a' &=\alpha (a_{0} - a) - \rho R (s,a), \\
\end{array} \end{equation}
where
$$ R(s,a)=\frac{s a}{1+s+ \kappa s^{2} },
\qquad \kappa  > 0. $$
The free parameter is $\rho$.
In the Hopf and fold continuations the parameter $s_0$ is also free.
The computed loci of Hopf points and folds suggest the existence
of {\it isolas} of periodic solutions. The computation of one such 
isola is also included in this demo. All calculations can be carried 
out by running the Python script \filef{plp.auto} included in the demo.

\newpage
%==============================================================================
%DEMO=ph1======================================================================
%==============================================================================
\section{ ph1 : Phase-Shifting using Continuation.} \label{sec:Demos_ph1}
This demo, which uses the activator-inhibitor model in 
\citename{DoKeKe:91a} \citeyear{DoKeKe:91a}, shows how one can
phase-shift a periodic solution. This can be useful in applications, for example 
when one wants a component of a periodic solution to have a specific value at 
time $0$.
The equations are given by
\begin{equation} \begin{array}{cl}
 s' &= (s_{0} - s) - \rho R (s,a)~, \\
 a' &=\alpha (a_{0} - a) - \rho R (s,a)~, \\
\end{array} \end{equation}
where
$$ R(s,a)=\frac{s a}{1+s+ \kappa s^{2} }~.$$
The first two runs compute a family
of stationary solutions and a bifurcating family of periodic solutions.
The free problem parameter in these runs is $\rho$.
The results are saved in the files \filef{b.sa}, \filef{s.sa}, and \filef{d.sa}.
The third run starts at a specified
periodic solution in \filef{s.sa}, namely, the solution with label $6$, and
phase-shifts this solution in time until $s(0)=30$. The above sequence of 
calculations can be carried out by running the Python script \filef{ph1.auto} 
included in the demo.

The basic idea for doing the phase shift in the third run is to drop the integral 
phase condition, which is automatically added when the {\cal AUTO}-constant \parf{IPS}
has value $2$. For this purpose the third run uses the value $4$ for \parf{IPS},
as specified in \filef{c.ph1}, in which case the periodicity conditions must be
specified explicitly in the subroutine {\tt BCND} in the equations-file \filef{ph1.f90}. 
Also, the interval of periodicity must be scaled explicitly to the interval $[0,1]$, 
which introduces the period $T$ as an explicit parameter in the differential equations.
Note that no integral phase condition is specified in {\tt ICND}. 
The problem formulation in \filef{ph1.f90} is therefore

\begin{equation} \begin{array}{cl}
 s' &= T[(s_{0} - s) - \rho R (s,a)]~, \\
 a' &= T[\alpha (a_{0} - a) - \rho R (s,a)]~, \\
\end{array} \end{equation}
\\
with boundary conditions
\\
\begin{equation} \begin{array}{cl}
 s(0) - s(1) &= 0~, \\
 a(0) - a(1) &= 0~. \\
\end{array} \end{equation}

Note that the \AUTO parameter {\tt PAR(9)}, defined in the subroutine
{\tt PVLS} in \filef{ph1.f90}, is used to monitor the value of $s(0)$.
Since there are two constraints, the third run requires only one free 
parameter, namely $T$ ({\tt PAR(11)}). Note that, to numerical accuracy, 
$T$ does not change during this run.
Alternatively one can use the free parameter $\rho$ ({\tt PAR(4)})
in the third run. In this case, to numerical accuracy, $\rho$ does not 
change during the run.
The third run terminates when {\tt PAR(9)} reached the value $30$, as 
specified in the equations-file \filef{c.ph1}.

\newpage
%==============================================================================
%DEMO=pp3======================================================================
%==============================================================================
\section{ pp3 : Periodic Families and Loci of Hopf Points.} \label{sec:Demos_pp3}
This demo illustrates the computation of stationary solution families
that contain Hopf bifurcations, and the computation of the emanating
families of periodic solutions.  In this example the periodic 
solution families intersect at a secondary bifurcation point 
(a branch point). It it also shown how to compute a locus of Hopf bifurcation
points in two parameters. (In this example the locus contains branch points,
which lead to another locus!)

The equations, which model a 3D predator-prey system with harvesting
(\citename{Do:84} \citeyear{Do:84}), are 
\begin{equation} \begin{array}{cl}
  u_1 ' &= u_1(1-u_1) - p_4 u_1 u_2  ,  \\
  u_2 ' &= -p_2 u_2 + p_4 u_1 u_2 - p_5 u_2 u_3
  -p_1(1-e^{-p_6 u_2}) \\
  u_3 ' &= -p_3 u_3  + p_5 u_2 u_3  .  \\\end{array} \end{equation}
The free parameter is $p_1$, while the other parameters are fixed,
namely $p_2=0.25$, $p_3=0.5$, $p_4=4$, $p_5=3$, and $p_6=5$.
However, both $p_1$ and $p_4$ are free in the computation of loci of Hopf points.

The script in \filef{pp3.auto} first computes the bifurcation diagram
involving the stationary solutions. It finds four Hopf bifurcations.
A periodic orbit family is computed from each of these four Hopf
bifurcations. Then the second Hopf bifurcation from the first run
is continued in two parameters, also producing the other locus.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir pp3} & create an empty work directory \\ 
  \commandf{cd pp3} & change directory \\ 
  \commandf{@dm pp3} & copy the demo files to the work directory \\ 
\hline
%============================================================================== 
  \commandf{auto pp3.auto } or & Run the script pp3.auto\\
  \commandf{auto('pp3.auto') } & \\
%==============================================================================
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo {\tt pp3}.}
\label{tbl:demo_pp3}
\end{center}
\end{table}

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  {\cal AUTO}-COMMAND  & ACTION \\
\hline
  \commandf{@p pp3} or \commandf{@pp pp3} & \begin{minipage}{8cm}~\\
      run {\cal PLAUT/PyPLAUT} to graph the contents of {\tt b.pp3} and {\tt
        s.pp3};\\
      \end{minipage} \\ 
\hline
  {\cal PLAUT/PyPLAUT}-COMMAND  & ACTION \\
\hline
  \commandf{d2}  & set convenient defaults\\ 
  \commandf{ax}  & select axes \\ 
  \commandf{1 3}  & select real columns 1 and 3 in {\tt b.pp3} \\ 
  \commandf{bd0}  & plot the bifurcation diagram; $max~u_1$ versus $p_1$ \\
\hline
  \commandf{bd}  & get blow-up of current bifurcation diagram \\ 
  \commandf{0~ 0.6 ~0~ 1.2} & enter diagram limits  \\
\hline
  \commandf{d1}  & choose other default settings (with labels) \\ 
  \commandf{bd}  & another blow-up of the bifurcation diagram \\ 
  \commandf{0~ 0.6 ~0~ 0.75} & enter diagram limits  \\
\hline
  \commandf{d2}  & set defaults\\ 
  \commandf{2d}  & enter 2D mode, for plotting labeled solutions\\ 
  \commandf{13 14 15 }  & select these orbits from {\tt s.pp3}\\ 
  \commandf{d}  & default orbit display; $u_1$ versus time\\
\hline
  \commandf{2 3}  & select columns 2 and 3 in {\tt s.pp3} \\
  \commandf{d}  & display the orbits; $u_2$ versus $u_1$\\
\hline
  \commandf{2d}  & enter 2D mode, for plotting labeled solutions\\ 
  \commandf{16 17 18 19}  & select these orbits\\ 
  \commandf{d}  & default orbit display; $u_1$ versus time\\
\hline
  \commandf{2 3}  & select columns 2 and 3 in {\tt s.pp3} \\
  \commandf{d}  & phase plane display; $u_2$ versus $u_1$\\
\hline
  \commandf{2 4}  & select columns 2 and 4 in {\tt s.pp3} \\
  \commandf{d}  & phase plane display; $u_3$ versus $u_1$\\
  \commandf{ex}  & exit from 2D mode  \\
\hline
  \commandf{end}  & exit from {\cal PLAUT} \\
\hline
%==============================================================================
\end{tabular}
\caption{Plotting commands for demo {\tt pp3}.}
\label{tbl:demo_pp3_2}
\end{center}
\end{table}

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  {\cal AUTO}-COMMAND  & ACTION \\
\hline
  \commandf{@p hb} or \commandf{@pp hb} & run {\cal PLAUT/PyPLAUT} to
  graph \\
 & the contents of {\tt b.hb} and {\tt s.hb}; \\ 
\hline
  {\cal PLAUT/PyPLAUT}-COMMAND  & ACTION \\
\hline
  \commandf{d0}  & set defaults\\ 
  \commandf{ax}  & select axes \\ 
  \commandf{1 6}  & select real columns 1 and 6 in {\tt b.hb} \\ 
  \commandf{bd0}  & plot the bifurcation diagram; $p_4$ versus $p_1$ \\
\hline
  \commandf{end}  & exit from {\cal PLAUT} \\
\hline
%==============================================================================
\end{tabular}
\caption{Plotting the Hopf loci for demo {\tt pp3}.}
\label{tbl:demo_pp3_3}
\end{center}
\end{table}


\newpage
%==============================================================================
%DEMO=tor======================================================================
%==============================================================================
\section{ tor : Detection of Torus Bifurcations.} \label{sec:Demos_tor}
This demo uses a model in 
\citename{FrRLuGaPo:93} \citeyear{FrRLuGaPo:93}
 to illustrate the detection of a torus bifurcation. 
It also illustrates branch switching at a secondary periodic bifurcation
with double Floquet multiplier at $z=1$.
The computational results also include folds, homoclinic orbits,
and period-doubling bifurcations.
Their continuation is not illustrated here;
see instead the demos \filef{plp}, \filef{pp2}, and \filef{pp3}, respectively.  
The equations are
\begin{equation} \begin{array}{cl}
  x'(t) & = \bigr[ -(\beta+\nu)x + \beta y - a_3 x^3 + b_3 (y-x)^3 \bigr] / r,\\
  y'(t) &= \beta x - (\beta + \gamma) y - z - b_3 (y-x)^3, \\
  z'(t) &= y,\end{array} \end{equation}
where $\gamma=-0.6$, $r=0.6$, $a_3=0.328578$, and $b_3=0.933578$.
Initially $\nu=-0.9$ and $\beta=0.5$.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir tor} & create an empty work directory \\ 
  \commandf{cd tor} & change directory \\
  \commandf{demo('tor')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='tor',c='tor')} & 
  \parbox[t]{3in}{
  1st run; compute a stationary solution family with Hopf bifurcation
  \vspace{0.2cm}}\\ 
\hline
%==============================================================================
  \commandf{r2=run(r1("HB1"),IPS=2,ICP=[1,11])} &
  \parbox[t]{3in}{ compute a family of periodic solutions; restart from \parf{r1}. \vspace{0.2cm}} \\ 
\hline
%==============================================================================
  \commandf{r3=run(r2("BP1"),ISW=-1,NMX=90)} & \parbox[t]{3in}{ compute a bifurcating family of periodic solutions; restart from \parf{r2}. \vspace{0.2cm}} \\ 
  \commandf{save(r1+r2+r3,'1')} & save output to \filef{b.1, s.1, d.1} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{tor}.}
\label{tbl:demo_tor}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=pen======================================================================
%==============================================================================
\section{ pen : Rotations of Coupled Pendula.} \label{sec:Demos_pen}
This demo illustrates the computation of rotations, i.e., solutions that
are periodic, modulo a phase gain of an even multiple of $\pi$.
\AUTO checks the starting data for components with such a phase gain
and, if present, it will automatically adjust the computations accordingly.
The model equations, a system of two coupled  pendula, 
(\citename{DoArOt:91} \citeyear{DoArOt:91}),
are given by
\begin{equation} \begin{array}{cl}
 & \phi_1'' + \eps \phi_1' + \sin \phi_1 
  = I + \gamma(\phi_2-\phi_1), \\
 & \phi_2'' + \eps \phi_2' + \sin \phi_2 
  = I + \gamma(\phi_1-\phi_2) ,\\
\end{array} \end{equation}
or, in equivalent first order form,
\begin{equation} \begin{array}{cl}
 & \phi_1'  =  \psi_1, \\
 & \phi_2'  =  \psi_2, \\
 & \psi_1'  = - \eps \psi_1 - \sin \phi_1 + I + \gamma(\phi_2-\phi_1), \\
 & \psi_2'  = - \eps \psi_2 - \sin \phi_2 + I + \gamma(\phi_1-\phi_2).\\
\end{array} \end{equation}
Throughout $\gamma=0.175$. Initially, $\eps=0.1$ and $I=0.4$.

Numerical data representing one complete rotation are
contained in the file \filef{pen.dat}. 
Each row in \filef{pen.dat} contains five real numbers, namely,
the time variable $t$, $\phi_1$, $\phi_2$, $\psi_1$ and $\psi_2$.
The correponding parameter values are defined in the user-supplied subroutine
\funcf{ STPNT}.

Actually, in this example, a scaled time variable $t$ is given in \filef{pen.dat}. 
For this reason the period (\parf{PAR(11)}) is also set in \funcf{STPNT}.
Normally \AUTO would automatically set the period according to
the data in \filef{pen.dat}.

The \AUTO-constant \parf{dat='pen'} in \filef{c.pen.1}
causes \AUTO to start from the data in \filef{pen.dat}.
The mesh will be suitably adapted to the solution, using the number of
mesh intervals \parf{NTST} and the number of collocation point per mesh
interval \parf{NCOL} specified in the constants-file \filef{c.pen.1}.

The first run, with $I$ as free problem parameter,
starts from the solution (here \parf{IRS=0}) in \filef{pen.dat}.
A period-doubling bifurcation is located, and the period-doubled family
is computed in the second run.
Two branch points are located, and the bifurcating
families are traced out in the third and fourth run, respectively.
The fifth run generates starting data for the subsequent computation of
a locus of period-doubling bifurcations.
The actual computation is done in the sixth run, with $\eps$ and $I$
as free problem parameters.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir pen} & create an empty work directory \\ 
  \commandf{cd pen} & change directory \\
  \commandf{demo('pen')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{pen=run('pen',c='pen.1')} & \parbox[t]{3in}{
locate a period doubling bifurcation; restart from \filef{pen.dat}} \\ 
\hline
%==============================================================================
  \commandf{pen=pen+run(pen('PD1'),c='pen.2')} & \parbox[t]{3in}{ a
    family of  period-doubled (and out-of-phase) rotations.
    Constants changed : \parf{IPS, NTST, ISW, NMX} \\
    append output to bifurcation diagram object \filef{pen}} \\
\hline
%============================================================================== 
  \commandf{pen=pen+run(pen('BP1'),c='pen.3')} & \parbox[t]{3in}{  a secondary bifurcating family (without bifurcation detection).  Constants changed : \parf{IRS, ISP} \\ 
  append output to bifurcation diagram object \filef{pen}} \\
\hline
%==============================================================================
  \commandf{pen=pen+run(pen('BP2'),c='pen.4')} & \parbox[t]{3in}{
    another secondary bifurcating family (without bifurcation
    detection).  Constants changed : \parf{IRS}\\
    append output to bifurcation diagram object \filef{pen}
 \vspace{0.2cm}}\\
\commandf{save(pen,'pen')} & save \parf{pen} to output-files \filef{b.pen, s.pen, d.pen} \\ 

\hline
%==============================================================================
  \commandf{t=run(pen('PD1'),c='pen.5')} & \parbox[t]{3in}{  generate starting data for period doubling continuation.  Constants changed : \parf{IRS, ICP, ICP, ISW, NMX} \vspace{0.2cm}} \\ 
\hline
%==============================================================================
  \commandf{pd=run(t,sv='pd')} & \parbox[t]{3in}{  compute a locus of period doubling bifurcations; restart from \parf{t}.  Constants changed : \parf{IRS} \vspace{0.2cm}} \\ 
  & save output-files as \filef{b.pd, s.pd, d.pd} \\ 
%\hline
%==============================================================================
%%  \commandf{@pn pen} & run an animation program to view the solutions in \filef{s.pen} \\ 
%%  & (on SGI machines only; see also the file \filef{auto/07p/pendula/README}).
%  \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{pen}.}
\label{tbl:demo_pen}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=chu======================================================================
%==============================================================================
\section{ chu :  A Non-Smooth System (Chua's Circuit).} \label{sec:Demos_chu}
Chua's circuit 
is one of the simplest electronic devices to exhibit complex behavior. 
For related calculations see
\citename{KhRoCh:93} \citeyear{KhRoCh:93}.
The equations modeling the circuit are
\begin{equation} \begin{array}{cl}
 u_1' &=  \alpha \bigl[~ u_2 - h(u_1) ~\bigr]~,\\ 
 u_2' &=  u_1 - u_2 + u_3~, \\  
 u_3' &=  - \beta~ u_2~,  
\end{array} \end{equation}
where
$$ h(x) = a_1 x + \frac{1}{2}~ (a_0 - a_1) ~
  \bigl\{ \abs{x+1} -  \abs{x-1} \bigr\}~,$$
and where we take
$\beta = 14.3$, $a_0 = - 1/7$, $a_1 = 2/7$.

Note that $h(x)$ is not a smooth function, and hence the solution 
to the equations  may have non-smooth derivatives.
However, for the orthogonal collocation method to attain its optimal accuracy,
it is necessary that the solution be sufficiently smooth.
Moreover, the adaptive mesh selection strategy will fail
if the solution or one of its lower order derivatives has discontinuities.
For these reasons  we use the smooth approximation
$$ \abs{x} ~\approx~ \frac{2 x}{\pi } ~ {\rm arctan}(Kx),$$
which get better as $K$ increases.
In the numerical calculations below we use $K = 10$.
The free parameter is $\alpha$.


\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir chu} & create an empty work directory \\ 
  \commandf{cd chu} & change directory \\
  \commandf{demo('chu')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='chu',c='chu')} & 1st run; stationary solutions \\ 
\hline
%==============================================================================
  \commandf{r2=run(r1("HB1"),IPS=2,ICP=[1,11])} & \parbox[t]{3in}{ 2nd run; periodic solutions, with detection of period-doubling. \vspace{0.2cm}} \\ 
  \commandf{save(r1+r2,'chu')} & save all output to \filef{b.chu, s.chu, d.chu} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{chu}.}
\label{tbl:demo_chu}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=phs======================================================================
%==============================================================================
\section{ phs : Effect of the Phase Condition.} \label{sec:Demos_phs}
This demo illustrates the effect of the phase condition 
on the computation of periodic solutions.
We consider the differential equation
\begin{equation} \begin{array}{cl}
 u_1'&= \lambda u_1 - u_2,  \\
 u_2'&= u_1 (1-u_1) .  \\
\end{array} \end{equation}
This equation has a Hopf bifurcation from the trivial solution at $\lambda=0$. 
The bifurcating family of periodic solutions
is vertical and along it the period increases monotonically.
The family terminates in a homoclinic orbit containing the
saddle point $(u_1,u_2)=(1,0)$.
Graphical inspection of the computed periodic orbits,
for example $u_1$ versus the scaled time variable $t$,
shows how the phase condition has the effect of keeping the ``peak'' 
in the solution in the same location.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir phs} & create an empty work directory \\ 
  \commandf{cd phs} & change directory \\
  \commandf{demo('phs')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='phs',c='phs.1')} & detect Hopf bifurcation \\ 
\hline
%==============================================================================
  \commandf{r2=run(r1('HB1'),c='phs.2')} & \parbox[t]{3in}{ compute periodic solutions. Constants changed : \parf{IRS, IPS, NPR} \vspace{0.2cm}} \\ 
  \commandf{save(r1+r2,'phs')} & save output to \filef{b.phs, s.phs, d.phs} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{phs}.}
\label{tbl:demo_phs}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=ivp======================================================================
%==============================================================================
\section{ ivp :  Time Integration with Euler's Method.} \label{sec:Demos_ivp}
This demo uses Euler's method to locate a stationary solution of the
following predator-prey system with harvesting~:

\begin{equation} \begin{array}{cl}
  u_1 ' &= p_2 u_1 (1 - u_1 ) - u_1 u_2 - p_1 (1-e^{-p_3 u_1}) ,\\
  u_2 ' &= -u_2  + p_4 u_1 u_2  ,\\\end{array} \end{equation}
where all problem parameters have a fixed value.
The equations are the same as those in demo \filef{pp2}.
The continuation parameter is the independent time variable, namely \parf{PAR(14)}.

Note that Euler time integration is only first order accurate, so that
the time step must be sufficiently small to ensure correct results.
Indeed, this option has been added only as a convenience, and should 
generally be used only to locate stationary states.
Note that the \AUTO-constants \parf{DS}, \parf{DSMIN}, and \parf{DSMAX}
control the step size
in the space consisting of time, here \parf{PAR(14)}, and the state vector,
here $(u_1,u_2)$.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir ivp} & create an empty work directory \\ 
  \commandf{cd ivp} & change directory \\
  \commandf{demo('ivp')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='ivp',c='ivp')} & time integration \\ 
  \commandf{save(r1,'ivp')} & save output-files as \filef{b.ivp, s.ivp, d.ivp} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{ivp}.}
\label{tbl:demo_ivp}
\end{center}
\end{table}


\newpage
%==============================================================================
%DEMO=r3b======================================================================
%==============================================================================
\section{ r3b : The Circular Restricted 3-Body Problem (CR3BP).} \label{sec:Demo_r3b}

This demo computes periodic solutions and two-dimensional unstable
manifolds of those periodic solutions in the restricted three body
problem:
\begin{align*}
\dot x &= x_p\\
\dot y &= y_p\\
\dot z &= z_p\\
\dot x_p&= 2y_p+x-(1-\mu)\frac{x+\mu}{{d_E}^3}-\mu\frac{x-1+\mu}{{d_M}^3}+lx_p\\
\dot y_p &= -2x_p +y - (1-\mu)\frac{y}{{d_E}^3} - \mu\frac{y}{{d_M}^3} + l y_p\\
\dot z_p &= -(1-\mu)\frac{z}{{d_E}^3} - \mu\frac{z}{{d_M}^3} + l z_p
\end{align*}
where $d_E=\sqrt{(x+\mu)^2+y^2+z^2}$ and $d_M=\sqrt{(x-1+\mu)^2+y^2+z^2}$.
Here $l\ne 0$ breaks the conservativeness of the system. In general,
continuations involve $l$ as a parameter, and $l$ will then
approximately stay at zero.

\subsection{Computation of Periodic Solutions of the CR3BP}

Running the Python script \filef{r3b.auto} will generate the families of periodic 
solutions L1, H1, and V1, for the case of the mass-ratio $\mu=0.063$:
\begin{center}
\begin{tabular}{l | l }
\commandf{auto r3b.auto} & \commandf{auto('r3b.auto')} \\
\end{tabular}
\end{center}
where, as in the following examples, the left hand side command can be used
at the shell prompt, and the right hand side command at the Python CLUI
prompt. Note that the commands starting with @ work in both interfaces,
but cannot be used in the expert scripts with a .py suffix.

For example, the data generated for the Lyapunov family L1 will
consist of
\begin{center}
\begin{tabular}{l l}
\filef{b.L1} & the bifurcation diagram data \\
\filef{s.L1} & a selection of periodic orbits \\
\filef{d.L1} & diagnostic data, including Floquet multipliers \\
\end{tabular}
\end{center}
The necessary labeled starting solutions are first computed and stored
in the file \filef{s.start}.
Each starting solution is an equilibrium (``libration
point''), and its data also contains the period of a bifurcating family of
periodic orbits.

The Table below shows the label of each of the starting solutions in 
s.start, indicating which libration point it corresponds to, and which 
family of periodic orbits it will generate:
\begin{center}
\begin{tabular}{| l | l | l |}
\hline
		Label&	Libration Pt.	&Family \\
\hline
		  1 &	    L1	&	  L1 \\
	  	  2 &       L1	&	  V1 \\
	  	  3 &       L2	&	  L2 \\
	  	  4 &       L2	&	  V2 \\
	  	  5 &       L3	&         L3 \\
	  	  6 &       L3	&	  V3 \\
	  	  7 &       L4	&	  V4 \\
	  	  8 &       L5	&	  V5 \\
\hline
\end{tabular}
\end{center}
Note (by looking at the constant-files \filef{c.r3b.*}) that actually only the 
starting solutions labeled 1 and 2 are used in the current calculations, 
as executed by the Python script.

Starting solution for other values of $\mu$ can be generated using the script
\filef{compute\_lps.py}, for instance by running
\begin{center}
\begin{tabular}{l | l}
\commandf{autox compute\_lps.py 0.05}	& \commandf{import compute\_lps} \\
					& \commandf{compute\_lps.compute(0.05)} \\
\end{tabular}
\end{center}
After that, it is necessary to run \filef{r3b.auto} again to regenerate the
families.

The demos L1a, H1a, H1b, H1c, V1a, V1b can be run subsequent to the r3b
demo to compute 2D unstable manifolds of selected periodic orbits that
belong to the L1, V1, and H1 families.

\subsection{Computing Unstable Manifolds of Periodic Orbits in the CR3BP}

Instructions for computing 2-d unstable manifolds of periodic orbits 
in the Circular Restricted 3-Body Problem (CR3BP) using AUTO-07p. 

\subsubsection{The instructions below are for the Halo family L1 in AUTO demo L1a.}

Instructions for computing 2-d unstable manifolds of other periodic 
orbits in the CR3BP are similar (Demos H1a, H1b, H1c, V1a, V1b), and
are given after these instructions.

Select a labeled solution which has exactly one Floquet multiplier with
absolute value greater than 1. (Floquet multipliers can be found in the file
\filef{d.L1} generated by demo r3b.) Enter the label of the periodic solution
in the file \filef{L1a.auto} at {\tt label=} in \filef{L1a.auto}. Also enter
the size of the
initial step into the direction of the unstable manifold there at {\tt step=}.
Note that representative values of these three quantities have already
been entered there.\\
Now run the Python script \filef{L1a.auto}:
\begin{center}
\begin{tabular}{ l | l }
\commandf{auto L1a.auto} & \commandf{auto('L1a.auto')}
\end{tabular}
\end{center}
This will run \filef{r3b.auto} as above if this was not already done.

Through various computational steps the execution of the Python script
will result in AUTO files \filef{b.L1a}, \filef{s.L1a}, and
\filef{d.L1a}, where the orbits in 
\filef{s.L1a} constitute the manifold, which can be viewed with the graphics 
program \commandf{plaut04} or \commandf{r3bplaut04}:
\begin{center}
\begin{tabular}{ l | l }
\commandf{@pl L1a} or \commandf{@r3b L1a} & \commandf{plot3('L1a',r3b=True)}
\end{tabular}
\end{center}
The various steps executed by the Python commands in the script file
\filef{L1a.auto} are explained below in Tables~\ref{tbl:demo_l1a1} and
\ref{tbl:demo_l1a2}, which also show
the equivalent Unix shell versions of these AUTO commands.

The Python script \filef{L1aX.auto} does the same as
\filef{L1a.auto}, but with
additional calculations that generate additional AUTO data files, e.g., 
to detect heteroclinic connections. Some of these additional runs take 
quite a bit of CPU time and generate big data files.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{|l|l|}
\hline
\commandf{mkdir r3b}	& \commandf{mkdir r3b} \\
\commandf{cd r3b}	& \commandf{cd r3b} \\
\commandf{@dm r3b}	& \commandf{demo('r3b')} \\
\multicolumn{2}{|l|}{Copy the r3b demo to the local directory r3b.}\\
\hline

\commandf{auto r3b.auto} & \commandf{auto('r3b.auto')} \\
\multicolumn{2}{|l|}{Generate the CR3BP AUTO data files.} \\
\hline

\commandf{autox ext.py L1 3 -1e-5} & \commandf{import ext} \\
			& \commandf{sext=ext.get('L1',3,-1e-5)} \\
\multicolumn{2}{|p{7in}|}{
                Convert the data for a selected labeled solution from
                \filef{s.L1}, 
		adding a zero adjoint variable. The solution label is 3,
                and the initial step size into the unstable manifold
                is $-10^{-5}$.
		The \filef{ext.py} script looks for the relevant
                Floquet multiplier in
		\filef{d.L1}. The converted solution will be written in the
                file \filef{s.ext} or stored in \parf{sext}.}\\
\hline

\commandf{@r flq ext}	& \commandf{flq=run(sext,c='flq',e='flq')} \\
\multicolumn{2}{|p{7in}|}{
		Compute the Floquet eigenfunction. Free scalar variables in
		this run (see \filef{c.flq}) are: 

                \begin{tabular}{l@{=}l}
		\parf{PAR(1)} & unfolding parameter \\
		\parf{PAR(4)} & multiplier\\
		\parf{PAR(5)} & norm of eigenfunction\\
                \end{tabular}

		If this run is successful then \filef{PAR(5)}
                should become nonzero,
		in fact, \filef{PAR(5)} should reach the value 1. 
                If the run is not successful then see REMARK 1 below.}\\
\hline

\commandf{@sv flq} & \commandf{save(flq,'flq')} \\
\multicolumn{2}{|l|}{
		Save the results in \filef{b.flq}, \filef{s.flq}, and
                \filef{d.flq}.}\\
\hline

\commandf{autox data.py} & \commandf{import data} \\
			& \commandf{startman=data.get(flq('UZ1'))} \\
\multicolumn{2}{|p{7in}|}{
		Extract data for a selected orbit from \filef{s.flq}.
                These data 
		are for both the orbit and its Floquet eigenfunction. It 
		is assumed that \filef{s.flq}
                contains only one labeled solution, 
		with label 2. If you did the ``optional'' computation (see 
		Remark 2) you may need to change the label of the 
		restart solution:}\\
\commandf{autox data.py flq n} & \commandf{startman=data.get(flq(n))} \\
\multicolumn{2}{|p{7in}|}{
		where $n$ is the different label number.
                The extracted data may be saved in a file called
                \filef{s.startman},
                which contains a new starting solution that can be
                used as a base for the manifold computations.
                The orbit coordinates are at
                ``time zero'', and the Floquet eigenfunction
                are saved at \parf{PAR(25:30)} and \parf{PAR(31:36)},
                respectively.}\\
\hline

\commandf{@R man L1a.0 startman}& \commandf{startL1a = run(startman,e='man',c='man.L1a.0')} \\
\multicolumn{2}{|p{7in}|}{
                This step does a time integration using continuation in the
                ``period'' $T$, i.e., \parf{PAR(11)}, which here is
                the
                ``integration time''.
                The labeled solutions from this run all correspond
                to the same orbit, except that the orbit gets longer and
                longer. The starting point of the orbit is the point on the
                periodic orbit at ``time zero'' plus a small distance
                ($\varepsilon$)
                into the direction of the unstable manifold. In \AUTO,
                $\varepsilon$
                corresponds to
                \parf{PAR(6)}. This parameter $\varepsilon$ is initialized
                via the script \filef{ext.py}.
                (The sign of $\varepsilon$ is significant!)
                The parameters in this run (see \filef{c.man.L1a.0}) are:

                \begin{tabular}{l@{=}lll@{=}l}
                  \parf{PAR(3)}  & energy & &
                  \parf{PAR(21)} & $x$-coordinate at end point\\
                  \parf{PAR(11)} & integration time & &
                  \parf{PAR(22)} & $y$-coordinate at end point\\
                  \parf{PAR(12)} & length of the orbit & &
                  \parf{PAR(23)} & $z$-coordinate at end point
                \end{tabular}
              }\\
\hline

\commandf{@sv startL1a}		& \commandf{save(startL1a,'startL1a')} \\
\multicolumn{2}{|l|}{
Save the results in \filef{b.startL1a}, \filef{s.startL1a}, 
and \filef{d.startL1a}.
}\\
\hline
\end{tabular}
\end{center}
\caption{Detailed AUTO shell and Python commands for the L1a demo
  (part 1).}
\label{tbl:demo_l1a1}
\end{table}


\begin{table}[htbp]
\begin{center}
\begin{tabular}{|l|l|}
\hline
\commandf{@R man L1a.1 startL1a} & \commandf{L1a=run(startL1a,c='man.L1a.1')} \\
\multicolumn{2}{|p{7in}|}{
		Look at \filef{c.man.L1a.1} to see from which label in
                \filef{s.startL1a} this
		run starts. In this run the y-coordinate of the end point 
		(\parf{PAR(22)}) is kept fixed,
                while the ``period'' (\parf{PAR(11)}), 
		i.e., the total integration time, is allowed to vary, as 
		is the value of epsilon, i.e., \parf{PAR(6)}.
                Note that if \parf{PAR(6)}
		becomes ``large'' then the manifold may no longer be accurate.
		The free parameters in this run are:

                \begin{tabular}{l@{=}lll@{=}l}
                  \parf{PAR(3)}  & energy & &
                  \parf{PAR(12)} & length of the orbit \\
                  \parf{PAR(6)}  & ``starting distance'' & &
                  \parf{PAR(21)} & $x$-coordinate at end point \\
                  \parf{PAR(11)} & integration time & &
                  \parf{PAR(23)} & $z$-coordinate at end point
                \end{tabular}
}\\
\hline

\commandf{@sv L1a}			& \commandf{save(L1a,'L1a')} \\

\multicolumn{2}{|l|}{
Save the results in \filef{b.L1a}, \filef{s.L1a}, and \filef{d.L1a}.
}\\
\hline

\commandf{@R man L1a.2 startL1a} &
\commandf{L1a2=run(startL1a,c='man.L1a.2')} \\
\multicolumn{2}{|p{7in}|}{
		Another run, starting from a longer initial orbit, which 
		computes part of the manifold. The free parameters are the 
		same as in the preceding run. This computation results in 
		the orbit winding around the selected periodic L1
                orbit.
}\\
\hline
\commandf{@sv L1a2} & \commandf{save(L1a2,'L1a2')} \\

\multicolumn{2}{|l|}{
		Save the results in \filef{b.L1a2}, \filef{s.L1a2},
                and
                \filef{d.L1a2} .}\\
\hline
\end{tabular}
\end{center}
\caption{Detailed AUTO shell and Python commands for the L1a demo
  (part 2).}
\label{tbl:demo_l1a2}
\end{table}

\noindent Use
\begin{center}
\begin{tabular}{ l | l }
\commandf{auto clean.auto} & \commandf{auto('clean.auto')}\\
\end{tabular}
\end{center}
to remove all generated files.

\noindent\textbf{REMARK 1}\\
If the run to compute the Floquet eigenfunction is not successful, i.e., if 
\parf{PAR(5)} does not become nonzero,
then try to compute the Floquet eigenfunction
in more stages, as in Table~\ref{tbl:demo_r3b_remark1}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{|l|l|}
\hline
\multicolumn{2}{|p{7in}|}{
		Give the label of the selected solution, and a value that 
		is smaller than the associated Floquet multiplier (magnitude
		greater than 1) .}\\
\commandf{autox ext.py L1 3 -1e-5 2000} & \commandf{import ext} \\
			& \commandf{sext=ext.get('L1',3,-1e-5,2000)} \\
\hline
\commandf{@R flq 2 ext}	& \commandf{flq=run(sext,c='flq.2',e='flq')} \\

\multicolumn{2}{|p{7in}|}{
		Continue the approximate multiplier; If all goes well then 
		the actual multiplier will be detected as a branch point 
		(BP) with Label 2. Free scalar variables in this run are: 

                \begin{tabular}{l@{=}l}
		\parf{PAR(1)} & unfolding parameter \\
		\parf{PAR(4)} & multiplier\\
		\parf{PAR(5)} & norm of eigenfunction
              \end{tabular}}\\
\hline

\commandf{@sv flq} & \commandf{save(flq,'flq')} \\
\hline
\commandf{@R flq 3} & \commandf{flq=run(flq,e='flq',c='flq.3')} \\

\multicolumn{2}{|p{7in}|}{
		Switch branches at the BP, thereby generating the nonzero 
		Floquet eigenfunction. The free scalar variables are : 

                \begin{tabular}{l@{=}l}
		\parf{PAR(1)} & unfolding parameter \\
		\parf{PAR(4)} & multiplier\\
		\parf{PAR(5)} & norm of eigenfunction
                \end{tabular}

		If all goes well then \parf{PAR(5)} should become
                nonzero, and the
		corresponding solution should have Label 4.
}\\
\hline
\commandf{@sv flq} & \commandf{save(flq,'flq')}\\
\hline
\end{tabular}
\end{center}
\caption{Detailed AUTO shell and Python commands for Remark 1.}
\label{tbl:demo_r3b_remark1}
\end{table}

\noindent\textbf{REMARK 2}\\
One can also follow the orbit, its multiplier and eigenfunction, as in
Table~\ref{tbl:demo_r3b_remark2}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{|l|l|}
\hline
\commandf{@R flq 4} & \commandf{flq=run(flq,e='flq',c='flq.4')}\\
\multicolumn{2}{|p{7in}|}{
		Free scalar variables in this run are

                \begin{tabular}{l@{=}l}
		\parf{PAR(1)}  & unfolding parameter \\
		\parf{PAR(4)}  & multiplier \\
		\parf{PAR(11)} & period \\
                \end{tabular}

		The norm, \parf{PAR(5)}, of the eigenfunction is fixed in
                this run.
}\\
\hline
\commandf{@sv flq} & \commandf{save(flq,'flq')}\\
\hline
\end{tabular}
\end{center}
\caption{Detailed AUTO shell and Python commands for Remark 2.}
\label{tbl:demo_r3b_remark2}
\end{table}

\subsubsection{The instructions below are for the Halo family H1 in AUTO demo H1a.}

Follow the instructions for L1a above, where you replace L by H throughout,
for instance you can run everything in one go using
\begin{center}
\begin{tabular}{l|l}
	\commandf{auto H1a.auto} & \commandf{auto('H1a.auto')} \\
\end{tabular}
\end{center}
or with the extra calculations:
\begin{center}
\begin{tabular}{l|l}
	\commandf{auto H1aX.auto} & \commandf{auto('H1aX.auto')} \\
\end{tabular}
\end{center}
The Floquet eigenfunction is now computed from label 7 with step size
$-10^{-3}$.
The detailed commands are likewise, except for the manifold calculations
in Table~\ref{tbl:demo_l1a2}, and those are given in
Table~\ref{tbl:demo_h1a}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{|l|l|}
\hline
\commandf{@R man H1a.1 startH1a} &
\commandf{H1a=run(startH1a,e='man',c='man.H1a.1')}\\
\multicolumn{2}{|p{7in}|}{
		Look at c.man.H1a.1 to see from which label in s.startH1a this
		run starts. In this run the x-coordinate of the end point 
		(\parf{PAR(21)}) is kept fixed, while the ``period''
                (\parf{PAR(11)}), 
		i.e., the total integration time, is allowed to vary, as 
		is the value of $\varepsilon$, i.e.,
                \parf{PAR(6)}. Note that if \parf{PAR(6)}
		becomes ``large'' then the manifold may no longer be accurate.
		The free parameters in this run are:

                \begin{tabular}{l@{=}lll@{=}l}
                  \parf{PAR(3)}  & energy & &
                  \parf{PAR(12)} & length of the orbit \\
                  \parf{PAR(6)}  & ``starting distance'' & &
                  \parf{PAR(22)} & $y$-coordinate at end point \\
                  \parf{PAR(11)} & integration time & &
                  \parf{PAR(23)} & $z$-coordinate at end point
                \end{tabular}}\\
\hline
\commandf{@sv H1a} &\commandf{save(H1a,'H1a')}\\

\multicolumn{2}{|l|}{
Save the results in \filef{b.H1a}, \filef{s.H1a}, and \filef{d.H1a}.}\\
\hline

\commandf{@R man H1a.2 startH1a} &
\commandf{hetH1a=run(startH1a,e='man',c='man.H1a.2')}\\

\multicolumn{2}{|p{7in}|}{
  Another run, starting from a longer initial orbit, which 
  computes part of the manifold. The free parameters are the 
  same as in the preceding run. This computation results in 
  the detection of a connecting orbit.
}\\
\hline
\commandf{@sv hetH1a} &\commandf{save(hetH1a,'hetH1a')}\\
\multicolumn{2}{|l|}{
Save the results in \filef{b.hetH1a}, \filef{s.hetH1a}, and \filef{d.hetH1a}.}\\
\hline
\end{tabular}
\end{center}
\caption{Detailed AUTO shell and Python commands for the H1a demo.}
\label{tbl:demo_h1a}
\end{table}

\subsubsection{The instructions below are for the Halo family H1 in AUTO demo H1b.}

Follow the instructions for L1a above, where you replace L by H, and a by b
throughout; for instance you can run everything in one go using
\begin{center}
\begin{tabular}{l|l}
	\commandf{auto H1b.auto} & \commandf{auto('H1b.auto')} \\
\end{tabular}
\end{center}
or with the extra calculations:
\begin{center}
\begin{tabular}{l|l}
	\commandf{auto H1bX.auto} & \commandf{auto('H1bX.auto')} \\
\end{tabular}
\end{center}
The Floquet eigenfunction is now computed from label 3 with step size
$-10^{-5}$.
The detailed commands follow the ones for H1a above, except that there
is one extra run; see Table~\ref{tbl:demo_h1b}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{|l|l|}
\hline
\commandf{@R man H1b.3 startH1b} &
\commandf{het2H1b=run(startH1b,e='man',c='man.H1b.3')}\\
\multicolumn{2}{|p{7in}|}{
		Another run, starting from a longer initial orbit, which 
		computes part of the manifold. The free parameters are the 
		same as in the preceding run. This computation results in 
		the detection of another connecting orbit.
}\\
\hline
\commandf{@sv het2H1b} & \commandf{save(het2H1b,'het2H1b')}\\
\multicolumn{2}{|l|}{
Save the results in \filef{b.het2H1b}, \filef{s.het2H1b}, and
                \filef{d.het2H1b}.}\\
\hline
\end{tabular}
\end{center}
\caption{Detailed AUTO shell and Python commands for the H1b demo.}
\label{tbl:demo_h1b}
\end{table}

\subsubsection{The instructions below are for the Halo family H1 in AUTO demo H1c.}

Follow the instructions for L1a above, where you replace L by H, and a by c
throughout; for instance you can run everything in one go using
\begin{center}
\begin{tabular}{l|l}
	\commandf{auto H1c.auto} & \commandf{auto('H1c.auto')} \\
\end{tabular}
\end{center}
The Floquet eigenfunction is now computed from label 68 with step size
$-10^{-2}$.

The detailed commands follow the ones for H1a above, except that the last
run is left out, and so the \filef{H1cX.auto} script is not necessary.

\subsubsection{The instructions below are for the Halo family V1 in AUTO demo V1a.}

Follow the instructions for L1a above, where you replace L by V throughout,
for instance you can run everything in one go using
\begin{center}
\begin{tabular}{l|l}
	\commandf{auto V1a.auto} & \commandf{auto('V1a.auto')} \\
\end{tabular}
\end{center}
The Floquet eigenfunction is now computed from label 8 with step size
$-10^{-5}$.
The detailed commands are likewise, except for the manifold calculations
in Table~\ref{tbl:demo_l1a2}, and those are given in
Table~\ref{tbl:demo_v1a}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{|l|l|}
\hline
\commandf{@R man V1a.1 startV1a} &
\commandf{V1a=run(startV1a,e='man',c='man.V1a.1')}\\

\multicolumn{2}{|p{7in}|}{
		Look at \filef{c.man.V1a.1} to see from which label in
                \filef{s.startV1a} this
		run starts. In this run the $z$-coordinate of the end point 
		(\parf{PAR(23)})
                is kept fixed, while the ``period'' (\parf{PAR(11)}), 
		i.e., the total integration time, is allowed to vary, as 
		is the value of $\varepsilon$, i.e., \parf{PAR(6)}.
                Note that if \parf{PAR(6)}
		becomes ``large'' then the manifold may no longer be accurate.
		The free parameters in this run are:
                \begin{tabular}{l@{=}lll@{=}l}
                  \parf{PAR(3)}  & energy & &
                  \parf{PAR(12)} & length of the orbit \\
                  \parf{PAR(6)}  & ``starting distance'' & &
                  \parf{PAR(21)} & $x$-coordinate at end point \\
                  \parf{PAR(11)} & integration time & &
                  \parf{PAR(22)} & $y$-coordinate at end point
                \end{tabular}
}\\
\hline
\commandf{@sv V1a} & \commandf{save(V1a,'V1a')}\\
\multicolumn{2}{|l|}{
		Save the results in \filef{b.V1a}, \filef{s.V1a}, and
                \filef{d.V1a}.}\\
\hline
\end{tabular}
\end{center}
\caption{Detailed AUTO shell and Python commands for the V1a demo.}
\label{tbl:demo_v1a}
\end{table}

\subsubsection{The instructions below are for the Halo family V1 in AUTO demo V1b.}

Follow the instructions for L1a above, where you replace L by V, and a by b
throughout; for instance you can run everything in one go using
\begin{center}
\begin{tabular}{l|l}
	\commandf{auto V1b.auto} & \commandf{auto('V1b.auto')} \\
\end{tabular}
\end{center}
or with the extra calculations:
\begin{center}
\begin{tabular}{l|l}
	\commandf{auto V1bX.auto} & \commandf{auto('V1bX.auto')} \\
\end{tabular}
\end{center}
The Floquet eigenfunction is now computed from label 12 with step size
$10^{-5}$.

The detailed commands are likewise, except for the manifold calculations
in Table~\ref{tbl:demo_l1a2}, and those are given in
Table~\ref{tbl:demo_v1b}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{|l|l|}
\hline
\commandf{@R man V1b.1 startV1b} &
\commandf{V1b=run(startV1b,e='man',c='man.V1b.1')}\\
\multicolumn{2}{|p{7in}|}{
		Look at \filef{c.man.V1b.1}
                to see from which label in \filef{s.startV1b} this
		run starts. In this run the $x$-coordinate of the end point 
		(\parf{PAR(21)}) is kept fixed, while the ``period''
                (\parf{PAR(11)}), 
		i.e., the total integration time, is allowed to vary, as 
		is the value of $\varepsilon$, i.e., \parf{PAR(6)}.
                Note that if \parf{PAR(6)}
		becomes ``large'' then the manifold may no longer be accurate.
		The free parameters in this run are:
                \begin{tabular}{l@{=}lll@{=}l}
                  \parf{PAR(3)}  & energy & &
                  \parf{PAR(12)} & length of the orbit \\
                  \parf{PAR(6)}  & ``starting distance'' & &
                  \parf{PAR(22)} & $y$-coordinate at end point \\
                  \parf{PAR(11)} & integration time & &
                  \parf{PAR(23)} & $z$-coordinate at end point
                \end{tabular}}\\
\hline
\commandf{@sv V1b}			& \commandf{save(V1b,'V1b')}\\
\multicolumn{2}{|l|}{
		Save the results in \filef{b.V1b}, \filef{s.V1b}, and
                \filef{d.V1b} .}\\
\hline
\commandf{@R man V1b.2 startV1b} &
\commandf{hetV1b=run(startV1b,e='man',c='man.V1b.2')} \\
\multicolumn{2}{|p{7in}|}{
		Another run, starting from a longer initial orbit, which 
		computes part of the manifold. The free parameters are the 
		same as in the preceding run. This computation results in 
		the detection of a connecting orbit.}\\
\hline

\commandf{@sv hetV1b} & \commandf{save(hetV1b,'hetV1b')}\\
\multicolumn{2}{|l|}{
		Save the results in \filef{b.hetV1b},
                \filef{s.hetV1b}, and \filef{d.hetV1b} .
}\\
\hline
\end{tabular}
\end{center}
\caption{Detailed AUTO shell and Python commands for the V1b demo.}
\label{tbl:demo_v1b}
\end{table}

%==============================================================================
%==============================================================================
\chapter{ \AUTO Demos : BVP.} \label{ch:Demos_BVP}
%==============================================================================
%==============================================================================

%==============================================================================
%DEMO=exp======================================================================
%==============================================================================
\section{ exp : Bratu's Equation.} \label{sec:Demos_exp}
This demo illustrates the computation of a solution family to
the boundary value problem


\begin{equation} \begin{array}{cl}
  u_1 ' &= u_2  ,  \\
  u_2 ' &= -p_1  e^{u_1} , \\
\end{array} \end{equation}
with boundary conditions $ u_1(0)=0 ,  \quad  u_1(1)=0.$
This equation is also considered in 
\citename{DoKeKe:91a} \citeyear{DoKeKe:91a}.
\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir exp} & create an empty work directory \\ 
  \commandf{cd exp} & change directory \\
  \commandf{demo('exp')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='exp',c='exp')} & 1st run; compute solution family containing fold \\ 
\hline
%==============================================================================
  \commandf{r2=run(r1,NTST=20)} & 2nd run; restart at the last labeled solution, using increased accuracy\\ 
  \commandf{save(r1+r2,'exp')} & save output to \filef{b.exp, s.exp, d.exp} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{exp}.}
\label{tbl:demo_exp}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=int======================================================================
%==============================================================================
\section{ int : Boundary and Integral Constraints.} \label{sec:Demos_int}
This demo illustrates the computation of a solution family to
the equation

\begin{equation} \begin{array}{cl}
 u_1 ' &= u_2 , \\
  u_2 ' &= -p_1  e^{u_1} , \\\end{array} \end{equation}
with a non-separated boundary condition and an integral constraint:

$$ u_1(0)-u_1(1)-p_2=0 ,\qquad \int_0^{1}u(t)dt-p_3=0 . $$
The solution family contains a fold, which, in the second run, is  
continued in two equation parameters.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir int} & create an empty work directory \\ 
  \commandf{cd int} & change directory \\
  \commandf{demo('int')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='int',c='int')} & 1st run; detection of a fold \\ 
  \commandf{save(r1,'int')} & save output-files as \filef{b.int, s.int, d.int} \\ 
\hline
%==============================================================================
  \commandf{r2=run(r1("LP1"),ICP=[1,2],ISW=2)} & 2nd run; generate starting data for a curve of folds.\\ 
\hline
%==============================================================================

  \commandf{r3=run(r2)} & \parbox[t]{3in}{3rd run; compute a curve of
    folds; restart from the last and only label in \parf{r2}. \vspace{0.2cm}}\\ 
  \commandf{save(r3,'lp')} & save the output-files as \filef{b.lp, s.lp, d.lp} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{int}.}
\label{tbl:demo_int}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=bvp======================================================================
%==============================================================================
\section{ bvp : A Nonlinear ODE Eigenvalue Problem.} \label{sec:Demos_bvp}
This demo illustrates the location of eigenvalues of a nonlinear ODE
boundary value problem as bifurcations from the trivial solution family.
The families of solutions that bifurcate at all five computed
eigenvalues, that is, the eigenfunctions, are computed in both directions.
The equations are
\begin{equation} \begin{array}{cl}
 u_1 ' &= u_2  ,  \\
  u_2 ' &=-(p_1 \pi)^{2}u_1 + u_1^{2} ,\end{array} \end{equation}
with boundary conditions $ u_1(0)=0 ,  \quad  u_1(1)=0.$~~~
We add the integral constraint
 $$ \int_0^{1} u_1(t) dt - p_2 = 0. $$
Then $p_2$ is simply the average of the first solution component.
The integral constaint gives a measure: the exact same continuations
could be done without any integral conditions in just the
one parameter $p_1$,
however $p_2$ gives us extra possibilities to plot and stop at
desirable solutions.
The values that \filef{bvp.auto} sets in \parf{UZR} make sure that
solutions are given for $p_2=\pm 3,\pm 6,\pm 9$, and the continuation
stops at $p_2=\pm 9$, and also makes sure that $0 \le p_1 \le 5.5$.
\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir bvp} & create an empty work directory \\ 
  \commandf{cd bvp} & change directory \\
  \commandf{@dm bvp } & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{auto bvp.auto } or & Run the script bvp.auto\\
  \commandf{auto('bvp.auto') } & \\
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{bvp}.}
\label{tbl:demo_bvp}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=lin======================================================================
%==============================================================================
\section{ lin : A Linear ODE Eigenvalue Problem.} \label{sec:Demos_lin}
This demo illustrates the location of eigenvalues of a linear ODE
boundary value problem as bifurcations from the trivial solution family.
By means of branch switching an eigenfunction is computed,
as is illustrated for the first eigenvalue. 
This eigenvalue is then continued in two parameters
by fixing the $L_2$-norm of the first solution component.
The eigenvalue problem is given by the equations

\begin{equation} \begin{array}{cl}
  u_1 ' &= u_2  ,  \\
  u_2 ' &= (p_1 \pi)^{2} u_1 , \end{array} \end{equation}
with boundary conditions $ u_1(0)-p_2=0 $ and $  u_1(1)=0.$
We add the integral constraint
 $$ \int_0^{1} u_1(t)^{2} dt - p_3 = 0. $$
Then $p_3$ is simply the $L_2$-norm of the first solution component.
In the first two runs $p_2$ is fixed, while $p_1$ and $p_3$ are free.
In the third run  $p_3$ is fixed, while $p_1$ and $p_2$ are free.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir lin} & create an empty work directory \\ 
  \commandf{cd lin} & change directory \\
  \commandf{demo('lin')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='lin',c='lin')} & \parbox[t]{3in}{1st run;
    compute the trivial solution family and locate eigenvalues. \vspace{0.2cm}} \\ 
\hline
%==============================================================================
  \commandf{r2=run(r1('BP1'),NTST=6,ISW=-1,DSMAX=0.5)} & \parbox[t]{3in}{2nd run; compute a few steps along the bifurcating family.  \vspace{0.2cm}}\\ 
  \commandf{save(r1+r2,'lin')} & save all output to \filef{b.lin, s.lin, d.lin} \\ 
\hline
%==============================================================================
  \commandf{r3=run(r2('UZ1'),ICP=[1,2],NTST=5,ISW=1)} & \parbox[t]{3in}{3rd run; compute a two-parameter curve of eigenvalues. \vspace{0.2cm}} \\ 
  \commandf{save(r3,'2p')} & save the output-files as \filef{b.2p, s.2p, d.2p} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{lin}.}
\label{tbl:demo_lin}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=non======================================================================
%==============================================================================
\section{ non : A Non-Autonomous BVP.} \label{sec:Demos_non}
This demo illustrates the continuation of solutions to
the non-autonomous boundary value problem

\begin{equation} \begin{array}{cl}
  u_1 ' &= u_2  ,  \\
  u_2 ' &= -p_1  e^{x^3 u_1} , \\\end{array} \end{equation}
with boundary conditions $ u_1(0)=0 ,  \quad  u_1(1)=0.$
Here $x$ is the independent variable.
This system is first converted to the following equivalent
autonomous system~:
\begin{equation} \begin{array}{cl}
  u_1 ' &= u_2  ,  \\
  u_2 ' &= -p_1  e^{u_3^3 u_1} ,  \\  
  u_3 ' &= 1 ,  \\
\end{array} \end{equation}
 with boundary conditions $ u_1(0)=0 ,  \quad  u_1(1)=0, \quad u_3(0)=0.$
(For a periodically forced system see demo \filef{frc}).

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir non} & create an empty work directory \\ 
  \commandf{cd non} & change directory \\
  \commandf{demo('non')} & copy the demo files to the work directory \\
\hline
%==============================================================================

  \commandf{r1=run(e='non',c='non')} & compute the solution family \\ 
  \commandf{save(r1,'non')} & save output-files as \filef{b.non, s.non, d.non} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{non}.}
\label{tbl:demo_non}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=kar======================================================================
%==============================================================================
\section{ kar : The Von Karman Swirling Flows.} \label{sec:Demos_kar}
The steady axi-symmetric flow of a viscous incompressible fluid
above an infinite rotating disk is modeled by the following 
ODE boundary value problem (Equation (11) in
\citename{LeKe:80} \citeyear{LeKe:80}~:
\begin{equation} \begin{array}{cl}
  u_1' &= T u_2,  \\
  u_2' &= T u_3,  \\
  u_3' &= T \bigl[ -2 \gamma u_4 + u_2^2 - 2 u_1 u_3 - u_4^2 \bigr], \\
  u_4' &= T u_5, \\
  u_5' &= T \bigl[ 2 \gamma u_2 + 2 u_2 u_4 - 2 u_1 u_5 \bigr], \\
\end{array} \end{equation}
with left boundary conditions
$$ u_1(0)=0, \qquad u_2(0)=0, \qquad u_4(0)=1-\gamma, $$
and (asymptotic) right boundary conditions
\begin{equation} \begin{array}{cl}
  & \bigl[ f_\infty + a(f_\infty,\gamma) \bigr] ~ u_2(1) + u_3(1)
  - \gamma ~ \frac{ u_4(1) }{ a(f_\infty,\gamma) } = 0,  \\
  & a(f_\infty,\gamma)~ \frac{ b^2(f_\infty,\gamma) }{ \gamma } ~u_2(1)
  + \bigl[ f_\infty + a(f_\infty,\gamma) \bigr] ~u_4(1) 
  + u_5(1) = 0, \\
 & u_1(1) = f_\infty,
 \end{array} \end{equation}
where
\begin{equation} \begin{array}{cl}
 & a(f_\infty,\gamma) = \frac{1 }{ \sqrt{2} }
  \bigl[ (f_\infty^4 + 4 \gamma^2)^{1/2} + f_\infty^2 \bigr]^{1/2}, \\
 & b(f_\infty,\gamma) = \frac{1 }{ \sqrt{2} }
  \bigl[ (f_\infty^4 + 4 \gamma^2)^{1/2} - f_\infty^2 \bigr]^{1/2}.  \\
\end{array} \end{equation}
Note that there are five differential equations and six boundary conditions.
Correspondingly, there are two free parameters in the computation of a 
solution family, namely $\gamma$ and $f_\infty$.
The ``period'' $T$ is fixed; $T=500$.
The starting solution is $u_i=0$, $i=1,\cdots,5$, 
at $\gamma=1$, $f_\infty=0$.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir kar} & create an empty work directory \\ 
  \commandf{cd kar} & change directory \\
  \commandf{demo('kar')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='kar',c='kar')} & computation of the solution family \\ 
  \commandf{save(r1,'kar')} & save output-files as \filef{b.kar, s.kar, d.kar} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{kar}.}
\label{tbl:demo_kar}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=spb======================================================================
%==============================================================================
\section{ spb : A Singularly-Perturbed BVP.} \label{sec:Demos_spb}
This demo illustrates the use of continuation to compute 
solutions to the singularly perturbed boundary value problem
\begin{equation} \begin{array}{cl}
  u_1 ' &= u_2  ,  \\
  u_2 ' &= \frac{\lambda }{ \eps} \bigl(
  u_1 u_2 (u_1^2 - 1) + u_1
  \bigr)  , \\ \end{array} \end{equation}
with boundary conditions $u_1(0)=3/2$,  $u_1(1)=\gamma.$
The parameter $\lambda$ has been introduced into the equations in order
to allow a homotopy from a simple equation with known exact solution
to the actual equation. This is done in the first run.
In the second run $\eps$ is decreased by continuation.
In the third run $\eps$ is fixed at $\eps=.001$ and the solution is continued 
in $\gamma$.
This run takes more than 1500 continuation steps.
For a detailed analysis of the solution behavior see 
\citename{JL:82} \citeyear{JL:82}.
\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir spb} & create an empty work directory \\ 
  \commandf{cd spb} & change directory \\
  \commandf{demo('spb')} & copy the demo files to the work directory \\
\hline
%==============================================================================

  \commandf{r1=run(e='spb',c='spb.0')} & 1st run; homotopy from $\lambda=0$ to $\lambda=1$ \\ 
  \commandf{save(r1,'0')} & save output-files as \filef{b.0, s.0, d.0} \\ 
\hline
%==============================================================================
  \commandf{r2=run(r1,c='spb.1')} & \parbox[t]{3in}{2nd run; let
    $\eps$ tend to zero; restart from the last label of \parf{r0}.
    constants changed : \parf{IRS, ICP(1), NTST, DS, UZR, STOP} \vspace{0.2cm}}\\ 
  \commandf{save(r2,'1')} & save the output-files as \filef{b.1, s.1, d.1} \\ 
\hline
%==============================================================================
  \commandf{r3=run(r2('UZ2'),c='spb.3')} & \parbox[t]{3in}{3rd run;
    continuation in $\gamma$; $\eps=0.001$; restart from 2nd UZ label
    of \parf{r2}.  Constants changed : \parf{IRS, ICP(1), ITNW, EPSL, EPSU, UZR} \vspace{0.2cm}} \\ 
  \commandf{save(r3,'2')} & save the output-files as \filef{b.2, s.2, d.2} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{spb}.}
\label{tbl:demo_spb}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=ezp======================================================================
%==============================================================================
\section{ ezp : Complex Bifurcation in a BVP.} \label{sec:Demos_ezp}
This demo illustrates the computation of a solution family to
the complex boundary value problem

\begin{equation} \begin{array}{cl}
  u_1 ' &= u_2  ,  \\
  u_2 ' &= -p_1  e^{u_1} , \\
\end{array} \end{equation}
with boundary conditions $ u_1(0)=0 , ~u_1(1)=0.$
Here $u_1$ and $u_2$ are allowed to be complex, 
while the parameter $p_1$ can only take real values.
In the real case, this is Bratu's equation, whose solution family 
contains a fold; see the demo \filef{exp}.
It is known 
(\citename{HeKe:90} \citeyear{HeKe:90}) that a simple quadratic fold gives rise to a pitch fork
bifurcation in the complex equation.
This bifurcation is located in the first computation below.
In the second and third run, both legs of the bifurcating solution family
are computed.
On it, both solution components $u_1$ and $u_2$ have nontrivial 
imaginary part.



\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir ezp} & create an empty work directory \\ 
  \commandf{cd ezp} & change directory \\
  \commandf{demo('ezp')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{ezp=run(e='ezp',c='ezp')} & 1st run; compute solution family containing fold \\ 
\hline
%==============================================================================
  \commandf{ezp=ezp+run(ezp('BP1'),ISW=-1)} & \parbox[t]{3in}{2nd run; compute bifurcating complex solution family.  \vspace{0.2cm}}\\ 
  \commandf{ap('ezp')} & append output-files to \filef{p.ezp, s.ezp, d.ezp} \\ 
\hline
%==============================================================================
  \commandf{ezp=ezp+run(ezp('BP1'),ISW=-1,DS='-')} & \parbox[t]{3in}{3rd run; compute 2nd leg of bifurcating family. \vspace{0.2cm}}\\ 
  \commandf{save(ezp,'ezp')} & save combined output to \filef{b.ezp, s.ezp, d.ezp} \\
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{ezp}.}
\label{tbl:demo_ezp}
\end{center}
\end{table}
%==============================================================================
\newpage

%
%==============================================================================
%DEMO=um2======================================================================
%==============================================================================
\section{ um2 : Basic computation of a 2D unstable manifold.} \label{sec:Demos_um2}
This demo shows how one can compute a 2D unstable manifold of an equilibrium
using {\it orbit continuation}.
The model equations are given by
\begin{equation} \begin{array}{cl}
 x' &= ~\eps x - y^3~, \\
 y' &=   ~~y + x^3~. \\
\end{array} \end{equation}
The origin has eigenvalues $\eps$ and $1$, where $\eps>0$, so that its 
unstable manifold is indeed $2$-dimensional. Since the phase space itself 
is $2$-dimensional, one can also consider this demo as showing how to generate 
part of a $2$-dimensional phase portrait. However, the basic steps in this demo 
also apply to the computation of $2$-dimensional unstable manifolds of equilibria 
in higher-dimensional phase space.

In the computations the independent time variable $t$ is scaled to vary in
the unit interval, so that the actual integration time $T$ becomes an 
explicit parameter in the equations, namely,

\begin{equation} \begin{array}{cl}
 x' &= ~T~(\eps x - y^3)~, \\
 y' &=      ~T~(~y + x^3)~. \\
\end{array} \end{equation}

To carry out the calculations run the Python script \filef{um2.auto} included 
in the demo. In order to better appreciate the power of orbit continuation 
for computing such manifolds, one can also run the script for a smaller value 
of $\eps$, {\it e.g.}, $\eps=10^{-2},\cdots,10^{-6}$, by changing the value
entered on the last line of the constants-file \filef{c.umn.2}. One can view
the phase portrait by plotting the solutions in the solutions-file \filef{s.3}
in the $x$-$y$ plane.

In the first run an orbit is ``grown'' by continuation in the integration time 
$T$, starting from a very small value of $T$, so that a solution that is
constant in time is an accurate initial approximation. The starting solution is 
in fact a point on a circle of small radius $r_0$ around the stationary point,
{\it i.e.}, around the origin. For illustrative purpose the value of $r_0$ is
$0.1$ in this demo, but could be smaller if more accuracy is needed.
The precise starting point is in the strongly unstable direction, namely, in 
the $y$-direction, which is the direction of the eigenvector associated with 
the ``strongly unstable eigenvalue'', which here has value $1$. 
The growing of the initial orbit is terminated when the norm of its endpoint 
reaches the value 0.6, {\it i.e.}, when $\sqrt{x(1)^2+y(1)^2}=0.6$. 

The value of $\eps$ is $0.5$ in the first run. In the second run continuation
is used to decrease the value of $\eps$ to $0.1$ (or, if desired, to a smaller 
value, as already mentioned above). The norm of the endpoint  $(x(1),y(1))$
is fixed in the second run, while $T$ is variable.

In the third run the norm of the endpoint remains fixed. However, the 
initial point $(x(0),y(0))$ is allowed to move around the small circle of 
radius $r_0$ around the orgin.  The endpoint thereby moves around the ``large''
circle of radius $0.6$. The integration time $T$ remains variable.
The orbits computed in this run generate the local 
manifold.

When viewing the orbits computed in the third run, as written in the file 
\filef{s.3}, notice that orbits near the ``weakly unstable direction'',
which here corresponds to the $x$ direction, have been well-computed. Such 
orbits are sensitively dependent on the initial condition $(x(0),y(0))$ when 
the problem is considered as an initial value problem. It is in fact the 
{\it continuation} of the {\it entire orbits} using a {\it boundary value 
approach} which enables their determination. As already mentioned, this 
feature is even more visible when running this demo with a smaller value 
of $\eps$.
\newpage

%==============================================================================
%DEMO=um3======================================================================
%==============================================================================
\section{ um3 : A 2D unstable manifold in 3D.} \label{sec:Demos_um3}
This demo uses {\it orbit continuation} to compute part of the 2D unstable 
manifold of the origin of the equations
\begin{equation} \begin{array}{cl}
 x' &= ~\eps x - y^3 + z^3~, \\
 y' &=   ~~y + x^3~, \\
 z' &=    -z + x^2~. \\
\end{array} \end{equation}
The origin has unstable eigenvalues $\eps$ and $1$, where $\eps>0$, so that its 
unstable manifold is $2$-dimensional. 
In the computations the independent time variable $t$ is scaled to vary in
the unit interval, so that the actual integration time $T$ becomes an 
explicit parameter in the equations; see, for example, demo \filef{um2}.
The calculations can be done by running the Python script \filef{um3.auto} 
included in the demo. 

In the first run an orbit is ``grown'' by continuation in the integration time 
$T$, starting from a very small value of $T$, so that a solution that is
constant in time is an accurate initial approximation. The starting solution is 
in fact a point on a circle of small radius $r_0=0.03$ in the unstable eigenspace
of the origin. 
The precise starting point is in the strongly unstable direction, namely, the
$y$-direction.
The initial orbit is grown until the $L_2$-norm of its endpoint 
$(x(1),y(1),z(1))$ reaches the value $1$. 
The value of $\eps$ is fixed at $0.5$ in the first run. In the second run 
continuation is used to decrease $\eps$ to $0.01$. The norm of the endpoint  
$(x(1),y(1),z(1))$ is fixed in this run, while $T$ is variable.

In the third run the norm of the endpoint remains fixed, but the 
initial point $(x(0),y(0),z(0))$ is allowed to move around the small circle of 
radius $r_0$ in the unstable eigenspace of the origin.  
The endpoint thereby moves on the surface of the ``large'' sphere of radius 
$1$. The integration time $T$ remains variable.
The orbits computed in this run generate the local manifold.

When viewing the orbits computed in the third run, as written in the file 
\filef{s.3}, notice that there appears to be second equilibrium with a 2D 
stable manifold which intersects the 2D unstable manifold of the origin. 
The intersection curve, which corresponds to a heteroclinic orbit,
is visible in the graphical representation of the manifold. 

\newpage
%
%==============================================================================
%DEMO=p2c======================================================================
%==============================================================================
\section{ p2c : Point to cycle connections.} \label{sec:Demos_p2c}
In this demo a point to cycle heteroclinic connection is computed via
homotopy, and then continued in two system parameters, in the Lorenz equations
\begin{eqnarray*}
  u_1' &=&  p_3 (u_2 - u_1), \\
  u_2' &=&  p_1 u_1 - u_2 - u_1 u_3,  \\
  u_3' &=&  u_1 u_2 - p_2 u_3. \end{eqnarray*}
Type \commandf{auto p2c.auto} to run the demo and
\commandf{auto clean.auto} to remove generated files.

Refer to \citename{DoKoVoKu08} \citeyear{DoKoVoKu08} and 
\url{http://www.bio.vu.nl/thb/research/project/globif/index_main.html}
for background information.

%
%==============================================================================
%DEMO=c2c======================================================================
%==============================================================================
\section{ c2c : Cycle to cycle connections.} \label{sec:Demos_c2c}

In this demo a cycle to cycle heteroclinic connection is computed via
homotopy, and then continued in one system parameter, in a food chain model:
\begin{eqnarray*}
    x' &=& x(1 - x) - \frac{5 x y}{1 + 3 x}, \\
    y' &=& \frac{5 x y}{1 + 3 x}  - p_1 y - \frac{0.1 y z}{1 + 2 y}, \\
    z' &=& \frac{0.1 y z}{1 + 2 y} - p_2 z. \end{eqnarray*}
Type \commandf{auto c2c.auto} to run the demo.
After that it is possible to compute two-parameter continuations of
folds of the cycle-to-cycle
connection, but since this is computationally intensive it is put in
a seperate file: type \commandf{auto c2cfolds.auto}.
Type \commandf{auto clean.auto} to remove all generated files.

Refer to \citename{DoKoVoKu09} \citeyear{DoKoVoKu09} and 
\url{http://www.bio.vu.nl/thb/research/project/globif/index_main.html}
for background information.

\newpage
 %==============================================================================
%DEMO=pcl======================================================================
 %==============================================================================
\section{ pcl : Lorenz: Point-to-cycle connections with Lin's method.} \label{sec:Demos_pcl}
This demo computes a point-to-cycle connection (or EtoP connection;
for equilibrium to periodic orbit) in the Lorenz equations
\begin{equation} \begin{array}{cl}
  x' &=  \sigma (y - x), \\
  y' &=  \rho x - y - x z,  \\
  z' &=  x y - \beta z, \\ \end{array} \end{equation}
using Lin's method, as described in \citename{KrRi:08}
\citeyear{KrRi:08}. Initially, we fix
$\beta=8/3$, $\sigma=10$, and let $\rho$ vary, starting from $0$.
Here we have a transition from simple to chaotic dynamics. For
approximate values of $\rho$ in the interval $[13.9265,24.0579]$
one finds preturbulence, organized by a pair of symmetrically
related periodic orbits that emanate from a homoclinic bifurcation
at $\rho\approx 13.9265$. For $\rho\approx 24.0579$ there exist
two symmetric point-to-cycle connections that mark the appearance
of a chaotic attractor for higher values of $\rho$.

The computation to find one of these two connections uses the following steps:
\begin{enumerate}
\item
Find the secondary equilibria emanating from the pitchfork
bifurcation of the equilibrium at $0$, and their Hopf bifurcations,
similarly to the demo \filef{lrz}.
\item
Follow the periodic orbit emanating from the Hopf bifurcation in
$\rho$ and its period $T$, until
$\rho=24.0579$, a value close to where a point-to-cycle connection is
known to exist.
\item
Extend the system, putting the variational equation (the eigenfunction)
into solution coordinates 4, 5, and 6. The trivial (0) eigenvector is
continued until we hit a branch point, corresponding to
where $\mu=$ \parf{PAR(12)} equals the natural logarithm of a Floquet
multiplier.
\item
Switch branches and continue the non-trivial eigenvector until its
norm $h$ equals 1.
\item
Extend the system again from 6 to 9 dimensions
to calculate a connection from the cross section $\Sigma$, given by
$x=10$, to the periodic orbit.
The connection starts at the non-trivial eigenvector with respect
to the periodic orbit with a distance of $\delta=10^{-7}$,
and grows backwards in time
until it hits the section $\Sigma$ at time $T^+$.
\item
Extend the system one last time from 9 to 12 dimensions.
We calculate a connection from the equilibrium at 0, starting at
its eigenvector over a distance of $\varepsilon=10^{-7}$,
to the cross section
$\Sigma$, at time $T^-$.
The second intersection is the one that is closest to the
intersection computed in step 5, and it is the one we want.
\item
Firstly, in the routine \funcf{PVLS} in the equations file \filef{pcl.f90},
the Lin vector, a normalized vector between the points of intersection
computed in steps 5 and 6 is put in $Z_x$, $Z_y$ and $Z_z$
  (\parf{PAR(24)-PAR(26)}).
Starting data for the Lin gap, which measures the distance between
these two points of intersection, is put in $\eta=$ \parf{PAR(23)}.
Subsequently, close this gap by continuing in 
$\eta$, $\rho$, $\delta$, $\varepsilon$, $T^-$, $T^+$, $\mu$, and $T$.
This process is illustrated in Figure~\ref{fig:Demos_pcl1}.
\item
Continue the point to cycle connection obtained in step 7
in the system parameters $\rho$ and $\beta$, together with
$\delta$, $\varepsilon$, $T^-$, $T^+$, $\mu$, and $T$.
Connections for various
values of $(\rho,\beta)$ are shown in Figure \ref{fig:Demos_pcl2}.
\end{enumerate}

The above sequence of calculations can be carried out by
running the Python script \filef{pcl.auto} (without constants files)
or \filef{pclc.auto} (with constants files) included in the demo.
See the script and the Fortran file \filef{pcl.f90} for details on
how all parameters are mapped and which precise AUTO constants
are changed at every step.
\begin{figure}[htb]
\begin{center}
\begin{picture}(550,190)
\put(-10,-20){\includegraphics[scale=0.48]{include/closegap_pcl_par}}
\put(240,-20){\includegraphics[scale=0.48]{include/closegap_pcl}}
\end{picture}
\caption{Closing the Lin-gap to obtain the point-to-cycle
connection.
The left panel is a plot of $\rho$ versus the gap size $\eta$,
and the right panel shows the corresponding orbit segments,
projected onto the $(x,z)$-plane.
To obtain these figures run \commandf{plot('closegap')} or
\commandf{@pp closegap}.}
\label{fig:Demos_pcl1}
\end{center}
\end{figure}

\begin{figure}[ht!]
\begin{center}
\begin{picture}(550,190)
\put(-10,-20){\includegraphics[scale=0.48]{include/cont_pcl_par}}
\put(240,-20){\includegraphics[scale=0.48]{include/cont_pcl}}
\end{picture}
\caption{Parameter space diagram (left) and corresponding
orbit segments in phase space (right),
where the connection is continued in $\rho$ and $\beta$.
To obtain these figures run \commandf{plot('cont')} or
\commandf{@pp cont}.}
\label{fig:Demos_pcl2}
\end{center}
\end{figure}


\newpage
%==============================================================================
%DEMO=snh======================================================================
%==============================================================================
\section{ snh : SNH with Global reinjection: Point-to-cycle connections with Lin's method.} \label{sec:Demos_snh}
This demo computes point-to-cycle
(or EtoP connection; for equilibrium to periodic orbit)
and homoclinic point-to-point connections in the model vector field
\begin{equation} \begin{array}{cl}
  x' &=  \nu_1 x - \omega y - (\alpha x - \beta y) \sin \varphi -
  (x^2+y^2)x + d (2 \cos \varphi+\nu_2)^2, \\
  y' &=  \nu_1 y + \omega x - (\alpha y + \beta x) \sin \varphi -
  (x^2+y^2) y + f (2 \cos \varphi+\nu_2)^2,  \\
  \varphi' &=  \nu_2 + s (x^2+y^2) + 2 \cos \varphi + c(x^2+y^2)^2,
  \\ \end{array} \end{equation}
using Lin's method, as described in Krauskopf and Rie\ss
(2008). %\cite{kr}
This system describes the dynamics near a saddle-node Hopf bifurcation
with global reinjection, as discussed in Krauskopf and Oldeman(2006).
We keep the following parameters fixed throughout: $\omega=1$,
$\alpha=-1.0$, $\beta=0$, $s=-1$, $c=0$, $d=0.01$, and $f=\pi d$.

Initially, we fix $\nu_2=-1.46$, since
for that value of $\nu_2$, close to $\nu_1=0.74$,
there exists a codimension-one connection from a periodic orbit
($\Gamma$) to an equilibrium ($b$). Together with a codimension-zero connection
back to $\Gamma$, it forms a heteroclinic cycle. In this example, the
flow is such that the codimension-one connecting orbit is an EtoP
orbit where the flow is from the periodic orbit to the equilibrium.
A homoclinic orbit
to $b$ also approaches this cycle. Below, we compute all three
connecting orbits.

The below sequences of calculations can be carried out by
running the Python script \filef{snh.auto} included in the demo.
The individual connections can be computed by running the scripts
\filef{h1b.auto} (homoclinic orbit), \filef{cb.auto} (codimension-one
EtoP), and \filef{tb.auto} (codimension-zero EtoP).
See the scripts and the Fortran file \filef{snh.f90} for details on
how all parameters are mapped and which precise AUTO constants
are changed at every step.

\subsection{The homoclinic point-to-point connection.}
The starting point for this investigation is a homoclinic orbit
connecting the point $b$ to itself, where the phase of $\varphi$ is
shifted by $2\pi$ (in other words, the homoclinic orbit reinjects
once and it is a heteroclinic orbit in the covering space).
We can most easily compute the homoclinic orbit using a 
homotopy method
(see the {\cal HomCont} section \ref{sec:Starting_strategies} for details):

\begin{enumerate}
\item
We locate the homoclinic orbit, or here, the heteroclinic orbit in the
covering space by continuing the one-dimensional stable manifold in
negative time. This way, {\cal HomCont} views the stable manifold as a
one-dimension unstable manifold to which its standard homotopy method
can be applied and which makes the method much more straightfoward
than starting with a two-dimensional unstable manifold.
We reach the unstable eigenspace of $E^u(b)$ as soon as the artificial
dummy parameter $\omega_1$, measuring a distance to $E^u(b)$, vanishes.
\item
We can now improve this connection by continuing in decreasing negative time,
keeping $\omega_1$ fixed, and freeing up the system parameter $\nu_1$.
\item
The resulting orbit can be continued forwards and backwards in the
system parameter $\nu_1$ and $\nu_2$, using standard {\cal HomCont} settings.
Note the setting of \parf{IEQUIB=1}: {\cal HomCont} auto-detects the phase
shift and only continues one equilibrium instead of treating
the orbit as a general heteroclinic orbit.
\end{enumerate}

The resulting homoclinic orbit snakes in parameter space between the two
tangencies of the codimension-zero connection and terminates at a
segment of the codimension-one EtoP connection. We show this in
Figure~\ref{fig:Demos_snh3}.

\subsection{The codimension-one point-to-cycle connection.}
To compute the codimension-one point-to-cycle connection,
the following steps are used (very similar to those in the
demo \commandf{pcl}):
\begin{enumerate}
\item
Continue the first equilibrium $a$ at $x=y=0$,
$\varphi=-\mathrm{arccos}(-\nu_2/2)$, which undergoes a Hopf bifurcation
at $\nu_1\approx 0.683447$.
\item
Follow the periodic orbit, emanating from the Hopf bifurcation, in
$\nu_1$ and its period $T$, until $\nu_1=0.74$.
\item
Extend the system, putting the variational equation (the eigenfunction)
into solution coordinates 4, 5, and 6. The trivial (0) eigenvector is
continued until we hit a branch point, corresponding to
where $\mu=$ \parf{PAR(12)} equals the natural logarithm of a Floquet
multiplier.
\item
Switch branches and continue the non-trivial eigenvector until its
norm $h$ equals 1.
\item
Extend the system again from 6 to 9 dimensions
to calculate a connection from the periodic orbit to the cross section
$\Sigma$, given by $\varphi=\pi$.
The connection starts at the non-trivial eigenvector with respect
to the periodic orbit with a distance of $\delta=-10^{-5}$,
and grows forwards in time
until it hits the section $\Sigma$ at time $T^-$.
\item
Extend the system one last time from 9 to 12 dimensions.
We calculate a connection backwards in time
from the second equilibrium $b$ at $x=y=0$,
$\varphi=\mathrm{arccos}(-\nu_2/2)$, starting at
its eigenvector over a distance of $\varepsilon=10^{-6}$,
to the cross section $\Sigma$, at time $T^+$.
The Lin vector, a normalized vector between the points of intersection
computed in steps 5 and 6, is put in $Z_x$, $Z_y$ and $Z_z$
(\parf{PAR(24)-PAR(26)}).
Starting data for the Lin gap, which measures the distance between
these two points of intersection is put in $\eta=$ \parf{PAR(23)}.
\item
Close the gap computed in step 6 by continuing in 
$\eta$, $\nu_1$, $\delta$, $\varepsilon$, $T^+$, $T^-$, $\mu$, and
$T$. The connection is found at $\nu_1=7.41189$.
This process is illustrated in Figure~\ref{fig:Demos_snh1}.
\item
Continue the point to cycle connection obtained in step 7
in the system parameters $\nu_1$ and $\nu_2$, together with
$\delta$, $\varepsilon$, $T^+$, $T^-$, $\mu$, and $T$.
Connections for various
values of $(\nu_1,\nu_2)$ are shown in Figure \ref{fig:Demos_snh2}.
\end{enumerate}

\begin{figure}[htb]
\begin{center}
\begin{picture}(550,190)
\put(-10,-20){\includegraphics[scale=0.48]{include/closegap_snh_par}}
\put(250,-15){\includegraphics[scale=0.48]{include/closegap_snh}}
\end{picture}
\caption{Closing the Lin-gap to obtain the point-to-cycle connection.
The left panel is a plot of $\nu_1$ versus the gap size $\eta$,
and the right panel shows the corresponding orbit segments.
To obtain these figures run \commandf{plot('closegap')} or
\commandf{@pp closegap}, and
\commandf{plot3('closegap')} or \commandf{@pl closegap}.}
\label{fig:Demos_snh1}
\end{center}
\end{figure}

\begin{figure}[h!]
\begin{center}
\begin{picture}(550,190)
\put(-10,-20){\includegraphics[scale=0.48]{include/cb_snh_par}}
\put(250,-15){\includegraphics[scale=0.48]{include/cb_snh}}
\end{picture}
\caption{Parameter space diagram (left) and corresponding orbit
segments in phase space (right),
where the connection is continued in $\nu_1$ and $\nu_2$.
To obtain these figures run \commandf{plot('cb')}
or \commandf{@pp cb}, and \commandf{plot3('cb')} or
\commandf{@pl cb}. Label 13 denotes the largest connection,
at a saddle-node bifurcation of limit cycles,
and label 16 the smallest one, where the periodic orbit disappears in
a Hopf bifurcation.}
\label{fig:Demos_snh2}
\end{center}
\end{figure}

\subsection{The codimension-zero point-to-cycle connection.}
Next we compute the codimension-zero connection back to the cycle
which must also exist near the accumulation of the parameter space
curve $h_1^b$.
This computation starts in the same way as the computation of the
codimension-one connection: steps 1 to 4 are the same except that in
step 3 we now find the negative Floquet exponent $\mu$,
instead of the positive exponent. Steps 5 to 8 proceed as follows:
\begin{enumerate}
\item[5.]
Similarly to step 5 before, we compute an orbit in the stable manifold
of the periodic orbit. However, Lin's method is not used, because it
is easier to use a homotopy method to connect directly to the unstable
eigenspace $E^u(b)$, which is given by the section where
$\varphi=\mathrm{arccos}(-\nu_2/2)$.
Because we compute an approximation to the stable rather than the
unstable manifold using almost the same boundary value problem,
we let $T^-$ be negative. Also the distance from the periodic orbit
to the connection is now given by $\delta=10^{-4}$, flipping its sign.
\item[6.]
Improve the connection computed in step 5, by decreasing
the negative value of $T^-$, fixing the starting point in $E^u(b)$
and freeing $\delta$.
\item[7.]
Follow the codimension-zero connection in the system parameter
$\nu_1$, together with $\mu$, $T$, $\delta$, and $T^-$, also adding
an integral condition for the connection. \AUTO detects two fold
points (LP), corresponding to tangencies of $W^u(b)$ and $W^s(\Gamma)$.
\item[8.]
Continue the two folds forwards and backwards in two parameters,
by adding the system parameter $\nu_2$ and setting the \AUTO constant
\parf{ISW=2}. The folds terminate where $\Gamma$ disappears in a
Hopf bifurcations (small $\nu_1$) and disappears in a saddle-node bifurcation
of limit cycles (large $\nu_1$). In both cases the continued
connection and orbit stop converging, so \AUTO reports MX.
\end{enumerate}

\begin{figure}[h!]
\begin{center}
\begin{picture}(550,190)
\put(-10,-20){\includegraphics[scale=0.48]{include/cont_snh_all_par}}
\put(251,-15){\includegraphics[scale=0.45]{include/cont_snh_all}}
\end{picture}
\caption{Parameter space diagram (left) and the corresponding homoclinic
orbit on the snaking curve $h_1^b$ for label 20 (right). The snaking
curve is in between the two tangencies for the codimension-zero EtoP
connection $t_b$ and terminates at a segment of the codimension-one
EtoP connection $c_b$.
To obtain these figures run \commandf{plot('all')}
or \commandf{@pp all}, and \commandf{plot3('all')} or
\commandf{@pl all}.}
\label{fig:Demos_snh3}
\end{center}
\end{figure}

\newpage
%==============================================================================
%DEMO=fnc======================================================================
%==============================================================================
\section{ fnc : Canards in the FitzHugh-Nagumo system.} \label{sec:Demos_fnc}

This demo computes attracting and repelling slow manifolds
in the self-coupled FitzHugh-Nagumo system:
\begin{equation} \label{eq:Demos_fnc} \begin{array}{cl} 
v' &= h - (v^3 - v + 1) / 2 - \gamma s v,\\
h' &= -\varepsilon (2h + 2.6 v),\\
s' &= -\varepsilon \delta s.\\
\end{array} \end{equation}
Furthermore, this demo continues canard orbits in parameter space.
Typically, trajectories in slow-fast systems such as this one
consist of a slow part
that follows the attracting slow manifold, followed by a fast part
when the trajectory hits a fold with respect to the fast direction.
After this jump, the trajectory follows a slow segment again.
A canard orbit, on the other hand, does not jump at the fold but
follows the repelling slow manifold. A central role is played by the
two-dimensional critical manifold $S$ which is given by the nullcline
of the fast variable in the limit for $\varepsilon=0$. It consists of
attracting and repelling sheets $S^a$ and $S^r$, which generically
meet at fold curves $F$ with respect to the fast flow direction.
For details, see \citename{DeKrOs:08} \citeyear{DeKrOs:08,DeKrOs:09}.

For system (\ref{eq:Demos_fnc}), where we fix $\gamma=0.5$ and
$\delta=0.565$, the critical manifold is given by
\begin{equation} \label{eq:Demos_fnc_S}
S=\{(v,h,s)\in \mathbb{R}^3| 2h-v^3+v-1-vs=0\},
\end{equation}
which is folded with respect to the fast variable $v$ along the folded
node curve
\begin{equation} \label{eq:Demos_fnc_F}
F=\{(v,h,s)\in S| 1 - 3v^2=0\}.
\end{equation}

The computation of the slow manifolds is performed in three steps.
They start with a constant-in-time solution at the folded node singularity
$(v,h,s)=(-0.49,0.6176,0.2797)$ for $\varepsilon=0.015$ on the scaled
time interval $[0,1]$ with time lengths $T^a=0$ and $T^r=0$, respectively.
Then, for the computation of the attracting manifold $(v^a,h^a,s^a)$,
via boundary conditions we always keep the starting point
$(v^a(0),h^a(0),s^a(0))$ on $S$ and $s^a(1)$ fixed to $0.2797$.
The steps are as follows:
\begin{enumerate}
\item
Homotopy step 1: grow the orbit segment in $T^a$, continuing also in
$v^a(0)$, $h^a(0)$, and $s^a(0)$, where the starting point
is kept on the folded node $F$ until $s^a(0)=0.6$.
\item
Homotopy step 2: the extra boundary condition for $F$ is dropped,
and we now instead fix $s^a(0)=0.6$.
We continue in $v^a(0)$, $h^a(0)$, and $T^a$ until $h^a(0)=-6.0$.
\item
Actual computation: we continue in $v^a(0)$, $s^a(0)$, and $T^a$,
fixing $h^a(0)=-6.0$. The end-point coordinates $v^a(1)$ and $h^a(1)$
are monitored so they can be matched with starting points of the
repelling manifold. These matches were found manually and are
now indicated at specific values of $T^a$ as UZ labels.
\end{enumerate}

For the repelling manifold $(v^r,h^r,s^r)$,
we always keep the end point $(v^r(1),h^r(1),s^r(1))$ on $S$
and $s^r(0)$ fixed to $0.2797$.
The steps are now as follows:
\begin{enumerate}
\item
Homotopy step 1: grow the orbit segment in $T^r$ until $s^r(1)=0.05$.
\item
Homotopy step 2: the extra boundary condition for $F$ is dropped,
and we now instead fix $s^r(1)=0.05$. We continue until $v^r(1)=0$.
\item
Actual computation: we continue in $s^r(0)$ and $T^r$,
fixing $v^r(1)=0$. The starting point coordinates $v^r(0)$ and $h^r(0)$
are now monitored for matches with the attracting manifold.
\end{enumerate}

The demo contains one folder \filef{attr}
for the "attracting" slow manifold and one folder \filef{rep} for 
the "repelling" slow manifold. In each of these two folders, the
manifolds can be computed by running the commands
\filef{auto attr.auto} and \filef{auto rep.auto}, respectively.
The alternative
script files \filef{attrc.auto} and \filef{repc.auto} use constants
files for every step instead of specifying the constants in the
script.

The main folder contains AUTO files to continue in 
parameter space six of the secondary canards of this systems. The
script \filef{fnc.auto} first computes the attracting and
repelling slow manifolds in their respective folders and next
concatenates matching manifolds in Python.  Six of these canard
orbits are then continued in $\varepsilon$ in both decreasing and
increasing direction.

If $T^a_j$ is the integration time for the canard segment $\xi^a_j$ on the 
attracting slow manifold and $T^r_j$ is the integration time for the orbit 
segment $\xi^r_j$ on the repelling slow manifold corresponding to the same 
canard solution, then the concatenated orbit segment $\xi_j$ has
$T^c_j=T^a_j+T^r_j$ as integration time.
The orbit $\xi_j$ is obtained from $\xi^a_j$ and $\xi^r_j$ by,
concatenating $\xi^a_j$ and $\xi^r_j$, and rescaling the time
so that it runs monotonically from 0 to 1.

Parameters are then also copied, where only those relating to the
start of the attracting manifold and the end of the repelling manifold
are kept, for these parameters are used for the boundary conditions of
the canard orbits. The new integration time $T^c_j$ is stored in
\parf{PAR(11)}.

Two constant files are provided. They correspond to the continuation
in epsilon in both decreasing (\filef{c.fnc}) and
and increasing (\filef{c.fnc.epsplus}) direction.
Continuation in any other system parameter is 
easily obtained by editing the \parf{ICP} entry.

The script \filef{plot.auto} produces the plots
we show here, in Figures~\ref{fig:Demos_fnc1},
\ref{fig:Demos_fnc2}, and \ref{fig:Demos_fnc3}.

\begin{figure}[h!]
\begin{center}
\begin{picture}(550,190)
\put(-10,-20){\includegraphics[scale=0.48]{include/fnc_attrrep1}}
\put(251,-15){\includegraphics[scale=0.45]{include/fnc_attrrep2}}
\end{picture}
\caption{Repelling and attracting slow manifold curves
where they match up (left) and their intersection curves at $s=0.2797$ in
the $(h,v)$ plane (right).}
\label{fig:Demos_fnc1}
\end{center}
\end{figure}

\begin{figure}[h!]
\begin{center}
\begin{picture}(550,190)
\put(-10,-20){\includegraphics[scale=0.48]{include/fnc_canards1}}
\put(240,-20){\includegraphics[scale=0.48]{include/fnc_canards2}}
\end{picture}
\caption{Continuation of canard orbits: the AUTO $L_2$ norm as
a function of $\varepsilon$ for all six orbits (left), and 
a projection of labels 4, 8, 11, and 16 (black, red, blue, green)
of the orbit $\xi_3$ on the $(v,s)$ plane (right).}
\label{fig:Demos_fnc2}
\end{center}
\end{figure}

\begin{figure}[h!]
\begin{center}
\begin{picture}(550,130)
\put(-17,-20){\includegraphics[scale=0.5]{include/fnc_canards3}}
\put(233,-20){\includegraphics[scale=0.5]{include/fnc_canards4}}
\put(359,-20){\includegraphics[scale=0.5]{include/fnc_canards5}}
\end{picture}
\caption{Continuation of canard orbits: projection of all canard
orbits on the $(v,s)$ plane for $\varepsilon=0.015$ (left),
$\varepsilon=10^{-4}$ (middle), and $\varepsilon=10^{-6}$ (right).}
\label{fig:Demos_fnc3}
\end{center}
\end{figure}

%==============================================================================
%==============================================================================
\chapter{ \AUTO Demos : Parabolic PDEs.} \label{ch:Demos_PDE}
%==============================================================================
%==============================================================================

\newpage
%==============================================================================
%DEMO=pd1======================================================================
%==============================================================================
\section{ pd1 : Stationary States (1D Problem).} \label{sec:Demos_pd1}
This demo uses Euler's method to locate a stationary solution of
a nonlinear parabolic PDE, followed by continuation of this stationary
state in a free problem parameter. The equation is
 $$ \frac{\partial u }{ \partial t} 
  = D~\frac{\partial^2 u }{ \partial x^2} ~+~  p_1~ u ~( 1-u) , $$
on the space interval $[0,L]$, where $L=$~{\tt PAR(11)}~$=10$ is fixed throughout,
as is the diffusion constant $D=$~{\tt PAR(15)}~$=0.1$.
The boundary conditions are $u(0) = u(L) = 0$ for all time.

In the first run the continuation parameter is the independent time variable,
namely \parf{PAR(14)}, while $p_1=1$ is fixed.
The \AUTO-constants \parf{DS}, \parf{DSMIN}, and \parf{DSMAX} then control the step size
in space-time, here consisting of \parf{PAR(14)} and  $u(x)$.
Initial data are $u(x)=\sin(\pi x/L)$ at time zero.
Note that in the subroutine \funcf{ STPNT} the initial data must be scaled to 
the unit interval, and that the scaled derivative must also be provided; 
see the equations-file \filef{pv1.f90}.
In the second run the continuation parameter is $p_1$.

Euler time integration is only first order accurate, so that
the time step must be sufficiently small to ensure correct results.
Indeed, this option has been added only as a convenience, and should 
generally be used only to locate stationary states.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir pd1} & create an empty work directory \\ 
  \commandf{cd pd1} & change directory \\
  \commandf{demo('pd1') } & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='pd1',c='pd1') } & time integration towards stationary state \\ 
  \commandf{save(r1,'1') } & save output-files as \filef{b.1, s.1, d.1} \\ 
\hline
%==============================================================================
\parbox[t]{3.3in}{
  \commandf{r2=run(r1,IPS=17,ICP=[1],NTST=20,
    NMX=100,RL1=50,NPR=25,DS=0.1,DSMAX=0.5)}}
& \parbox[t]{3in}{continuation of stationary states; read restart data
  from the last label of \parf{r1} \vspace{0.2cm}} \\ 
  \commandf{save(r2,'2') } & save output-files as \filef{b.2, s.2, d.2} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{pd1}.}
\label{tbl:demo_pd1}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=pd2======================================================================
%==============================================================================
\section{ pd2 : Stationary States (2D Problem).} \label{sec:Demos_pd2}
This demo uses Euler's method to locate a stationary solution of
a nonlinear parabolic PDE, followed by continuation of this stationary
state in a free problem parameter. The equations are
\begin{equation} \begin{array}{cl}
  {\partial u_1 / \partial t} &= D_1~{\partial^2 u_1 / \partial x^2}
  ~+~  p_1~ u ~( 1-u) ~-~ u_1 u_2 , \\
  {\partial u_2 / \partial t} 
  &= D_2~{\partial^2 u_2 / \partial x^2} ~-~ u_2 ~+~ u_1 u_2 , \\
\end{array} \end{equation}
on the space interval $[0,L]$, where $L=$~\parf{PAR(11)}~$=1$ is fixed throughout,
as are the diffusion constants $D_1=$~\parf{PAR(15)}~$=1$ and $D_2=$~\parf{PAR(16)}~$=1$.
The boundary conditions are $u_1(0) = u_1(L) = 0$ and $u_2(0) = u_2(L) = 1$,
for all time.

In the first run the continuation parameter is the independent time variable,
namely \parf{PAR(14)}, while $p_1=12$ is fixed.
The \AUTO-constants \parf{DS}, \parf{DSMIN}, and \parf{DSMAX} then control the step size
in space-time, here consisting of \parf{PAR(14)} and $(u_1(x),u_2(x))$.
Initial data at time zero are $u_1(x)=\sin(\pi x/L)$ and $u_2(x)=1$.
Note that in the subroutine \funcf{ STPNT} the initial data must be scaled to 
the unit interval, and that the scaled derivatives must also be provided; 
see the equations-file \filef{pv2.f90}.
In the second run the continuation parameter is $p_1$.
A branch point is located during this run.

Euler time integration is only first order accurate, so that
the time step must be sufficiently small to ensure correct results.
Indeed, this option has been added only as a convenience, and should 
generally be used only to locate stationary states.


\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir pd2} & create an empty work directory \\ 
  \commandf{cd pd2} & change directory \\
  \commandf{demo('pd2') } & copy the demo files to the work directory \\
\hline
%==============================================================================

  \commandf{r1=run(e='pd2',c='pd2') } & time integration towards stationary state \\ 
  \commandf{save(r1,'1')} & save output-files as \filef{b.1, s.1, d.1} \\ 
\hline
%==============================================================================
\parbox[t]{3.4in}{
  \commandf{r2 = run(r1,IPS=17,ICP=[1],ISP=2,NMX=15,
            NPR=50,DS=-0.1,DSMAX=1.0,UZR=\{-1:0.0\})}} & \parbox[t]{3in}{continuation of stationary states; read restart data from \filef{s.1} \vspace{0.2cm}}\\ 
  \commandf{save(r2,'2') } & save output-files as \filef{b.2, s.2, d.2} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{pd2}.}
\label{tbl:demo_pd2}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=wav======================================================================
%==============================================================================
\section{ wav : Periodic Waves.} \label{sec:Demos_wav}
This demo illustrates the computation of various periodic wave solutions
to a system of coupled parabolic partial differential equations
on the spatial interval $[0,1]$.
The equations, that model an enzyme catalyzed reaction 
(\citename{DoKe:86a} \citeyear{DoKe:86a}) are~:
\begin{equation} \begin{array}{cl}
 {\partial u_1 / \partial t}
  &=
  ~{\partial^{2} u_1 / \partial x^{2}}
  -p_1 \bigl[p_4 R(u_1,u_2) - (p_2 - u_1) \bigr] ,\\
 {\partial u_2 / \partial t}
  &=
  \beta {\partial^{2} u_2 / \partial x^{2}}
  -p_1 \bigl[p_4 R(u_1,u_2) - p_7 (p_3 - u_2) \bigr].\\
\end{array} \end{equation}
All equation parameters, except $p_3$, are fixed throughout.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir wav} & create an empty work directory \\ 
  \commandf{cd wav} & change directory \\
  \commandf{demo('wav')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='wav',c='wav')} &
  \parbox[t]{3in}{
  1st run; stationary solutions of the system without diffusion \vspace{0.2cm}} \\ 
  \commandf{save(r1,"ode")} & save output-files as \filef{b.ode, s.ode, d.ode} \\ 
\hline
%==============================================================================
  \commandf{r2=run(e='wav',c='wav',IPS=11)} &
  \parbox[t]{3in}{2nd run; detect bifurcations to wave train solutions \vspace{0.2cm}}\\ 
\hline
%==============================================================================
  \parbox[t]{3.5in}{
  \commandf{r3=run(r2("HB1"),IPS=12,ICP=[3,11],ILP=0,
    ISP=0,RL1=700,DS=0.1,DSMAX=1.0,
    UZR=\{3:[610.0,638.0], -11:500.0\})}}
 & \parbox[t]{3in}{3rd run; wave train solutions of fixed wave speed \vspace{0.2cm}}\\ 
  \commandf{save(r2+r3,'wav') } & save output to \filef{b.wav, s.wav, d.wav} \\ 
\hline
%==============================================================================
  \parbox[t]{3.5in}{
  \commandf{uz3=load(r3("UZ3"),RL1=1000,
    DS=0.5,DSMAX=2.0,UZR=\{\})}}&
  load restart label\\
  \commandf{r4=run(uz3,ICP=[3,10],NPR=50)} & \parbox[t]{3in}{4th run; wave train solutions of fixed wave length \vspace{0.2cm}}\\ 
  \commandf{save(r4,'rng') } & save output-files as \filef{b.rng, s.rng, d.rng} \\ 
\hline
%==============================================================================
  \commandf{r5=run(uz3,IPS=14,ICP=[14],NMX=230,NPR=5)} & \parbox[t]{3in}{5th run; time evolution computation \vspace{0.2cm}}\\ 
  \commandf{save(r5,'tim') } & save output-files as \filef{b.tim, s.tim, d.tim} \\ 
%
%#
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{wav}.}
\label{tbl:demo_wav}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=brc======================================================================
%==============================================================================
\section{ brc : Chebyshev Collocation in Space.} \label{sec:Demos_brc}
This demo illustrates the computation of stationary solutions and periodic
solutions to systems of parabolic PDEs in one space variable,
using Chebyshev collocation in space.
More precisely, the approximate solution is assumed of the form
$u(x,t) = \sum_{k=0}^{n+1} u_k(t) \ell_k(x)$.
Here $u_k(t)$ corresponds to $u(x_k,t)$ at the Chebyshev points
$\bigl\{ x_k \bigr\}_{k=1}^{n}$ with respect to the interval $[0,1]$.
The polynomials $\bigl\{ \ell_k(x) \bigr\}_{k=0}^{n+1}$ are the Lagrange
interpolating coefficients with respect to points 
$\bigl\{ x_k \bigr\}_{k=0}^{n+1}$, where $x_0=0$ and $x_{n+1}=1$.
The number of Chebyshev points in $[0,1]$,
as well as the number of equations in the PDE system,
can be set by the user in the file \filef{brc.f90}.

As an illustrative application we consider the Brusselator
(\citename{HoKnKu:87} \citeyear{HoKnKu:87})
\begin{equation} \begin{array}{cl}
  u_t &= {D_x / L^2} u_{xx} + u^2v - (B+1)u + A,  \\
  v_t &= {D_y / L^2} v_{xx} - u^2v + Bu,  \\
\end{array} \end{equation}
with boundary conditions $u(0,t)=u(1,t)=A$
and $v(0,t)=v(1,t)=B/A$.

Note that, given the non-adaptive spatial discretization,
the computational procedure here is not appropriate for
PDEs with solutions that rapidly vary in space, and care must
be taken to recognize spurious solutions and bifurcations.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir brc} & create an empty work directory \\ 
  \commandf{cd brc} & change directory \\
  \commandf{demo('brc')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='brc',c='brc') } & \parbox[t]{3in}{
compute the stationary solution family with Hopf bifurcations.
\vspace{0.2cm}}\\ 
\hline
%==============================================================================
  \commandf{r2=run(r1("HB1"),IPS=2,ICP=[5,11]) } & \parbox[t]{3in}{compute a family of periodic solutions from the first Hopf point. \vspace{0.2cm}}\\ 
\hline
%==============================================================================
  \commandf{r3=run(r2("BP1"),ISW=-1) } & \parbox[t]{3in}{compute a solution family from a secondary periodic bifurcation. \vspace{0.2cm}}\\ 
  \commandf{save(r1+r2+r3,'brc') } & save all output to \filef{b.brc, s.brc, d.brc} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{brc}.}
\label{tbl:demo_brc}
\end{center}
\end{table}


\newpage
%==============================================================================
%DEMO=brf======================================================================
%==============================================================================
\section{ brf : Finite Differences in Space.} \label{sec:Demos_brf}
This demo illustrates the computation of stationary solutions and periodic
solutions to systems of parabolic PDEs in one space variable.
A fourth order accurate finite difference approximation is used to
approximate the second order space derivatives. 
This reduces the PDE to an autonomous ODE of fixed dimension
which \AUTO is capable of treating.
The spatial mesh is uniform; the number of mesh intervals,
as well as the number of equations in the PDE system,
can be set by the user in the file \filef{brf.f90}.

As an illustrative application we consider the Brusselator
(\citename{HoKnKu:87} \citeyear{HoKnKu:87})
\begin{equation} \begin{array}{cl}
  u_t &= {D_x / L^2} u_{xx} + u^2v - (B+1)u + A,  \\
  v_t &= {D_y / L^2} v_{xx} - u^2v + Bu,  \\
\end{array} \end{equation}
with boundary conditions $u(0,t)=u(1,t)=A$
and $v(0,t)=v(1,t)=B/A$.

Note that, given the non-adaptive spatial discretization,
the computational procedure here is not appropriate for
PDEs with solutions that rapidly vary in space, and care must
be taken to recognize spurious solutions and bifurcations.


\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir brf} & create an empty work directory \\ 
  \commandf{cd brf} & change directory \\
  \commandf{demo('brf') } & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='brf',c='brf') } & \parbox[t]{3in}{compute the
    stationary solution family with Hopf bifurcations \vspace{0.2cm}}  \\ 
\hline
%==============================================================================
\parbox[t]{3in}{
  \commandf{r2=run(r1("HB1"),IPS=2,ICP=[5,11], NMX=120,EPSL=1e-8) }
\vspace{0.2cm}}
 & \parbox[t]{3in}{compute a family of periodic solutions from the first Hopf point. \vspace{0.2cm}}\\ 
\hline
%==============================================================================
\parbox[t]{3in}{
  \commandf{r3=run(r2("BP1"),ISW=-1, NMX=100,EPSL=1e-7) }
\vspace{0.2cm}}
& \parbox[t]{3in}{compute a solution family from a secondary periodic bifurcation.\vspace{0.2cm}}\\ 
  \commandf{save(r1+r2+r3,'brf') } & save all output to \filef{b.brf, s.brf, d.brf} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{brf}.}
\label{tbl:demo_brf}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=bru======================================================================
%==============================================================================
\section{ bru : Euler Time Integration (the Brusselator).} \label{sec:Demos_bru}
This demo illustrates the use of Euler's method for time integration
of a nonlinear parabolic PDE.
The example is the Brusselator
(\citename{HoKnKu:87} \citeyear{HoKnKu:87}), given by
\begin{equation} \begin{array}{cl}
  u_t &= {D_x / L^2} u_{xx} + u^2v - (B+1)u + A,  \\
  v_t &= {D_y / L^2} v_{xx} - u^2v + Bu,  \\
\end{array} \end{equation}
with boundary conditions $u(0,t)=u(1,t)=A$
and $v(0,t)=v(1,t)=B/A$. All parameters are given fixed values
for which a stable periodic solution is known to exist.

The continuation parameter is the independent time variable,
namely \parf{PAR(14)}.
The \AUTO-constants \parf{DS}, \parf{DSMIN}, and \parf{DSMAX}
then control the step size
in space-time, here consisting of \parf{PAR(14)} and $(u(x),v(x))$.
Initial data at time zero are 
$u(x)=A - 0.5 \sin(\pi x)$ and 
$v(x)=B/A + 0.7 \sin(\pi x)$.
Note that in the subroutine \funcf{ STPNT} the space derivatives of $u$ and $v$
must also be provided; 
see the equations-file \filef{bru.f90}.

Euler time integration is only first order accurate, so that
the time step must be sufficiently small to ensure correct results.
This option has been added only as a convenience, and should 
generally be used only to locate stationary states.
Indeed, in the case of the asymptotic periodic state of this demo,
the number of required steps is very large and use of a better time 
integrator is advisable.


\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir bru} & create an empty work directory \\ 
  \commandf{cd bru} & change directory \\
  \commandf{demo('bru') } & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='bru',c='bru') } & time integration \\ 
  \commandf{save(r1,'bru') } & save output-files as \filef{b.bru, s.bru, d.bru} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{bru}.}
\label{tbl:demo_bru}
\end{center}
\end{table}

%==============================================================================
%==============================================================================
\chapter{ \AUTO Demos : Optimization.} \label{ch:Demos_Opt}
%==============================================================================
%==============================================================================

\newpage
%==============================================================================
%DEMO=opt======================================================================
%==============================================================================
\section{ opt : A Model Algebraic Optimization Problem.} \label{sec:Demos_opt}
This demo illustrates the method of successive continuation 
for constrained optimization problems 
 by applying it to the following
simple problem~:~
Find the
maximum sum of coordinates on the unit sphere in $R^{5}$.
Coordinate 1 is treated as the state variable.
Coordinates 2-5 are treated as control parameters.
For details on the successive continuation procedure
see  \citename{DoKeKe:91a} \citeyear{DoKeKe:91a},
\citename{DoKeKe:91b} \citeyear{DoKeKe:91b}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir opt} & create an empty work directory \\ 
  \commandf{cd opt} & change directory \\
  \commandf{demo('opt')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='opt',c='opt')} & one free equation parameter \\ 
  \commandf{save(r1,'1')} & save output-files as \filef{b.1, s.1, d.1} \\ 
\hline
%==============================================================================
  \commandf{r2=run(r1("LP1"))} & \parbox[t]{3in}{two free equation parameters; read restart data from \parf{r1} \vspace{0.2cm}}\\ 
  \commandf{save(r2,'2')} & save output-files as \filef{b.2, s.2, d.2} \\ 
\hline
%============================================================================== 
  \commandf{r3=run(r2("LP1"))} & \parbox[t]{3in}{three free equation parameters; read restart data from \parf{r2} \vspace{0.2cm}}\\ 
  \commandf{save(r3,'3')} & save output-files as \filef{b.3, s.3, d.3} \\ 
\hline
%==============================================================================
  \commandf{run(r3("LP1"))} & \parbox[t]{3in}{four free equation parameters; read restart data from \parf{r3} \vspace{0.2cm}}\\ 
  \commandf{save(r4,'4')} & save output-files as \filef{b.4, s.4, d.4} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{opt}.}
\label{tbl:demo_opt}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=ops======================================================================
%==============================================================================
\section{ ops : Optimization of Periodic Solutions.} \label{sec:Demos_ops}
This demo illustrates the method of successive continuation
for the optimization of periodic solutions.
For a detailed description of the basic method see
\citename{DoKeKe:91b} \citeyear{DoKeKe:91b}.
The illustrative system of autonomous ODEs, taken from 
\citename{Alej:91} \citeyear{Alej:91}, is
\begin{equation} \begin{array}{cl}
  x'(t) & = [-\lambda_4(x^3/3-x) + (z-x)/\lambda_2 - y]/\lambda_1, \\
  y'(t) &= x-\lambda_3, \\
  z'(t) &= -(z-x)/\lambda_2,
\end{array} \end{equation}
with objective functional
$$ \omega = 
  \int_0^{1} g(x,y,z;\lambda_1,\lambda_2,\lambda_3,\lambda_4) ~ dt, $$
where $g(x,y,z;\lambda_1,\lambda_2,\lambda_3,\lambda_4) \equiv \lambda_3$.
Thus, in this application, a one-parameter extremum of $g$ corresponds
to a fold with respect to the problem parameter $\lambda_3$, 
and multi-parameter extrema correspond to generalized folds.
Note that, in general, the objective functional is an integral along 
the periodic orbit, so that a variety of optimization problems
can be addressed.

For the case of periodic solutions, the extended optimality system
can be generated automatically, i.e., one need only define the vector field 
and the objective functional, as in done in the file \filef{ops.f90}.
For reference purpose it is convenient here to write down
the full extended system in its general form~:

\begin{equation} \begin{array}{cl}
  &u'(t)  = T f \bigl( u(t),\lambda \bigr) ,
  \qquad T\in \R {\rm ~(period)},~ u(\cdot),f(\cdot,\cdot) \in \Rn, 
  ~ \lambda \in \R^{n_{\lambda}},  \\
  & \cr
  &w'(t)  = -Tf_u\bigl( u(t),\lambda \bigr)^{*} w(t) 
  + \kappa u_0'(t) 
  + \gamma g_u\bigl( u(t),\lambda \bigr)^{*}, 
  \qquad w(\cdot) \in \Rn,~ \kappa, \gamma \in \R, \\
  & \cr
  &u(1) - u(0) = 0, \qquad w(1) - w(0) = 0,  \\
  & \cr  
  &\int_{0}^{1} u(t)^{*} u_0'(t)~ dt = 0,  \\
  & \cr
  &\int_{0}^{1}  \omega - g\bigl(u(t),\lambda\bigr)  ~dt = 0,  \\
  & \cr
  &\int_0^{1}  w(t)^{*}w(t)
  + \kappa^2 + \gamma^{2} - \alpha ~ dt = 0, 
  \qquad \alpha \in \R,  \\ 
  & \cr
  &\int_0^{1}  f\bigl( u(t),\lambda \bigr)^{*}w(t) 
  - \gamma g_{T}\bigl( u(t),\lambda \bigr)
  - \tau_0  ~ dt= 0, \qquad \tau_0 \in \R,  \\
  & \cr
  &\int_0^{1}  T f_{\lambda_i}\bigl( u(t),\lambda \bigr)^{*}w(t)
  - \gamma g_{\lambda_i}\bigl( u(t),\lambda \bigr)
  - \tau_i  ~dt= 0, 
  \qquad \tau_i \in \R, \quad i=1, \cdots, n_{\lambda}.\\
\end{array} \end{equation}
Above  $u_0$ is a reference solution, namely, the previous solution along 
a solution family.  

\newpage
In the computations below, the two preliminary runs, with \parf{IPS}=1 and \parf{IPS}=2,
respectively, locate periodic solutions. 
The subsequent runs are with \parf{IPS}=15 and hence use the automatically
 generated extended system.

\begin{itemize}
\item[-] 
  \commandf{Run 1.}~ Locate a Hopf bifurcation. 
  The free system parameter is $\lambda_3$. 
\item[-]\commandf{Run 2.}~ 
  Compute a family of periodic solutions from the Hopf bifurcation.
\item[-]\commandf{Run 3.}~ 
  This run retraces part of the periodic solution family, 
  using the full optimality system,
  but with all adjoint variables, $w(\cdot), \kappa, \gamma$, 
  and hence $\alpha$, equal to zero.
  The optimality parameters $\tau_0$ and $\tau_3$ are zero throughout.
  An extremum of the objective functional with respect to $\lambda_3$
  is located.
  Such a point corresponds to a branch point of the extended system. 
  Given the choice of objective functional in this demo, 
  this extremum is also a fold with respect to $\lambda_3$.
\item[-]\commandf{Run 4.}~
  Branch switching at the above-found branch point yields nonzero
  values of the adjoint variables.
  Any point on the bifurcating family away from the branch point
  can serve as starting solution for the next run.
  In fact, the branch-switching can be viewed as generating
  a nonzero eigenvector in an eigenvalue-eigenvector relation.
  Apart from the adjoint variables, all other variables remain
  unchanged along the bifurcating family.
\item[-]\commandf{Run 5.}~ 
  The above-found starting solution is continued in two system parameters, 
  here $\lambda_3$ and $\lambda_2$; i.e., a two-parameter family 
  of extrema with respect to $\lambda_3$ is computed.
  Along this family the value of the optimality parameter $\tau_2$ 
  is monitored, i.e., the value of the functional that vanishes 
  at an extremum with respect to the system parameter $\lambda_2$.
  Such a zero of $\tau_2$ is, in fact, located, and hence an extremum 
  of the objective functional with respect to both $\lambda_2$ and 
  $\lambda_3$ has been found.
  Note that, in general, $\tau_i$ is the value of the
  functional that vanishes at an extremum with respect to the system
  parameter $\lambda_i$.
\item[-]\commandf{Run 6.}~ 
  In the final run, the above-found two-parameter extremum is continued
  in three system parameters, here $\lambda_1$, $\lambda_2$, 
  and $\lambda_3$, toward $\lambda_1=0$.
  Again, given the particular choice of objective functional,
  this final continuation has an alternate significance here~:
  it also represents a three-parameter family of transcritical
  secondary periodic bifurcations points.
\end{itemize}

Although not illustrated here, one can restart an ordinary
continuation of periodic solutions, using \parf{IPS}=2 or \parf{IPS}=3,
from a labeled solution point on a family computed with \parf{IPS}=15.

\newpage
The free scalar variables specified in the \AUTO constants-files
for Run~3 and Run~4 are shown in  Table~\ref{tbl:demo_ops_1}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | r | r | r | r | r | r | r |}
\hline
  Index& 3 & 11 & 12 & 22  & -22 & -23 & -31 \\
\hline
  Variable& $\lambda_3$ & $T$ &  $\alpha$ & $\tau_2$  
  & $[\lambda_2]$ & $[\lambda_3]$ & $[T]$ \\
\hline
\end{tabular}
\caption{\commandf{Runs 3 and 4}~ (files \filef{c.ops.3} and \filef{c.ops.4}).}
\label{tbl:demo_ops_1}
\end{center}
\end{table}

The parameter $\alpha$, which is the norm of the adjoint variables,
becomes nonzero after branch switching in Run~4.
The negative indices (-22, -23, and -31) set the active optimality 
functionals, namely for $\lambda_2$, $\lambda_3$, and $T$, respectively,
with corresponding variables $\tau_2$, $\tau_3$, and $\tau_0$,
respectively.
These should be set in the first run with \parf{IPS}=15 and remain unchanged
in all subsequent runs.


\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | r | r | r | r | r | r | r |}
\hline
  Index& 3 & ~2 & 11 & 22  & -22 & -23 & -31 \\
\hline
  Variable& $\lambda_3$ & $\lambda_2$ & $T$ & $\tau_2$  
  & $[\lambda_2]$ & $[\lambda_3]$ & $[T]$ \\
\hline
\end{tabular}
\caption{\commandf{Run 5}~ (file \filef{c.ops.5}).}
\label{tbl:demo_ops_2}
\end{center}
\end{table}

In Run~5 the parameter $\alpha$, which has been replaced by $\lambda_2$,
remains fixed and nonzero.
The variable $\tau_2$ monitors the value of the optimality functional 
associated with $\lambda_2$.
The zero of $\tau_2$ located in this run signals an extremum  
with respect to $\lambda_2$.


\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | r | r | r | r | r | r | r |}
\hline
  Index& 3 & ~2 & ~1 & 11  & -22 & -23 & -31 \\
\hline
  Variable& $\lambda_3$ & $\lambda_2$ & $\lambda_1$ & $T$  
  & $[\lambda_2]$ & $[\lambda_3]$ & $[T]$ \\
\hline
\end{tabular}
\caption{\commandf{Run 6}~ (file \filef{c.ops.6}).}
\label{tbl:demo_ops_3}
\end{center}
\end{table}


In Run~6 $\tau_2$, which has been replaced by $\lambda_1$, remains zero.


Note that $\tau_0$ and $\tau_3$ are not used as variables in any
of the runs; in fact, their values remain zero throughout.
Also note that the optimality functionals corresponding to 
$\tau_0$ and $\tau_3$ (or, equivalently, to $T$ and $\lambda_3$) 
\emp{ are} active in all runs.
This set-up allows the detection of the extremum of the objective functional,
with $T$ and $\lambda_3$ as scalar equation parameters,
as a bifurcation in the third run.

The parameter $\lambda_4$, and its corresponding optimality variable $\tau_4$,
are not used in this demo.
Also, $\lambda_1$ is used in the last run only, and its corresponding 
optimality variable $\tau_1$ is never used.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir ops} & create an empty work directory \\ 
  \commandf{cd ops} & change directory \\
  \commandf{demo('ops')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='ops',c='ops')} & locate a Hopf bifurcation \\ 
\hline
%==============================================================================
  \commandf{uzr=\{3:[0.92,0.93]\}} & set variable for \parf{UZR} \\
  \parbox[t]{3.2in}{\commandf{
      r2=run(r1("HB1"),IPS=2,ICP=[3,11], NMX=150,RL0=0.9,UZR=uzr)}} &
   \parbox[t]{3in}{compute a family of periodic solutions;  restart
     from \parf{r1} \vspace{0.2cm}}\\ 
  \commandf{save(r1+r2,'0')} & save output to \filef{b.0, s.0, d.0} \\ 
\hline
%==============================================================================
  \commandf{icp=[3,11,12,22,-22,-23,-31]} & set variable for \parf{ICP} \\
  \parbox[t]{3.2in}{\commandf{
   r3=run(r2("UZ1"),IPS=15,ILP=0, ICP=icp,ISP=2,NMX=25,ITNW=7,DS=-0.05)}}
  & \parbox[t]{3in}{locate a 1-parameter extremum as a bifurcation; restart from \parf{r2} \vspace{0.2cm}}\\ 
\hline
%==============================================================================
  \commandf{r4=run(r3("BP1"),ISW=-1,ISP=0,NMX=5)} & \parbox[t]{3in}{switch branches to generate optimality starting data; restart from \parf{r3} \vspace{0.2cm}}\\ 
  \commandf{save(r3+r4,'1')} & save output to \filef{b.1, s.1, d.1} \\ 
\hline
%==============================================================================
  \commandf{icp[1:3]=[2,11]} & set variable for \parf{ICP} \\
  \commandf{uzr[22]=0.0} & set variable for \parf{UZR} \\
  \parbox[t]{3.2in}{
  \commandf{r5=run(r4,ICP=icp,ISW=1,NMX=150, RL0=0.8,RL1=1.9,DS='-',UZR=uzr)}} 
 & \parbox[t]{3in}{compute 2-parameter family of 1-parameter extrema;
   restart from \parf{r4} \vspace{0.2cm}}\\ 
  \commandf{save(r5,'2')} & save the output-files as \filef{b.2, s.2, d.2} \\ 
\hline
%==============================================================================
  \commandf{icp[2:4]=[1,11]} & set variable for \parf{ICP} \\
  \parbox[t]{3.4in}{\commandf{r6=run(r5("UZ4"),IRS=15,ICP=icp,NTST=50,
UZR=\{1:[0.1,0.05,0.01,0.005,0.001]\})}} &
 \parbox[t]{3in}{compute 3-parameter family of 2-parameter extrema; restart from \parf{r5} \vspace{0.2cm}}\\ 
  \commandf{save(r6,'3')} & save the output-files as \filef{b.3, s.3, d.3} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{ops}.}
\label{tbl:demo_ops_4}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=obv======================================================================
%==============================================================================
\section{ obv : Optimization for a BVP.} \label{sec:Demos_obv}
This demo illustrates use of the method of successive continuation
for a  boundary value optimization problem.
A detailed description of the basic method, as well as a discussion
of the specific application considered here, is given in 
\citename{DoKeKe:91b} \citeyear{DoKeKe:91b}.
The required extended system is fully programmed here in the user-supplied
routines in \filef{obv.f90}.
For the case of periodic solutions the optimality system can be generated
automatically; see the demo \filef{ops}.

Consider the system
\begin{equation} \begin{array}{cl}
  u_1'(t) & = u_2(t), \\
  u_2'(t) &=
  -\lambda_1 e^{p(u_1,\lambda_2,\lambda_3)},
\end{array} \end{equation}
where
$ p(u_1,\lambda_2,\lambda_3) \equiv
  u_1 + \lambda_2 u_1^{2} + \lambda_3 u_1^{4},$
with boundary conditions
\begin{equation} \begin{array}{cl}
  u_1(0) &= 0, \\
  u_1(1) &= 0. \\
\end{array} \end{equation}
The objective functional is
$$ \omega = \int_0^{1} (u_1(t)-1)^{2}~ dt
  +  \frac{1}{10} \sum_{k=1}^{3} \lambda_{k}^{2}.  $$
The  successive continuation equations are given by
\begin{equation} \begin{array}{cl}
  u_1'(t) &= u_2(t), \\
  u_2'(t) &=
  -\lambda_1 e^{p(u_1,\lambda_2,\lambda_3)}, \\
  w_1'(t) &=
  \lambda_1 e^{p(u_1,\lambda_2,\lambda_3)} p_{u_1} w_2(t)
  + 2 \gamma(u_1(t)-1), \\
  w_2'(t) &= -w_1(t), \\
\end{array} \end{equation}
where
$$ p_{u_1} \equiv
  \frac{{\partial p} }{ {\partial u_1}} =
  1 + 2\lambda_2 u_1 + 4\lambda_3 u_1^{3},$$
with 
\begin{equation} \begin{array}{cl}
  u_1(0) = 0,\qquad  &w_1(0) - \beta_1 = 0,\qquad  w_2(0) = 0, \\
  u_1(1) = 0,\qquad  &w_1(1) + \beta_2 = 0,\qquad  w_2(1) = 0, \\\end{array} \end{equation}

$$ \int_0^{1} \bigl[ \omega - (u_1(t)-1)^{2}
  - \frac{1}{10} \sum_{k=1}^{3} \lambda_{k}^{2} \bigr]~ dt = 0, $$

$$ \int_0^{1} \bigl[w_1^{2}(t) - \alpha_0 \bigr]~ dt = 0, $$
 
\begin{equation} \begin{array}{cl}
  &\int_0^{1} \bigl[
  -e^{p(u_1,\lambda_2,\lambda_3)} w_2(t)
  - \frac{1}{5}\gamma \lambda_1
  \bigr]~ dt = 0, \\
  &\int_0^{1} \bigl[
  -\lambda_1 e^{p(u_1,\lambda_2,\lambda_3)} u_1(t)^{2} w_2(t)
  - \frac{1}{5}\gamma \lambda_2
  - \tau_2  \bigr]~ dt = 0, \\
  &\int_0^{1} \bigl[
  -\lambda_1 e^{p(u_1,\lambda_2,\lambda_3)} u_1(t)^{4} w_2(t)
  - \frac{1}{5}\gamma \lambda_3
  - \tau_3 \bigr]~ dt = 0. \\\end{array} \end{equation}

In the first run the free equation parameter is $\lambda_1$.
All adjoint variables are zero.
Three extrema of the objective function are located.
These correspond to branch points and, in the second run,
branch switching is done at one of these.
Along the bifurcating family the adjoint variables become nonzero,
while state variables and $\lambda_1$ remain constant.
Any such non-trivial solution point can be used for continuation 
in two equation parameters, after fixing the $L_2$-norm of one of 
the adjoint variables. This is done in the third run.
Along the resulting family several two-parameter extrema are located 
by monotoring certain inner products.
One of these is further continued in three equation parameters in the final run,
where a three-parameter extremum is located.


\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir obv} & create an empty work directory \\ 
  \commandf{cd obv} & change directory \\
  \commandf{demo('obv')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='obv',c='obv')} & locate 1-parameter extrema as branch points \\ 
  \commandf{save(r1,'obv')} & save output-files as \filef{b.obv, s.obv, d.obv} \\ 
\hline
%==============================================================================
  \commandf{r2=run(r1("BP1"),ISW=-1,NMX=5)} & \parbox[t]{3in}{compute a few step on the first bifurcating family \vspace{0.2cm}}\\ 
  \commandf{save(r2,'1')} & save the output-files as \filef{b.1, s.1, d.1} \\ 
\hline
%==============================================================================
\parbox[t]{3.2in}{
  \commandf{r3=run(r2,ICP=[10,1,2,17,18,13,14,15], ISW=1,NMX=100)}} & \parbox[t]{3in}{locate 2-parameter extremum; restart from \parf{r2} \vspace{0.2cm}}\\ 
  \commandf{save(r3,'2')} & save the output-files as \filef{b.2, s.2, d.2} \\ 
\hline
%==============================================================================
\parbox[t]{3.2in}{
  \commandf{r4=run(r3("UZ2"), ICP=[10,1,2,3,18,13,14,15],NMX=25)}} & \parbox[t]{3in}{locate 3-parameter extremum; restart from \parf{r3} \vspace{0.2cm}}\\ 
  \commandf{save(r4,'3')} & save the output-files as \filef{b.3, s.3, d.3} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{obv}.}
\label{tbl:demo_obv}
\end{center}
\end{table}

%==============================================================================
%==============================================================================
\chapter{ \AUTO Demos : Connecting orbits.} \label{ch:Demos_Heteroclinics}
%==============================================================================
%==============================================================================

\newpage
%==============================================================================
%DEMO=fsh======================================================================
%==============================================================================
\section{ fsh : A Saddle-Node Connection.} \label{sec:Demos_fsh}
This demo illustrates the computation of travelling wave front solutions
to the Fisher equation,
\begin{equation} \begin{array}{cl}
  & w_t = w_{xx} + f(w),
  \qquad -\infty < x < \infty,
  \quad  t > 0,  \\
  & f(w) \equiv w(1-w) .  \\
\end{array} \end{equation}
We look for solutions of the form $w(x,t)=u(x+ct)$, where
$c$ is the wave speed.
This gives the first order system
\begin{equation} \begin{array}{cl}
  &  u_1'(z)  = u_2(z),  \\
  &  u_2'(z)  = c u_2(z) - f\bigl(u_1(z)\bigr).  \\
\end{array} \end{equation}
Its fixed point $(0,0)$ has two positive eigenvalues when $c>2$.
The other fixed point, $(1,0)$, is a saddle point.
A family of orbits connecting the two fixed points
requires one free parameter; see 
\citename{FrDo:91} \citeyear{FrDo:91}.
Here we take this parameter to be the wave speed $c$.

In the first run a starting connecting orbit is computed 
by continuation in the period $T$.
This procedure can be used generally for time integration of an ODE with \AUTO.
Starting data in \funcf{STPNT} correspond to a point on the approximate stable manifold
of $(1,0)$, with $T$ small.
In this demo the ``free'' end point of the orbit necessary approaches the
unstable fixed point $(0,0)$.
A computed orbit with sufficiently large $T$ is then chosen as restart orbit
in the second run, where, typically, one replaces $T$ by $c$ as continuation
parameter.
However, in the second run below, we also add a phase condition, 
and both $c$ and $T$ remain free.



\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir fsh} & create an empty work directory \\ 
  \commandf{cd fsh} & change directory \\
  \commandf{demo('fsh')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='fsh',c='fsh')} & continuation in the period $T$, with $c$ fixed; no phase condition \\ 
  \commandf{save(r1,'0')} & save output-files as \filef{b.0, s.0, d.0} \\ 
\hline
%==============================================================================
 \parbox[t]{2in}{
  \commandf{r2 = run(r1("EP2"), ICP=[2,11,12,13,14], NINT=1,
DS='-', UZR=\{2:[1,2,3,5,10]\})} \vspace{0.2cm}} & 
 \parbox[t]{3in}{continuation in $c$ and $T$, with active phase
   condition. \vspace{0.2cm}} \\ 
  \commandf{save(r2,'fsh')} & save output-files as \filef{b.fsh, s.fsh, d.fsh} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{fsh}.}
\label{tbl:demo_fsh}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=nag======================================================================
%==============================================================================
\section{ nag : A Saddle-Saddle Connection.} \label{sec:Demos_nag}
This demo illustrates the computation of traveling wave front solutions
to Nagumo's equation,
\begin{equation} \begin{array}{cl}
  & w_t = w_{xx} + f(w,a),
  \qquad -\infty < x < \infty,
  \quad  t > 0,  \\
  & f(w,a) \equiv w(1-w)(w-a), \qquad 0<a<1.  \\
\end{array} \end{equation}
We look for solutions of the form $w(x,t)=u(x+ct)$, where
$c$ is the wave speed.
This gives the first order system
\begin{equation} \begin{array}{cl}
  &  u_1'(z)  = u_2(z),  \\
  &  u_2'(z)  = c u_2(z) - f\bigl(u_1(z),a\bigr),  \\
\end{array} \end{equation}
where $z=x+ct$, and $' = d/dz$.
If $a=1/2$ and $c=0$ then there are two analytically known
heteroclinic connections, one of which is given by
$$ u_1(z) = \frac{
  {e^{\frac{1}{2} \sqrt{2} z}}
  }{
  {1 + e^{\frac{1 }{ 2} \sqrt{2} z}}  },
  \qquad  u_2(z) = u_1'(z),  \qquad  -\infty < z < \infty.
  $$
The second heteroclinic connection is obtained by reflecting the
phase plane representation of the first with respect to the
$u_1$-axis.
In fact, the two connections together constitute a heteroclinic cycle.
One of the exact solutions is used below as starting orbit.
To start from the second exact solution, change SIGN=-1 in the  
routine \funcf{STPNT} in \filef{nag.f90} and repeat the computations below;
see also
\citename{FrDo:91} \citeyear{FrDo:91}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir nag} & create an empty work directory \\ 
  \commandf{cd nag} & change directory \\
  \commandf{demo('nag')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='nag',c='nag')} & compute part of first family of heteroclinic orbits \\ 
\hline
%==============================================================================
  \commandf{r2=run(e='nag',c='nag',DS='-')} & compute first family in opposite direction\\ 
  \commandf{save(r1+r2,'nag')} & save all output to \filef{b.nag, s.nag, d.nag} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{nag}.}
\label{tbl:demo_nag}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=stw======================================================================
%==============================================================================
\section{ stw : Continuation of Sharp Traveling Waves.} \label{sec:Demos_stw}
This demo illustrates the computation of sharp traveling wave front solutions
to nonlinear diffusion problems of the form
$$ w_t = A(w) w_{xx} + B(w) w_x^{2} + C(w),  $$
with
$A(w) = a_1 w + a_2 w^{2}$,
$B(w) = b_0 + b_1 w + b_2 w^{2}$,
and
$C(w) = c_0 + c_1 w + c_2 w^{2}$.
Such equations can have \commandf{sharp traveling wave fronts} as solutions, i.e., solutions of the form
$w(x,t)=u(x+ct)$ for which there is a $z_0$ such that
$u(z)=0$ for $z \ge z_0$,
$u(z) \not= 0$ for $z < z_0$, and
$u(z) \rightarrow constant$ as $z \rightarrow -\infty$.
These solutions are actually generalized solutions, since they need
not be differentiable at $z_0$.

Specifically, in this demo a homotopy path will be computed 
from an analytically known exact sharp traveling wave solution of
$$ w_t = 2w w_{xx} + 2 w_x^{2} + w(1-w),  \leqno(1) $$
to a corresponding sharp traveling wave of
$$ w_t = (2w+w^{2}) w_{xx} + w w_x^{2} + w(1-w). \leqno(2) $$
This problem is also considered in
\citename{DoKeKe:91b} \citeyear{DoKeKe:91b}.
For these two special cases the functions $A,B,C$ are defined
by the coefficients in Table~\ref{tbl:demo_stw_1}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l | l | l | l | l | l | l | l |}
\hline
         & $a_1$ & $a_2$ & $b_0$ &$b_1$ &$b_2$ &$c_0$ &$c_1$ &$c_2$ \\
\hline
Case (1) &  2    &   0   &   2   &  0   &  0   &  0   &  1   &  -1 \\
\hline
Case (2) &  2    &   1   &   0   &  1   &  0   &  0   &  1   &  -1 \\
\hline
\end{tabular}
\caption{Problem coefficients in demo \filef{stw}.}
\label{tbl:demo_stw_1}
\end{center}
\end{table}

With $w(x,t)=u(x+ct)$, $z=x+ct$, one obtains the reduced system
\begin{equation} \begin{array}{cl}
  & u_1'(z) = u_2,  \\
  & u_2'(z) = \bigl[c u_2 - B(u_1) u_2^{2} - C(u_1) \bigr]/A(u_1). \\
\end{array} \end{equation}
To remove the singularity when $u_1=0$, we apply a
nonlinear transformation of the independent variable 
(see \citename{Ar:80} \citeyear{Ar:80}), viz.,
${d / d \tilde z} = A(u_1) {d / dz}$,
which changes the above equation into
\begin{equation} \begin{array}{cl}
  & u_1'(\tilde z) = A(u_1) u_2,  \\
  & u_2'(\tilde z) = c u_2 - B(u_1) u_2^{2} - C(u_1). \\
\end{array} \end{equation}
Sharp traveling waves then correspond to heteroclinic connections
in this transformed system.

\newpage 
Finally, we  map $ [0,T] \rightarrow [0,1] $
by the transformation $\xi = \tilde z / T$.
With this scaling of the independent variable, the reduced system
becomes
\begin{equation} \begin{array}{cl}
  & u_1'(\xi) = T A(u_1) u_2,  \\
  & u_2'(\xi) = T \bigl[ c u_2 - B(u_1) u_2^{2} - C(u_1)\bigr]. \\
\end{array} \end{equation}
For Case~1 this equation has a known exact solution, namely,
$$ u(\xi) = \frac{1 }{ 1 + \exp(T\xi) }, \qquad
  v(\xi) = \frac{ -\frac{1 }{ 2}  }{ 1 + \exp(-T\xi) }. $$
This solution has wave speed $c=1$.
In the limit as $T \rightarrow \infty$ its phase plane trajectory
connects the stationary points $(1,0)$ and $(0,-\frac{1 }{ 2})$.
 
The sharp traveling wave in Case~2
can now be obtained using the following homotopy.
Let
$(a_1,a_2,b_0,b_1,b_2) =
  (1-\lambda) (2,0,2,0,0) + \lambda (2,1,0,1,0)$.
Then as $\lambda$ varies continuously from 0 to 1, the parameters
$(a_1,a_2,b_0,b_1,b_2)$
vary continously from the values for Case~1
  to the values for Case~2.


\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir stw} & create an empty work directory \\ 
  \commandf{cd stw} & change directory \\
  \commandf{demo('stw')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='stw',c='stw')} & continuation of the sharp traveling wave \\ 
  \commandf{save(r1,'stw')} & save output-files as \filef{b.stw, s.stw, d.stw} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{stw}.}
\label{tbl:demo_stw_2}
\end{center}
\end{table}


%==============================================================================
%==============================================================================
\chapter{ \AUTO Demos : Miscellaneous.} \label{ch:Demos_Misc}
%==============================================================================
%==============================================================================

\newpage
%==============================================================================
%DEMO=pvl======================================================================
%==============================================================================
\section{ pvl : Use of the Routine \funcf{ PVLS}.} \label{sec:Demos_pvl}

Consider Bratu's equation
\begin{equation} \begin{array}{cl}
  u_1 ' &= u_2  ,  \\
  u_2 ' &= -p_1  e^{u_1} , \\ 
\end{array} \end{equation}
with boundary conditions $ u_1(0)=0$, $u_1(1)=0.$
As in demo \filef{exp}, a solution curve requires one free parameter;
here $p_1$.

Note that additional parameters are specified in the user-supplied subroutine 
\funcf{ PVLS} in file \filef{pvl.f90}, namely,
$p_2$ (the $L_2$-norm of $u_1$),
$p_3$ (the minimum of $u_2$ on the space-interval $[0,1]$~),
$p_4$ (the boundary value $u_2(0)$~),
$p_5$ (the same boundary value $u_2(0)$~).
These additional parameters should be considered as ``solution measures''
for output purposes; they should not be treated as true
continuation parameters.

Note also that four free parameters are specified in the \AUTO-constants file 
\filef{c.pvl}, namely, $p_1$, $p_2$, $p_3$, $p_4$, and $p_5$.
The first one in this list, $p_1$, is the true continuation parameter. 
The parameters $p_2$, $p_3$, $p_4$, and $p_5$ are \emp{ overspecified}
so that their values will appear in the output.
However, 
\emp{ it is essential that the true continuation parameter appear first.}
For example, it would be an error to specify the parameters
in the following order~: $p_2$, $p_1$, $p_3$, $p_4$, $p_5$.

In general, true continuation parameters must appear first in the
parameter-specification in the \AUTO constants-file.
Overspecified parameters will be printed, and can be
defined in \funcf{ PVLS}, but they are not part of the intrinsic continuation
procedure.

As this demo also illustrates (see the \parf{UZR} values in \filef{c.pvl}),
labeled solutions can also be output at selected values 
of the overspecified parameters.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir pvl} & create an empty work directory \\ 
  \commandf{cd pvl} & change directory \\
  \commandf{demo('pvl')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='pvl',c='pvl')} & compute a solution family \\ 
  \commandf{save(r1,'pvl')} & save output-files as \filef{b.pvl, s.pvl, d.pvl} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{pvl}.}
\label{tbl:demo_pvl}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=ext======================================================================
%==============================================================================
\section{ ext : Spurious Solutions to BVP.} \label{sec:Demos_ext}

This demo illustrates the computation of spurious solutions
to the boundary value problem
\begin{equation} \begin{array}{cl}
& u_1' - u_2 = 0 , \\
& u_2' + \lambda^2 \pi^2 \sin( u_1 + u_1^2 + u_1^3 ) = 0,
  \qquad t \in [0,1], \\ 
& u_1(0) = 0, \quad u_1(1) = 0. \\
\end{array} \end{equation}
Here the differential equation is discretized using a fixed uniform mesh.
This results in spurious solutions that disappear when an adaptive mesh is used.
See the \AUTO-constant \parf{IAD} in Section~\ref{sec:Discretization_constants}.
This example is also considered in
\citename{BeDo:81} \citeyear{BeDo:81}
and
\citename{DoKeKe:91b} \citeyear{DoKeKe:91b}.

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir ext} & create an empty work directory \\ 
  \commandf{cd ext} & change directory \\
  \commandf{demo('ext')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='ext',c='ext')} & detect bifurcations from the trivial solution family \\ 
\hline
%==============================================================================
  \commandf{r2=run(r1("BP3"),ISW=-1,NCOL=3)} & \parbox[t]{3in}{compute a bifurcating family containing spurious bifurcations. \vspace{0.2cm}}\\ 
  \commandf{save(r1+r2,'ext')} & save all output to \filef{b.ext, s.ext, d.ext} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{ext}.}
\label{tbl:demo_ext}
\end{center}
\end{table}

\newpage
%==============================================================================
%DEMO=tim======================================================================
%==============================================================================
\section{ tim : A Test Problem for Timing \AUTO.} \label{sec:Demos_tim}
This demo is a boundary value problem with variable dimension \parf{NDIM}. 
It can be used to time the performance of \AUTO 
for various choices of \parf{NDIM} (which must be even), \parf{NTST}, and \parf{NCOL}.
The equations are
\begin{equation} \begin{array}{cl}
  u_i ' &= u_i  ,  \\
  v_i ' &= -p_1 ~  e(u_i) , \\
\end{array} \end{equation}
$i=1,\cdots$,\parf{NDIM}/2,
with boundary conditions $ u_i(0)=0$, $u_i(1)=0.$
Here 
$$ e(u) = \sum_{k=0}^{n} ~ \frac{u^k }{ k!} ~ , $$
with $n=25$.
The computation requires 10 full $LU$-decompositions of the linearized system
that arises from Newton's method for solving the collocation equations.
The commands for running the timing problem for a particular choice 
of \parf{NDIM}, \parf{NTST}, and \parf{NCOL} are given below.
(Note that if \parf{NDIM} is changed then \parf{NBC} must be changed accordingly.)

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir tim} & create an empty work directory \\ 
  \commandf{cd tim} & change directory \\
  \commandf{demo('tim')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(e='tim',c='tim')} & Timing run \\ 
  \commandf{save(r1,'tim')} & save output-files as \filef{b.tim, s.tim, d.tim} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Commands for running demo \filef{tim}.}
\label{tbl:demo_tim}
\end{center}
\end{table}


%==============================================================================
%==============================================================================
\chapter{ {\cal HomCont}.} \label{ch:HomCont}
%==============================================================================
%==============================================================================
\section{ Introduction.} \label{sec:HomCont_Intro}
{\cal HomCont} is a collection of routines for the continuation 
of homoclinic solutions to ODEs in two or more parameters.
The accurate detection and multi-parameter continuation of certain
codimension-two singularities is allowed for, including all known
cases that involve a unique homoclinic orbit at the singular point.
Homoclinic connections to hyperbolic and non-hyperbolic equilibria are 
allowed as are certain heteroclinic orbits. 
Homoclinic orbits in reversible systems can also be computed.
The theory behind the methods used is
explained in \citeasnoun{ChKu:94}, \citeasnoun{BaCh:94},
\citename{Sa:95} \citeyear{Sa:95,Sa:95a}, \citeasnoun{ChKuSa:95} and
references therein.  The final cited paper contains a concise
description of the present version. 

The current implementation of {\cal HomCont} must be considered as experimental,
and updates are anticipated.
The {\cal HomCont} routines are in the file {\tt auto/07p/src/autlib5.f}. 
Expert users wishing to modify the routines may look there.
Note also that at present, {\cal HomCont} can be run only in 
{\cal AUTO} Command Mode and not with the GUI. 


\section{{\cal HomCont} Files and Routines.} \label{sec:HomCont_files}

In order to run {\cal HomCont} one must prepare an equations file \filef{xxx.f90}, 
where \filef{xxx} is the name of the example, 
and constants-file \filef{c.xxx}.
These files are in the standard {\cal AUTO} format, but
the \filef{c.xxx} file almost always also must
contain constants that are specific to homoclinic continuation.
The choice \parf{IPS}=9 in \filef{c.xxx} specifies the problem as
being homoclinic continuation.

The equation-file \filef{kpr.f90} serves as a sample for new equation
files. It contains the Fortran routines 
\funcf{ FUNC}, \funcf{ STPNT}, \funcf{ PVLS}, \funcf{ BCND}, \funcf{ ICND} 
and \funcf{ FOPT}. The final three are
dummy routines which are never needed for homoclinic continuation.
Note a minor difference in \funcf{ STPNT} and \funcf{ PVLS} with other 
{\cal AUTO} equation-files, in that the common block 
\parf{/BLHOM/} is required.

The constants-file \filef{c.xxx} is identical in format to other
{\cal AUTO} constants-files, except for the added constants.
Note that the values of the constants
\parf{NBC} and \parf{NINT} are irrelevant, as these are set
automatically by the choice \parf{IPS}=9. Also, the choice \parf{JAC=1}
is strongly recommended, because the Jacobian is used extensively for
calculating the linearization at the equilibria and hence for
evaluating boundary conditions and certain test functions. However,
note that \parf{JAC=1} does not necessarily mean that {\cal auto} will
use the analytically specified Jacobian for continuation.

The earlier HomCont files \filef{h.xxx} are obsolete but still
supported. You can convert from the old to the new format by running
the command \commandf{@cnvc xxx yyy} where \commandf{xxx} refers to either
or both of the files \filef{c.xxx} and \filef{h.xxx}. A new-style
constants file, \filef{c.yyy} is written. The command
\commandf{@cnvc xxx} overwrites \filef{c.xxx} and deletes \filef{h.xxx}.

\section{ {\cal HomCont}-Constants.} \label{sec:HomCont_Constants}
An example for the HomCont-specific constants in \filef{c.xxx} is listed below:
\begin{verbatim}
          NUNSTAB=1, NSTAB=2, IEQUIB=1, ITWIST=1, ISTART=5
          IREV = []
          IFIXED = [13]
          IPSI = [9,10]
\end{verbatim}
These constants have the following meaning. 

\subsection{\parf{NUNSTAB}}  \label{sec:NUNSTAB}

Number of unstable eigenvalues of the left-hand equilibrium (the equilibrium 
approached by the orbit as $t \to -\infty$). The default value is -1,
which means autodetection. In almost all cases autodetection is
possible. The exception is when starting from a homoclinic to a
saddle-node equilibrium when \parf{IEQUIB$\ne$1}. Examples for this
exception are in runs 9, 12, and 13 of the
demo \texttt{kpr} (see Chapter~\ref{ch:HomCont_kpr}).
Even in this case
only one of \parf{NUNSTAB} and \parf{NSTAB} needs to be specified, the
other one being computed as \parf{NDIM} minus the specified constant.

\subsection{\parf{NSTAB}}  \label{sec:NSTAB}
Number of stable eigenvalues of the right-hand equilibrium (the equilibrium
approached by the orbit as $t \to +\infty$). The same default as for
\parf{NUNSTAB} applies here.

\subsection{\parf{IEQUIB}}  \label{sec:IEQUIB}
\begin{itemize}
\item[-] \parf{IEQUIB=0}~: 
Homoclinic orbits to hyperbolic equilibria;  
the equilibrium is specified explicitly in \funcf{PVLS} and stored in
\parf{PAR(11+I)}, \parf{I=1,NDIM}.
\item[-] \parf{IEQUIB=1}~(default): 
Homoclinic orbits to hyperbolic equilibria;  
the equilibrium is solved for during continuation. Initial values for
the equilibrium are stored in \parf{PAR(11+I)}, \parf{I=1,NDIM} in \funcf{ STPNT}.
\item[-] \parf{IEQUIB=2}~: 
Homoclinic orbits to a saddle-node; initial values for
the equilibrium are stored in \parf{PAR(11+I)}, \parf{I=1,NDIM} in \funcf{ STPNT}.
\item[-] \parf{IEQUIB=-1}~: 
Heteroclinic orbits to hyperbolic equilibria;
the equilibria are specified explicitly in \funcf{ PVLS} and stored in
\parf{PAR(11+I)},  
\parf{I=1,NDIM} (left-hand equilibrium) and \parf{PAR(11+I)}, 
\parf{I=NDIM+1,2*NDIM} (right-hand equilibrium). 
\item[-] \parf{IEQUIB=-2}~: 
Heteroclinic orbits to hyperbolic equilibria;
the equilibria are solved for during continuation. Initial values are
specified in \funcf{ STPNT} and stored in \parf{PAR(11+I)}, \parf{I=1,NDIM} (left-hand equilibrium), 
\parf{PAR(11+I)}, \parf{I=NDIM+1,2*NDIM} (right-hand equilibrium).
\end{itemize}

\subsection{\parf{ITWIST}}  \label{sec:ITWIST}
\begin{itemize}
\item[-] \parf{ITWIST=0}~(default): 
the orientation of the homoclinic orbit is not computed.
\item[-] \parf{ITWIST=1}~: 
the orientation of the homoclinic orbit is computed. For this purpose, the
adjoint variational equation is solved for the unique bounded
solution. If \parf{IRS = 0}, an initial solution to the adjoint equation
must be specified as well. However, if \parf{IRS>0} and \parf{ITWIST} 
has just been increased from zero, then {\cal AUTO} will
automatically generate the initial solution to the adjoint. 
In this case, a dummy Newton-step should be performed, see 
Section~\ref{sec:Starting_strategies} for more details.
\end{itemize}

\subsection{\parf{ISTART}}  \label{sec:ISTART}
\begin{itemize}
\item[-] \parf{ISTART=1}~:
No special action is taken.
\item[-] \parf{ISTART=2}~: 
If \parf{IRS=0}, an explicit solution must be specified in the
subroutine \funcf{ STPNT} in the usual format. 
\item[-] \parf{ISTART=3}~: 
The ``homotopy'' approach is used for starting, see 
Section~\ref{sec:Starting_strategies} 
for more details. Note that this is not available with the choice 
\parf{IEQUIB=2}.
\item[-] \parf{ISTART=4}~:
A phase-shift is performed for homoclinic orbits to let the
equilibrium (either fixed or non-fixed, depending on IEQUIB)
correspond to $t=0$ and $t=1$. This is necessary if a periodic
orbit that is close to a homoclinic orbit is continued into
a homoclinic orbit.
\item[-] \parf{ISTART=5}~(default):
If \parf{IRS=0}, the restart solution comes from a data file, or
the restart solution is a homoclinic orbit with problem
type \parf{IPS=9}, no special action is taken, as for \parf{ISTART=1}.
For other problem types, use a phase-shift, as for \parf{ISTART=4}.
\item[-] \parf{ISTART=-N, $N=1,2,3,\ldots$}~:
Homoclinic branch switching: this description is for reference only.
We refer to the demo in Chapter~\ref{ch:HomCont_hbs} to see how this
can be used in actual practice and to \citeasnoun{OlChKr:03} for
theory and background.

The orbit is split into $N+1$ parts and
{\cal AUTO} sees it as an $(N+1)\times$\parf{NDIM}-dimensional object.
The first part $u_0$ goes from the equilibrium to the point $x_0$ that is 
furthest from the equilibrium. 
Then follow $N-1$ shifted copies of the orbit, which travel
from the point $x_0$ back to the point $x_0$. The last part $U_N$
goes from the point $x_0$ back to the equilibrium. 
The derivatives $\dot{x}_0$ with respect to time
of the point that is furthest from the equilibrium are stored at the 
parameters \parf{PAR(NP-NDIM+1...NP)}, where \parf{NP=max(NPARX,NPAR)}.

If \parf{ITWIST=1}, and this was also the case in the preceding run,
then a copy of the adjoint vector $\Psi$ at $x_0$ is stored at the parameters
\parf{PAR(NP-NDIM*2+1...NP-NDIM)} and Lin's method can be used
to do homoclinic branch switching. To be more precise, the individual parts
$u_i$ and $u_{i+1}$ are at distances $\varepsilon_i$ away from each
other, along the Lin vector $Psi$, at the left- and right-hand end
points. These gaps $\varepsilon_i$ are at parameters
\parf{PAR(20+2*i)}. Moreover, each part (except $u_{N+1}$) ends at
at a Poincar\'e section which goes through $x_0$ and is perpendicular
to $\dot{x}_0$.

The times $T_i$ that each part $u_i$ takes are stored as follows: 
$T_0=$\parf{PAR(10)}, $T_N=$\parf{PAR(11)} and $T_i=$\parf{PAR(19+2*i)}
for $i=1\ldots N-1$. Through a continuation in problem parameters,
gaps $\varepsilon_i$, and times $T_i$ 
it is possible to switch from a $1$-homoclinic to
an $N$-homoclinic orbit.

If \parf{ITWIST=0}, the adjoint vector is not computed and Lin's
method is not used. Instead, AUTO produces a gap
$\varepsilon$=\parf{PAR(22)} at the right-hand end point $p$ of
$u_{N+1}$, measuring the distance between the stable manifold of the
equilibrium and $p$. This technique can also be used to find 2-homoclinic
orbits, by varying in $\varepsilon$ and $T_1$, similar to the method
described before, but only if the unstable manifold in
one-dimensional. Because this method is more limited than the method
using Lin vectors, we do not recommend it for normal usage.

To switch back to a normal homoclinic orbit, set \parf{ISTART} back to
a positive value such as 1. Now HomCont has lost all the information
about the adjoint, so if \parf{ITWIST} is set to 0, HomCont
does a normal continuation without the adjoint, and
if \parf{ITWIST} is set to 1, one needs to do a Newton dummy step
first to recalculate the adhoint.
\end{itemize}

\subsection{\parf{IREV}}  \label{sec:IREV}
If \parf{IREV$\ne$[]} then it is assumed that
the system is reversible under the transformation 
$t \to -t$ and $U(i) \to -U(i)$ for all $i$ with 
\parf{IREV(i)>0}. Then only half the homoclinic solution is
solved for with right-hand boundary conditions specifying
that the solution is symmetric under the reversibility
(see \citeasnoun{ChSp:93}). The number of free parameters
is then reduced by one. Otherwise the default applies, \parf{IREV=[]}.

\subsection{\parf{IFIXED}}  \label{sec:IFIXED}
Labels of test functions that are held fixed. 
E.g., with \parf{IFIXED=[n]} one can compute a locus in
one extra parameter of a singularity defined by 
test function \parf{PSI(n)=0}. The default is \parf{IFIXED=[]}.

\subsection{\parf{IPSI}}  \label{sec:IPSI}
Labels of activated test functions for detecting homoclinic
bifurcations, see Section~\ref{sec:HomCont_Test_functions} 
for a list. If a test function is activated then the
corresponding parameter (\parf{IPSI(I)+20}) 
must be added to the list of continuation parameters \parf{ICP}
and zero of this parameter added to the list of user-defined
output points \parf{UZR,} in \filef{c.xxx}.
The default is \parf{IPSI=[]}.

\section{ Restrictions on {\cal HomCont} Constants.}
Note that certain combinations of these constants are not allowed
in the present implementation. In particular,
\begin{itemize}
\item[-] 
The computation of orientation \parf{ITWIST=1} is not
implemented for \parf{IEQUIB<0} (heteroclinic orbits), 
\parf{IEQUIB=2} (saddle-node homoclinics),
\parf{IREV$\ne$[]} (reversible systems), \parf{ISTART=3} (homotopy
method for starting), or if the equilibrium contains complex
eigenvalues in its linearization.  
\item[-] The homotopy method \parf{ISTART=3} is not fully implemented
for heteroclinic connections \parf{IEQUIB<0}, saddle-node homoclinic
orbits \parf{IEQUIB=2} or reversible systems \parf{IREV$\ne$[]}.
\item[-] Certain test functions are not valid for certain forms
of continuation 
(see Section~\ref{sec:HomCont_Test_functions} below); 
for example
\parf{PSI(13)} and \parf{PSI(14)} only make sense if 
\parf{ITWIST=1} and \parf{PSI(15)} and \parf{PSI(16)} only apply
to \parf{IEQUIB=2}.
\end{itemize}

\section{ Restrictions on the Use of \parf{PAR}.}
The parameters \parf{PAR(1)} -- \parf{PAR(9)} can be used freely by
the user. The other parameters are used as follows~:

\begin{itemize}

\item[-] \parf{PAR(11)}~: 
The value of \parf{PAR(11)} equals the length of the time interval over
which a homoclinic solution is computed. Also referred to as ``period''.
This must be specified in \funcf{ STPNT}.

\item[-] \parf{PAR(10)}~: 
If \parf{ITWIST=1} then \parf{PAR(10)} is used internally as a
dummy parameter so that the adjoint equation is well-posed.

\item[-] \parf{PAR(12)-PAR(20)}~:
These are used for specifying the 
equilibria and (if \parf{ISTART=3}) the artificial parameters of
the homotopy method (see Section~\ref{sec:Starting_strategies} below).

\item[-] \parf{PAR(21)-PAR(36)}~: 
These parameters are used for storing the test functions 
(see Section~\ref{sec:HomCont_Test_functions}).
\end{itemize}

The output is in an identical format to {\cal AUTO} except that
additional information at each computed point is written 
in \parf{fort.9}. This information comprises the eigenvalues of
the (left-hand) equilibrium, the values of each activated test
function and, if \parf{ITWIST=1}, 
whether the saddle homoclinic loop is orientable
or not.
Note that the statement about orientability is only meaningful if the
leading eigenvalues are not complex and the homoclinic solution is not
in a flip configuration, that is, none of the test functions 
$\psi_i$ for $i=11,12,13,14$ is zero (or close to zero), 
see Section~\ref{sec:HomCont_Test_functions}.
 Finally, the values of the \parf{IPSI} activated test functions are written. 

\section{ Test Functions.} \label{sec:HomCont_Test_functions}
Codimension-two homoclinic orbits are detected along branches of codim
1 homoclinics by locating zeroes of certain test functions
$\psi_i$. The test functions that are ``switched on'' during any
continuation are given by the choice of the labels $i$, and are
specified by the parameters \parf{IPSI)} in \filef{
c.xxx}.  Here \parf{IPSI=[IPSI(1),$\ldots$,IPSI(NPSI)]} gives the labels of
the test functions (numbers between 1 and 16). A zero of
each labeled test function defines a certain codimension-two 
homoclinic singularity, specified as follows.
The notation used for eigenvalues is the same as that in
\citeasnoun{ChKu:94} or \citeasnoun{ChKuSa:95}. 

\begin{itemize}
\item[-] $ i=1$: 
Resonant eigenvalues (neutral saddle); $\mu_1=-\lambda_1$.
\item[-] $ i=2$: 
Double real leading stable eigenvalues (saddle to saddle-focus
transition); $\mu_1=\mu_2$. 
\item[-] $ i=3$: 
Double real leading unstable eigenvalues (saddle to saddle-focus
transition);\\ 
$\lambda_1=\lambda_2$. 
\item[-] $ i=4$: 
Neutral saddle, saddle-focus or bi-focus (includes $ i=1$);
$\mbox{Re}(\mu_1)  =  - \mbox{Re}(\lambda_1)$. 
\item[-] $ i=5$: 
Neutrally-divergent saddle-focus (stable eigenvalues complex);\\
$\mbox{Re}(\lambda_1) = - \mbox{Re}(\mu_1) - \mbox{Re}(\mu_2)$.
\item[-] $ i=6$: 
Neutrally-divergent saddle-focus (unstable eigenvalues complex);\\
$\mbox{Re}(\mu_1) = - \mbox{Re}(\lambda_1) - \mbox{Re}(\lambda_2)$. 
\item[-] $ i=7$: 
Three leading eigenvalues (stable);
$\mbox{Re}(\lambda_1) = - \mbox{Re}(\mu_1) - \mbox{Re}(\mu_2)$. 
\item[-] $ i=8$: 
Three leading eigenvalues (unstable);
$\mbox{Re}(\mu_1) = - \mbox{Re}(\lambda_1) - \mbox{Re}(\lambda_2)$.
\item[-] $ i=9$: 
Local bifurcation (zero eigenvalue or Hopf): 
number of stable eigenvalues decreases; $\mbox{Re}(\mu_1)=0$.
\item[-] $ i=10$: 
Local bifurcation (zero eigenvalue or Hopf): 
number of unstable eigenvalues decreases; $\mbox{Re}(\lambda_1)=0$.
\item[-] $ i=11$: 
Orbit flip with respect to leading stable direction 
(e.g., 1D unstable manifold).
\item[-] $ i=12$: 
Orbit flip with respect to leading unstable direction, 
(e.g., 1D stable manifold).
\item[-] $ i=13$: 
Inclination flip with respect to stable manifold
(e.g., 1D unstable manifold).
\item[-] $ i=14$: 
Inclination flip with respect to unstable manifold
(e.g., 1D stable manifold).
\item[-] $ i=15$: 
Non-central homoclinic to saddle-node (in stable manifold).
\item[-] $ i=16$: 
Non-central homoclinic to saddle-node (in unstable manifold).
\end{itemize}

Expert users may wish to add their own test functions by editing 
the function \funcf{ PSIHO} in \filef{autlib5.f}.

{\it It is important to remember that, in order to specify activated 
test functions, it is required to also 
add the corresponding label $+20$ to the list of continuation
parameters and a zero of this parameter to the list of user-defined
output points. Having done this, the corresponding parameters
are output to the screen and zeros are accurately located.} 

\section{ Starting Strategies.} \label{sec:Starting_strategies}
There are four possible starting procedures for continuation. 

\begin{itemize}

\item[{\bf(i)}]
Data can be read from a previously-obtained output point from {\cal AUTO}
 (e.g., from continuation of a periodic orbit up to large period;
note that if the end-point of the data stored is not close to the
equilibrium, a phase shift must be performed by setting
\parf{ISTART=4}). These data can be read from fort.8 (saved to \filef{
s.xxx}) by making \parf{IRS} correspond to the label of the data
point in question.

\item[{\bf(ii)}]
Data from numerical integration (e.g.,\ computation of a stable
periodic orbit, or an approximate homoclinic obtained by shooting)  
can be read in from a data file using the \AUTO constant \parf{dat}
(see Section~\ref{sec:dat}). 
The  numerical data should be stored in
a file  \filef{xxx.dat}, in multi-column format according to the read statement
\begin{verbatim}
       READ(...,*) T(J),(U(I,J),I=1,NDIM)
\end{verbatim}
where $T$ runs in the interval \parf{[0,1]}.
When starting from this solution \parf{IRS} should be set to 0 and 
the value of \parf{ISTART} is irrelevant.

\item[{\bf(iii)}]
By setting \parf{ISTART=2},  
an explicit homoclinic solution can be specified in the routine \funcf{ STPNT} 
in the usual {\cal AUTO} format, that is 
$U=...(T)$ where $T$ is scaled to lie in the
interval $[0,1]$. 

\item[{\bf(iv)}]
The choice \parf{ISTART=3}, allows for
a homotopy method to be used to approach a homoclinic orbit
starting from a small approximation to a solution to the 
linear problem in the unstable manifold \cite{DoFrMo:93}. For
details of implementation, the reader is referred to 
Section~5.1.2.\ of \citeasnoun{ChKu:94}, under the simplification
that we do not solve for the adjoint $u(t)$ here. The basic idea
is to start with a small solution in the unstable manifold, and perform
continuation in \parf{PAR(11)=}$2T$ and dummy initial-condition 
parameters $\xi_i$ in order to satisfy the correct right-hand boundary
conditions, which are defined by zeros of other dummy parameters
$\omega_i$. More precisely, the left-hand end point is placed in the
tangent space to the unstable manifold of the saddle and is characterized by
\parf{NUNSTAB} coordinates $\xi_i$ satisfying the condition
$$
\xi_1^2 + \xi_2^2 + \ldots +\xi_\parf{NUNSTAB}^2  = \eps_0^2,
$$
where $\eps_0$ is a user-defined small number.
At the right-hand end point, \parf{NUNSTUB} values $\omega_i$ 
measure the deviation of this point from the tangent
space to the stable manifold of the saddle. 
\par
Suppose that \parf{IEQUIB=0,1} and set \parf{IP=12+IEQUIB*NDIM}. Then
\par
\medskip
\begin{center}
\begin{tabular}{ll}
\parf{PAR(IP)} & :$\ \ \eps_0$\\
\parf{PAR(IP+i)} &  :$\ \ \xi_\parf{i}$, \parf{i=1,2,...,NUNSTAB}\\
\parf{PAR(IP+NUNSTAB+i)} & :$\ \ \omega_\parf{i}$, \parf{i=1,2,...,NUNSTAB}
\end{tabular}
\end{center}
\par
\medskip
{\it Note that to avoid interference with the test functions 
(i.e. \parf{PAR(21)-PAR(36)}), one must have \parf{IP+2*NUNSTAB < 21}.} 
\par
If an $\omega_i$ is vanished, it can be frozen while another dummy or system parameter is allowed to
vary in order to make consequently all $\omega_i=0$. The resulting final solution
gives the initial homoclinic orbit provided the right-hand end point
is sufficiently close to the saddle. 
See Chapter~\ref{ch:HomCont_kpr} for an example, 
however, we recommend the homotopy method only for ``expert users''.
\end{itemize}

To compute the orientation of a homoclinic orbit (in order to detect
inclination-flip bifurcations) it is necessary to compute, in tandem,
a solution to the modified adjoint variational equation, by setting
\parf{ITWIST=1}. In order to obtain starting data for such a
computation when restarting from a point where just the homoclinic
is computed, upon increasing \parf{ITWIST} to 1, {\cal AUTO} generates
trivial data for the adjoint. Because the adjoint equations are
linear, only a single step of Newton's method is required to
enable these trivial data to converge to the correct unique bounded
solution. This can be achieved by making a single continuation step in a
trivial parameter (i.e. a parameter that does not appear
in the problem). 

Decreasing \parf{ITWIST} to 0 automatically deletes the data for the adjoint
from the continuation problem.


\section{ Notes on Running {\cal HomCont} Demos.} \label{sec:HomCont_Tutorial_examples}
{\cal HomCont} demos are given in the following chapters.
To copy all files of a demo \filef{xxx} (for example, \filef{san}),
move to a clean directory and type \commandf{demo('xxx')}.
Simply typing \commandf{auto xxx.auto} will then automatically
execute all runs of the demo.
%To automatically run a demo in ``step-by-step'' mode,
%type  \commandf{make first}, \commandf{make second}, etc.,
%to run each separate computation of the demo. 
At each step, the user is encouraged to plot the data
saved by using the command \commandf{plot} (e.g., \commandf{plot(r)}
plots the data saved in the \python variable \parf{r}).

Of course, in a real application, the runs will not have been prepared
in advance, and {\cal AUTO}-commands must be used.
Such commands can be found in a table at the end of each chapter.
A sequence of detailed \AUTO-commands will be given in these tables
as illustrated in Table~\ref{tbl:HomCont_demos_1}
and Table~\ref{tbl:HomCont_demos_2} for two representative runs of 
{\cal HomCont} demo \filef{san}.

The user is encouraged to copy the format of one of these demos
when constructing new examples.

The output of the {\cal HomCont} demos reproduced in  the following chapters
is somewhat machine dependent, as already noted 
in Section~\ref{sec:Tutorial_all_runs}.
In exceptional circumstances, {\cal AUTO} may reach its maximum number of
steps \parf{NMX} before a certain output point, or the label of
an output point may change. In such case the user may have
to make appropriate changes in the {\cal AUTO} constants-files.


\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{san=load('san',IPS=9,NDIM=3,ISP=0,ILP=0,} &\\
  \commandf{  ITNW=7,JAC=1,NTST=35,IEQUIB=0,DS=0.05)}
  & set common \AUTO constants\\
  \commandf{r1=run(san,ICP=[1,8],UZR=\{-1:0.25\})} & run AUTO using the
  specified constants\\
  \commandf{save(r1,'6')}                & save output-files as \filef{b.6, s.6, d.6}  \\ 
\hline
%==============================================================================
  \commandf{@R san 1}           & use the constants file \filef{c.san.1}   \\ 
  \commandf{@sv 6}              &    \\ 
\hline
%==============================================================================
\end{tabular}
\caption{ These two sets of {\cal AUTO}-Commands are equivalent.}
\label{tbl:HomCont_demos_1}
\end{center}
\end{table}

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{r9=run(r8,ICP=[2,8],UZR=\{-2:3.0\})} & \parbox[t]{3in}{get
    the \AUTO constants-file and run \AUTO/{\cal HomCont}; restart
    from the last label in \parf{r8}\vspace{0.2cm}}\\
  \commandf{r6=r6+r9}                        & append output to the
  \python variable \parf{r6}  \\ 
  \commandf{save(r6,'6')}                    & save output to the
  files \filef{b.6, s.6, d.6}  \\ 
\hline
%==============================================================================
  \commandf{@R san 9 6}         & use the constants file
  \filef{c.san.9}, start from the file \filef{s.6}  \\ 
  \commandf{@ap 6}              & append output to the
   files \filef{b.6, s.6, d.6}  \\ 
\hline
%==============================================================================
\end{tabular}
\caption{ These two sets of {\cal AUTO}-Commands behave similarly.}
\label{tbl:HomCont_demos_2}
\end{center}
\end{table}



%==============================================================================
%==============================================================================
\chapter{ {\cal HomCont} Demo : san.} \label{ch:HomCont_san}
%==============================================================================
%==============================================================================

%==============================================================================
%DEMO=san======================================================================
%==============================================================================
\section{ Sandstede's Model.}
\newcommand{\ti}{\tilde}
Consider the system \cite{Sa:95b}
\begin{equation} \label{bs1} \begin{array}{rcl}
\dot{x} & = & a \, x + b \, y - a \, x^2 + (\ti \mu - \alpha \, z) \, x
\, (2-3x) \\
\dot{y} & = & b \, x + a \, y - \frac{3}{2} \, b \, x^2 - 
\frac{3}{2} \, a \, x \, y - (\ti \mu - \alpha \, z) \, 2 \, y \\
\dot{z} & = & c \, z + \mu \, x + \gamma\, x\, y + \alpha \, 
\beta \, (x^2 \, (1-x) - y^2)

\end{array} \end{equation}
as given in the file \filef{san.f90}.
Choosing the constants appearing
in (\ref{bs1}) appropriately allows for computing inclination and
orbit flips as well as non-orientable resonant bifurcations, see
\cite{Sa:95b} for details and proofs. The starting point for all
calculations is $a=0$, $b=1$ where there exists an explicit solution
given by  
$$ 
(x(t),y(t),z(t)) = 
\left( 1 - \left(\frac{1-e^t}{1+e^t}\right)^2 , 4 \, e^t \,
\frac{1-e^t}{(1+e^t)^3} , 0 \right). 
$$
This solution is specified in the routine \funcf{ STPNT}.

\section{Inclination Flip.}
We start by copying the demo to the current work directory 
and running the first step
\begin{center}
\commandf{demo('san')}\\
\commandf{san=load('san',IPS=9,NDIM=3,ISP=0,ILP=0,ITNW=7,JAC=1,NTST=35,IEQUIB=0,DS=0.05)}
\commandf{r1=run(san,ICP=[1,8],UZR=\{-1:0.25\})}
\end{center}
This computation starts from the analytic solution above with 
$a=0$, $b=1$, $c=-2$, $\alpha=0$, $\beta=1$ and 
$\gamma = \mu=\ti \mu =0$. The homoclinic solution is followed in the
parameters $(a,\ti \mu)$ \parf{=(PAR(1), PAR(8))} up to $a=0.25$. 
The output is summarised on the screen as
\begin{verbatim}
  BR    PT  TY  LAB    PAR(1)        L2-NORM            PAR(8)     
   1     1  EP    1   0.00000E+00   4.00000E-01 ...  0.00000E+00
   1     5  UZ    2   2.50000E-01   4.03054E-01 ... -1.85981E-11
\end{verbatim}
and saved in more detail in the \python variable \parf{r1}.

Next we want to add a solution to the adjoint equation to the
solution obtained at $a=0.25$. This is
achieved by starting from the last label, and making the changes
\parf{ITWIST = 1}, \parf{NMX = 2} and \parf{ICP(1) = 9}. We also disable any
user-defined functions \parf{UZR=\{\}}. The computation so-defined 
is a single step in a trivial parameter \parf{PAR(9)} (namely a parameter
that does not appear in the problem). The effect is to perform a Newton
step to enable \AUTO to converge to a solution of the adjoint equation.
\begin{center}
\commandf{r2=run(r1,ICP=[9,8],ITWIST=1,NMX=2,UZR=\{\})}
\end{center} 
The output is stored in the \python variable \parf{r2}.

We can now continue the homoclinic plus
adjoint in $(\alpha,\ti \mu)$ \parf{=(PAR(4), PAR(8))} by
changing the constants to read
\parf{NMX = 50} and \parf{ICP(1) = 4}.
We also add \parf{PAR(10)} to the list of continuation parameters
\parf{ICP}. Here \parf{PAR(10)} is a dummy parameter used in
order to make the continuation of the adjoint well posed. Theoretically,
it should be zero if the computation of the adjoint is successful
\cite{Sa:95b}.
The test functions for detecting resonant bifurcations 
(\parf{ISPI(1)=1}) and inclination flips (\parf{ISPI(1)=13}) are
also activated. Recall that this should be specified in
three ways. First we add \parf{PAR(21)} and \parf{PAR(33)}
to the list of continuation parameters, second we set up user defined
output at zeros of these parameters, and finally we set \parf{IPSI=[1,13]}
We also add another user zero for detecting when \parf{PAR(4)=1.0}.
Running 
\begin{center}
\commandf{r3=run(r2,ICP=[4,8,10,21,33],IPSI=[1,13],NMX=50,NPR=20,UZR=\{4:1.0,21:0,33:0\})}\\
\commandf{save(r3,'r3')}
\end{center}
starts from the last, and in this case, only, labelled solution in \parf{r2}
and outputs to the screen
\begin{verbatim}
 BR  PT  TY LAB    PAR(4)     ...    PAR(8)       PAR(10)   ...    PAR(33)    
  1  20       4  7.84722E-01  ... -2.72146E-11 -4.21812E-09 ...  1.44112E+01
  1  27  UZ   5  1.00000E+00  ... -3.91152E-11 -4.38659E-09 ...  5.70167E+00
  1  35  UZ   6  1.23086E+00  ... -6.18304E-11 -4.62672E-09 ... -9.48584E-06
  1  40       7  1.38397E+00  ... -8.41993E-11 -4.63701E-09 ... -1.34882E+00
  1  50  EP   8  1.69521E+00  ... -1.36449E-10 -5.35972E-09 ... -5.31105E-01
\end{verbatim}
Full output is stored in \filef{b.3}, \filef{s.3} and \filef{d.3}. 
\begin{figure}[b]
\epsfysize 9.0cm
\centerline{\epsffile{include/san1}}
\caption{Second versus third component of the solution to the adjoint
equation at labels 4, 6 and 8}
\label{Ftest1}
\end{figure}
Note that the artificial parameter $\epsilon=$\parf{PAR(10)} is zero within
the allowed tolerance. At label \parf{6}, a zero of test function $\psi_{13}$ has
been detected which corresponds to an inclination flip with respect to
the stable manifold. That the orientation of the homoclinic loop
changes as the family passes through this point can be read from
the information in \filef{d.3}.
However in \filef{d.3}, the line 
\begin{verbatim} 
ORIENTABLE (    0.2982090775E-03)
\end{verbatim}
at \parf{PT=35} would seems to contradict the 
detection of the inclination flip at this point. Nonetheless, the
important fact is the zero of the test function; and note that 
the value of the variable indicating the orientation is 
small compared to its value at the other regular points. 
Data for the adjoint equation at \parf{LAB= 4, 6} and \parf{8} at
and on either side of the inclination flip are presented in 
Fig.\ \ref{Ftest1}. The switching of the solution between components
of the leading unstable left eigenvector is apparent.
Finally, we remark that the Newton step in the dummy 
parameter \parf{PAR(20)} performed above is crucial
to obtain convergence. Indeed, if instead we try to continue the
homoclinic orbit and the solution of the adjoint equation directly by
setting
\begin{verbatim}
  ITWIST = 1   IRS = 2   NMX = 50   ICP(1) = 4
\end{verbatim}
and running
\begin{center}
\commandf{r4=run(r1,ICP=[4,8,10,21,33],ITWIST=1,IPSI=[1,13],NMX=50,UZR=\{33:0\})}
\end{center}
we obtain a no convergence error.

\section{Non-orientable Resonant Eigenvalues.}
Inspecting the output saved in the third run,
we observe the existence of a non-orientable homoclinic orbit at the
second \parf{UZ} label 
\parf{6}. We restart at this label, with
the first continuation parameter being once again $a=$\parf{PAR(1)}, 
by changing constants according to 
\begin{verbatim}
   DS = -0.05    NMX = 20    ICP(1) = 1
\end{verbatim}
Running, 
 \begin{center}
\commandf{r5=run(r3('UZ2'),ICP=[1,8,10,21,33],NMX=20,DS='-',sv='5')}\\
\end{center}
the output at label \parf{9}
\begin{verbatim}
  BR    PT  TY LAB     PAR(1)           PAR(8)        PAR(10)       PAR(21)       
   1     8  UZ   9  -1.30447E-07 ...  3.41490E-12  -1.63406E-09  -2.60894E-07
\end{verbatim}
indicates that \AUTO has detected a zero of
\parf{PAR(21)}, implying that a non-orientable resonant bifurcation
occurred at that point.

\section{Orbit Flip.}
In this section we compute an orbit flip. To this end we restart
from the original explicit solution, without computing the orientation. We 
begin by separately performing continuation in $(\alpha,\ti \mu)$, 
$(\beta,\ti \mu)$, $(a,\ti \mu)$, $(b,\ti \mu)$ and $(\mu, \ti \mu)$
in order to reach the parameter values 
$(a,b,\alpha,\beta, \mu)=(0.5,3,1,0,0.25)$.
The sequence of continuations up to the desired parameter values 
are run via
\begin{center}
\commandf{r6=run(san,ICP=[4,8],UZR=\{-4:1\})\\
r7=run(r6,ICP=[5,8],UZR=\{-5:0\},DS='-')\\
r8=run(r7,ICP=[1,8],UZR=\{-1:0.5\},DS='-')\\
r9=run(r8,ICP=[2,8],UZR=\{-2:3.0\})\\ 
r10=run(r9,ICP=[7,8],UZR=\{-7:0.25\})\\}
\end{center}
with appropriate continuation parameters and user output values
set. The desired output is stored in \parf{r10}.

The final saved point \parf{LAB=6} contains a homoclinic solution at
the desired parameter values. From here we perform continuation in
the negative direction of $(\mu,\ti \mu)=$ (\parf{PAR(7),PAR(8)}) with
the test function $\psi_{11}$ for orbit flips with respect to the
stable manifold activated.
\begin{center}
\commandf{r11=run(r10,ICP=[7,8,31],IPSI=[11],UZR=\{31:0.0,-7:-0.5\},DS='-')\\
save(r11,'11')}
\end{center}
The output detects an inclination flip (by a zero of \parf{PAR(31)}) 
at \parf{PAR(7)=0} 
\begin{verbatim}
  BR    PT  TY LAB    PAR(7)      ...    PAR(8)        PAR(31)    
   1     5  UZ   7  6.33545E-06   ...  1.70968E-06  -8.70508E-05
\end{verbatim}
at which parameter value the homoclinic orbit is contained in the $(x,y)$-plane
(see Fig.\ \ref{Ftest2}).

\begin{figure}[t]
\epsfysize 9.0cm
\centerline{\epsffile{include/san2}}
\caption{Orbits on either side of the orbit flip bifurcation. The critical
orbit is contained in the $(x,y)$-plane}
\label{Ftest2}
\end{figure}

Finally, we demonstrate that the orbit flip can be continued as 
three parameters (\parf{PAR(6), PAR(7), PAR(8)}) are varied. 
\begin{center}
\commandf{of = r11('UZ1')\\
r12=run(of,ICP=[7,8,6],IPSI=[],NPR=5,NMX=20,IFIXED=[11],UZR=\{\},DS='-')
save(r12,'12')}
\end{center}
\begin{verbatim}
 BR    PT  TY LAB    PAR(7)       ...    PAR(8)        PAR(6)     
  1     5       9  -7.38787E-19   ...  -2.91178E-10  -3.25000E-01
  1    10      10  -5.27166E-19   ...  -2.23972E-10  -8.25000E-01
  1    15      11  -6.15227E-19   ...  -2.91908E-10  -1.32500E+00
  1    20  EP  12  -5.96426E-19   ...  -3.20088E-10  -1.82500E+00
\end{verbatim}
The orbit flip continues to be defined by a planar homoclinic orbit
at \parf{PAR(7)=PAR(8)=0}.

\section{ Detailed \AUTO-Commands.}

\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir san} & create an empty work directory \\ 
  \commandf{cd san} & change directory \\
  \commandf{demo('san')} & copy the demo files to the work directory\\
  \commandf{san=load('san',IPS=9,NDIM=3,ISP=0,ILP=0,} & \\
  \commandf{  ITNW=7,JAC=1,NTST=35,IEQUIB=0,DS=0.05)} & configure
    common constants\\
\hline
%==============================================================================
  \commandf{r1=run(san,ICP=[1,8],UZR=\{-1:0.25\})}& continuation in \parf{PAR(1)} \\ 
\hline
%==============================================================================
  \commandf{r2=run(r1,ICP=[9,8],ITWIST=1,NMX=2,UZR=\{\})} & generate adjoint variables \\ 
\hline
%=============================================================================
  \commandf{r3=run(r2,ICP=[4,8,10,21,33],IPSI=[1,13],} & \\
  \commandf{  NMX=50,NPR=20,UZR=\{4:1.0,21:0,33:0\}) } & continue homoclinic orbit and adjoint\\ 
  \commandf{save(r3,'3') } & save output-files as \filef{b.3, s.3, d.3} \\ 
\hline
%==============================================================================
  \commandf{r4=run(r1,ICP=[4,8,10,21,33],ITWIST=1,} & \\
  \commandf{  IPSI=[1,13],NMX=50,UZR=\{33:0\}) } & no convergence without dummy step \\ 
  \commandf{sv('4') } &  save output-files as \filef{b.4, s.4, d.4} \\ 
\hline
%=============================================================================
  \commandf{r5=run(r3('UZ2'),ICP=[1,8,10,21,33],NMX=20,} & continue non-orientable orbit\\
  \commandf{  DS='-',sv='5') }& save output-files as \filef{b.5, s.5, d.5} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Detailed \AUTO-Commands for running demo \filef{san}.}
\label{tbl:demo_san_1}
\end{center}
\end{table}


\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{r6=run(san,ICP=[4,8],UZR=\{-4:1\})} & restart and homotopy to \parf{PAR(4)}=1.0 \\ 
\hline
%==============================================================================
  \commandf{r7=run(r6,ICP=[5,8],UZR=\{-5:0\},DS='-')} & homotopy
  to \parf{PAR(5)}=0.0 \\ 
\hline
%==============================================================================
  \commandf{r8=run(r7,ICP=[1,8],UZR=\{-1:0.5\},DS='-')} & homotopy to \parf{PAR(1)}=0.5 \\ 
\hline
  \commandf{r9=run(r8,ICP=[2,8],UZR=\{-2:3.0\})} & homotopy to \parf{PAR(2)}=3.0\\ 
\hline
%==============================================================================
  \commandf{r10=run(r9,ICP=[7,8],UZR=\{-7:0.25\})} & homotopy to \parf{PAR(7)}=0.25\\ 
\hline
%==============================================================================
  \commandf{r11=run(r10,ICP=[7,8,31],IPSI=[11],} & \\
  \commandf{  UZR=\{31:0.0,-7:-0.5\},DS='-')} & continue in \parf{PAR(7)} to detect orbit flip \\ 
  \commandf{save(r11,'11') } & save output-files as \filef{b.11, s.11, d.11} \\ 
\hline
%==============================================================================
  \commandf{of=r11('UZ1')} & select first UZ-labelled point
  of \parf{r11} to start from\\
  \commandf{r12=run(of,ICP=[7,8,6],IPSI=[],NPR=5,} & \\
  \commandf{  NMX=20,IFIXED=[11],UZR=\{\},DS='-') } & three-parameter continuation of orbit flip \\ 
  \commandf{save(r12,'12') } & save output-files as \filef{b.12, s.12, d.12} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Detailed \AUTO-Commands for running demo \filef{san}.}
\label{tbl:demo_san_2}
\end{center}
\end{table}




%==============================================================================
%==============================================================================
\chapter{ {\cal HomCont} Demo : mtn.} \label{ch:HomCont_mtn}
%==============================================================================
%==============================================================================

%==============================================================================
%DEMO=mtn======================================================================
%==============================================================================
\section{ A Predator-Prey Model with Immigration.}
Consider the following system of two equations \cite{Sc:95}
\begin{equation} \label{sn.1} \begin{array}{rcl}
\dot{X} & = & RX\left(1-{\ds \frac{X}{K}}\right) - 
{\ds \frac{A_1XY}{B_1+X}} + D_0K \\
\dot{Y} & = & E_1 {\ds \frac{A_1XY}{B_1+X}} - D_1Y - 
{\ds\frac{A_2ZY^2}{B_2^2+Y^2}}.
\end{array} \end{equation}
\begin{figure}[b]
\epsfysize 10.0cm
\centerline{\epsffile{include/mtn1}}
\caption{Parametric portrait of the predator-prey system }
\label{SNF.1}
\end{figure}
The values of all parameters except $(K,Z)$ are set as follows~:
$$
R=0.5,\ A_1=0.4,\ B_1=0.6,\ D_0=0.01,\ E_1=0.6,\ A_2=1.0,\ B_2=0.5,\ D_1=0.15.
$$
\par
\noindent
The parametric portrait of the system (\ref{sn.1}) on the
$(Z,K)$-plane is presented in Figure \ref{SNF.1}. It contains fold
($t_{1,2}$) and Hopf ($H$) bifurcation curves, as well as a homoclinic
bifurcation curve $P$. The fold curves meet at a cusp singular point
$C$, while the Hopf and the homoclinic curves originate at a
Bogdanov-Takens point $BT$. Only the homoclinic curve $P$ will be 
considered here, the other bifurcation curves can be computed using
\AUTO or,
for example, {\cal locbif} \cite{KhKuLeNi:93}.

\section{Continuation of Central Saddle-Node Homoclinics.}
Local bifurcation analysis shows that at $K=6.0,\ Z=0.06729762\ldots$,
the system has a saddle-node equilibrium 
$$
(X^0,Y^0) = (5.738626\ldots,0.5108401\ldots),
$$
with one zero and one negative eigenvalue. Direct simulations reveal a
homoclinic 
orbit to this saddle-node, departing and returning along its central
direction (i.e., tangent to the null-vector).
\par
Starting from this solution, stored in the file \filef{mtn.dat}, we
continue the saddle-node central homoclinic orbit 
with respect to the parameters $K$ and $Z$ by copying the
demo and running it
\begin{center}
\commandf{dm('mtn')}\\
\commandf{r1=run('mtn',c='mtn.1',sv='1')}
\end{center}
The file \filef{mtn.f90} contains approximate
parameter values
$$
K=\parf{PAR(1)}=6.0,\ Z=\parf{PAR(2)}=0.06729762,
$$
as well as the coordinates of the saddle-node
$$
X^0=\parf{PAR(12)}=5.738626,\ Y^0=\parf{PAR(13)}=0.5108401,
$$
and the length of the truncated time-interval
$$
T_0=\parf{PAR(11)} = 1046.178 \: .
$$
Since a homoclinic orbit to a saddle-node is being followed, we have also
made the choice
$$
\parf{IEQUIB = 2}
$$
in \filef{c.mtn.1}. The two test-functions, $\psi_{15}$ and $\psi_{16}$, 
to detect non-central saddle-node homoclinic
orbits are also activated, which must be specified in three ways. 
Firstly, in \filef{c.mtn.1}, \parf{IPSI} is
set to \parf{[15,16]} so the active test functions
are chosen as 15 and 16. This sets up the monitoring of these
test functions. Secondly, in \filef{c.mtn.1} user-defined functions
(\parf{UZR}) are set up to look for zeros of the parameters
corresponding to these test functions. Recall that the
parameters to be zeroed are always the test functions plus 20.
Finally, these parameters are included in the list of continuation
parameters (\parf{ICP}).

Among the output there is a line 
\begin{verbatim}
  BR    PT  TY  LAB    PAR(1)     ...    PAR(2)        PAR(35)       PAR(36)
   1    26  UZ    4   6.61046E+00 ...   6.93248E-02   5.23950E-09  -6.42344E-02
\end{verbatim}
indicating that a zero of the test function \parf{IPSI(1)=15} 
This means that at
$$
D_1=(K^1,Z^1)=(6.6105\ldots, 0.069325\ldots)
$$
the homoclinic orbit to the saddle-node becomes {\it non-central}, namely,
it returns to the equilibrium along the stable eigenvector, forming a
non-smooth loop. The output is saved in \filef{b.1}, \filef{s.1} and
\filef{d.1}. 
Repeating computations in the opposite direction along the curve, 
\parf{IRS=1, DS=-0.01} in \filef{c.mtn.2}, 
\begin{center}
\commandf{r1=r1+run(r1(1),c='mtn.2',ap='1')}
\end{center}
one obtains 
\begin{verbatim}
  BR    PT  TY  LAB    PAR(1)     ...    PAR(2)        PAR(35)       PAR(36)
   1    34  UZ   10   5.18039E+00 ...   6.38554E-02   8.86654E-10  -7.28132E-02
\end{verbatim}
which means another non-central saddle-node homoclinic bifurcation occurs
at
$$
D_2=(K^2,Z^2)=(5.1803\ldots,0.063855\ldots).
$$
Note that these data were obtained using a smaller value of \parf{NTST} than
the original computation (compare \filef{c.mtn.1} with \filef{c.mtn.2}). The
high original value of \parf{NTST} was only necessary for the first few steps
because the original solution is specified on a uniform mesh. 

\section{Switching between Saddle-Node and Saddle Homoclinic Orbits.}
Now we can switch to continuation of saddle homoclinic orbits at the
located codim 2 points $D_1$ and $D_2$. 
\begin{center}
\commandf{r1=r1+run(r1('UZ1'),c='mtn.3',ap='1')}
\end{center}
starts from $D_1$. Note that now 
\begin{center}
\parf{IEQUIB = 1}  
\end{center}
has been specified in \filef{c.mtn.3}. Also, test functions $\psi_9$
and $\psi_{10}$ have been activated in order
to monitor for non-hyperbolic equilibria along the homoclinic locus. 
We get the following output
\begin{verbatim}
  BR    PT  TY  LAB    PAR(1)     ...    PAR(2)        PAR(29)       PAR(30)    
   1    10       12   7.11454E+00 ...   7.08176E-02  -4.64986E-01   3.18355E-03
   1    20       13   9.17683E+00 ...   7.67874E-02  -4.68491E-01   1.60931E-02
   1    30       14   1.21084E+01 ...   8.54348E-02  -4.71887E-01   3.06966E-02
   1    40  EP   15   1.50379E+01 ...   9.42805E-02  -4.74379E-01   4.14457E-02
\end{verbatim}
The fact that \parf{PAR(29)} and \parf{PAR(30)} do not change sign indicates 
that there are no further non-hyperbolic equilibria
along this family. Note that restarting in the opposite direction with
\parf{IRS=15,DS=-0.02} 
\begin{center}
\commandf{r4=run(r1,c='mtn.4',sv='4')}
\end{center}
will detect the same codim 2 point $D_1$ but now as a zero
of the test-function $\psi_{10}$
\begin{verbatim}
  BR    PT  TY  LAB    PAR(1)     ...    PAR(2)        PAR(29)       PAR(30)
   1    38  UZ   11   6.61046E+00 ...   6.93248E-02  -4.63660E-01   3.13439E-08
\end{verbatim}
Note that the values of \parf{PAR(1)} and \parf{PAR(2)} are equal to those
at label \parf{4} up to at least six significant figures.

Actually, the program runs further and
eventually computes the point $D_2$ and the whole lower family of $P$
emanating from it, however, the solutions between $D_1$ and $D_2$
should be considered as spurious\footnote{\label{ft1} The program actually
computes the saddle-saddle heteroclinic orbit bifurcating from the
non-central saddle-node homoclinic at the point $D_1$, see
\citeasnoun[Fig. 2]{ChKuSa:95}, and continues it to the one emanating from
$D_2$.}, therefore we do not save these data.
The reliable way to compute the lower family of $P$ is to restart computation
of saddle homoclinic orbits in the other direction from the point $D_2$
\begin{center}
\commandf{r1=r1+run(r1('UZ3'),c='mtn.5',ap='1')}
\end{center}
This gives the lower family of $P$ approaching the BT point
(see Figure \ref{SNF.1})
\begin{verbatim}
  BR    PT  TY  LAB    PAR(1)     ...   PAR(2)        PAR(29)       PAR(30)
   1    10       16   4.96649E+00 ...  6.29843E-02  -4.38247E-01   4.94481E-03
   1    20       17   4.92531E+00 ...  7.96087E-02  -3.39922E-01   3.28829E-02
   1    30       18   7.09217E+00 ...  1.58708E-01  -1.69289E-01   3.87631E-02
   1    40  EP   19   1.10181E+01 ...  2.80980E-01  -3.48294E-02   2.10449E-02
\end{verbatim}
The data are appended to the stored results in \filef{b.1}, \filef{s.1} and
\filef{d.1}. One could now display all data using the \AUTO
command \commandf{@pp 1} to reproduce the curve $P$ shown in Figure
\ref{SNF.1}.
\par
%------------------------------------------------------
\begin{figure}[p]
\epsfysize 10.0cm
\centerline{\epsffile{include/mtn2}}
\caption{Approximation by a large-period cycle}
\label{SNF.2}
\end{figure}
%------------------------------------------------------
%------------------------------------------------------
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/mtn3}}
\caption{Projection onto the ($K,D_0$)-plane of the 
three-parameter curve of non-central  saddle-node homoclinic orbit}
\label{SNF.3}
\end{figure}
%------------------------------------------------------
%
It is worthwhile to compare the homoclinic curves computed above with
a curve $T_0=const$ along which the system has a limit cycle of constant large
period $T_0=1046.178$, which can easily be computed using \AUTO or
{\cal locbif}. Such a curve is plotted in Figure \ref{SNF.2}. 
It obviously approximates well the saddle homoclinic loci of $P$, but 
demonstrates much bigger
deviation from the saddle-node homoclinic segment $D_1D_2$. This happens
because the period of the limit cycle grows to infinity while approaching both
types of homoclinic orbit, but with {\it different asymptotics}: 
as $-\ln\|\alpha-\alpha^*\|$, in the saddle homoclinic case, and 
as $\|\alpha-\alpha^*\|^{-1}$ in the saddle-node case. 

\section{Three-Parameter Continuation.}
Finally, we can follow the curve of non-central saddle-node homoclinic
orbits in three parameters. The extra continuation parameter is
$D_0$=\parf{PAR(3)}.  To achieve this we restart at label \parf{4},
corresponding to the codim 2 point $D_1$. We return to continuation of
saddle-node homoclinics, \parf{NUNSTAB=0},\parf{IEQUIB=2}, but append the
defining equation $\psi_{15}=0$ to the continuation problem
(via \parf{IFIXED=[15]}). The new
continuation problem is specified in \filef{c.mtn.6}.
\begin{center}
\commandf{r6=run(r1('UZ1'),c='mtn.6',sv='6')}
\end{center}
Notice that we set \parf{ILP=1} and choose \parf{PAR(3)} as the first 
continuation parameter so that \AUTO can detect limit points 
with respect to this parameter. We also make a user-defined function
(\parf{UZR})
to detect intersections with the plane $D_0=0.01$.
We get among other output
\begin{verbatim}
  BR    PT  TY  LAB    PAR(3)        L2-NORM    ...    PAR(1)        PAR(2)
   1    22  LP   20   1.08120E-02   5.32589E+00 ...   5.67363E+00   6.60818E-02
   1    31  UZ   21   1.00000E-02   4.81969E+00 ...   5.18032E+00   6.38551E-02
\end{verbatim}
the first line of which represents the $D_0$ value at which 
the homoclinic curve $P$ has a tangency with the family $t_2$ 
of fold bifurcations. Beyond this value of $D_0$,
$P$ consists entirely of saddle homoclinic orbits. The data at label \parf{20} 
reproduce the coordinates of the point $D_2$. The results of this
computation and a similar one starting from $D_1$ in the opposite direction
(with \parf{DS=-0.01}) are displayed in Figure \ref{SNF.3}.
%

\section{ Detailed \AUTO-Commands.}
\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir mtn} & create an empty work directory \\ 
  \commandf{cd mtn} & change directory \\
  \commandf{demo('mtn')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run('mtn',c='mtn.1',sv='1')} &  continue saddle-node
  homoclinic orbit from \filef{mnt.dat}\\
  & save output-files as \filef{b.1, s.1, d.1} \\ 
\hline
%==============================================================================
  \commandf{r1=r1+run(r1(1),c='mtn.2',ap='1')} & continue in opposite
  direction; restart from label 1 \\ 
  & append output-files to \filef{b.1, s.1, d.1} \\ 
\hline
%=============================================================================
  \commandf{r1=r1+run(r1('UZ1'),c='mtn.3',ap='1')} & switch to saddle
  homoclinic orbit  ; restart: 1st \parf{UZ} \\ 
  & append output-files to \filef{b.1, s.1, d.1} \\ 
\hline
%==============================================================================
  \commandf{r4=run(r1,c='mtn.4',sv='4')} & continue in reverse
  direction; restart from last label \\ 
  & save output-files as \filef{b.4, s.4, d.4} \\ 
\hline
%=============================================================================
  \commandf{r1=r1+run(r1('UZ3'),c='mtn.5',ap='1')} & other saddle
  homoclinic orbit family; restart: 3rd \parf{UZ} \\
  & append output-files to \filef{b., s.1, d.1} \\ 
\hline
%==============================================================================
  \commandf{r6=run(r1('UZ1'),c='mtn.6',sv='6')} & 3-parameter non-central saddle-node homoclinic. \\ 
  & save output-files as \filef{b.6, s.6, d.6} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Detailed \AUTO-Commands for running demo \filef{mtn}.}
\label{tbl:demo_mtn_1}
\end{center}
\end{table}



%==============================================================================
%==============================================================================
\chapter{ {\cal HomCont} Demo : kpr.} \label{ch:HomCont_kpr}
%==============================================================================
%==============================================================================

%==============================================================================
%DEMO=kpr======================================================================
%==============================================================================
\section{ Koper's Extended Van der Pol Model.}
%
The equation-file \filef{kpr.f90} contains the equations
\begin{equation} \label{ko} \begin{array}{rcl}
\dot{x} & = & \eps_1^{-1}\:(k\: y - x^3 +3\:x - \lambda) \\
\dot{y} & = & x - 2\: y + z \\
\dot{z} & = & \eps_2(y-z), 
\end{array} \end{equation}
with $\eps_1 =0.1$ and $\eps_2=1$ \cite{Ko:95}.

To copy across the demo \filef{kpr} and compile we type
\begin{center}
\commandf{demo('kpr')} \\
\end{center}

\section{The Primary Branch of Homoclinics.}
First, we locate a homoclinic orbit using 
the homotopy method. The file \filef{kpr.f90} 
already contains 
approximate parameter values for a homoclinic orbit, 
namely $\lambda=$\parf{PAR(1)=-1.851185}, $k=$\parf{PAR(2)=-0.15}. 
The file \filef{c.kpr.1} specifies the appropriate
constants for continuation in $2T$\parf{=PAR(11)} (also referred
to as \parf{PERIOD}) and the dummy parameter $\omega_1$=\parf{PAR(17)}
starting
from a small solution in the local unstable manifold; 
\begin{center}
\commandf{r1=run('kpr',c='kpr.1',sv='1')}
\end{center}
Among the output there is the line
\begin{verbatim}
     BR    PT  TY LAB    PERIOD        L2-NORM     ...    PAR(17)    ...
      1    29  UZ   2  1.90018E+01   1.69382E+00   ...  4.46147E-09  ...
\end{verbatim}
which indicates that a zero of the artificial parameter $\omega_1$
has been located. This means that the right-hand end point of the solution
belongs to the plane that is tangent to the stable manifold at the saddle. 
The output is stored in files \filef{b.1, s.1, d.1}. 
Upon plotting the data at label \parf{2} (see Figure \ref{kf.1a})
it can be noted that although the right-hand projection boundary
condition is satisfied, the solution is still quite away from the
equilibrium. 

The right-hand endpoint can be made to approach the
equilibrium by performing a further continuation in $T$ with the
right-hand projection condition satisfied (\parf{PAR(17)} fixed) but
with $\lambda$ allowed to vary. 
%
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/kpr1}}
\caption{Projection on the $(x,y)$-plane of solutions 
of the boundary value 
problem with $2T=19.08778$.}
\label{kf.1a}
\end{figure}
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/kpr2}}
\caption{Projection on the $(x,y)$-plane of solutions of the 
boundary value problem with $2T = 60.0$.}
\label{kf.1b}
\end{figure}
%
\begin{center}
\commandf{r2=run(r1('UZ1'),c='kpr.2',sv='2')}
\end{center}
the output at label \parf{4}, stored in \filef{s.2},
\begin{verbatim}
   BR   PT TY  LAB    PERIOD       L2-NORM     ...    PAR(1)     ...
    1   35 UZ    4   6.00000E+01  1.67281E+00  ...  -1.85119E+00 ...
\end{verbatim}
provides a good approximation to a homoclinic solution (see Figure
\ref{kf.1b}). 

The second stage to obtain a starting solution 
is to add a solution to the modified adjoint
variational equation. This is achieved by setting both 
\parf{ITWIST} and \parf{ISTART} to 1 (in \filef{c.kpr.3}), which generates
a trivial guess for the adjoint equations. Because the adjoint
equations are linear, only a single
Newton step (by continuation in a trivial parameter) 
is required to provide a solution.
Rather than choose a parameter that might be used internally
by \AUTO, in \filef{c.kpr.3} we take the continuation parameter
to be \parf{PAR(11)}, which is not quite a trivial parameter
but whose affect upon the solution is mild.
\begin{center}
\commandf{r3=run(r2('UZ1'),c='kpr.3',sv='3')}
\end{center}
The output at the second point (label \parf{6}) 
contains the converged homoclinic
solution (variables (\parf{U(1), U(2), U(3)}) and the adjoint (\parf{
U(4), U(5), U(6)})). We now have a starting solution 
and are ready to perform two-parameter continuation.

The fourth run
\begin{center}
\commandf{r3=r3+run(r3,c='kpr.4',ap='3')}
\end{center}
continues the homoclinic orbit in \parf{PAR(1)} and \parf{PAR(2)}. 
%
%------------------------------------------------------
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/kpr4}}
\caption{Projection on the $(x,y)$-plane of solutions $\phi(t)$
at \parf{1} ($\lambda=-1.825470, k=-0.1760749$) and
\parf{2} ($\lambda=-1.686154, k=-0.3183548$).}
\label{kf.2a}
\end{figure}
%------------------------------------------------------
%------------------------------------------------------
\begin{figure}[p]
\epsfysize 8.0cm
\centerline{\epsffile{include/kpr5}}
\caption{Three-dimensional blow-up of the solution curves
 $\phi(t)$ 
at labels \parf{1} (dotted) and \parf{2} (solid line) from Figure 3.8.}
\label{kf.2b}
\end{figure}
%------------------------------------------------------
%
Note that several other parameters appear in
the output. \parf{PAR(10)} is a dummy parameter
that should be zero when the adjoint is being computed correctly;
\parf{PAR(29)}, \parf{PAR(30)}, \parf{PAR(33)} correspond to the
test functions $\psi_9$,$\psi_{10}$ and $\psi_{13}$. 
That these test functions were activated is specified
in three places in \filef{c.kpr.4} 
as described in Section~\ref{sec:HomCont_Test_functions}.  

Note that at the end-point of
the family (reached when after \parf{NMX=50} steps) \parf{PAR(29)} is
approximately zero which corresponds to a zero of $\psi_9$, a 
non-central saddle-node homoclinic orbit. We shall return to the computation of
this codimension-two point later. Before reaching this point,
among the output we find two zeroes of \parf{PAR(33)}
(test function $\psi_{13}$) which gives the accurate
location of two inclination-flip bifurcations,
\begin{verbatim}
 BR  PT  TY LAB    PAR(1)     ...     PAR(2)        PAR(10)    ...   PAR(33)
  1   6  UZ   7  -1.80166E+00 ...  -2.00266E-01  -7.25140E-07 ...  1.14077E-04
  1  12  UZ   8  -1.56876E+00 ...  -4.39547E-01  -2.15617E-07 ... -1.48740E-07
\end{verbatim}
That the test function really does have a regular zero at this point can
be checked from the data saved in \filef{b.3}, plotting \parf{PAR(33)} as
a function of \parf{PAR(1)} or \parf{PAR(2)}. 
Figure \ref{kf.2a} presents solutions $\phi(t)$ of the modified adjoint 
variational equation (for details see \citeasnoun{ChKuSa:95})
at parameter values on the homoclinic 
family before and after the first detected inclination flip. 
Note that these solutions were obtained by choosing a smaller
step \parf{DS} and more output (smaller \parf{NPR}) in
\filef{c.kpr.4}.
A blow-up of the region close to the origin of this 
figure is shown in Figure \ref{kf.2b}.
It illustrates the flip of the solutions of the adjoint equation while
moving through the bifurcation point. Note that the data in this
figure were plotted after first performing an additional
continuation of the solutions with respect to \parf{PAR(11)}. 

Continuing in the other direction 
\begin{center}
\commandf{r3=r3+run(r3()[0],c='kpr.5',ap='3')}
\end{center}
we approach a Bogdanov-Takens point
\begin{verbatim}  
 BR    PT  TY LAB    PAR(1)     ...    PAR(10)    ...    PAR(33)    
  1    50  EP  10 -1.93828E+00  ... -7.52334E+00  ... -3.19793E+01
\end{verbatim}
%------------------------------------------------------
\begin{figure}[t]
\epsfysize 9.0cm
\centerline{\epsffile{include/kpr6}}
\caption{Computed homoclinic orbits approaching the BT point}
\label{kp.6}
\end{figure}
%------------------------------------------------------
Note that the numerical approximation has ceased to become reliable, since 
\parf{PAR(10)} has now become large. 
Phase portraits of homoclinic orbits between the BT point and the first
inclination flip 
are depicted in Figure \ref{kp.6}. Note how the computed homoclinic orbits
approaching the BT point have their endpoints well away from the equilibrium.
To follow the homoclinic orbit to 
the BT point with more precision, we would need to first perform continuation 
in $T$ (\parf{PAR(11)}) to obtain a more accurate homoclinic solution.


\section{More Accuracy and Saddle-Node Homoclinic Orbits.}
Continuation in $T$ 
in order to obtain an approximation of the homoclinic orbit over a
longer interval is necessary for parameter values near a non-hyperbolic
equilibrium (either a saddle-node or BT) where the convergence
to the equilibrium is slower. 
First, we start from the original homoclinic orbit computed
via the homotopy method, label \parf{4}, which is well away from
the non-hyperbolic equilibrium.
Also, we shall no longer be interested in
in inclination flips so we set \parf{ITWIST=0} in \filef{c.kpr.6},
and in order to compute up to \parf{PAR(11)=1000}, we set up a
user-defined function for this. Running \AUTO with \parf{PAR(11)} and 
\parf{PAR(2)} as free parameters
\begin{center}
\commandf{r6=run(r2('EP1'),c='kpr.6',sv='6')}
\end{center}
we obtain among the output
\begin{verbatim}
  BR    PT  TY LAB     PERIOD       L2-NORM    ...    PAR(2)     
   1    35  UZ   6   1.00000E+03  1.66191E+00  ... -1.50000E-01
\end{verbatim}

We can now repeat the computation of the family of saddle homoclinic
orbits in \parf{PAR(1)} and \parf{PAR(2)} from this point with
the test functions $\psi_9$ and $\psi_{10}$ for non-central
saddle-node homoclinic orbits activated 
\begin{center}
\commandf{r7=run(r6('UZ1'),c='kpr.7',sv='7')}
\end{center}
The saddle-node point is now detected at 
\begin{verbatim} 
  BR    PT  TY LAB    PAR(1)     ...    PAR(2)        PAR(29)       PAR(30)
   1    29  UZ   8  1.76505E-01  ... -2.40533E+00  -1.74004E-06   2.30933E+01
\end{verbatim}
which is stored in \filef{s.7}.
That \parf{PAR(29)} ($\psi_9$) is zeroed shows that this
is a non-central saddle-node connecting the centre manifold to the strong stable
manifold. Note that all output beyond this point, although a well-posed
solution to the boundary-value problem, is spurious in that it no longer
represents a homoclinic orbit to a saddle equilibrium (see
\citeasnoun{ChKuSa:95}). If we had chosen
to, we could continue in the other direction in order to
approach the BT point more accurately by reversing the sign of
\parf{DS} in \filef{c.kpr.7}.
 
The file \filef{c.kpr.8} contains the constants necessary 
for switching to continuation of the central saddle-node homoclinic curve 
in two parameters starting from the non-central saddle-node homoclinic orbit
stored as label \parf{8} in \filef{s.7}.
\begin{center}
\commandf{r8=run(r7('UZ1'),c='kpr.8',sv='8')}
\end{center}
In this run we have activated the test functions for saddle to saddle-node
transition points along curves of saddle homoclinic orbits ($\psi_{15}$ and 
$\psi_{16}$). Among the output we find
\begin{verbatim}
  BR    PT  TY LAB    PAR(1)     ...    PAR(2)        PAR(35)       PAR(36)    
   1    38  UZ  11   1.76509E-01 ...  -2.40533E+00   6.89014E-03   3.09956E-05
\end{verbatim}
%------------------------------------------------------
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/kpr7}}
\caption{Two non-central saddle-node homoclinic orbits, \parf{1} and \parf{3};
and, \parf{2}, a central saddle-node homoclinic orbit between
these two points \label{kf.7}}
\end{figure}
%------------------------------------------------------
%------------------------------------------------------
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/kpr8}}
\caption{The big homoclinic orbit approaching a figure-of-eight}
\label{kp.8}
\end{figure}
%------------------------------------------------------
%
which corresponds to the family of homoclinic orbits leaving
the locus of saddle-nodes in a second non-central saddle-node
homoclinic bifurcation (a zero of $\psi_{16}$). 

Note that the parameter values do not vary much between the
two codimension-two non-central saddle-node points (labels \parf{8} and \parf{11}).
However, Figure \ref{kf.7} shows clearly that between the two
codimension-two points 
the homoclinic orbit
rotates between the two components of the 1D stable manifold, i.e.\
between the two boundaries of the center-stable manifold of the saddle
node. The overall effect of this process is the transformation of a
nearby ``small'' saddle homoclinic orbit to a ``big'' saddle
homoclinic orbit (i.e.\ with two extra turning points in phase space).  

Finally, we can switch to continuation of the big saddle homoclinic orbit 
from the new codim 2 point at label \parf{11}. 
\begin{center}
\commandf{r9=run(r8('UZ1'),c='kpr.9',sv='9')}
\end{center}
Note that \AUTO takes a large number of steps near the line  
\parf{PAR(1)=0}, while \parf{PAR(2)} approaches $-2.189\ldots$  
(which is why we chose such a large value \parf{NMX=500} in \filef{c.kpr.9}). This
particular computation ends at 
\begin{verbatim}  
  BR    PT  TY LAB    PAR(1)        L2-NORM    ...    PAR(2)   
   1   500  EP  24  2.04263E-05   2.18126E-01  ... -2.18951E+00
\end{verbatim}
By plotting phase portraits of orbits approaching this end point (see Figure
\ref{kp.8}) we see a ``canard-like'' like transformation of the big homoclinic
orbit to a pair of homoclinic orbits in a figure-of-eight configuration.
That we get a figure-of-eight is not a surprise because \parf{PAR(1)=0}
corresponds to a symmetry in the differential equations \cite{Ko:94};
note also that the equilibrium, stored as (\parf{PAR(12), PAR(13), PAR(14)}) in
\filef{d.9}, approaches the origin as we approach the figure-of-eight homoclinic.

\section{Three-Parameter Continuation.}
We now consider curves in three parameters of each of
the codimension-two points encountered in this model, by
freeing the parameter $\eps=$ \parf{PAR(3)}.
First we continue the first inclination flip stored at label
\parf{7} in \filef{s.3}
\begin{center}
\commandf{r10=run(r3('UZ1'),c='kpr.10',sv='10')}
\end{center}
Note that \parf{ITWIST=1} in \filef{c.kpr.10}, so that the adjoint is also
continued, and there is one fixed condition \parf{IFIXED(1)=13} so that
test function $\psi_{13}$ has been frozen.
Among the output there is a codimension-three point (zero of $\psi_9$)
where the neutrally twisted homoclinic orbit collides with the saddle-node
curve
\begin{verbatim}
 BR  PT  TY LAB    PAR(1)     ...   PAR(2)        PAR(3)        PAR(29)    ...
  1  18  UZ  11   1.28270E-01 ... -2.51932E+00   5.74477E-01  -2.59151E-06 ...
\end{verbatim}
The other detected inclination flip (at label \parf{8} in \filef{s.3}) is continued
similarly
\begin{center}
\commandf{r11=run(r3('UZ2'),c='kpr.11',sv='11')}
\end{center}
giving among its output another codim 3 saddle-node inclination-flip point
\begin{verbatim} 
 BR  PT  TY LAB    PAR(1)     ...   PAR(2)        PAR(3)        PAR(29)    ...  
  1  27  UZ  11   1.53542E-01 ... -2.45810E+00   1.17171E+00  -1.13312E-06 ...
\end{verbatim}
Output beyond both of these codim 3 points is spurious and both computations end in
an \parf{MX} point (no convergence).

To continue the non-central saddle-node homoclinic orbits it is
necessary to work on the data without the solution $\phi(t)$. We
restart from the data saved at \parf{LAB=8} and \parf{LAB=11} in
\filef{s.7} and \filef{s.8} respectively. We could continue these codim 2 points in two
ways, either by appending the defining condition $\psi_{16} =0$ to
the continuation of saddle-node homoclinic orbits (with \parf{IEQUIB=2},
etc.), or by appending $\psi_{9} =0$ to the continuation 
of a saddle homoclinic orbit (with \parf{IEQUIB=1}). 
The first approach is used in the example \filef{mtn},  
for contrast we shall adopt the second approach here.
%------------------------------------------------------
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/kpr10}}
\caption{Projection onto the \parf{(PAR(3),PAR(2))}-plane of the non-central
saddle-node homoclinic orbit curves (labeled \parf{1} and \parf{2}) and the 
inclination-flip curves (labeled \parf{3} and \parf{4})}.
\label{kp.10}
\end{figure}
%------------------------------------------------------
%
\begin{center}
\commandf{r12=run(r7('UZ1'),c='kpr.12',sv='12')}\\
\commandf{r12=r12+run(r8('UZ1'),c='kpr.13',ap='12')}
\end{center}
The projection onto the $(\eps,k)$-plane of all four of these
codimension-two curves is given in Figure \ref{kp.10}. 
The intersection of the inclination-flip lines with one of the
non-central saddle-node homoclinic lines is apparent. Note that the two
non-central saddle-node homoclinic orbit curves are almost overlaid, but
that as in Figure \ref{kf.7} the orbits look quite distinct in phase space.

\section{ Detailed \AUTO-Commands.}
\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir kpr} & create an empty work directory \\ 
  \commandf{cd kpr} & change directory \\
  \commandf{demo('kpr')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run('kpr',c='kpr.1',sv='1')} &  continuation in the time-length parameter \parf{PAR(11)} \\ 
  & save output-files as \filef{b.1, s.1, d.1} \\ 
\hline
%==============================================================================
  \commandf{r2=run(r1('UZ1'),c='kpr.2',sv='2')} & locate the homoclinic orbit \\ 
  & save output-files as \filef{b.2, s.2, d.2} \\ 
\hline
%=============================================================================
  \commandf{r3=run(r2('UZ1'),c='kpr.3',sv='3')} & generate adjoint variables\\ 
  & save output-files as \filef{b.3, s.3, d.3} \\ 
\hline
%==============================================================================
  \commandf{r3=r3+run(r3,c='kpr.4',ap='3')} & continue the homoclinic orbit \\ 
  & append output-files to \filef{b.3, s.3, d.3} \\ 
\hline
%=============================================================================
  \commandf{r3=r3+run(r3()[0],c='kpr.5',ap='3')} & continue in reverse direction\\
  & append output-files to \filef{b.3, s.3, d.3} \\ 
\hline
%==============================================================================
  \commandf{r6=run(r2('EP1'),c='kpr.6',sv='6')} & increase the period \\ 
  & save output-files as \filef{b.6, s.6, d.6} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Detailed \AUTO-Commands for running demo \filef{kpr}.}
\label{tbl:demo_kpr_1}
\end{center}
\end{table}


\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{r7=run(r6('UZ1'),c='kpr.7',sv='7')} & recompute the family
  of homoclinic orbits \\ 
  \commandf{sv('7')} & save output-files as \filef{b.7, s.7, d.7} \\ 
\hline
%==============================================================================
  \commandf{r8=run(r7('UZ1'),c='kpr.8',sv='8')} & continue central
  saddle-node homoclinics \\ 
  & save output-files as \filef{b.8, s.8, d.8} \\ 
\hline
%==============================================================================
  \commandf{r9=run(r8('UZ1'),c='kpr.9',sv='9')} & continue homoclinics
  from codim-2 point \\ 
  & save output-files as \filef{b.9, s.9, d.9} \\ 
\hline
%==============================================================================
  \commandf{r10=run(r3('UZ1'),c='kpr.10',} & 3-parameter curve of inclination-flips\\ 
  \commandf{  sv='10')} & save output-files as \filef{b.10, s.10, d.10} \\ 
\hline
%==============================================================================
  \commandf{r11=run(r3('UZ2'),c='kpr.11',} & another curve of inclination-flips \\ 
  \commandf{  sv='11')} & save output-files as \filef{b.11, s.11, d.11} \\ 
\hline
%==============================================================================
  \commandf{r12=run(r7('UZ1'),c='kpr.12',} & continue non-central saddle-node homoclinics\\ 
  \commandf{  sv='12')} & save output-files as \filef{b.12, s.12, d.12} \\ 
\hline
%==============================================================================
  \commandf{r12=r12+run(r8('UZ1'),c='kpr.13',} & continue non-central saddle-node homoclinics\\ 
  \commandf{  ap='12')} & append output-files to \filef{b.12, s.12, d.12} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Detailed \AUTO-Commands for running demo \filef{kpr}.}
\label{tbl:demo_kpr_2}
\end{center}
\end{table}


%==============================================================================
%==============================================================================
\chapter{ {\cal HomCont} Demo : cir.} \label{ch:HomCont_cir}
%==============================================================================
%==============================================================================

%==============================================================================
%DEMO=cir======================================================================
%==============================================================================
\section{ Electronic Circuit of Freire \textit{et al}.}
Consider the following model of a three-variable electronic circuit
\cite{FrRLuGaPo:93}
 \begin{equation}
\left \{ 
\begin{array}{rcl}
\dot{x} & = & \left [-(\beta+\nu) x + \beta y -a_3 x^3 
+b_3(y-x)^3\right ]/r, \\
\dot{y} & = & \beta x -(\beta+\gamma)y -z -b_3(y-x)^3, \\
\dot{z} & = & y.
\end{array}
\right.  
\label{5.fr1}
\end{equation}
These autonomous equations are also considered in the \AUTO demo \filef{tor}.

First, we copy the demo into a new directory and compile
\begin{center}
\commandf{dm('cir')} \\
\end{center}
The system is contained in 
the equation-file \filef{cir.f90} and the initial run-time constants
are stored in \filef{c.cir.1}. We begin by starting from
the data from \filef{cir.dat} for a saddle-focus homoclinic orbit 
at 
$\nu=-0.721309$, $\beta=0.6$, $\gamma=0$, $r=0.6$, $A_3=0.328578$ 
and $B_3=0.933578$, which was obtained by shooting over 
the time interval $2T=$\parf{PAR(11)}$=36.13$.
We wish to follow the family in the $(\beta,\nu)$-plane, but 
first we perform continuation in $(T,\nu)$ to obtain a better 
approximation to a homoclinic orbit.
\begin{center}
\commandf{r1=run('cir',c='cir.1')}
\end{center} 
yields the output
\begin{verbatim}
 BR  PT  TY LAB     PERIOD       L2-NORM    ...   PAR(1)     
  1  21  UZ   2  1.000000E+02  1.286637E-01 ... -7.213093E-01
  1  42  UZ   3  2.000000E+02  9.097899E-02 ... -7.213093E-01
  1  50  EP   4  2.400000E+02  8.305208E-02 ... -7.213093E-01
\end{verbatim}
Note that $\nu=$\parf{PAR(1)} remains constant during the continuation
as the parameter values do not change, only the length of
the interval over which the approximate homoclinic solution is computed.
Note from the eigenvalues, stored in \filef{d.1} that this is a homoclinic
orbit to a saddle-focus with a one-dimensional unstable manifold.

We now restart at \parf{LAB=3}, corresponding to a time interval $2T=200$,
and change the principal continuation parameters to be $(\nu,\beta)$.
The new constants defining the continuation are given in \filef{c.cir.2}.
We also activate the test functions pertinent to codimension-two
singularities which may be encountered along a family of saddle-focus
homoclinic orbits, viz.\ $\psi_2$, $\psi_4$, $\psi_5$, $\psi_9$ and $\psi_{10}$.
This must be specified in three ways: by appropriate
\parf{IPSI} in \filef{c.cir.2}, by adding the corresponding parameter labels
to the list of continuation parameters \parf{ICP(I)} in \filef{c.cir.2}
(recall that these parameter indices are 20 more than the corresponding
$\psi$ indices), and finally adding UZR functions defining zeros of
these parameters in \filef{c.cir.2}. Running 
\begin{center}  
\commandf{r2=run(r1('UZ2'),c='cir.2',sv='2')}
\end{center} 
results in
\begin{verbatim}
BR  PT  TY LAB    PAR(1)     ...    PAR(2)     ...    PAR(25)       PAR(29)    
1   17  UZ   5 -7.256925E-01 ...  4.535645E-01 ... -1.765251E-05 -2.888436E-01
1   75  UZ   6 -1.014704E+00 ...  9.998966E-03 ...  1.664509E+00 -5.035997E-03
1   78  UZ   7 -1.026445E+00 ... -2.330391E-05 ...  1.710804E+00  1.165176E-05
1   81  UZ   8 -1.038012E+00 ... -1.000144E-02 ...  1.756690E+00  4.964621E-03  
1  100  EP   9 -1.164160E+00 ... -1.087732E-01 ...  2.230329E+00  5.042736E-02
\end{verbatim}
with results saved in \filef{b.2, s.2, d.2}.
%------------------------------------------------------
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/cir1}}
\caption{Solutions of the boundary value problem at labels 6 and 8, 
either side of the Shil'nikov-Hopf bifurcation}
\label{Fcircuit1}
\end{figure}
%------------------------------------------------------
%------------------------------------------------------
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/cir2}}
\caption{Phase portraits of three homoclinic orbits 
on the family, showing the saddle-focus to saddle transition}
\label{Fcircuit2}
\end{figure}
%------------------------------------------------------
Upon inspection of the output, note that label 5, where \parf{PAR(25)}$\approx 0$, 
corresponds to a neutrally-divergent saddle-focus, $\psi_5=0$. 
Label 7, where \parf{PAR(29)}$\approx 0$ corresponds to a local bifurcation, $\psi_9=0$, 
which we note from the eigenvalues stored in \filef{d.2} corresponds to a \emp{
Shil'nikov-Hopf} bifurcation. Note that \parf{PAR(2)} is also approximately zero
at label 7, which accords with the analytical observation that the origin of
(\ref{5.fr1}) undergoes a Hopf bifurcation when $\beta=0$.
Labels 6 and 8 are the user-defined output
points, the solutions at which are plotted in Fig.\ \ref{Fcircuit1}.
Note that solutions beyond label 7 (e.g., the plotted solution
at label 8) do not correspond to homoclinic orbits, but to 
\emp{ point-to-cycle} heteroclinic orbits (c.f.\ Section~2.2.1 of
\citeasnoun{ChKuSa:95}).

We now continue in the other direction along the family. It turns out
that starting from the initial point in the other direction results in
missing a codim 2 point which is close to the starting point. Instead we
start from the first saved point from the previous computation
(label 5 in \filef{s.2}):
\begin{center}
\commandf{r3=run(r2('UZ1'),c='cir.3',ap='2')}
\end{center}
The output
\begin{verbatim}
 BR  PT  TY LAB    PAR(1)     ...    PAR(2)        PAR(22)       PAR(24)    
  1   9  UZ  10 -7.204001E-01 ...  5.912315E-01 -1.725669E+00 -3.295862E-05
  1  18  UZ  11 -7.590583E-01 ...  7.428734E-01  3.432139E-05 -2.822988E-01
  1  26  UZ  12 -7.746686E-01 ...  7.746147E-01  5.833163E-01  1.637611E-07
  1  28  EP  13 -7.746628E-01 ...  7.746453E-01  5.908902E-01  1.426214E-04
\end{verbatim}
contains a neutral saddle-focus (a \emp{ Belyakov} transition) 
at \parf{LAB=10} ($\psi_4=0$), a double real leading eigenvalue 
(saddle-focus to saddle transition) at \parf{LAB =11} ($\psi_2=0$) 
and a neutral saddle at \parf{LAB=12} ($\psi_4=0$). Data at several
points on the complete family are plotted in Fig.\ \ref{Fcircuit2}.
If we had continued further (by increasing \parf{NMX}), 
the computation would end at a no convergence error \parf{TY=MX} owing 
to the homoclinic family approaching a Bogdanov-Takens singularity 
at small amplitude. To compute further towards the BT point 
we would first need to continue to a higher value of \parf{PAR(11)}.

\section{ Detailed \AUTO-Commands.}
\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir cir} & create an empty work directory \\ 
  \commandf{cd cir} & change directory \\
  \commandf{demo('cir')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run(c='cir.1',sv='1')} &  increase the truncation interval; restart from \filef{cir.dat}\\ 
  & save output-files as \filef{b.1, s.1, d.1} \\ 
\hline
%==============================================================================
  \commandf{r2=run(r1('UZ2'),c='cir.2',sv='2')} &  continue saddle-focus
  homoclinic orbit; restart from \parf{r1} \\ 
  & save output-files as \filef{b.2, s.2, d.2} \\ 
\hline
%=============================================================================
  \commandf{r3=run(r2('UZ1'),c='cir.3',ap='2')} & generate adjoint variables  ; restart from \parf{r2} \\ 
  & append output-files as \filef{b.2, s.2, d.2} \\ 
\hline
%==============================================================================
\end{tabular}
\caption{Detailed \AUTO-Commands for running demo \filef{cir}.}
\label{tbl:demo_cir_1}
\end{center}
\end{table}



%==============================================================================
%==============================================================================
\chapter{ {\cal HomCont} Demo : she.} \label{ch:HomCont_she}
%==============================================================================
%==============================================================================

%==============================================================================
%DEMO=she======================================================================
%==============================================================================
\section{ A Heteroclinic Example.}
The following system of five equations \citeasnoun{RuMa:95}
\begin{equation} \label{sh1} \begin{array}{rcl}
\dot{x} & = & \mu \, x + x\, y - z\, u, \\
\dot{y} & = & -y - x^2, \\
\dot{z} & = & \mu\, z + x\, u - 9\sigma\, z / 4(1+\sigma)  \\
\dot{u} & = & - \sigma u / 4 - \sigma Q v / 4\pi^2
+ 3(1 + \sigma) x z / 4\sigma \\
\dot{v} & = & \zeta u / 4  - \zeta v / 4
\end{array} 
\end{equation}
has been used to describe shearing instabilities in fluid convection.
The equations possess a rich structure of local and global bifurcations.
Here we shall reproduce a single curve in the $(\sigma,\mu)$-plane
of codimension-one heteroclinic orbits connecting a non-trivial 
equilibrium to the origin for $Q=0$ and $\zeta=4$. The defining
problem is contained in equation-file 
\filef{she.f90}\footnote{The last parameter used to store the equilibria (\parf{PAR(21)}) is
overlaped here with the first test-function. In this example, it is harmless since the test functions are 
irrelevant for heteroclinic continuation.}, and starting data for the orbit at 
$(\sigma,\mu)=(0.5,0.163875)$ are stored in \filef{she.dat},
with a truncation interval of \parf{PAR(11)=85.07}.

We begin by computing towards $\mu=0$ with the option \parf{IEQUIB=-2}
which means that both equilibria are solved for as part of
the continuation process.
\begin{center}
\commandf{demo('she')} \\
\commandf{r1=run('she',c='she.1',sv='1')}
\end{center} 
This yields the output
\begin{verbatim}
  BR    PT  TY  LAB    PAR(3)        L2-NORM    ...   PAR(1)     
   1     1  EP    1   5.00000E-01   4.05950E-01 ...  1.63875E-01
   1     5        2   4.52847E-01   3.72688E-01 ...  1.36505E-01
   1    10        3   3.94351E-01   3.30390E-01 ...  1.04419E-01
   1    15        4   3.35908E-01   2.87331E-01 ...  7.51623E-02
   1    20        5   2.77287E-01   2.43351E-01 ...  4.95320E-02
   1    25        6   2.18210E-01   1.98147E-01 ...  2.84629E-02
   1    30  EP    7   1.58178E-01   1.51246E-01 ...  1.29327E-02
\end{verbatim}
Alternatively, for this problem there exists an analytic expression for
the two equilibria. This is specified in the subroutine \funcf{PVLS} of
\filef{she.f90}. Re-running with \parf{IEQUIB=-1}
\begin{center}
\commandf{r2=run('she',c='she.2')}
\end{center}
we obtain the output
\begin{verbatim}
   1     1  EP    1   5.00000E-01   4.05950E-01 ...  1.63875E-01
   1     5        2   4.43202E-01   3.65772E-01 ...  1.31056E-01
   1    10        3   3.72309E-01   3.14244E-01 ...  9.30098E-02
   1    15        4   3.00884E-01   2.61156E-01 ...  5.93397E-02
   1    20        5   2.28665E-01   2.06219E-01 ...  3.17994E-02
   1    25        6   1.55541E-01   1.49165E-01 ...  1.23990E-02
   1    30  EP    7   8.10746E-02   9.14311E-02 ...  2.38662E-03
\end{verbatim}
This output is similar to that above, but note that it is obtained slightly
more efficiently because the extra parameters \parf{PAR(12-21)} representing the
coordinates of the equilibria are no longer
part of the continuation problem. Also note that \AUTO has chosen to take
slightly larger steps along the family. Finally, we can continue in the opposite
direction along the family from the original starting point (again with \parf{IEQUIB=-1}).
\begin{center}
\commandf{r3=run(r2(2),c='she.3')}\\
\commandf{save(r2+r3,'2')}
\end{center}
%
%------------------------------------------------------
\begin{figure}[b]
\epsfysize 9.0cm
\centerline{\epsffile{include/she1}}
\caption{Projections into $(x,y,z)$-space of the family of heteroclinic
orbits.}
\label{Fshear}
\end{figure}
%------------------------------------------------------
%
\begin{verbatim}
  BR    PT  TY  LAB    PAR(3)        L2-NORM    ...   PAR(1)     
   1     5        8   4.99759E-01   4.06015E-01 ...  1.63732E-01
   1    10        9   5.70530E-01   4.55187E-01 ...  2.06526E-01
   1    15       10   6.41644E-01   5.03184E-01 ...  2.50783E-01
   1    20       11   7.13330E-01   5.50067E-01 ...  2.95934E-01
   1    25       12   7.85769E-01   5.95871E-01 ...  3.41549E-01
   1    30       13   8.59097E-01   6.40618E-01 ...  3.87300E-01
   1    35  EP   14   9.33416E-01   6.84317E-01 ...  4.32927E-01
\end{verbatim}
The results of both computations are presented in Figure \ref{Fshear}, 
from which we see that the orbit shrinks to zero as
\parf{PAR(1)=}$\mu \to 0$.

\section{ Detailed \AUTO-Commands.}
\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir she} & create an empty work directory \\ 
  \commandf{cd she} & change directory \\
  \commandf{demo('she')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  \commandf{r1=run('she',c='she.1',sv='1')} &  continue heteroclinic orbit; start from \filef{she.dat}\\ 
  & save output-files as \filef{b.1, s.1, d.1} \\ 
\hline
%==============================================================================
  \commandf{r2=run('she',c='she.2')} &  repeat with \parf{IEQUIB=-1} \\ 
\hline
%=============================================================================
  \commandf{r3=run(r2(2),c='she.3')} & continue in reverse direction ;\\
  & restart from label 2 of \parf{r2} \\ 
  \commandf{save(r2+r3,'2')} & Save appended results to \filef{b.2, s.2, d.2}\\ 
\hline
%=============================================================================
\end{tabular}
\caption{Detailed \AUTO-Commands for running demo \filef{she}.}
\label{tbl:demo_she_1}
\end{center}
\end{table}





%==============================================================================
%==============================================================================
\chapter{ {\cal HomCont} Demo : rev.} \label{ch:HomCont_rev}
%==============================================================================
%==============================================================================

%==============================================================================
%DEMO=rev======================================================================
%==============================================================================
\section{ A Reversible System.}
The fourth-order differential equation
$$
u'''' + P u'' + u -u^3 =0
$$
arises in a number of contexts, e.g., as the travelling-wave
equation for a nonlinear-Schr\"{o}dinger equation with fourth-order
dissipation \cite{BuAk:95} and as a model of a strut on a symmetric 
nonlinear elastic foundation \cite{HuBoTh:89}. It may be expressed as
a system
\begin{equation}
\left \{ 
\begin{array}{rcl}
\dot{u_1} & = & u_2 \\
\dot{u_2} & = & u_3 \\
\dot{u_3} & = & u_4 \\
\dot{u_4} & = & -P u_3 - u_1 + u_1^3
\end{array}
\right.  
\label{6.1}
\end{equation}
Note that (\ref{6.1}) is invariant under two separate reversibilities
\begin{equation}
R_1: (u_1,u_2,u_3,u_4,t) \mapsto (u_1,-u_2,u_3,-u_4,-t)  
\label{6.R1}
\end{equation}
and 
\begin{equation}
R_2: (u_1,u_2,u_3,u_4,t) \mapsto (-u_1,u_2,-u_3,u_4,-t)  
\label{6.R2}
\end{equation}
First, we copy the demo into a new directory 
\begin{center}
\commandf{demo('rev')}
\end{center}
For this example, we shall make two separate starts
from data stored in equation and data files \filef{rev.c.1,
rev.dat.1} and \filef{rev.c.3, rev.dat.3} respectively. The first
of these contains initial data for a solution that is reversible
under $R_1$ and the second for data that is reversible under $R_2$. 
%
%Note that \commandf{make} or \commandf{make all} will only run the
%first of these. To make the output starting from the
%$R_2$-reversible solution we need to \commandf{make run2}. As before,
%though we illustrate here the step by step approach.


\section{An \texorpdfstring{$R_1$}{R1}-Reversible Homoclinic Solution.}

The first run
\begin{center}
\commandf{r1=run('rev',c='rev.1',sv='1')}
\end{center}
starts by using the file \filef{rev.dat.1} via the
\parf{'dat'} \AUTO-constant in \filef{c.rev.1}.
The orbit contained in
the data file is a ``primary'' homoclinic solution for $P=1.6$, with
truncation (half-)interval \parf{PAR(11) = 39.0448429}.
which is reversible under $R_1$. Note that this reversibility is
specified in \filef{c.rev.1} via \parf{IREV=[0,1,0,1]}. Note also, from
\filef{c.rev.1} that we only have one free parameter \parf{PAR(1)}
because symmetric homoclinic orbits in reversible systems are
generic rather than of codimension one.
The first run  results in the output
\begin{verbatim}
  BR    PT  TY  LAB    PAR(1)        L2-NORM       MAX U(1)   ...
   1     1  EP    1   1.60000E+00   2.85704E-01   3.62232E-01
   1     8  UZ    2   1.70000E+00   2.90288E-01   4.18225E-01
   1    11  UZ    3   1.80000E+00   2.95723E-01   4.80604E-01
   1    14  UZ    4   1.90000E+00   2.74864E-01   4.43069E-01
   1    20  EP    5   1.99678E+00   1.13379E-01   9.59430E-02
\end{verbatim}
which is consistent with the theoretical result that the solution
tends uniformly to zero as $P\to 0$. Note, by plotting the data
saved in \filef{s.1} that only ``half'' of the 
homoclinic orbit is computed up to its point of symmetry. See Figure
\ref{Frev1}.

%------------------------------------------------------
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/rev1}}
\caption{$R_1$-Reversible homoclinic solutions on the half-interval
$x/T \in [0,1]$ where $T=39.0448429$ for $P$ approaching $2$ (solutions
with labels \parf{1-5} respectively have decreasing amplitude)}
\label{Frev1}
\end{figure}
%------------------------------------------------------
%------------------------------------------------------
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/rev2}}
\caption{$R_1$-reversible homoclinic orbits with oscillatory decay 
as $x \to -\infty$ (corresponding to label \parf{6}) and monotone decay 
(at label \parf{10})}
\label{Frev2}
\end{figure}
%------------------------------------------------------

The second run continues in the other direction of \parf{PAR(1)}, with
the test function $\psi_2$ activated 
for the detection of saddle to saddle-focus transition points
\begin{center}
\commandf{r1=r1+run(r1('UZ1'),c='rev.2',ap='1')}
\end{center}
The output
\begin{verbatim}
 BR  PT  TY  LAB    PAR(1)        L2-NORM       MAX U(1)   ...   PAR(22)    
  1  11  UZ    6   1.00001E+00   2.81700E-01   1.76625E-01 ... -3.00001E+00
  1  22  UZ    7  -1.00743E-07   2.89421E-01   4.69706E-02 ... -2.00000E+00
  1  33  UZ    8  -1.00000E+00   3.02208E-01   4.32654E-03 ... -1.00000E+00
  1  44  UZ    9  -2.00000E+00   3.16798E-01   1.22616E-11 ...  2.66362E-08
  1  55  EP   10  -3.09920E+00   3.32927E-01  -4.00188E-10 ...  1.09920E+00
\end{verbatim}
shows a saddle to saddle-focus transition 
(indicated by a zero of \parf{PAR(22)}) at \parf{PAR(1)=-2}. Beyond
that label the first component of the solution is negative and (up to the
point of symmetry) monotone decreasing. See Figure \ref{Frev2}.

\section{An \texorpdfstring{$R_2$}{R2}-Reversible Homoclinic Solution.}

\begin{center}
\commandf{r3=run('rev',c='rev.3',sv='3')}
\end{center}
starts by using the file \filef{rev.dat.3} via the
\parf{'dat'} \AUTO-constant in \filef{c.rev.3},
and runs them with the constants stored in \filef{c.rev.3}. 
The orbit contained in
the data file is a ``multi-pulse'' homoclinic solution for $P=1.6$, with
truncation (half-)interval \parf{PAR(11) = 47.4464189}.
which is reversible under $R_2$. This reversibility is
specified in \filef{c.rev.1} via \parf{IREV=[1,0,1,0]}.
The output 
\begin{verbatim}
  BR    PT  TY  LAB    PAR(1)        L2-NORM       MAX U(1)   ...
   1     1  EP    1   1.60000E+00   3.69766E-01   3.83942E-01
   1     7  UZ    2   1.70000E+00   3.83640E-01   4.89066E-01
   1     9  LP    3   1.71157E+00   3.92475E-01   5.46080E-01
   1    11  UZ    4   1.69884E+00   4.04207E-01   6.10428E-01
   1    14  UZ    5   1.60000E+00   4.32940E-01   7.77395E-01
   1    26  UZ    6   1.00000E+00   4.80849E-01   1.08252E+00
   1    49  UZ    7  -5.38706E-08   5.15846E-01   1.25863E+00
   1   128  MX    8  -9.15462E-01   5.44202E-01   1.32395E+00
\end{verbatim}
contains the label of a limit point (\parf{ILP} was set to \parf{1} in
\filef{c.rev.3}), which corresponds to a ``coalescence'' of two reversible
homoclinic orbits. The two solutions on either side of this limit point are
displayed in Figure \ref{Frev3}. The computation ends in a no-convergence
point. The solution here is depicted in Figure \ref{Frev4}. The lack of
convergence is due to the large peak and trough of the solution rapidly
moving to the left as $P \to -2$ (cf. \citeasnoun{ChSp:93}).

%------------------------------------------------------
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/rev3}}
\caption{Two $R_2$-reversible homoclinic orbits at $P=1.6$ 
corresponding to labels \parf{1} (smaller amplitude) and \parf{5} (larger amplitude)}
\label{Frev3}
\end{figure}
%------------------------------------------------------
%------------------------------------------------------
\begin{figure}[p]
\epsfysize 9.0cm
\centerline{\epsffile{include/rev4}}
\caption{An $R_2$-reversible homoclinic orbit at label \parf{8}}
\label{Frev4}
\end{figure}
%------------------------------------------------------

Continuing from the initial solution in the other parameter direction
\begin{center}
\commandf{r3=r3+run(r3('UZ1'),c='rev.4',ap='3')}
\end{center}
we obtain the output
\begin{verbatim}
  BR    PT  TY  LAB    PAR(1)        L2-NORM       MAX U(1)   ...
   1     7  UZ    9   1.60000E+00   3.70171E-01   3.84045E-01
   1    33  UZ   10   9.99998E-01   3.61440E-01   1.77504E-01
   1    94  UZ   11  -5.14775E-08   3.71301E-01   4.69706E-02
   1   153  MX   12  -2.54464E-01   3.75071E-01   3.00627E-02
\end{verbatim}
which again ends at a no convergence error for similar reasons.

\section{ Detailed \AUTO-Commands.}
\begin{table}[htbp]
\begin{center}
\begin{tabular}{| l | l |}
\hline
  \AUTO-COMMAND  & ACTION \\
\hline
%==============================================================================
  \commandf{mkdir rev} & create an empty work directory \\ 
  \commandf{cd rev} & change directory \\
  \commandf{demo('rev')} & copy the demo files to the work directory \\
\hline
%==============================================================================
  & use the starting data in \filef{rev.dat.1} \\ 
  \commandf{r1=run('rev',c='rev.1',sv='1')} &  increase \parf{PAR(1)} \\ 
  & save output-files as \filef{b.1, s.1, d.1} \\ 
\hline
%==============================================================================
  \commandf{r1=r1+run(r1('UZ1'),c='rev.2',ap='1')} &  continue in
  reverse direction; restart: 1st \parf{UZ} \\ 
  & append output-files to \filef{b.1, s.1, d.1} \\ 
\hline
%=============================================================================
  & use the starting data in \filef{rev.dat.3} \\ 
  \commandf{r3=run('rev',c='rev.3',sv='3')} & restart with different reversibility \\ 
  & save output-files as \filef{b.3, s.3, d.3} \\ 
\hline
%==============================================================================
  \commandf{r3=r3+run(r3('UZ1'),c='rev.4',ap='3')} & continue in
  reverse direction; restart: 1st \parf{UZ} \\ 
  & append output-files to \filef{b.3, s.3, d.3} \\ 
\hline
%=============================================================================
\end{tabular}
\caption{Detailed \AUTO-Commands for running demo \filef{rev}.}
\label{tbl:demo_rev_1}
\end{center}
\end{table}

%==============================================================================
%==============================================================================
\chapter{ {\cal HomCont} Demo : Homoclinic branch switching.} \label{ch:HomCont_hbs}
%==============================================================================
%==============================================================================

%==============================================================================
%DEMO=hbs======================================================================
%==============================================================================

This demo illustrates homoclinic branch switching, which is an
implementation of Lin's method \cite{Li:90,Sa:93,Ye:01}
as described in \citeasnoun{OlChKr:03}. We use a
direct branch switching method to switch from 1- to 2- and
3-homoclinic orbits near an inclination flip bifurcation 
in a model due to Sandstede, 
which was introduced in Chapter~\ref{ch:HomCont_san}.
This also shows how to obtain a homoclinic orbit through continuation
of a periodic orbit born at a Hopf bifurcation.
Thereafter, we illustrate homoclinic branch switching for the
FitzHugh-Nagumo equations and a 5th-order Korteweg-De Vries model.

The equation files in these demos are written in C.

\section{ Branch switching at an inclination flip in Sand\-stede's
  model.}
\label{sec:HomCont_hbs_san}
Consider the system \cite{Sa:95b}
\begin{equation} \begin{array}{rcl}
\dot{x} & = & a x + b y - a x^2 - \alpha z x (2-3x), \\
\dot{y} & = & b x + a y - \frac{3}{2} x (b x + a y) + \alpha z 2 y, \\
\dot{z} & = & c z + \mu x + 3 x z + \alpha (x^2 (1-x) - y^2).
\end{array} \end{equation}
as given in the file \filef{sib.c}, where for simplicity we have
set $\tilde\mu=0$, $\beta=1$ and $\gamma=3$.

We study an inclination flip that exists for $a=0.375$,
$b=0.625$ and $c=-0.75$. This corresponds to the situation
where the eigenvalues of the equilibrium at the origin are
$a+b=1$, $a-b=-0.25$ and $c=-0.75$. Hence, the corresponding
bifurcation diagram consists of a complicated structure involving a
fan of infinitely many $n$-periodic and $n$-homoclinic orbits
for arbitrary $n$ and a region with horseshoe dynamics; see
also \citeasnoun{HoKr:00} and the references therein.

This computation starts from an equilibrium at $(2/3,0,0)$, which
exists for $a=\mu=\alpha=0$. Also, $b$ is set to $0.625$ (the value
we would like it to be) and $c$ is set to $-2.5$ in \funcf{stpnt}.
Choosing $c=-2$ at this stage leads to convergence problems.
This equilibrium is not the one corresponding to the homoclinic orbit,
but it is an equilibrium with complex eigenvalues, that we can follow
until it reaches a Hopf bifurcation. A periodic orbit emanates from 
this Hopf bifurcation and can be followed to the homoclinic orbit.
However, first we need to change $a$ from $0$ to $0.375$.

All the following commands, except for \commandf{demo('sib')}
are contained within the file \commandf{'sib.auto'} which you can 
either execute in a batch mode by entering\\
\commandf{> auto sib.auto}\\
or step by step using\\
\commandf{AUTO> demofile('sib.auto')}.

We start by copying the demo to the current work directory 
and running the first step
\begin{center}
\commandf{demo('sib') }\\
\commandf{r1=run(e='sib',c='sib') } \\
\commandf{save(r1,'1') }
\end{center}
The equilibrium is followed in $a$ until $a$ (or \parf{PAR(1)}) is at our
desired value, $0.375$.
\begin{verbatim}
  BR    PT  TY  LAB    PAR(1)     ...    U(1)          U(2)          U(3)     
   1     1  EP    1   0.00000E+00 ... 6.66667E-01   0.00000E+00   0.00000E+00
   1     5  UZ    2   3.75000E-01 ... 6.66667E-01  -1.33333E-01   0.00000E+00
\end{verbatim}
The output is saved in the files \filef{b.1}, \filef{s.1} and
\filef{d.1}.
Next we continue in $\alpha$ (\parf{PAR(4)}) until a Hopf bifurcation is
found:
\begin{center}
\commandf{r2=run(r1,ICP=[4]) }\\
\commandf{save(r2,'2') }
\end{center}
or, alternatively,
\begin{center}
\commandf{rn(c='sib.2',s='1')}\\
\commandf{sv('2') }
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB    PAR(4)     ...    U(1)          U(2)          U(3)     
   1     6  HB    3   3.18429E-01 ... 6.54375E-01  -1.34754E-01   7.70102E-02
\end{verbatim}
The output is saved in the files \filef{b.2}, \filef{s.2} and
\filef{d.2}.
This Hopf bifurcation can then be continued into a periodic orbit. The
periodic orbit eventually reaches a homoclinic bifurcation. We
continue in $\mu$=\parf{PAR(5)} and \parf{PAR(11)}, 
which corresponds to the period, and stop when the period is equal to $35$.
\begin{center}
\commandf{r3=run(r2('HB1'),IPS=2,ICP=[5,11],NMX=200,DS=0.01,DSMAX=0.01,UZR=\{-11:35\})} \\
\commandf{save(r3,'3')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB    PAR(5)        L2-NORM    ...    PERIOD    
   3    10        5  -2.41881E-03   6.70569E-01 ...  1.08975E+01
                                                ...
   3    40        8  -1.29495E-02   6.14547E-01 ...  1.41297E+01
                                                ...
   3    81  UZ   13  -1.04657E-04   4.01829E-01 ...  3.50000E+01
\end{verbatim}
The output is saved in the files \filef{b.3}, \filef{s.3} and
\filef{d.3}. Note that $\mu$ first decreases and then increases towards
$0$, which is precisely what we expect in this model, as homoclinic
orbits occur on the line $\mu=0$ in the $(\alpha,\mu)$-plane.
It is now instructive to look at a phase space diagram to see what is
going on.
\begin{center}
\commandf{plot(r3) }
\end{center}
Selecting 'solution' for Type, [5,6,7,8,9,10,11,12,13] for Label,
[U(1)] for X and [U(2)] for Y, we obtain the diagram depicted in 
Figure~\ref{hopfbif}(a), where the periodic orbit grows from the
Hopf equilibrium to a homoclinic orbit.
\begin{figure}[htb]
\begin{center}
\begin{picture}(400,180)
\put(0,0){
\put(157,148){(a)}
\includegraphics[scale=0.5]{include/hopfbif}}
\put(200,0){
\put(157,148){(b)}
\includegraphics[scale=0.5]{include/notshifted}}
\end{picture}
\caption{Periodic orbit growing from a Hopf bifurcation to a
  homoclinic orbit (a). The unshifted homoclinic orbit (b).}
\label{hopfbif}
\end{center}
\end{figure}

Note however, that the homoclinic orbit has the wrong left-hand and
right-hand end points. This can be seen by plotting the solution
corresponding to Label [13] using 't' vs. 'x' (coordinate [U(1)]), 
as depicted in Figure~\ref{hopfbif}(b).

Hence, in order to continue this as a real homoclinic 
we have to give {\cal HomCont} special instructions, to do a phase-shift in
time. This can be done by setting \parf{ISTART=4}. Moreover, 
since we have not specified the value of
the equilibrium at the origin in \filef{sib.c}, 
we need to set \parf{IEQUIB=1} (this is the default value) to let
{\cal HomCont} detect the equilibrium. Note that in this case this is not
strictly necessary; however, we do this for instructional purposes.

Now we use {\cal HomCont} to continue the homoclinic orbit in $c$ and $\mu$ 
(\parf{PAR(3)}, \parf{PAR(5)}), to get the desired value $c=-2.0$.
\begin{center}
\commandf{r4=run(r3,IPS=9,ICP=[3,5],NPR=60,JAC=1,UZR=\{-3:-2.0\},ISTART=4) } \\
\commandf{save(r4,'4')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB    PAR(3)        L2-NORM      ...    PAR(5)     
   3    51  UZ   14  -2.00000E+00   4.01890E-01   ...  2.66146E-09
\end{verbatim}
The output is saved in the files \filef{b.4}, \filef{s.4} and
\filef{d.4}. Note that \parf{PAR(5)}=$\mu$ remains zero, which is exactly
what we expect.

Next we want to add a solution to the adjoint equation to this
solution. This is achieved by making the change \parf{ITWIST = 1}.
Also, we set \parf{ISTART} to 1 to tell 
{\cal HomCont} that it should not try to shift the orbit anymore.
\begin{center}
\commandf{r5=run(r4,ICP=[5,8],NMX=2,ITWIST=1,ISTART=1)} \\
\commandf{save(r5,'5') }
\end{center}
or, alternatively,
\begin{center}
\commandf{rn(c='sib.5',s='4')}\\
\commandf{sv('5')}\\
\end{center}
The output is stored in \filef{b.5}, \filef{s.5}  and \filef{d.5}.
\begin{verbatim}
  BR    PT  TY  LAB    PAR(5)        L2-NORM    ...    PAR(8)     
   3     2  EP   15   2.66146E-09   4.01890E-01 ...   1.00000E-02
\end{verbatim}
Here \parf{PAR(8)} is a dummy (unused) parameter and $\mu$ just stays where
it is. Now that we have obtained the solution of the adjoint equation,
we are able to detect inclination flips. This can be achieved by
setting \parf{IPSI} to [13] and monitoring \parf{PAR(33)}.
\begin{center}
\commandf{r6=run(r5,ICP=[4,5,33],NMX=30,DS=-0.01,DSMAX=1.0,UZR=\{33:0,-4:0\},IPSI=[13])}
\end{center} 
\begin{verbatim}
  BR    PT  TY  LAB    PAR(4)        L2-NORM    ...  PAR(5)        PAR(33)
   3    19  UZ   16   7.11774E-02   4.01890E-01 ... 1.24376E-11  -2.36702E-07
\end{verbatim}   
The output is stored in the \python variable \parf{r6}.
Hence an inclination flip was found at $\alpha=0.711774$.

Now we are ready to perform homoclinic branch switching, using
the techniques described in \cite{OlChKr:03}. 
Our first aim is to find a 2-homoclinic orbit. The
ingredients we need are: a homoclinic orbit where $n$-homoclinic orbits
are close by, and the solution to the adjoint equation to
obtain the Lin vector. Since both ingredients are there, we can now
continue in $\mu$, $\varepsilon_1$ and $T_1$, to obtain the initial
Lin gap. Recall from Chapter~\ref{ch:HomCont} that the Lin gaps 
$\varepsilon_i$ correspond to
\parf{PAR(20+i*2)} and the time intervals $T_i$ 
correspond to \parf{PAR(21+i*2)}. We stop when
$\varepsilon_1=0.2$. We need to specify \parf{ITWIST=2}, to tell 
{\cal HomCont} we
aim to find a 2-homoclinic orbit, so that it will split it up in three
parts with two potential Lin gaps. We effectively have a 9-dimensional
system at this point.
\begin{center}
\commandf{r7=run(r6('UZ1'),ICP=[21,22,5],NMX=300,NPR=10,UZR=\{-22:0.2\},ISTART=-2,IPSI=[])}\\
\commandf{save(r7,'7')}
\end{center} 
\begin{verbatim}
  BR    PT  TY  LAB    PAR(21)       L2-NORM    ...  PAR(22)       PAR(5)     
   3    10       18   3.45897E+01   4.46818E-01 ... 7.87712E-07  -1.55885E-11
   3    20       19   2.73699E+01   4.46818E-01 ... 2.91119E-05  -1.63974E-09
   3    30       20   1.73720E+01   4.46817E-01 ... 4.42273E-03  -3.10167E-05
   3    38  UZ   21   1.01451E+01   4.46796E-01 ... 2.00000E-01  -1.48615E-02
\end{verbatim}
The output is stored in \filef{b.7}, \filef{s.7}  and \filef{d.7}.
Here we see that $T_1$, the time it takes to make the first loop with
respect to the Poincar\'e section, decreases. This is illustrated in
Figure~\ref{broken}. Next we are ready to close this gap, by continuing
in $\alpha$, $\mu$, and $\varepsilon_1$, while keeping $T_1$ at a
constant value.
\begin{figure}[htb]
\begin{center}
\begin{picture}(400,180)
\put(0,0){
\put(157,148){(a)}
\includegraphics[scale=0.5]{include/loop}}
\put(200,0){
\put(157,148){(b)}
\includegraphics[scale=0.5]{include/broken}}
\end{picture}
\caption{Behaviour of the second piece of the
`broken homoclinic orbit' when creating a Lin gap (a).
Projection of the ``broken homoclinic orbit''
onto the $(x,y)$-plane, where $\varepsilon_1=0.2$. To include all the
pieces necessary to obtain this
figure, the ``X'' box must contain [U(1),U(4),U(7)]
and the ``Y'' box must contain [U(2),U(5),U(8)] (b).}
\label{broken}
\end{center}
\end{figure}
\begin{center}
\commandf{r8=run(r7,ICP=[4,5,22],NPR=310,DS=0.01,DSMAX=0.01,UZR=\{-22:0.0,4:0.074\})} \\
\commandf{r6=r6+r8}
\end{center} 
\begin{verbatim}
  BR    PT  TY  LAB    PAR(4)        L2-NORM    ...   PAR(5)        PAR(22)    
   3     3  UZ   22   7.40000E-02   4.46781E-01 ... -1.43162E-02   1.93746E-01
   3    32  UZ   23   1.98414E-01   4.46590E-01 ... -6.05495E-03   2.29300E-06
\end{verbatim}
The output is appended to the \python variable \parf{r6}.
Now we have obtained a 2-homoclinic orbit at label 23. However, the
homoclinic orbit is still split in three parts. We can switch back to
a normal orbit by setting \parf{ITWIST} back to 0 and continuing in the usual
way. Here we continue back to the inclination flip point in $\alpha$
and $\mu$.
\begin{center}
\commandf{r9=run(r8,ICP=[4,5],NMX=30,DS='-',DSMAX=0.1,UZR=\{4:0.15\},ISTART=1,ITWIST=0)} \\
\commandf{r6=r6+r9}
\end{center} 
\begin{verbatim}
  BR    PT  TY  LAB    PAR(4)        L2-NORM    ...   PAR(5)     
   3     7  UZ   24   1.50000E-01   4.94490E-01 ... -3.60248E-03
   3    30  EP   25   7.61403E-02   4.98746E-01 ... -2.64847E-06
\end{verbatim}
So the 2-homoclinic orbit converges back to the 1-homoclinic orbit at
the inclination flip bifurcation.
The output is appended to the python variable \parf{r6}.
The resulting 2-homoclinic orbits can be seen using
\begin{center}
\commandf{plot(r6) }
\end{center} 
and is depicted in Figure~\ref{hom2}(a).
\begin{figure}[htb]
\begin{center}
\begin{picture}(400,180)
\put(0,0){
\put(157,148){(a)}
\includegraphics[scale=0.5]{include/hom2}}
\put(200,0){
\put(157,148){(b)}
\includegraphics[scale=0.5]{include/hom3}}
\end{picture}
\caption{The 2-homoclinic orbit as $a$ is changed (a).
The two different 3-homoclinic orbits (b).}
\label{hom2}
\end{center}
\end{figure}

Next, we aim to find a 3-homoclinic orbit. To do so, we
restart at the inclination flip point at label 16 and set
\parf{ITWIST=3}. Moreover, we need to continue in one more
gap, $\varepsilon_2$=\parf{PAR(24)} and, once again, stop
when $\varepsilon_1$=\parf{PAR(22)=0}. Note that the 
dimension of the boundary value problem we continue
is now equal to 12. This is not to be confused with the setting
of the \AUTO constant \parf{NDIM=3}, because {\cal HomCont} handles this
internally.
\begin{center}
\commandf{r10=run(r6('UZ1'), ICP=[21,22,24,5], NMX=300, NPR=10, 
  UZR=\{-22:0.2\}, ISTART=-3, IPSI=[])} \\
\commandf{save(r10,'10') }
\end{center} 
\begin{verbatim}
  BR    PT  TY  LAB    PAR(21)    ...   PAR(22)       PAR(24)       PAR(5)     
   3    10       26   3.45896E+01 ...  7.87894E-07   6.42157E-07  -1.06346E-11
   3    20       27   2.73699E+01 ...  2.91126E-05   6.51591E-07  -1.63655E-09
   3    30       28   1.73719E+01 ...  4.42289E-03   1.44090E-04  -3.10188E-05
   3    38  UZ   29   1.01451E+01 ...  2.00000E-01   6.97445E-02  -1.48615E-02
\end{verbatim}
The output is stored in \filef{b.10}, \filef{s.10}  and \filef{d.10}.
Now we need to subsequently close the Lin gaps. Our strategy is to
keep $T_1$ fixed. We first continue in $\alpha$, $\mu$,
$\varepsilon_1$ and $\varepsilon_2$ until $\varepsilon_1=0$.
\begin{center}
\commandf{r11=run(r10,ICP=[4,5,22,24],NPR=310,DS=0.01,DSMAX=0.01,UZR=\{-22:0.0,4:0.082\})} \\
\commandf{r6=r6+r11}
\end{center} 
\begin{verbatim}
  BR    PT  TY  LAB    PAR(4)     ...   PAR(5)        PAR(22)       PAR(24)
   3     6  UZ   30   8.20000E-02 ... -1.29790E-02   1.76995E-01   6.37184E-02
   3    32  UZ   31   1.98414E-01 ... -6.05495E-03   2.30717E-06   3.62449E-02
\end{verbatim}
The output is appended to the \python variable \parf{r6}.
Note that this continuation is very similar to the one where we found
a 2-homoclinic orbit. In fact we have now found a 2-homoclinic orbit
(numerically) followed by a `broken' 1-homoclinic orbit; only the mesh
is not aligned.

The next step is to close the gap corresponding to $\varepsilon_2$ to
obtain a 3-homoclinic orbit. We replace the continuation parameter
$\varepsilon_1$ by $T_2$, because $T_2$ (\parf{PAR(23)})
still has to be decreased from
its high value (35) and $\varepsilon_1$ needs to stay at 0.
\begin{center}
\commandf{r12=run(r11,ICP=[4,5,23,24],NMX=32,NTST=40,DS=-1,DSMAX=1,
  UZR=\{24:0,4:0.18\})}\\
\commandf{r6=r6+r12}
\end{center} 
\begin{verbatim}
  BR    PT  TY  LAB    PAR(4)     ...   PAR(5)        PAR(23)       PAR(24)
   3    16  UZ   32   1.98395E-01 ... -6.05536E-03   2.01311E+01   1.82491E-08
   3    24  UZ   33   1.80000E-01 ... -6.50293E-03   1.27554E+01  -3.14294E-02
   3    30  UZ   34   1.66990E-01 ... -6.89269E-03   9.41745E+00  -1.03179E-06
   3    32  EP   35   1.78172E-01 ... -6.55364E-03   9.50300E+00  -7.20367E-02
\end{verbatim}
The output is appended to the \python variable \parf{r6}.
Note that we have found two zeros of \parf{PAR(24)}, at labels 32 and
34, respectively. The two zeros
correspond to two different 3-homoclinic
orbits, which, when followed from periodic orbits, both emanate from
from the same saddle-node bifurcation.
These two 3-homoclinic orbits are depicted in Figure~\ref{hom2}(b).
We can follow both of these back to the inclination flip point, by
setting \parf{ITWIST} back to 0:
\begin{center}
\commandf{r13=run(r6('UZ7'), ICP=[4,5], NMX=30, DS=-0.01, DSMAX=0.1,
  UZR=\{4:0.13\}, ISTART=1, ITWIST=0)}\\
\commandf{r6=r6+r13}
\end{center} 
\begin{verbatim}
  BR    PT  TY  LAB    PAR(4)        L2-NORM    ...   PAR(5)     
   3    13  UZ   36   1.29999E-01   5.04807E-01 ... -2.33902E-03
   3    30  EP   37   9.27258E-02   5.06560E-01 ... -2.76788E-04
\end{verbatim}
\begin{center}
\commandf{r14=run(r6('UZ9'), ICP=[4,5], NMX=30, DS=-0.01, DSMAX=0.1,
  UZR=\{4:0.145\}, ISTART=1, ITWIST=0)} \\
\commandf{r6=r6+r14}
\commandf{save(r6,'6')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB    PAR(4)        L2-NORM    ...   PAR(5)     
   3     7  UZ   38   1.45000E-01   5.47347E-01 ... -4.79400E-03
   3    30  EP   39   8.39399E-02   5.52605E-01 ... -7.36611E-05
\end{verbatim}
All the combined appended output is saved to \filef{b.6}, \filef{s.6}
and \filef{d.6}.
The bifurcation diagram and the paths we followed when closing the Lin
gaps are depicted in Figure~\ref{parspace}. It is possible and
straightforward to obtain $4, 5, 6, \dots$-homoclinic orbits by 
extending the above strategy.
\begin{figure}[htb]
\begin{center}
\includegraphics[scale=0.5]{include/parspace}
\caption{Parameter space diagram near an inclination flip. 
The curve
through label 17 corresponds to a 1-homoclinic orbit. 
The opening of the Lin gaps occurs along the vertical line from
label 16 to label 23. The curves
through labels 23 and 30 denote the path that is followed when
closing the Lin gaps. The (approximately overlaid)
curves though labels 25 and 35 correspond to the 
2- and one of the 3-homoclinic orbits.
Finally, the curve through label 37 corresponds to the other
3-homoclinic orbit, which was obtained for \parf{PAR(23)}=$T_2=12.03201$.}
\label{parspace}
\end{center}
\end{figure}

\section{ Branch switching for a Shil'nikov type homoclinic orbit in
the FitzHugh-Nagumo equations.}

The FitzHugh-Nagumo (FHN) equations \cite{FitzH:61,NaArYo:62} 
are a simplified version of the
Hodgkin-Huxley equations \cite{HoHu:52}. 
They model nerve axon dynamics and are given by

\begin{equation}
\begin{split}
u_t&=u_{xx}-f_a(u)-w, \\
w_t&=\epsilon(u-\gamma w),
\end{split}
\label{fhnpde}
\end{equation}
where
\[
f_a(u) = u (u-a)(u-1).
\]

Travelling wave solutions of the form $(u,w)(x,t)=(u,w)(\xi)$, where
$\xi=x+ct$ are solutions of the following ODE system:

\begin{equation}
\begin{split}
\dot u &= v,\\
\dot v &= c v + f_a(u) + w,\\
\dot w &= \frac{\epsilon}{c} (u - \gamma w).
\end{split}
\label{fhnode}
\end{equation}
In particular we consider solitary wave solutions of \eqref{fhnpde}.
These correspond to orbits homoclinic to $(u,v,w)=0$ in system \eqref{fhnode}.
In our numerical example we keep $\gamma=0$.

We aim to find a $2$-homoclinic orbit at a Shil'nikov bifurcation.
All the commands given here are in the file fnb.auto.
First we obtain a homoclinic orbit using a homotopy technique (see
\citeasnoun{FrDoMo:94}), using \parf{ISTART=3}, for the parameter 
values $c=0.21, a=0.2, \epsilon=0.0025$.

\begin{center}
\commandf{demo('fnb') }\\
\commandf{r1 = run('fhn',sv='1')}
\end{center}

Among the output we see:
\begin{verbatim}
  BR    PT  TY  LAB     PERIOD       L2-NORM    ...   PAR(17)
   1    21  UZ    4   2.91921E+01   2.38053E-01 ...  2.37630E-11
\end{verbatim}
and a zero of \parf{PAR(17)} means that a zero of an artificial parameter has
been located and the right-hand end point of the corresponding
solution belongs to the plane that is tangent to the stable manifold
at the saddle. This point still needs to come closer to the
equilibrium, which we can achieve by further increasing the period to
300, while keeping \parf{PAR(17)} at 0:
\begin{center}
\commandf{r2 = run(r1('UZ1'),c='fhn.2',sv='2')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB     PERIOD       L2-NORM    ...   PAR(2)
   1   189  UZ   11   3.00000E+02   7.37932E-02 ...  1.79286E-01
\end{verbatim}

Next we stop using the homotopy technique and increase the period even
further, to 1000.
\begin{center}
\commandf{r3 = run(r2('UZ1'),c='fhn.3',sv='3')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB     PERIOD       L2-NORM    ...   PAR(2)
   1    80  UZ   14   1.00000E+03   4.04183E-02 ...  1.79286E-01
\end{verbatim}

A continuation in \parf{PAR(2)}=$a$ and \parf{PAR(1)}=$c$ needs to be 
performed to arrive
at the place where we wish to find a 2-homoclinic orbit: $a=0$. At the
same time we monitor \parf{PAR(22)} to locate Belyakov points.
\begin{center}
\commandf{r4 = run(r3('UZ1'),c='fhn.4',sv='4')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB    PAR(2)        L2-NORM    ...   PAR(1)        PAR(22)
   1     6  UZ   16   1.31812E-01   3.28710E-02 ...  2.17166E-01  -6.31253E-06
   1    23  UZ   20  -8.55398E-08   1.56158E-02 ...  2.74218E-01  -9.88772E-02
\end{verbatim}
Hence, there exists a Belyakov point at $(a,c)=(0.131812,0.21766)$.
At label 19 we have a lower value of $a$ than at the Belyakov point,
and by inspection of the file
\filef{d.4} we can observe that the equilibrium has one positive
eigenvalue and a complex conjugate pair of eigenvalues with negative
real part, and conclude that this orbit is of Shil'nikov type.
Before starting the homoclinic branch switching, we calculate
the adjoint to obtain a `Lin vector':
\begin{center}
\commandf{r5 = run(r4('UZ5'),c='fhn.5',sv='5')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB    PAR(9)        L2-NORM    ...   PAR(3)     
   1     2  EP   29  -1.00000E+00   1.56158E-02 ...  2.50000E-03
\end{verbatim}
Next, we continue in the time $T_1$ (\parf{PAR(21)}), the gap
$\varepsilon_1$ (\parf{PAR(22)}) and $c$ (\parf{PAR(1)}), 
and by setting \parf{ISTART}=-2
we try to locate a 2-homoclinic orbit:
\begin{center}
\commandf{r6 = run(r5,c='fhn.6',sv='6')}
\end{center}
In fact we find many of them, exactly as is predicted by the theory:
\begin{verbatim}
  BR    PT  TY  LAB    PAR(21)    ...   PAR(1)        PAR(22)
... 
   1   174  UZ   45   1.64799E+02 ...  2.74218E-01  -3.44422E-11
   1   178  UZ   46   1.44799E+02 ...  2.74218E-01   3.29142E-14
   1   182  UZ   47   1.24854E+02 ...  2.74218E-01   1.70138E-15
   1   187  UZ   48   1.04789E+02 ...  2.74218E-01  -8.57896E-14
   1   191  UZ   49   8.49517E+01 ...  2.74218E-01   1.93804E-13
   1   196  UZ   50   6.45145E+01 ...  2.74218E-01  -2.26551E-09
\end{verbatim}
Each of these homoclinic orbits differ 
by about 20 in the value $T_1$. This is about 
the time it takes to make one half-turn close to and
around the equilibrium, so that orbits differ by the number of 
half turns around the equilibrium before a big excursion
in phase space. Note that the variation of 
$c$ is so small that it does not appear.

A plot of $T_1$ vs. $\varepsilon_1$ gives insight into how the gap
is opened and closed in the continuation process. This is depicted in 
Figure~\ref{shilgap}.
\begin{figure}[htb]
\begin{center}
\includegraphics[scale=0.5]{include/shilgap}
\caption{A plot of $\varepsilon_1$ as a function of $T_1$ 
during our computation of Shil'nikov-type two-homoclinic orbits. 
Each zero corresponds to a different orbit.}
\label{shilgap}
\end{center}
\end{figure}
We are now in a
position to continue each of these orbits as a
normal homoclinic orbit by setting \parf{ISTART=1} and
\parf{ITWIST=0}. We leave
this as an exercise to the reader.

\section{ Branch switching to a 3-homoclinic orbit in
a 5th-order Korteweg-De Vries model}

In \citeasnoun{ChGr:97} the following water wave model was considered:
\begin{equation}
\frac{2}{15}r''''-b r''+ar+\frac{3}{2}r^2-
\frac{1}{2}(r')^2+[rr']' = 0.
\label{cgode}
\end{equation}
It represents solitary-wave solutions $r(x+at)$, $r\to 0$ as $x\to
\pm\infty$ of the 5th-order PDE
\[
r_t+\frac{2}{15}r_{xxxx}-b r_{xxx}+3r r_x+2 r_x r_{xx}+r r_{xxx=0},
\]
where $a$ is the wave speed.
The ODE corresponds to a Hamiltonian system with Hamiltonian
\[ H=-\frac{1}{2}q_1^3-\frac{1}{2}a q_1^2+p_1 q_2-\frac{1}{2}b q_2^2+
\frac{15}{4}p_2^2+\frac{1}{2}q_2^2 q_1 \]
and 
\[q_1=r, \quad q_2=r', \quad p_1=-\frac{2}{15}r'''+br'-rr', \quad p_2=\frac{2}{15}r''.\]
System \eqref{cgode} is also reversible under the transformation 
\[ t \mapsto -t, (q_1,q_2,p_1,p_2)\mapsto (q_1,-q_2,-p_1,p_2),\] 
but we do not exploit the reversible structure (\parf{IREV=0}), and
instead use it as an example of Hamiltonian system.
This system exhibits an orbit flip for a reversible Hamiltonian system.
In Hamiltonian systems, homoclinic orbits are codimension-zero
phenomena, and we have to add an additional parameter $\lambda$ that breaks
the Hamiltonian structure in this system, by introducing artificial friction.
Thus, the actual system of equations that is
used for continuation is
\[\dot x=(\lambda I + J)\nabla H(x),\]
where $x=(q_1,q_2,p_1,p_2)$ and $J$ is the usual skew symmetric matrix
in $\mathbb{R}^4$.
It is now possible to continue a homoclinic orbit in {\cal HomCont} in two
parameters ($\lambda$ and either $a$ or $b$); see also
\citeasnoun{Be:90a}.

An explicit solution exists for $a=3/5(2b+1)(b-2), b\geq -1/2$, and it is
given by 
\[r(t)=3(b+\frac{1}{2})\mathrm{sech}^2\left([\frac{3}{4}(2b+1)]^{1/2}t\right).\]
It corresponds to a reversible orbit flip for $b>2$ ($a>0$) 
We start from this explicit solution, using \parf{ISTART=2}, for $a=3$ and
$b=(\sqrt{65}+3)/4$:

\begin{center}
\commandf{demo('kdv') }\\
\commandf{r1=run('kdv',sv='1')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB    PAR(1)        L2-NORM    ...   PAR(3)     
   1     1  EP    1   3.00000E+00   5.56544E+00 ...  0.00000E+00
   1     2  EP    2   3.04959E+00   5.49141E+00 ... -4.53380E-18
\end{verbatim}
Here \parf{PAR(1)}=$a$, \parf{PAR(2)}=$b$, and
\parf{PAR(3)}=$\lambda$. We have only done a
very small continuation to give \AUTO a chance to create a good mesh
and avoid convergence problems later.
Next, we set \parf{ITWIST=1} and calculate the adjoint:
\begin{center}
\commandf{r2=run(r1,c='kdv.2',sv='2')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB    PAR(2)        L2-NORM    ...   PAR(9)
   1     2  EP    3   2.76557E+00   5.49141E+00 ... -3.12500E-04
\end{verbatim}
We now need to move back to the orbit flip at $a=3$:
\begin{center}
\commandf{r3=run(r2,c='kdv.3',sv='3')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB    PAR(1)        L2-NORM    ...   PAR(3)     
   1    14  UZ    5   3.00000E+00   5.47613E+00 ...  1.47725E-09
\end{verbatim}
Now all preparations are done to start homoclinic branch
switching. This is very similar to the technique used in 
Sandstede's model in Section~\ref{sec:HomCont_hbs_san}; 
to find a 3-homoclinic orbit, we open 2 Lin gaps,
until $T_1=3.5$, while also varying $\lambda$=\parf{PAR(3)}.
\begin{center}
\commandf{r4=run(r3('UZ2'),c='kdv.4',sv='4')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB    PAR(3)     ...   PAR(21)       PAR(22)       PAR(24)
   1    13        8   5.85315E-10 ...  1.65474E+01  -9.20183E-08  -6.11537E-07
   1    23  UZ    9   1.52986E-09 ...  9.85223E+00  -6.68578E-12   2.01956E-07
   1    26       10   4.09273E-09 ...  6.87525E+00   2.68679E-07   7.64502E-07
   1    33  UZ   11   2.15483E-06 ...  3.49999E+00   7.94022E-04   3.99104E-04
\end{verbatim}
We then look for an orbit with $a<3$ and close the gap corresponding 
to $\varepsilon_1$=\parf{PAR(22)}, for decreasing $a$.
\begin{center}
\commandf{r5=run(r4,c='kdv.5',sv='5')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB    PAR(2)     ...   PAR(3)        PAR(22)       PAR(24)
   1    10       12   2.57977E+00 ...  2.15713E-06   7.65450E-04   3.82670E-04
   1    13  UZ   13   2.32044E+00 ...  3.86701E-11   1.13817E-10   1.58675E-08
   1    20  EP   14  -1.47788E-01 ... -9.46232E-04  -7.53666E-01  -3.43203E-01
\end{verbatim}
and finally close the gap corresponding to $\varepsilon_2$=\parf{PAR(24)},
\begin{center}
\commandf{r6=run(r5('UZ1'),c='kdv.6',sv='6')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB    PAR(2)     ...   PAR(3)        PAR(23)       PAR(24)
   1    23  UZ   15   2.32044E+00 ...  3.30393E-12   1.48758E+01  -2.30540E-10
   1    35       16   2.31894E+00 ... -2.15192E-08   7.69389E+00  -1.07760E-05
   1    51  UZ   17   2.33846E+00 ...  2.57829E-07   3.48152E+00   1.29755E-04
   1    58  UZ   18   3.08085E+00 ...  2.28299E-12   3.50004E+00  -1.62266E-10
\end{verbatim}
so that a three-homoclinic orbit is found. Here the zero at label
17 is the one we are looking for. Label 15 is a false positive since
$T_2=PAR(23)$ is still too high. At label 18, $a$=\parf{PAR(1)} 
has changed
considerably to the extend that $a>3$ and a second 3-homoclinic orbit 
is found. Note that for all zeros of \parf{PAR(24)}=$\varepsilon_2$, the
parameter $\lambda$=\parf{PAR(3)} is also zero (within \AUTO accuracy), 
which it has to be to remain
within the original Hamiltonian system.
Setting \parf{ISTART=1}, a normal ``trivial'' continuation (with \parf{NMX=1})
of the orbit corresponding to label 17
lets {\cal HomCont} produce a proper concatenated
3-homoclinic orbit:
\begin{center}
\commandf{r7=run(r6('UZ2'),c='kdv.7',sv='7')}
\end{center}
\begin{verbatim}
  BR    PT  TY  LAB    PAR(2)        L2-NORM    ...   PAR(3)     
   1     1  EP   20   2.33846E+00   7.50835E+00 ...  2.57829E-07
\end{verbatim}
This 3-homoclinic orbit is depicted in Figure~\ref{kdv3hom}.
\begin{figure}[htb]
\begin{center}
\includegraphics[scale=0.5]{include/kdv3hom}
\caption{A 3-homoclinic orbit in a 5th-order Hamiltonian 
Korteweg-De Vries model.}
\label{kdv3hom}
\end{center}
\end{figure}

%==============================================================================
%==============================================================================


\bibliography{include/auto} \label{sec:bibliography}


\end{document}