SOME REMARKS ABOUT THE SOFTWARE


Contents
--------

When the mac.tgz file is opened, it creates the following
subdirectories:

mac
mac/bin
mac/data
mac/doc
mac/src

Directory mac contains the README.1st file, that should be the first
file to read.

Directory mac/bin will contain, after compilation, the binary file for
each program.

Directory mac/data contains the input data files as well as the output
of the programs.

Directory mac/doc contains the documentation.

Directory mac/src contains the source code as well as the makefile.

As it is explained in the doc file mac.ps, this is not a package like
Maple. This is a set of routines that perform some operations on
polynomials of several variables. My idea to write this is to show how
to code such routines, not to build a ready-to-use package. However,
I've added some main programs in order to show how these routines
work. The explanations on the algorithms used are in the file
mac.ps. If you look into the source code, you'll see some routines
that are very similar (they only differ, for instance, in the type of
some parameters). This repetition can be elliminated by using some of
the capabilities of C++. Moreover, not all the routines present in
these files are actually used. Some of them (like reb6s and reb6p,
that are in the files io6s.c and io6p.c) were used during the
developping/debugging stages; I haven't removed them from this final
version.

Note all the programs are written in ANSI C, with a single exception:
to have complex arithmetic, we have used C++ to overload the
arithmetic operators. So, the files ending with .cc contain C code but
they use complex arithmetic, and they are compiled with a C++
compiler. As sometimes I use this with a different arithmetic
(interval, for instance), I've re-written the overload of the complex
operators (this is contained in the file arit-c.h) but, instead of
defining a complex as a couple of doubles, I've defined it as a couple
of variables of type renum (it stands for real number). In the present
version of the software, file arit-c.h includes, at the beginning, the
file arit-r.h that defines renum as double. If you want to change the
basic aritmetic to a different one (interval, multiple precision,
rational, etc.), you have to put the new definition of type renum in
arit-r.h as well as the corresponding definitions to overload the
arithmetic operations. Then, you only need to introduce the
corresponding modifications in my input/output routines (they are
written in C) in order to handle the new type.

Finally, a technical remark. As it is explained in the paper mac.ps,
there are some hypotheses needed for this algorithms to work. We note
that this code does not check those hypotheses (for instance, the
nonresonant conditions) since, in the examples used here, I know in
advance that they are satisfied. If the reader wants to change some
parameters (or even the whole example), he/she has either to check
those conditions or to modify the code in order to have those
conditions checked.


Building the examples
---------------------

To compile the examples, go to the directory mac/src and edit the
makefile. In the first lines you can set the name of your C and C++
compilers, as well as the corresponding flags to use during
compilation and linking. The ones I've left there correspond to the
GNU C/C++ compiler (they are called gcc and g++). For instance, these
options should work smoothly if you are working on a Linux PC (all the
linux distributions I know come with those compilers installed). If
you are on a different system (without gcc/g++ installed), you should
put the corresponding values at the beginning of the makefile.
Remember that some compilers need a special flag to deal with ANSI C
source code. If you have to do modifications to the makefile, let me
know your operating system, your compiler and the options you use.
I'll add this information to the makefile.

In the makefile there are a few parameters to tell the programs some
default directories for several purposes. More concretely, there is
the definition of the BIN directory (where the binaries of the
programs will be left) and the DATA directory, that is the default
place used for the programs to look for and write the several
input/output files needed. Note that I've used relative pathnames, but
it is probably better to use absolute ones. I use the default values
I've left there, starting the programs either from the bin directory
(typing, for instance, './nf') or from the data directory (typing then
'../bin/nf').

