The SolSyIn package

USER MANUAL

May 2001

You will find here also the Romanian version.

Content:

1. Introduction

2. Characteristics

3. Installing the software

4. Basic concepts

5. Description of programs

5.1. Program "Solar System Integrator" (integrat.exe)

5.2. Program "System Checker" (checker.exe)

5.3. Program "Graphic Displayer" (display.exe)

5.4. Program "System Maker" (sysmaker.exe)

5.5. Program "Table Maker" (tabmaker.exe)

5.6. Program "Plotter" (plotter.exe)

6. Controlling the integration error

7. The list of some dynamical processes to be outlined

8. Examples

9. The list of warning messages

10. Useful addresses


1. Introduction

Many researches involved in different scientific domains are developing their own computational programs to solve specific research themes. The outcomes of this activity can be seen in articles and journals just in the form of tables and graphs. The beauty, efficiency and accuracy of some algorithms remains unknown for others; without mentioning the fact that peoples sharing the same scientific preoccupations could find them also very useful. All these things have guided our steps toward what we are going to present next.

The SolSyIn package (from "Solar System Integrator") is the fruit of several years of research in Astronomy, more precisely in the field of "Dynamics of small bodies in the Solar System". It brings together many ideas and algorithms which give it a large spectrum of applicability, in scientific and educational areas.

This manual is not intended to be a textbook in Astronomy. Its unique purpose is to present as clear as possible all the futures of the SolSyIn package and the manner in which it can be used to simulate some dynamical processes. For this reason, the astronomical terms encountered along this manual are not explained.


2. Characteristics

SolSyIn is more than its name suggests: (i) it's a numerical integrator for dynamical systems of bodies (many, but no more than 10,000!) moving in gravitational field (newtonian/relativistic and radiative); (ii) a program for verifying the results of integration (intermediary and final ones); (iii) a program for viewing the system of bodies along its evolution; (iv) a program which creates new dynamical systems of bodies in various configurations; (v) a program which extracts different dynamical parameters from the databases created during integration, with the possibility of making 2D and 3D scientific plots.

To be more specific, we enumerate below the main characteristics of the package:


3. Installing the software

The SolSyIn package has the following structure of directories and files, which must be preserved during the decompression process of the distribution (the name of directories are written in bold):

---------------------------------------------------------------------------
SolSyIn \ Bat \ *.bat             (batch files for automatic manipulation)
        \ Cat \ *.cat             (catalogs taken from Internet)
        \ Dat \ *.dat             (data files generated during integration)
        \ Def \ *.def             (definition files of dynamical systems)
        \ Tab \ *.tab             (tables generated for plotting)
        \ Plo \ Hdr \ *.hdr       (header formats for plotting)
              \ *.plo             (GnuPlot command files)
        \ Src \ Lib \ *.lib       (library sources files)
              \ *.pp              (main programs source files)
        \ Doc                     (documentation)
        \ integrat.exe            (program "Solar System Integrator")
        \ checker.exe             (program "System Checker")
        \ display.exe             (program "Graphic Displayer")
        \ sysmaker.exe            (program "System Maker")
        \ tabmaker.exe            (program "Table Maker")
        \ plotter.exe             (program "Plotter")
        \ remove.exe              (utility "Data File Remover")
        \ cwsdpmi.exe             (32-bit DOS extender)
---------------------------------------------------------------------------

The significance of these files is the following:

*.bat - DOS command files created by user for non-interactively manipulating the programs from the SolSyIn package with command line parameters;

*.cat - catalogs of bodies which must be updated by user from time to time;

*.dat - binary data files created during integration and containing information about the dynamical evolution of the system; they are automatically manipulated by programs;

*.def - ASCII files which defines the initial state of a dynamical system; they are created automatically, but can be modified manually by the user;

*.tab - ASCII tables extracted from binary data files, which can be graphically represented; they are automatically manipulated, but the user can understand their content by reading the header;

*.hdr - predetermined header files of GnuPlot commands, which define the content of a 2D or 3D plot; the user can creates many other such files;

