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:
-
The numerical integrator - It uses
for integration the 15th order Radau-Everhart numerical algorithm, well
known for its great accuracy in integrating a general system of bodies.
It is quite efficient, for example, using a Pentium II computer, it reproduces
the dynamical evolution of all nine planets from our Solar System (Mercury-Pluto),
moving in their common gravitational field, during 1,000 years interval,
in just few minutes.
-
Checking the accuracy - This integrator
internally manipulates the integration accuracy, by changing correspondingly
the integration step size, assuring itself that a quick convergence to
the solution is achieved on each step. The global error of integration
entirely dissipates in the chaotic fluctuations associated with the motion's
orbital uncertainty. Practically, the integration accuracy is just a measure
of the chaotic degree of motion and it can be measured in several ways,
which will be explained later in this manual.
-
Graphical display - More than can be
explained here...it can be seen right there!
-
Creating new dynamical systems - Paradoxically
maybe, this item represents the most complex component of the SolSyIn
package. It is possible to create new dynamical systems or older ones can
be completed with bodies, in various ways: by specifying the coordinates
or orbital elements in different reference systems, by adding real asteroids
and comets taken from the most important databases over Internet, by sampling
a region in real space or in the phase space of orbital elements (the uncertainty
region) with an arbitrary number of bodies. Only the available resources
of your computer limit the complexity of created systems.
-
Extracting data - Shortly, from the
database that is created during integration it is possible to extract several
dynamical parameters (such as rectangular coordinates in corotational systems,
orbital elements, mutual distances, libration arguments of resonances,
coordinates in target plane - necessarily for evaluating impact conditions,
etc).
-
Creating plots - All previous mentioned
parameters can be graphically represented with the help of GnuPlot graphic
program (freely available over Internet), through specific command files
contained in the SolSyIn 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
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:
-
planet - with flag "P", has considerable
mass and exerts gravitational influence upon all other bodies from the
system; stars, planets, natural satellites and (eventually) bigger asteroids
should enter into this category;
-
asteroid - with flag "A", has no mass
and, therefore, exerts no influence upon other bodies; asteroids, comets
and artificial bodies should enter into this category;
-
meteoroid - with flag "M", has small
mass, but exerts no influence upon other bodies. On the other hand, it's
receptive at the radiative field of the central body (its intensity is
set at the intensity of the solar radiative field); meteoroids from meteor
streams should enter into this category.
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
-
name in package: 'astero.cat'
-
number of objects: over 20.000
-
producer: DASTCOM Database - JPL's
Solar System Dynamics Site
-
Internet location: http://ssd.jpl.nasa.gov/data/ELEMENTS.NUMBR.gz
-
size: 0.9 Mb (ASCII gzipped archive)
-
content: keplerian orbital elements
of all numbered asteroids at the same epoch, togheter with their proper
names;
2. The catalog of numbered asteroids (high
accuracy)
-
name in package: 'astdys.cat'
-
number of objects: over 20.000
-
producer: Asteroids Dynamic Site (ASTDYS)
-
Internet location: http://hamilton.dm.unipi.it/astdys/catalogs/allnum.cat
-
size: 2.5 Mb (ASCII)
-
content: keplerian orbital elements
with high accuracy of all numbered asteroids at the same epoch, togheter
with their visual magnitude parameters;
3. The catalog of short period comets
-
name in package: 'comets.cat'
-
number of objects: over 300
-
producer: DASTCOM Database - JPL's
Solar System Dynamics Site
-
Internet location: http://ssd.jpl.nasa.gov/data/ELEMENTS.COMET
-
size: 0.04 Mb (ASCII)
-
content: cometary orbital elements
of the majority of short period comets and also of some hyperbolic and
dead comets (see the fragments of Shoemaker-Levy 9) at the perihelion passage
epoch, togheter with their names;
4. The catalog of near-Earth asteroids
(NEO)
-
name in package: 'neodys.cat'
-
number of objects: over 1.300
-
producer: NEO Dynamic Site (NEODYS)
-
Internet location: http://newton.dm.unipi.it/neodys/neodys.cat
-
size: 0.2 Mb (ASCII)
-
content: keplerian orbital elements
with high accuracy of all NEO type asteroids at the same epoch, togheter
with their visual magnitude parameters;
5. The catalog of near-Earth asteroids
(with orbital uncertainty)
-
name in package: 'neocov.cat'
-
number of objects: over 1.300
-
producer: NEO Dynamic Site (NEODYS)
-
Internet location: http://newton.dm.unipi.it/neodys/neodys.ctc
-
size: 2.0 Mb (ASCII)
-
content: equinoctial orbital elements
with high accuracy of all NEO type asteroids at the same epoch, togheter
with their covariance and normal matrices, which describe the orbital uncertainty,
and their visual magnitude parameters.
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.
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:
-
include relativistic effects - when
it is enabled, the newtonian gravitational field of the central body is
replaced with the relativistic one, in order to distinguish some fine relativistic
effects;
-
integration direction - forward / backward;
-
integration precision - this parameter
does not establish properly the integration precision, but it gives to
the integrator an information about the number of steps to be taken per
unity of time. It appears inside the mathematical theory of the numerical
algorithm. When the system of bodies experiences a short term periodicity,
the number of integration steps has to be larger, which means a smaller
value taken for this parameter. There is no prescription about setting
up its value, but there is a trick to be made: from several tests with
different values we will choose that one which produces the highest integration
speed. This mode of selection is based on the following behaviour of the
integrator: as smaller the precision parameter is, as smaller the speed
of integration becomes (due to a larger number of intermediary steps) and,
on the other hand, for large values of that parameter, the integrator -
trying to preserve the intrinsic precision of integration - will perform
such called "back-corrections". These corrections force the integrator
to repeat the computations on the previous step, in this way improving
the results, but this process, obviously, consumes extra time. It always
exists a value which maximizes the integration speed and this is the optimum
one. A value of about 1E-12 has proven to be a good choice in many cases;
-
interval of integration - it is measured
starting from the initial moment of time declared in the definition file
of the system;
-
frequency of stored data - for long
span numerical integrations the generated database becomes huge in size.
If we are not interested in all intermediary results, thus this database
is a waste of space. To remove this unpleasant effect we have the option
to store intermediary results only at a given frequency;
-
number of body whose minimum distances
are recorded - in many dynamical problems we have to find out the minimum
distances between various bodies from the system. If the storing frequency
described previously is above 1, then important intermediary results might
be skipped and, consequently, minimum distances are not properly recorded.
For this reason, this parameter, if different than zero, it indicates that
body from the system for which all mutual distances are recorded. The integration
speed, in this case, is not significantly diminished.
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):
-
axes ("A") - displays in the top right
corner the projection plane's axis of the image;
-
central body ("B") - selects the central
body taken from the entire set of bodies, accordingly with their ordering
number from the definition file; in this manner, we can visualize trajectories
in satellite systems;
-
continuous ("C") - selects the display
mode: continuous, through points, without erasing previous positions -
trajectories; and discontinuous, through filled circles, and erasing previous
positions;
-
big points ("G") - selects the size
of points which make up trajectories;
-
colors ("L") - switches from colored
and only white representation of bodies on screen;
-
numbering ("N") - displays the ordering
number of each body when the discontinuous display mode is enabled;
-
orientation ("O") - selects the projection
plane's axes of the image: the axis OX points toward the vernal point,
the axis OZ is perpendicular onto ecliptic plane and the axis OY is making
a right-oriented rectangular reference system with the other two axes;
-
progression ("P") - displays a progression
bar in the bottom right corner of the image, showing the percent of records
being read from the data file;
-
running ("R") - starts/stops the sequential
browsing process of records from a data file;
-
speed up ("S") - increases the reading
speed of the records by skipping them in blocks of about one hundred;
-
restart ("T") - performs the first
record reading from a data file;
-
velocity ("V") - displays the velocity
vectors of each body, relative to the selected central body, when the discontinuous
display mode is enabled;
-
zoom ("+ / -") - increases/decreases
the zooming factor of the image, relative to the selected central body.
An image scale is shown at the bottom of the menu. The scaling interval
is between 100 UA - 0.0001 UA (astronomical units);
-
screen to bitmap (SPACE) - captures
the screen's image into a black-white "bitmap" file, which is stored on
disk under the name "screen0.bmp", "screen1.bmp", etc.
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:
-
rectangular coordinates - (x,y,z) components
of the position vector; if the value of the parent body's field appearing
below is not zero, these coordinates will have instead the meaning of corotational
coordinates taken in a reference frame rotating with the same period as
parent body is doing around the central one.
-
keplerian orbital elements - (a,e,i,o,p,m)
in respect to the relative body;
-
equinoctial orbital elements - (a,h,k,p,q,l)
in respect to the relative body;
-
various distances - the mutual distance
between two bodies (r), the minimal distance between two osculating keplerian
orbits (moid) and Tisserand parameter (tiss), all in respect to the parent
body;
-
mean motion resonance - the parameters
describing such a resonance are the semimajor axis (a) and libration argument
of the resonance (sigma); the user have to introduce first the resonance
ratio; this resonance is given in respect to the selected parent body;
-
coordinates in target plane - they
are bi-dimensional polar coordinates (d, phi), measured in a plane perpendicular
onto the direction of motion of the body when it makes the closest approach
to the target body (parent body); used for impact probability computations.
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:
-
obtaining the trajectory and the variation
of orbital elements of a body (taken from catalog) in the Solar System
(for example, the Halley comet shown previously);
-
identification of close encounters between
bodies (especially with the Earth);
-
long term variation of mutual distances between
the osculating orbits of two bodies (the distance "moid", especially between
Earth and a small body);
-
evaluating the degree of chaos of a motion
by numerically computing the maximum Lyapounov exponent;
-
identifying resonant motions (both mean motion
resonances and secular ones);
-
identifying protection mechanisms against
close encounters (mainly with the Earth);
-
orbital uncertainty propagation of NEO type
asteroids;
-
finding impact conditions and impact probabilities
with the Earth of NEO type asteroids;
-
computing meteoroids' dispersions in meteor
streams.
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
-
"test.bat" - simulates the dynamical evolution
of comet Halley in the Solar System, for one century (this system is used
for a quick test of the SolSyIn package);
-
"345.bat" - simulates an old and famous problem
of celestial mechanics: "What is the evolution of three particles forming
a Pythagorean triangle (with sides 3,4 and 5) and having their masses proportionally
with the opposite sides in the triangle?". After a chaotic evolution, two
bodies form a binary system and the third one is moving away on a sinusoidal
orbit;
-
"epicycle.bat" - this system produces embedded
satellite systems, remembering the "Epicycles Theory" used by ancient astronomers
to explain the apparent motion of the planets;
-
"impact.bat" - it reproduces the well known
impact on Jupiter of the 21 fragments from the dead comet Shoemaker-Levy
9. The initial configuration of the fragments coincides with that one photographed
by Hubble space telescope several months before the impact;
-
"intruder.bat" - it produces a virtual scenario
in which a star weighted a half solar mass is passing near the Sun and
destabilizes our planetary system.
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
