Running rauto

The easiest way to get started with rauto is to look at the examples provided with the package. We explain rauto's typical work cycle using the cusp normal form $\dot{x}=\mu + \lambda x - x^3$ as a simple example. Create a directory where you would like to do your computations, for example, rauto and change to this directory. Then type `rdm cusp'. This will create the sub-directory cusp. Change to the directory cusp and type `ls'. You should now see something like

frank/tmp> mkdir rauto
frank/tmp> cd rauto/
tmp/rauto> rdm cusp
tmp/rauto> ls
cusp
tmp/rauto> cd cusp
rauto/cusp> ls
cusp.f  demo  r.cusp  scandemo

The equations file is cusp.f and the master constants file is r.cusp. Note that the names of these two files follow the pattern name.f and r.name, which is required by rauto. We ignore the files demo and scandemo for the moment.

In our initial runs, that is, runs starting at the solution provided in STPNT, we are going to compute a branch of equilibrium points with respect to the parameter $\mu$. These computations will start at the point $x=0$, $\lambda =1$ and $\mu =0$. Before you continue:

$\bullet$

Take a look at the equations and master constants file.

$\bullet$

Sketch the $\mu$-$x$-bifurcation diagram for $\lambda>0$.

In our equations file U(1)${}=x$, PAR(1) ${}=\lambda$ and PAR(2)${}=\mu$. The constants file is preset for a continuation in $\mu\in[-2,2]$ for $\mu$ increasing. The basic call to rauto for performing an initial run is

rauto [-h] name run

where name is the name of the problem (cusp), and run is a unique name we assign to the computation or branch for later reference. Note that rauto and all its auxiliary programs have a -h switch, which will print a usage message and exit. Since we are going to perform a continuation for increasing $\mu$, we call our first run muf for `$\mu$ forwards'. To run this computation simply type `rauto cusp muf'. You should see something like

rauto/cusp> rauto cusp muf
rauto: *** number of runs=1
rauto: *** starting run muf: run 1 of 1, IRS=0
Starting cusp ...

  BR    PT  TY LAB    PAR(2)        L2-NORM         U(1)        PAR(1)
   1     1  EP   1   0.00000E+00   0.00000E+00   0.00000E+00   1.00000E+00
   1    14  LP   2   3.84900E-01   5.77351E-01  -5.77351E-01   1.00000E+00
   1    20       3   1.68950E-01   9.01430E-01  -9.01430E-01   1.00000E+00
   1    40       4  -1.19337E+00   1.36827E+00  -1.36827E+00   1.00000E+00
   1    49  EP   5  -2.07783E+00   1.53434E+00  -1.53434E+00   1.00000E+00

 Total Time    0.240E-01
cusp ... done

This will create the directory data, which stores the results of all rauto computations.

Figure: plotbd muf

r0.381

Rauto comes with a number of tools for processing data obtained through rauto computations. The most elementary of these are lsruns, printbd and rmruns. Lsruns will print a list of runs, printbd will re-print rauto's output of a run and rmruns will delete all files of all runs or of the runs given on the command line. Try `lsruns' and `printbd muf'. A more sophisticated tool is plotbd. Plotbd will plot a bifurcation diagram using all runs specified on the command line. For the moment we have only muf, so try `plotbd muf'. If you are a fan of black-and-white bifurcation diagrams, try `plotbd -bw muf'. You should see a gnuplot window with a plot similar to Figure 4. The horizontal axis is $\mu$ and the vertical axis is $\Vert x\Vert _2$, which corresponds to columns 5 and 6 of rauto's output during continuation. You may specify an argument of the form xaxis:yaxis to plot other columns, where xaxis and yaxis are the numbers of columns to be plotted as the $x$- and $y$-axis. Counting starts with column PAR as number 1. Try to plot $x$ versus $\mu$.

In a subsequent initial run we are now going to compute the missing part of the branch computed so far by continuation from the same starting point, but in the other direction. Instead of changing DS in the master constants file, we rather tell rauto on the command line to start a continuation in the other direction. Rauto allows to set almost any AUTO constant to a value different from that in the master constants file by using a command of the extended form

rauto name run (-auto_constant value) ...

