Rauto - execute AUTO continuation runs.

Rauto is a command line interface to AUTO.

Usage

rauto [-h$\mathrm \vert$-f] name run [restart_run -IRS irange ...] [options ...]

	options		:		(-iopt inum) $\mathrm \vert$ (-dopt dnum) $\mathrm \vert$ spopt $\mathrm \vert$ lopt
	iopt		:		NDIM $\mathrm \vert$ IPS $\mathrm \vert$ ILP $\mathrm \vert$ NTST $\mathrm \vert$ NCOL $\mathrm \vert$ IAD $\mathrm \vert$ ISP $\mathrm \vert$ ISW
			$\mathrm \vert$		IPLT $\mathrm \vert$ NBC $\mathrm \vert$ NINT $\mathrm \vert$ NMX $\mathrm \vert$ NPR $\mathrm \vert$ MXBF $\mathrm \vert$ IID $\mathrm \vert$ ITMX
			$\mathrm \vert$		ITNW $\mathrm \vert$ NWTN $\mathrm \vert$ JAC $\mathrm \vert$ IADS
	dopt		:		RL0 $\mathrm \vert$ RL1 $\mathrm \vert$ A0 $\mathrm \vert$ A1 $\mathrm \vert$ EPSL $\mathrm \vert$ EPSU $\mathrm \vert$ EPSS $\mathrm \vert$ DSMIN $\mathrm \vert$ DSMAX
	spopt		:		(-ICP inum ...) $\mathrm \vert$ (-DS (dnum$\mathrm \vert$+$\mathrm \vert$-))
	lopt		:		((-THL$\mathrm \vert$-THU) (inum dnum) ...) $\mathrm \vert$ (-UZR (inum drange) ...)
	irange		:		inum $\mathrm \vert$ inum:[inum:]inum
	drange		:		dnum $\mathrm \vert$ dnum:[dnum:]dnum

Switches

	-h		:		Display a usage message and exit with nonzero return value.
	-f		:		Force execution of computation even if the data seems up-to-date.

Arguments

	name		:		Base name of the equation file name.f.
	run		:		Unique name (identifier) of the run to be performed.
	restart_run		:		Name of the run that contains the restart solutions.

In single-run mode (one restart label) run may contain, and in multiple-run mode (two or more restart labels) run must contain a %d format specifier f : %[0[width]]d. This specifier is replaced with the restart label of the current run. Width sets the minimum field width and the initial `0' forces zero-padding. For example, `%03d' will result in `007' for restart label 7. The run name resulting from this substitution is called the qualified run name, for example, `agent007' is the qualified run name of the run name `agent%03d' with restart label 7.

Options

Options is a list of AUTO constants preceeded with a `-'. The meaning of these constants is briefly explained in Section 2 and Appendix B and in detail in the AUTO manual [1]. Upper- and lower case are equivalent and can be mixed. The majority of options requires an integer argument inum, or, a floating point argument dnum, which will be assigned to the corresponding AUTO constant. Exceptions to this rule are -IRS, the special options -ICP and -DS, and the list options -THL, -THU and -UZR.

IRS expects a list of restart labels and accepts integer numbers and/or integer ranges. The notation of ranges follows the matlab syntax irange : begin:[step:]end, that is, `1:5' expands to `1 2 3 4 5' and `1:2:5' to `1 3 5'. ICP expects a list of indices of continuation parameters. Note that you must not give the number of parameters. The initial continuation step size DS accepts the two direction flags `+' and `-' besides an explicit floating point value. Specifying a direction flag will set the direction of continuation to forward or backward, respectively, without changing the absolute value of the initial step size.

THL and THU follows a list of pairs consisting of an integer index and a floating-point value weight. Index is the index of a parameter or of a state variable and weight is the scaling factor that will be applied to this variable in the arc-length computation. UZR expects pairs consisting of an integer index and a floating-point value uzr_value similarly to THL and THU. However, ranges of floating-point values may be given for uzr_value. The syntax is identical to integer ranges. For example, the pair `1 1:0.5:2' expands to the three-element list of pairs `1 1.0 1 1.5 1 2.0'.

Detailed description

Rauto combines into a single invocation a number of basic steps that are necessary to perform a run with AUTO, which makes it easier to execute and organize large numbers of runs. Before using rauto you need to prepare an equations file name.f, defining the right-hand side of your system and an initial solution, and the master constants file r.name with initial values for all AUTO constants; see Section 2 for details. If you want to start from numerical data you also have to provide the file name.dat that contains points along a solution; see the description of rfcon for details.

AUTO computations are divided into two phases: a few initial runs of rauto with restart label IRS and restart_run omitted, and subsequent restarted runs where restart_run and restart labels are specified. When starting from numerical data only a single initial run is performed with rfcon. At this point we describe initial runs when using rauto, an initial run using rfcon is explained in the command description of rfcon. On startup of an initial run all AUTO constants are initialized from the master constants file data/r.name and from the constants file data/r.restart_run for a restarted run, which means that a restarted run inherits all constants from its restart run. There are three exceptions to this rule: ISW is always set to 1, DS is always initialized with a positive value and the user list UZR is always set to an empty list, only UZR points given on the command line will have the desired effect. After initialization rauto checks for which AUTO constants new values were given on the command line and substitutes all of these. Rauto then enters a loop over all restart labels that were specified on the command line, or IRS=0 for an initial run.

For each restart label rauto checks if the files data/r.qrun and data/l.qrun already exist, where qrun is the qualified run name; see Section Arguments above. Existence of these files indicates that this particular run has been computed before. Three tests are performed to decide whether or not it is necessary to rerun the computation. The computation is assumed to be up-to-date if the equations file is older than data/r.qrun, if all AUTO constants are identical to the ones in data/r.qrun and if the output of `printls restart_run restart_lab' is identical to data/l.qrun. If one of these tests fails or if data/r.qrun does not exist, then the computation is executed. Otherwise, a message indicating that the run is up-to-date is printed on the screen. Since AUTO shows a certain lack of communication skills rauto employs a heuristic test to verify hat the computation was successful. If this test fails an error message is printed. On success rauto saves all computed data and creates or updates the files data/r.qrun and data/l.qrun.

Return values

Rauto returns 0 on success and 1 if an error occurred or the -h switch was given. In the case that an error occurs during a run of AUTO, or if the run of AUTO is interrupted, the file data/r.qrun will be deleted, which schedules the interrupted run for recomputation.

Use `set -e' in sh or bash scripts to stop a sequence of computations as soon as an error occurs.