options.plo - user options file for graphic representation;

plotting.plo - main GnuPlot command file, which does not have to be modified; the path toward this graphic program has to be specified in the file "path" from the same directory;

*.lib, *.pp - Free Pascal source codes of main programs and libraries;

integrat.exe - program "Solar System Integrator" for numerical integration (the package's core);

checker.exe - program "System Checker" for checking the integration results;

display.exe - program "Graphic Displayer" for displaying graphically the dynamical evolution;

sysmaker.exe - program "System Maker" for creating new dynamical systems of bodies;

tabmaker.exe - program "Table Maker" for creating data tables;

plotter.exe - program "Plotter" for creating plots;

remove.exe - utility "Data File Remover" for erasing the data files "*.dat".

The SolSyIn package is a 32-bit software written in Free Pascal 1.0 programming language for DOS operating system (GO32v2), using CWSDPMI extender which is included in distribution. The generated code optimizes floating point operations and, particularly, for PII Intel processors and beyond. Executables are compressed with UPX utility for reducing their size. They run nicely under pure DOS and also under DOS prompt from WINDOWS. In the first case the running efficiency is just few percents higher than in the second one. Only for long runs (meaning hours) it's probably more benefic and without troubles to run the package under DOS (in this case it's very useful to use a program manager for I/O disk operations, such as SMARTDRV utility).

Modeling the dynamical evolution of a system of bodies requires a highly intensive CPU usage, because of the very big number of floating point operations that are performed. Thus, a higher running frequency of the processor allows higher performances to be reached be the SolSyIn package. It runs anyway on any computer having a mathematic coprocessor (optimum 300 MHz). On today's personal computers we are able to reach performances than on 80's they were accessible only to supercomputers!

The programs dynamically allocate memory, depending on the complexity of the integrated system. At least 8 Mb RAM memory has to be available (optimum 32 Mb). Under DOS, the DPMI server creates a swap file on disk if the available RAM memory drops to zero.

A dynamical system cannot be analyzed during integration. Its dynamical evolution is recorded on disk into a binary file containing intermediary integration data (in double precision). Sometimes, the size of this file can reach several tens or even hundreds of megabytes, proportionally with the number of bodies making the system and also with the length of the integration time. Therefore, a bigger capacity of HDD allows a more complex integration to be performed. Anyway, having a minimum required RAM memory, the package runs at any capacity of the disk, but the recording process of the data file is suppressed (without warning) if the available space is overflowed. For minimizing the I/O disk operations, the programs create on memory a 5 Mb buffer zone for temporarily storing integration data.

The invoking process of the GnuPlot graphic program requires setting up correctly its complete path into the directories' tree, stored in the file "path" from "Plo" directory.

A QUICK TEST OF THE PACKAGE

A quick and minimal interactive test of the package can be performed by executing the batch file "test.bat" from the "Bat" directory. This file calls itself all the programs mentioned above. Its execution is accompanied by some auxiliary comments. After performing this test, it is also interesting to check other existent "*.bat" files, but a better understanding of their execution requires reading the next paragraphs.
 

4. Basic concepts
console
Excepting the program "Graphic Displayer", all others are console programs, communicating with the user through two text windows (see the near figure in false colors). The top window (named further display window) displays various information to the user, mainly quantitative ones, as long as the bottom window (named message window) displays messages in scrolling mode or waits for user's inputs. These messages show to the user the current actions that are performed by the programs. The first displayed message is always the name of the program followed by its version (in format "month/year"). Some of the programs own several display windows, which are numbered in the top-right corner with "page 1", "page 2", etc. The passing process from one window to another is performed by simply pressing a key or, depending on the program, by selecting a given option. These display windows describe, also, all the options that the user has at any moment, and their associated keys.

Into "Src" directory is located the messages' file "mess.log". If it is moved (or copied) into the root directory of the package, every program writes on it, at running time, its own messages, together with the moments of time when it starts and stops the execution. Later, it is possible to consult this file in order to recreate all the actions undertaken by programs and to debug possible errors.

