The user interacts with the program Orbit9 -to define what has to be done- essentially only by editing the options file orb9.opt. In this section we shall comment on that file line by line. The option file, as well as other input files, is handled through the utility routines contained in the file genio.f in such a way that the input takes the general format:
variable= value ; comment
allowing for comments which in most cases explain all the available options.
;input control and options file for Orbit9
; 1. input file names
The program needs to find initial conditions both for the planets and for the massless bodies (``asteroids'') in two files prepared in a suitable format. The first options are just the names of these files:
inplan='plan91.inc'; input file for initial conditions of the planets
The planets initial condition files has a single possible format, regardless of whether the task is to continue a previous integration or whether the integration starts from a catalogue of osculating orbital elements. Thus the periodic dump file, orb9.dmp, contains the initial conditions for the planets in a format perfectly suitable to be used as input. Sample initial conditions files are provided; they must contain a header, specifying which bodies are in the file, the reference epoch, the coordinate system, the meaning of each coordinate, the planetary masses, and the shift with respect to the reference epoch (in years). To continue an integration interrupted for whatever reason, the periodic dump file must be edited to remove the dumps until the last complete one, renamed (to avoid conflicts between input and output), and that name must be entered in the line of orb9.opt shown above; the only option to be changed is nout, with the understanding that the count of the output records includes the ones already done up to the dump used (warning: the output files have to be renamed to avoid overwriting; the macro o9stor is provided to perform this renaming). The initial data can be supplied in a variety of coordinate systems; although the choice for the direct output of Orbit9 is somewhat narrower, by using the output conversion program Conv9 it is possible to obtain output with the same choices. For a complete list of these choices see section 4. Nevertheless, the output files different from the dump files orb9.dmp, orb9.dma should not be used for continuation of a previous integration, because the rounding off of the formatted output would result in a significant loss of accuracy in the continuation.
ibar= 1; barycentric correction 1=yes 0=no
inbar='barsun91.inc'; file with barycentric correction
When the dynamical model of the motion of the asteroids (and of the planets as well) neglects the perturbation produced by some planets, the initial conditions have to be corrected to account for the missing short periodic perturbations. As an example, the file barsun99.inc contains the vector from the barycenter of the inner solar system (Sun and planets up to Mars) to the Sun, in the system ECLM00, for the same epoch as the initial conditions file; to perform correctly a computation of the orbits of the outer planets, and of asteroids perturbed by the outer planets only, this barycentric vector must be added to the initial heliocentric positions and velocities of all the bodies; the mass of the inner planets is then added to the mass of the Sun. Warning: when an integration of the outer planets is continued from a dump output orb9.dmp, the barycentric correction is already there, and the masses of the inner planets are already included in the mass of the Sun (that is, the mass of the Sun is not 1 in units of the mass of the Sun!), thus the flag ibar has to be set to 0.
inast='oscel.91'; input file for initial conditions of the asteroids
The asteroids initial condition file can be given in either of two formats. The first one is identical to that of the planets, apart from the fact that the masses are not given; the periodic dump file orb9.dma is in this format, and can be used for continuation in the same way discussed above for the planets. The other format is automatically used every time the asteroid input file name contains the string oscel; then it is assumed that the input file is a catalogue given in a format compatible with the computer readable catalogues distributed by the Minor Planet Center. An example of the latter is given in the file oscel.test.
; 2. job description: ast.ordered in two lists, with and without LCE nvz= 2 ; no. Lyapounov exponents 110 334 1 4 1998QW (This line empty!)
The lines of orb9.opt listed above describe the orbit computation which has to be done, by listing the asteroids (from the input catalogue specified above) whose orbit has to be computed, and the ones for which the maximum Lyapounov exponent has to be estimated. The first nvz asteroids in the list are computed with variational equation, the others without; an empty line terminates the list. Warning: if the asteroid initial conditions are read from a MPC format catalogue, it is assumed that in the catalogue they are listed in order by number; then it is required that the two sublists, the one with LCE and the one without, are also odered by number. This requirement is not there for the other format, e.g. for continuation integrations. Nothing forbids the computation of the orbits of other asteroids, including fictitious ones; the user must only copy the input format either from oscel.anyextension or from orb9.dmp, and give to the file a name either containing, or not containing, the string oscel. By format I do not mean the exact number of decimal digits, since the Fortran read is done in free format; I mean the header and the order of the variables.
; 3. options: output
dt= 1.0000d+02; time between two outputs
nout= 100; output number at job termination
The output will consist of four files, vast.dat, vpla.dat, vast.fil, vpla.fil. They all begin with a header, explaining what is in the file in exactly the same fomat used in the input files, and then a time series of orbital elements sampled at regular intervals of length dt (in years), for a total of nout+1 data points (including one record containing the initial conditions), for a total integration time span of dt*nout years. The vast.xxx files contain asteroid data, the vpla.xxx the corresponding planet data. The vxxx.dat files contain data purely sampled, the vxxx.fil files contain data digitally filtered, then decimated in such a way that the output interval is still dt; the filtered output is in phase with the sampled one, but there are two gaps at the beginning and at the end of the integration interval due to finite filter length. For details on the filter options, see below and section 4.
idump= 10; number of outputs between dump/renormalisation
Two operations are performed not at every output, but periodically every idump output data points, that is every dt*idump years: dump of the full precision data to allow to restart the integration (this is done for safety, e.g. as protection against power failures; under normal job termination conditions, only the last dump can be useful for continuation), and renormalisation of the variational vector to avoid overflow problem in strongly chaotic cases (there is no logical reason for which the periodicity of these two operations should be the same, I just try to keep the number of options as low as possible).
isamp= 100; sampling ratio of the filter; choose 5, 20, 50 or 100
The digitally smoothed data are obtained by computing the orbital elements at a time interval dt/isamp and entering them into a digital filter which outputs them at the interval dt; the output is smoothed in the sense that all the oscillations with periods between 2*dt/isamp and 2*dt are reduced by a large (typically between 103 and 104) attenuation factor. Warning: the choice of the filter input interval dt/isamp is critical in that the oscillations with periods close to dt/isamp can produce long period aliases which might not be filtered (see section 4). The example above is adequate for a computation of the outer planets and of main belt asteroids, since no large perturbation occurs with period of about 1 year; for a computation including the orbit of the Earth it would be deadly wrong. The choice of the sampling ratios isamp is limited by the actual availability of the filter coefficients, which must be in files with file names filter.dxx; for the format of these files, see the examples given. New filters can be designed by the Filgen software by M. Carpino; however, there is a limit to the filter length which can be reset by editing the file parfil.h.
iprqua= 2; how much output: 1 elem. filtr; 2 also sampl.;
This is self explanatory; normally leave 2, unless you want only the smoothed data and you are running out of disk space.
sysz= 'HEL' ; output system: BAR, HEL, JAC, HEC
refz= 'INVL1B' ; output reference system: INVL1B, ECLM50, EQUM00, etc
Here we can choose the coordinate system for the output, and the reference system. As for the sampled data, the transformation to whatever coordinate system we want could be done in the output conversion stage with Conv9; however, for the filtered output, the two operations of filtering and of changing coordinate system do not commute, thus it is essential to know in which coordinate system the output will be used to perform the correct smoothing. On the contrary the change of reference system is a rotation, a linear operation, and to do it either before or after filtering does not matter at all. See section 4 for a description of the options available.
; 4. options: variational equation
v1= 1.00d+03; variation vector norm forcing renormalisation
semim= 3.0; approx. semimajor axis for norm of var.vect.
These options pertain to the calculation of the maximum Lyapounov exponent: the renormalisation is forced whenever the periodic check (at time intervals of dt*idump years) finds the norm of the variation vector increased by a factor v1; the norm is computed with a metric defined by semim, which should be the approximate semimajor axis in AU of the asteroid orbit, if you want the orbital postion and the orbital velocity on a circular orbit both to have norm 1. As a matter of principle, the Lyapounov exponents do not depend upon the metric; but this is true only at the limit of infinite time, so it is better to set this at least approximately correct.
; 5. options: propagator $ = option not yet implemented
h= 0.03; stepsize for multistep (maximum if iauto=1)
iauto= 1; automatic stepsize control 1=yes 0=no
error= 1.d-13: target error in longitude, rad/rev2
The propagator options are quite difficult to select unless the user has a good understanding of the performance of multistep and implicit Runge-Kutta integrators. Therefore the program provides for an automatic choice of the most critical integration parameters, which is enabled by the flag iauto. If the automatic mode is selected, the program automatically selects the stepsize in such a way that in all the orbits (planets and asteroids) the truncation error accumulated in longitude does not exceed error radians per revolution squared; moreover the stepsize is not longer than h, in such a way that the user can force a shorter step. It has to be taken into account that in the present version (2.1) the prediction of the integration error is done on the basis of the initial osculating semimajor axis and eccentricity of each orbit; thus an orbit which later becomes more eccentric could result in a wrong predicition, not to speak of an orbit so unstable that the semimajor axis can significantly change during the integration. In practice the parameter error must be set to a small value, e.g. in the example given the target is an error less than 0.1 radians after 1 million revolutions, but not too small because otherwise the rounding off error might become more important; actually, the program checks the local ronding off error of your machine and forces error to be not smaller than that. Again, there is no protection against the much larger errors occuring during fast close approaches; some more reliable version might appear later.
iord= 12; order of multistep predictor
epms= 1.0d-12; convergence control for corrector $
iork= 12; order of starter
eprk= 1.00d-10; convergence control for implicit Runge-Kutta
lit1= 10; iterations for first step
lit2= 4; iterations for following steps
imet= 1; main integration method: 1 multistep 2 symplectic
iusci=10; output of numerical convergence controls 0 no
icha=0; 0 interactive 1 batch, change step
Apparently, there are many more choices on the propagator, but the user is warned not to change anything with respect to this example unless he knows what he is doing. As an example, it might appear a good idea to increase the order of the multistep and to use longer steps; unfortunately, there is a stability limit which is not checked in the present version, and the use of iord larger than 12 is likely to result in such an instability; for a discussion of all the theory, the user should consult Milani and Nobili, Celestial Mechanics 43, 1-34, 1988, taking into account that the algorithm used here is backward difference, second sum, of order iord. All the other options pertain to the starter or even to not yet implemented features.