Once the makefile has been set up, you can compile the programs. You
can type 'make all' (that will compile and link all the examples) or
you can only compile some of them, typing 'make' followed by the name
of the program you want to build up (below you'll find the names). The
binaries are left in the directory mac/bin (unless you have changed
this in the makefile).

Let us note that the name of the several files used by the programs
are defined in 'files-nf.h' (files related to the normal form),
'files-cm.h' (files related to the central manifold) and 'files-fi.h'
(files related to the first integrals).

The name of the different programs is the following:

 1.- nf: computation of the normal form around L5.

 2.- cm: computation of the centre manifold around L1, L2 and L3.

 3.- fi: computation of first integrals around L5.

 4.- cvnf: computation of the expansions of the changes of variables
     for the normal form computed by nf.

 5.- cvcm: computation of the expansions of the changes of variables
     for the central manifold computed by cm.

 6.- tcnf: transformation of a set of points from normal form
     coordinates to synodical ones, and viceversa.

 7.- tcdcm: transformation of a set of points from the central
     manifold into synodical coordinates (the reverse change has not
     been implemented).

 8.- ninf: numerical integration of the vectorfield of the normal form
     obtained by nf.

 9.- nicm: numerical integration of the vectorfield of the central
     manifold obtained by cm.

10.- rtbp: estimate the error (by means of numerical integration of
     the restricted three-body problem) for the normal form and
     central manifold computations. This is a testing program.

11.- efi: evaluation of a first integral. This is a testing program.

Note that you can also type 'make clean', that will erase all the
object files (.o) in the mac/src directory and all the files in the
mac/bin directory. The output files left in the data directory have to
be erased manually.

In the next section there are some hints about how to run these
programs.


Running the examples
--------------------

Here we will explain the input taken by these programs, as well as the
output produced. The output of the program to the screen is only to
inform you about what it is doing at each moment. Since this is not
necessary for understanding neither the inner working of the programs
nor the results (that are stored in files), we will not give any
explanation. For details, look into the source code. We only recall
that the expansions computed by these programs are asymptotic series,
and that they are only accurate in a small neighbourhood of the
corresponding equilibrium point. For examples of the results obtained
in this kind of computation, look at the references [11], [26], [27]
and [47] in mac.ps (related calculations can be found in ([14], [28],
[29], [32] and [50]).

 1.- nf. it has two parameters. the first one is the mass parameter of
    the rtbp and it is given in the source code (it is the value
    assigned to the variable called 'mu' at the beginning of the file
    'main-nf.cc'). The second parameter is the degree ('n') of the
    power expansion of the Hamiltonian that we put in normal form
    (hence, the final normal form will contain terms up to degree
    n/2 in the final action variables). The program asks for this
    value at the begining of the execution.

    The program writes to the screen some information about what it is
    doing. The important part of the output is left in several files,
    in the directory mac/data:

    nf.ctl: ascii file with the two parameters used in the present
       run. In the first line there is the degree used for the
       expansions and, in the second line, the value of the mass
       parameter.

   nf.cvl: ascii file with the (real) change of variables that puts
      the linearized vectorfield around L5 in real normal form. This
      file is needed by program tcnf.

   nf.gen: binary file with the several generating functions used to
      put the Hamiltonian in normal form. This file is used by program
      cvnf.

   nf.res: ascii file with the final normal form. This file is used by
      program ninf.

 2.- cm. it needs three parameters. the first one is the mass
    parameter, that is assigned in the source code (beginning of the
    file 'main-cm.cc') to a variable named 'mu'. The other two values
    are asked interactively. They are: the libration point, that must
    be 1, 2 or 3, and the degree of the expansion of the Hamiltonian.
    The Hamiltonian restricted to the central manifold will be given
    up to the same degree.

    The output is given in four files plus the screen. The files are:

    cm.ctl: ascii file with the parameters used in the present
       run. The first line contains an integer number (1, 2 or 3)
       referring to the libration point (L1, L2 or L3). The second
       line contains the degree of the power expansions. The third
       line contains the mass parameter used, and the fourth one
       contains the distance from the libration point to the closest
       primary. This value is used by program tcdcm.

    cm.cvl: ascii file with the (real) change of variables that puts
       the linearized vectorfield around the collinear point in real
       normal form. This data is used by program tcdcm.

    cm.gen: binary file with the several generating functions used to
       uncouple the centre part of the Hamiltonian from the hyperbolic
       one. This file is used by program cvcm.

    cm.res: ascii file with the Hamiltonian reduced to the centre
       manifold. This is used by program nicm.

 3.- fi. It needs five parameters. The first one is the degree of the
    expansions used. The second, third and fourth parameters are
    coefficients used to determine the first integral (see file
    mac/doc/mac.ps). The last parameter is the mass value 'mu', that
    it is assigned in the source code, at the beginning of the file
    'main-fi.cc'.

    The output is stored in the files (plus the usual information
    given through the console):

    fi.res: ascii file with the computed first integral.
    fi.ctl: ascii file with the parameters used.
    fi.cvl: ascii file with the linear changed used for the linear
       normal form around L5.

    warning: as the name of this program (fi) coincides with a command
    of some shells (like bash), you should start it by also typing the
    path. This is, if you are in the bin directory, type './fi'
    instead of 'fi' (there are many other workarounds for this --like
    changing the name of the program--, use the one you like).

 4.- cvnf. It looks for the file mac/data/nf.gen (see above). It asks
    (interactively) for the degree up to which the changes are desired
    (of course, this value must be less than or equal to the maximum
    degree of the generating function stored in nf.gen. Moreover, the
    program also asks for which change we want to compute, the direct
    one (from normal form to initial coordinates), the inverse one, or
    both.

    The output is stored in several files:

    cvnf.[1-6]: binary files with the power expansion of the direct
       change of variables. The number between 1 and 6 in the
       extension field of the name of the file refers to the
       coordinate (1 is x, 2 is px, and so on).

    cvnfi.[1-6]: binary files with the power expnasion of the inverse
       change of variables. See the remarks for files cvnf.[1-6].

 5.- cvcm. It looks for the file mac/data/cm.gen (see above). It also
    asks interactively for the degree up to which the changes are
    desired (this value can not be bigger than the degree up to
    which the centre manifold hs been computed). The program only
    computes the change that goes from the centre manifold
    coordinates to the initial ones.

    The output is stored in six files:

    cvcm.[1-6]: binary files with the power expansion of the change of
       variables. The numbers 1,2,...,6 have the same meaning as for
       the files cvnf.[1-6] (see above).

 6.- tcnf. It needs three values in the command line. The first one
    contains phase space points, in the same format as the file
    ninf.res (see below). The second parameter is the name of the
    output file. It will contain the transformed points in the same
    format as the input file. The third parameter is a flag with two
    possible values: if it is 1, the transformation goes from normal
    form coordinates (i.e., the output file of the program ninf) to
    initial ones; if it is -1 performs the reverse transformation (we
    note that, in both cases, the first file is the input file and the
    second one is the output file).

    The program needs the files nf.ctl, nf.cvl and cvnf.[1-6] (see
    above). All of them are assumed to be in the directory mac/data.
    If the flag is 1, the program also writes a file called 'rtbp.mu',
    that contain the mass parameter corresponding to this data. This
    is done in order to pass this value to program rtbp, that performs
    a numerical integration of the restricted three body problem (see
    below).

 7.- tcdcm. It needs the name of two files in the command line. The
    first file contains initial conditions corresponding to the
    centre manifold, in the same format as the file nicm.res (see
    below), and it is supposed to be in the directory mac/data. The
    second file given in the command line is the name of the desired
    output file, and it will be created in the directory mac/data with
    the same format as the input file. If the program is invoked with
    an empty command line (or with a wrong number of arguments), it
    issues a short help message.

    The program also looks for the files (all of them in the directory
    mac/data) cm.ctl, cm.cvl and cvcm.[1-6] (see above). The program
    also writes the file 'rtbp.mu'. See the reamrks given for the
    program tcnf.

 8.- ninf. It needs the files nf.res (see above) and ninf.dad: this is
    an ascii file (with only two lines) that is provided by the user.
    The format is the following:
         np
         a1 a2 a3
    where (a1,a2,a3) refers to the initial condition (for the normal
    form coordinates) given by the three actions a1,a2,a3 and taking
    the corresponding phases equal to zero. np is the number of points
    of the corresponding trajectory that we are going to compute. As
    the normal form is integrable, the trajectory is obtained by
    computing closed formulas. The timestep used has been of 0.1
    units, but any other value is possible.

    These resulting points will be stored in the output file:

    ninf.res: ascii file with the computed trajectory. The format of
       the file is
           np nd
           x0 px0 y0 py0 z0 pz0
           x1 px1 y1 py1 z1 pz1
           .   .  .   .  .   .
           .   .  .   .  .   .
           .   .  .   .  .   .
       where np is the number of points in the file and nd the number
       of coordinates for each point (in this case, this is obviously
       6). This has been done in order to use the same routines for
       cases with points with four coordinates (see below).

 9.- nicm. It needs the files mac/data/cm.res (see above) and
    mac/data/nicm.dad: This is an ascii file (with only two lines)
    that has to be created by the user. The format is the following:
         np
         x px y py
    where (x,px,y,py) is an initial condition in the centre manifold
    and np denotes the number of points (of the trajectory defined by
    the initial condition (x,px,y,py)) that are computed and stored in
    the output file mac/data/nicm.res. The np computed points are
    obtained by numerical integration of the differential equations
    associated to the Hamiltonian reduced to the centre manifold. The
    numerical integrator uses a a couple of Runge-Kutta methods of
    order 7 and 8 to implement error estimation and an automatic
    stepsize control. In the present version of the program, the
    stpsize is fixed to the value 0.1, that produces a small enough
    error for the runs I've been doing, but you can change this in
    order to use the automatic stepsize control (see instructions
    inside the file rk78.c).

    The program writes to the console the point number, the value of
    the stepsize used (that is now a constant value) and the value of
    the Hamiltonian, that must remain almost constant (its variation
    is due to the numerical integration). The computed points are
    stored in a file:

    nicm.res: ascii file with the computed points (all of them belong
       to the same trajectory inside the centre manifold). The format
       is the following:
          np nd
          x0 px0 y0 py0
          x1 px1 y1 py1
          .   .  .   .
          .   .  .   .
          .   .  .   .
       where np is the number of points in the file and nd the number
       of coordinates in each point (in this case, this is obviously
       4). This has been done in order to use the same routines for
       cases with points with six coordinates.

10.- rtbp. It needs the files rtbp.mu (to read the mass parameter) and
    rtbp.dad, both from directory mac/data and both in ascii format.
    File rtbp.dad must have the same format as file ninf.res (see
    above). The program checks if all the points in the file rtbp.dad
    belong to the same trajectory. To do that, it integrates
    numerically the (exact) equations of the rtbp starting from each
    point in the file, and printing (to the standard output) the
    difference between the numerical prediction and the following
    point in the table. The numerical integration is done by means of
    the numerical integrator contained in the file rk78.c. Of course,
    the time step has to be the same used when creating the table that
    we are testing. As mentioned before, we have used a time step of
    0.1 adimensional units, since it is enough for our purposes. There
    is no problem in using a smaller step size, but if you want to use
    a bigger one you should modify a little bit some of these
    programs. The reason is that you can not call the rk78 routine
    with a big (and constant!) time step and to expect accurate
    results. You should use then either the stepsize control facility,
    or to split this call in several consecutive calls with a smaller
    step size.

    This program does not write any file.

11.- efi. it needs the ascii files fi.ctl, fi.cvl, fi.res (see above)
    and efi.dad (they are all assumed to be in the directory mac/data).
    File efi.dad contains only two lines, with the following format:
         np
         dx dpx dy dpy dz dpz
    The second line is the initial condition, but the coordinates used
    are centered at the equilibrium point L5. The program integrates
    numerically the rtbp vectorfield (using the rk78 routine with
    automatic selection of step size) and evaluates the first integral
    (stored in the file fi.res) computed by program fi. The number of
    time steps is given at the first line of file efi.dad. The user is
    asked interactively to provide the degree up to which the first
    integral is going to be used (of course, it is assumed that such
    degree has been previously computed by fi and stored in fi.res).
    The output is written to the console, with the following format:
    the first column denotes the time (the initial condition is taken
    at t=0), the second is the value of the first integral, the third
    value is the absolute difference between the value of the first
    integral at the initial condition and the value at the present
    point, the last column is the third one divided by the value of
    the first integral at the initial condition.

    This program does not write any file.


Barcelona, December 28th, 1997.

Angel Jorba
Departament de Matematica Aplicada i Analisi
Universitat de Barcelona
Gran Via 585
08007 Barcelona (Spain)

E-mail: angel@maia.ub.es
Web: http://www.maia.ub.es/~angel