As you noticed in the previous paragraph at the testing moment, the SolSyIn programs accept command line parameters. Their sintax is very natural: they replace, accordingly, what the programs expect to be inputted from the keyboard. From this reason, their type must be compatible with the type of the input at the given moment, otherwise they are ignored. SPACE key is emulated in command line with the symbol "_". Due to this mechanism, the SolSyIn programs are able to call each other (for example, when a new body taken from a catalog is added to a defined system, using "System Maker" program, this system is integrated until the epoch of time when the new body's orbital elements are valid, and this process is made by an automatic call of the integration program). Not all keyboard inputs can be substituted in this manner. Exceptions are those commands that are exclusively destined for visualization (for graphic or browsing data).

The object around the SolSyIn package is developed is the dynamical system of bodies. It defines, at a given time, the state of a configuration of celestial bodies in the three-dimensional space, relative to a central body, and also some fundamental parameters of integration. These initial states are stored in such called definition files, having the extension ".def". These files are accessed by each program when the user answer at the request:

Input the name of a definition file (*.def):

At this point, the name of a valid file located in "Def" directory has to be introduced or read (without extension) from the command line. The structure of a such definition file is given bellow as an example. Lines beginning with the symbol "#" are comments, their majority being inserted when the file was created.

---------------------------------------------------------------------------
# Test system I: one planet (Mercury) around the Sun
#
#Initial date (julian days)
  2451545
#Central mass (solar masses)
  1.00000000000000E+00
#Number of moving bodies
  1
#Bodies info: flag (P-planet, A-asteroid, M-meteoroid), mass (solar masses),
#position vector (AU) and velocity vector (AU/days)
  P <1>
  1.66013679527193E-07
 -1.30093603003195E-01
 -4.47287619078405E-01
 -2.45983101945919E-02
  2.13663956512622E-02
 -6.44798948631322E-03
 -2.48786398976518E-03
#Include relativistic effects (0 = no / 1 = yes)
  0
#Integration direction (-1 = backward / 1 = forward)
  1
#Integration precision (from 1.0E-10 to 1.0E-15)
  1.0E-12
#Interval of integration (days)
  365250
#Frequency of stored data in *.dat file (1 = all data, 2 = half of data, etc.)
  1
#Number of body whose minimum distances are recorded (0 for none)
  0
---------------------------------------------------------------------------

Any quantity appearing under the commentary lines can be modified up to described limits. Also, inside the section showing the flag type, mass, position vector and velocity vector, new bodies can be placed. In this case, the number of moving bodies shown above has to be updated. Using the program "System Maker" it is not necessarily to know the structure of these definition files, but there will be some limits in modifying the existent systems.

The routine which checks the syntax of definition files is very rigid one, refusing any bad defined system. Despite of this precaution, the user is able to define systems of bodies which may crash the numerical integrator. As a general rule, it has to be definitely avoided the creation of two ore more bodies with the same position in space, or having their velocity vectors orientated in such a way that, in a very short time, they will occupy the same position. Otherwise, an undesirable "Division by zero" error will halt suddenly the execution of the program. By defining dynamical systems in a manner similar to those found in reality, it will prevent such singular cases to arise.

A dynamical system is composed by a fixed central body located at the origin of the reference axes, and other moving bodies (relative to the central one) having, generally, smaller masses or nil (massless). There are three symbolic types of bodies, every type being treated differently by the integration routine. Thus, we have:

We have made this distinction in order to give to the integration program the possibility of using optimized specific routines for each type of body.

Of course, the central body has also mass and it exerts its gravitational influence upon all other bodies from the system. This influence can be a newtonian or a relativistic one, accordingly with the specification given in the definition files. On the other hand, the gravitational fields of massive bodies are modeled in the hypothesis of point-like bodies. Because of this assumption, motions around nonspherical or nonhomogenous bodies are not correctly simulated with the SolSyIn package.

The ordering number that appears after the body's flag (for example, "<1>") is automatically inserted when the system is created, but it is ignored at reading. However, some programs identify the bodies of a dynamical system with this ordering number, starting with zero for the central body and continuing with the moving bodies in that order in which they appear in the definition file. There is a strict rule in which the bodies are declared in the definition files, depending on their flag's type. This rule is given here: flag "P", followed by flag "A" and finishing with flag "M". Any mixture of bodies which violates this ordering rule will produce an invalid definition file.

After the section describing the bodies' characteristics, there are included some integration parameters which setup the integrator. These parameters will be described later in the paragraph dedicated to the numerical integrator.

The SolSyIn package comes with some predetermined systems of bodies which model, very accurately, our planetary system. Thus, the files "moon.def", "sol-4.def", "sol-7.def", "sol-9.def", "sol-12.def" and "sol-13.def" describe some planetary configurations, very often used in dynamical problems related to the Solar System (you will find more details by reading their headers). These systems were obtained through JPL Horizons On-Line Ephemeris System from NASA.They have a very good accuracy, being obtained from a long-term ephemeris catalog named "DE-405", and used in spatial navigation. Also, in "Def" directory you will find the system "empty.def", which contains only the central body. It can be used to create completely new dynamical systems. These previously enumerated systems must be preserved in their initial form. Anyway, they can be renamed and multiplied using the program "System Maker".

Besides the liberty offered to the user in creating his own configurations of bodies, the SolSyIn package comes with several highly accurate catalogs of small bodies from the Solar System (asteroids and comets), which can be used to define real dynamical systems. At nowadays discovery rate, these catalogs have to be updated at least several times a year. We summarize below these five types of catalogs recognized by the package, togheter with details regarding their location on Internet:

1. The catalog of numbered asteroids

2. The catalog of numbered asteroids (high accuracy) 3. The catalog of short period comets 4. The catalog of near-Earth asteroids (NEO) 5. The catalog of near-Earth asteroids (with orbital uncertainty) In order to make the SolSyIn distribution as small as possible, the package does not contain the full version of these catalogs. Please read the file "catalogs.txt" located in "Cat" directory to find out the actual content of the catalogs. Their full version is included in the file "catalogs.zip" which extend the standard distribution.
 
diagram
In the next figure we present a standard usage scheme of the SolSyIn package, arranged on stages. At stage (I) the dynamical system is defined, using the adequate  program, next, at stage (II) this system is numerically integrated. At stage (III) the dynamical evolution of the integrated system can be graphically visualized. At stage (IV) we have the option to check the integration results and accuracy. At stage (V) a table containing some orbital parameters can be generated from the binary data file, and finally, at stage (VI) the variation of this parameters over time can be represented in various plots. Each stage is accomplished by using a specific program from the package, a detailed description of their usage being given n the next paragraph. At stages (III) - (V) the database created at stage (II) has to be present, otherwise each program will use just one record, the initial one which appears in the definitition file. In this manner, even before doing the integration, we can take a snapshot of the initial characteristics of the dynamical systems. Obviously, at stage (VI) the data table created at the previous stage has to be present.


5. Description of programs

In this section we will describe each program from the package, but not in the order given in the previous figure, rather than in a natural order of understanding the SolSyIn functionality.
5.1. Program "Solar System Integrator" (integrat.exe)

This program represents the most important component of the SolSyIn package. Its main task is to perform a numerical integration of a system of bodies. It uses the 15th order Radau-Everhart numerical algorithm, optimized for accurately handling close encounters, a classic integrator often used in the scientific literature for integrating small bodies in the Solar System. The system of bodies is propagated in time from the initial epoch, in accordance with the integration parameters from the definition file. They are described below:

The program "Solar System Integrator" has the ability to resume a previously interrupted numerical integration. To accomplish this task, it starts verifying if the system of bodies does have an associated data file. If it does, from this data file the integrator read the last record, and continues to integrate from here. If this data file is not compatible with the loaded definition file, then the program stops with the following warning message

Wrong file format!

In this case, this file has to be erased (it probably lasts from a previously integration). This process can be nicely initiated by calling the "Data File Remover" (remove.exe) utility.

Besides of all data fields appearing in the display window and describing the current state of the integration, we will highlight here only the following one

-last back-correction at

This field displays (when the SPACE key is pressed) the last moment of time in which the integrator has made such a kind of correction. As we have emphasized earlier, these corrections are initiated when the selected integration precision is too big and, consequently, the number of steps that are taken per unity of time is too small. In the mean time, when two bodies undergo deep close encounters, then the integrator will initiates such corrections. When the value from this field changes rapidly in time, it means that the dynamics just entered in a different state, requiring the modification of the integration precision (for example, when short period gravitational captures are taking place). A bad setup of the integration precision will alter substantially the integration speed, rather than the overall error of integration.

5.2. Program "System Checker" (checker.exe)

It can be used to obtain information about performed numerical integrations (page 1) and about the content of the generated databases (page 2). Here are displayed the ecliptic rectangular coordinates and keplerian orbital elements of the current body, relative to the central body. These two types of bodies can be identified with any body from the system, in accordance with their ordering number from the definition file. In this manner, we can visualize the orbital elements of the satellite systems (for example, the "Earth-Moon" system). "System Checker" is the only one program from the package that displays the calendrical data associated with the recorded moments of time.

Using the key combinations from page 1, it is possible to browse the database in sequence or by skipping data in blocks of about one hundred records. Also, there is a shortcut key to reach the end of the file. In the same manner, we can select the current body among all moving bodies from the system.

5.3. Program "Graphic Displayer" (display.exe)
 

This in the only one program from the SolSyIn package which has a graphic displayer. Next figure shows its screen appearance in false colors. This program is intended to represent graphically, in a bi-dimensional projection, the relative positions of bodies from the system. The many display options are as follows (ordered by their associated keys): We mention here also that the process of reading the records and the process of moving the map around can be performed manually with the help of keyboard's arrows.

5.4. Program "System Maker" (sysmaker.exe)

This is the most complex component of the SolSyIn package, offering to the user a large variety of defining dynamical systems. This task can be performed by explicitly feeding the coordinates given in different reference systems or by selecting a predetermined body from a catalog accompanying the package. It is possible to create new dynamical systems (starting with the system "empty.def"), or to modify/complete an existent one.

The program owns several display windows that will be described next:

Page 1

Here is the place where we can change the mass of the central body and the initial epoch of time. In the first case, the parameter can be changed without problems, but in the second one thinks are quite delicate, because the positions of bodies making the system have to be updated for the new epoch. For this reason, the program seeks itself into the associated database (if it exists) a recorded epoch of time as close as possible to the inputted one. After that, it asks the user for permission to perform a short numerical integration to match date entirely. At this moment, the user has to choose a name for a temporarily created system of bodies (usually "temp") - in this manner the program avoiding to overwrite an existent database. If the user does not agree with the program's request, than the closest found epoch of time is used instead, or even it is not changed at all. When we create a new dynamical system, starting with the "empty.def" definition file, there is no restriction in choosing the new epoch of time.

Further, there are three options for modifying the system: by keeping the number of bodies unchanged (only some integration parameter can be altered) - see page 2, including one new body into the system (well prescribed) - see page 3, or including several bodies with common dynamical characteristics (sampling) - see page 5.

Page 2

It's the last page of the program where some integration parameters can be changed. By pressing SPACE key, with the whole set of collected data, the program will create a new dynamical system of bodies. The user will be asked for a name. The program does not warn you when it overwrites the definition files!

Page 3

This is the page where a single body can be specified. First option requires the coordinates of the body to be selected - see page 4, and the others are for selecting a body from a catalog. In the last case the user has to be able to identify a body through its name or provisional designation or at least a fragment of them. Please consult the content of the catalogs from "Cat" directory for a better accustoming. Spaces from names are replaced with the symbol  "_". The first body from catalog matching the name (or the fragment) is selected. Furthermore, a body can be selected also by specifying its ordering number in catalog, preceded by the symbol "#" (for example, with the name "#1" selected for "astero.cat" catalog the program will choose the asteroid "1_Ceres").

The orbital elements of a body taken from a catalog are valid at a given epoch of time, generally, different than the initial epoch of the dynamical system. Thus, the program tries to match these different epochs in a manner being described at page 1. If we do not want to match them through a numerical integration, the program will place the selected body at the current epoch of time, which, of course, it's not correct. The message

Date matched!

notifies the user about the correctness of joining the body at the system.

Finally, we mention that the orbital elements of the bodies selected from catalogs are converted in rectangular coordinates, using for the mass of the central body a solar mass, so, not the mass selected at page 1. This method of computation assures the correctness of adding the body to the system.

Page 4

This is the page where we can select a body by introducing explicitly its coordinates. First of all, we have to specify the type of the body and (eventually) its mass. We can not break the rule, described previously, about ordering bodies against their type. The first displayed mass value is the mass of the last body already found in the system. We can specify also the coordinate type to be filled in (rectangular ecliptic or keplerian) and the relative body located at the origin of the reference frame. In the case of keplerian elements, the relative body must be of type "P", which is obvious, that is the reason for which this field is reset when we change the type of the coordinates.

In the case of rectangular coordinates, we have to supply the components of position and velocity vectors in the ecliptic reference frame. By default, the program chooses an initial position which corresponds to a circular motion at a distance of 1 UA from the central body (if it has one solar mass). For the keplerian elements, we have to supply the semimajor axis (a) or, alternatively, the periastron distance (q), eccentricity (e), inclination (i), longitude of ascending node (o), periastron argument (p) and mean anomaly on orbit (m) or, alternatively, the epoch of the periastron passage (t). The value of the eccentricity determines the type of the orbit (ecliptic or hyperbolic one) and, consequently, it has to be provided first. Choosing the alternative parameters, (q) and (t), will force the program to compute and display the values of the standard ones, (a) and (m), rather than those we are expected. Each parameter has two extreme values that can not be exceeded. These values depend on the type of the orbit. Also, it is not allowed to select a parabolic orbit.

Page 5

It is the page where we can choose several bodies at once having some common dynamical characteristics, i.e. they belong to the same region of space defined by some dynamical constraints. This method of selection is used for studying the dispersion of bodies in time. None of these bodies should have type "P", otherwise some singularities arise.

First option determines the user to provide explicitly the above-mentioned region of space - see page 6, and the second option is for selecting the uncertainty region of a NEO type asteroid taken from catalog. After reading all information about this uncertainty region, it will be uniformly sampled with bodies, in order to study the orbital uncertainty propagation of the nominal asteroid - see page 7. The manner in which we select a body from catalog is taking place under the same considerations described at page 3. If there are no information about the uncertainty region of an asteroid, the program will move to the final page, adding only the nominal asteroid at the newly created system.

Page 6

This page describes the option to add several bodies in the vicinity of an existent one, named further as parent body. For this reason, the parent body can not have the flag "P". If there are no such bodies into the system, the program stops with the message:

Parent body (with flag A or M) not found!

The type of bodies inserted in this manner coincides with the type of their parent body (in the case of "M" type bodies, they will have also the same mass).

The options here are similar with those described at page 4, the only difference being that the coordinates will represent now the dispersions of absolute values against those of the parent body. Moreover, we can choose the parent body and the number of "clone" bodies which fill uniformly the selected region of space. For rectangular coordinates, the relative body has no meaning.

Page 7

Here is the place where we select those parameter which determines the manner in which the uncertainty region selected at page 5 will be sampled with "clone" bodies. The parent body has the same significance as previously described. Initially, it is identified with the asteroid selected from catalog (named "nominal asteroid"), but further it can be switched with any other existent body from the system, having the flag "A", generally, placed very close to the nominal one. In this manner, we can sample only a limited area of the uncertainty region.

Other parameters have the following significance: standard deviation (it describes the extent of the uncertainty region in probabilistic terms, a value of 3 or 4 being usually a good choice), the percent of the uncertainty region which is going to be sampled (the area is centered on the selected parent body), or alternatively, the radius of the area to be sampled (this is a dimensionless quantity measured in the phase space of the equinoctial orbital elements) and sampling quality (it describes the preciseness in computing the percent that is selected previously, as long as this process is made approximately through a Monte-Carlo numerical procedure). After the entire sampling is performed, the program moves to the final page and displays the sampling error.

We have to notice that the "System Maker" program does not offer the possibility of changing the coordinates or the mass of an existent body. To do that, the user is invited to edit himself the corresponding definition file.

5.5. Program "Table Maker" (tabmaker.exe)

With the help of this program we are able to extract several dynamical parameters from the binary files created during the integration and to generate ASCII tables having fields separated by empty spaces.

The large amount of included options has required dividing them in two pages that will be detailed below:

Page 1

First of all, here is the place where we can select the type of the fields that will be generated:

After that, we have to select also: the set of bodies which are the subject of computation (given in an interval), the relative body against the motion is referred and the parent body against the previous described mutual parameters are referred.

Page 2

In this page we can set the following options: the interval of time over which the table is generated (the whole integration period is selected by default), the number of digits of numerical values generated into the table (if this number is bigger than 8, the exponential format will be used), the output mode of the data and the storing frequency.

Generally, the output mode of the data is selected by the program itself function of the generated parameters, but when the user chooses more than one body to be processed, he has the option to produce a table with the elements of each body (normal processing mode) or to compute the relative dispersions of these elements (compute dispersions mode).

By pressing SPACE key the program initiates the process of writing the table. This will be stored on disk as a file located in "Tab" directory. The user is able to monitor the progression of the writing process and to stop it at any time he wants. The generated table has a header where all previous selected options are displayed, so we can recognize later its contents.

5.6.Program "Plotter" (plotter.exe)

This program makes the connection between the SolSyIn package and GnuPlot graphic program, by putting options in its command line. It calls the graphic program and pass to it several plotting options. The user has to decide in which manner the table data is going to be processed, in accordance with its content. The directory "Plo\Hdr" contains some format files which send to the graphic program the ordering number of columns to be processed and other data. Generally, the name of these files coincides with the symbol used in Astronomy for a particular dynamical parameter (for example, by calling the file "a.hdr" in the command line of "Plotter" program, it will produce the plot of semimajor axis' variation).

In the option file "options.plo" the user can modify as well other plotting parameters, more representative one being the terminal type (the variants are: on screen, as "gif" image file or as "eps" image file). At this moment it is very useful to know a little bit of syntax of GnuPlot commands. In the next figure is represented the plot which has to be obtained by running the test dynamical system from the installing section, "test.bat". [The jump of the semimajor axis easily identified near the end of the integration period is due to a close approach with planet Venus - check yourself!].
 
 


6.Controlling the integration error

When we speak about a numerical integrator which, basically, approximates the motion of a system of bodies in space, we have to put into discussion the integration (approximation) error. We do not enter into details here, but we just want to emphasize that the overall error of integration has three different sources: (i) error in initial conditions of the problem (in our case, it depends on the error of astronomical measurements affecting the coordinates of the bodies at the observing epoch), (ii) intrinsic error of the integrator (it depends how the mathematical algorithm handles a specific dynamical evolution) and (iii) round-off error performed by the processor (it is related with the hardware characteristics of the mathematical coprocessor). Because the computations are not performed with infinite precision (ideal case), the last two types of errors act during the entire process of integration, resulting in an augmentation of the initial error. A first indication about the magnitude of the round-off error can be obtain by testing the such called machine accuracy, "epsilon". This parameter is the largest positive number verifying the equality "1+epsilon = 1". Unfortunately, this parameter is not zero, a value of about 1E-20 being specific to the entire spectrum of personal computers. Thus, starting with the 20th digit, one by one, every digit of a computed parameter is altered due to this cumulative effect of the errors.

This cumulative effect can be outlined by integrating a test system, "test-1.def", in two different ways. First, we perform a full integration and save the final coordinates of the moving body. Afterwards, we will erase the data file and start another integration. Now, if we stop this process
somewhere in the middle of its execution and then we will resume it until the end, the final results are slightly different than those saved previously (check yourself!). This behaviour is due to the propagation mechanism of the errors, propagation which takes place differently in these two integrations, because the intermediary integration steps are not the same (after a while). As a rule, on a different kind of computer we will obtain different final results, but all having the same magnitude.

This method of double integration can be performed also on the system "test-4". Comparing now the final results for the second body from the system, they will be completely different, which is very discouraging. Nevertheless, such kind of numeric anomalies can not be avoided as long as all floating point numbers are stored with finite precision into the computer. For a good integrator - which is the case of Radau-Everhart integrator - the speed of error's propagation depends solely on the chaotic character of body's motion. This chaotic behaviour can be measured by joining a "clone" body to the real one, sharing the same orbit, but with a very small difference in mean anomaly (for examples, a difference of about 10-8 degrees), and after that, by measuring this difference in time. As more chaotic the motion is, as quicker the bodies diverges in time, and this process does not depend on the type of the computer.

The error's propagation can be studied also using another approach, such called "reversibility test". A dynamical system is propagated along the entire interval span and, after that, the integration direction is reversed, and the system is propagated backward (specifying also a nil interval of integration). Comparing the initial and final coordinates of a body, we will have a measure of the error's propagation and also about the degree of chaos governing the motion.

The test systems: "test-1.def",..., "test-4.def" are intended to be used just for errors' measurements in various critical situations, starting with a regular orbit (test 1), with an orbit dominated by deep close encounters (test 2), with an orbit having a very short period (test 3) and, finally, with a very chaotic dynamical system (test 4). The numerical experiments performed with this integrator confirm that it handles very well the intrinsic error's propagation, in such a way that the overall error is just a measure of the chaotic degree of motion.

Using the program "System Maker" we are able to study the orbital uncertainty propagation of NEO type asteroids, which are representative for this kind of strong chaotic motions.


7. The list of some dynamical processes to be outlined

It's hard to imagine a list of all dynamical processes to be outlined with the SolSyIn package. Anyway, it was created primarily to point out the following dynamical processes:


8. Examples

In "Bat" directory there are several commented examples of real and fictive dynamical systems. They do not require the user assistance, only for their visualization. Thus Many other examples of dynamical systems, most of them being real, are given in "Def" directory, as definition files.
9. The list of warning messages
The SolSyIn programs, in critical situations, notify the user with the following warning messages:
 
File not found! This message is posted when the program tries to access a missing definition file or data file;
Wrong file format! This message is posted when the program tries to access a corrupted definition file or data file; In the first case, please verify if its data are consistent; In the last case, probably, this file belongs to a previous numerical integration of a different dynamical system and thus, it has to be erased;
No match! This message is posted when we want to modify the initial epoch of time of a dynamical system and this epoch is not found in the data file; The program will display the time difference and will ask for the permission to perform a numerical integration in order to match these epochs;
Date matched! This message is posted when the program matches correctly the epochs of time, when it is required; 
Object not found! This message is posted when the program do not find in a catalog an object matching the name or the fragment of it, provided by user;
Parent body (with flag A or M) not found! This message is posted when the program tries to sample a region of space with bodies, and there is no parent body in the system with an adequate flag;
Sampling failed! This message is posted when the user stops the sampling process of a space region with bodies, by pressing ESC key; As a rule, by decreasing the sampling quality, it drastically diminishes the time in which this process is performed.

The programs "Plotter" and "Data File Remover" do not display any warning message to the user, but when they are called without command line parameters, then a usage screen is displayed. The user is not informed when any of these parameters are erroneous, but the waited process is simply not performed.


10. Useful addresses

In this section we list several internet addresses from where some programs can be found and also some information about catalogs.

Software

Catalogs

Copyright (c) 2001 by Stefan Berinde