Auto_constant is the name of any AUTO constant that is of type integer or double precision and value is the new value of appropriate type that shall be assigned to it. However, the constant DS is special in two aspects. When reading a constants file rauto ignores the sign and initially sets DS to the absolute value of the number found in the constants file. A negative value for DS must be given on the command line. To simplify matters DS also accepts the direction flags + and - on the command line instead of a floating point number. If you just want to start a continuation in one or the other direction and are happy with the absolute value of DS in the constants file then specify a direction flag. In our example, to start a continuation for decreasing $\mu$ type `rauto cusp mub -DS -'. Note the change of the run name to mub for `$\mu$ backwards'. You should see something like

rauto/cusp> rauto cusp mub -DS -
rauto: *** number of runs=1
rauto: *** starting run mub: run 1 of 1, IRS=0
Starting cusp ...

  BR    PT  TY LAB    PAR(2)        L2-NORM         U(1)        PAR(1)
   1     1  EP   1   0.00000E+00   0.00000E+00   0.00000E+00   1.00000E+00
   1    14  LP   2  -3.84900E-01   5.77351E-01   5.77351E-01   1.00000E+00
   1    20       3  -1.68950E-01   9.01430E-01   9.01430E-01   1.00000E+00
   1    40       4   1.19337E+00   1.36827E+00   1.36827E+00   1.00000E+00
   1    49  EP   5   2.07783E+00   1.53434E+00   1.53434E+00   1.00000E+00

 Total Time    0.800E-02
cusp ... done

This will create a second run, type `lsruns' to see a list of all runs. You may plot a combined bifurcation diagram of both runs by typing `plotbd 1:3 muf mub', or, the more advanced command `plotbd 1:3 `lsruns`' making use of command substitution by the shell. The latter technique is very convenient for plotting combinations of many runs.

Typing rauto commands on the command line quickly becomes tiring, in particular, if you need to set many AUTO constants. The recommended way of using rauto is to step by step add rauto commands to a shell script. This not only allows you to collect all data about your computations in a single file, it also facilitates recomputing runs when necessary and massive computations involving large numbers of runs. Let us illustrate this style of working with the example cusp at hand. Type `rmruns' and answer `yes' when asked for confirmation:

rauto/cusp> rmruns
Remove the following runs?
 mub       muf
rmruns: (yes/no) yes
rauto/cusp> lsruns
lsruns: no matching runs

Create the file `cuspdemo' and make it executable:

rauto/cusp> touch cuspdemo
rauto/cusp> chmod +x cuspdemo
rauto/cusp> ls -l cuspdemo
-rwx------  1 frank users 0 2007-04-06 19:30 cuspdemo

Yes, I was typing this over Easter. Now open the file cuspdemo with your favorite text editor (or use `cat > cuspdemo'), and write

#!/bin/sh
set -e
rauto cusp muf
rauto cusp mub -DS -

This is a simple shell script for the command interpreter sh. The command `set -e' makes sure that the execution of the script stops whenever rauto encounters an error. Save the script (or press ^D) and type `./cuspdemo'. This will re-compute the runs muf and mub and produce the same output as before. Now type `./cuspdemo' again. This time you should see something like

rauto/cusp> ./cuspdemo
rauto: *** number of runs=1
rauto: *** starting run muf: run 1 of 1, IRS=0
rauto: *** run muf up to date, nothing done
rauto: *** number of runs=1
rauto: *** starting run mub: run 1 of 1, IRS=0
rauto: *** run mub up to date, nothing done

Rauto employs a number of tests to check whether a run is up to date or needs recomputation. This way you can (and should) add commands for new computations to the end of the list of rauto commands in a shell script and then simply re-execute the script. If you later change some constants of earlier computations rauto will recompute only the runs that might be affected by these changes. Rauto has a `-f' switch for forcing a recomputation in the impossible event that these tests fail. Play around with this example, change some constants and watch what happens.

The preceeding discussion should have equipped you with enough information to get started with rauto, in particular, if you are already an experienced user of AUTO. You might want to jump ahead to the command reference and start working with rauto and its many utility programs. With the subsequent examples we demonstrate how to execute restarted runs, select restart solutions, perform branch switching, start from numerical data and we explain rauto's constants inheritance mechanism. These examples also illustrate some advanced features, which include using command substitution, variable expansion and arithmetic expansion together with rauto as well as rauto's multiple run mode for so-called scans for creating 3d-bifurcation diagrams. A section with detailed descriptions of these and even more fancy features is in preparation.