Moving Planets Around (MPA) Project

This repository has been moved to the MovingPlanetsAround/ABIE repository and will no longer be updated. The book associated with the ABIE code Moving Planets Around has been published by the MIT Press in September 2020. See https://mitpress.mit.edu/books/moving-planets-around.

The Alice-Bob Integrator Environment (ABIE)

The source code of ABIE is stored under the directory ABIE. From this particular directory, ABIE can be launched with

python abie.py -c ../Test_ABIE/solar_system.conf -o output.hdf5

Where ../Test_ABIE/solar_system.conf is the path and file name of the initial condition config file. output.hdf5 is the file name of integration data output.

ABIE also support loading initial conditions from Rebound data file (requires Rebound). For example, one can use ABIE to evolve a system with Kozai-Lidov generated by Rebound:

python abie.py ../Test_ABIE/kozai_lidov.reb -t <t_end>

The argument t_end is needed because Rebound doesn't store the termination time in its data files.

The unit of t_end depends on the setting of CONST_G parameter.

Using ABIE as a library

ABIE can also be executed programatically. You could install ABIE as a python package:

python setup.py install

Note that setup.py is in the parent directory of ABIE's main source code directory. See an example in the run.py file.

ABIE output format

ABIE uses the HDF5 format to store its integration output data. The internal layout of the HDF5 file looks like this:

/Step#0
    ecc: eccentricities of each object (1 - N) as a function of time (0, t-1): [t * N] array
    inc: inclinations of each object (1 - N) as a function of time (0, t-1): [t * N] array
    hash: unique integer identifier for each particle: [t * N] array
    mass: masses of each planet: [t * N] array
    ptype: particle type of each object. 0 = massive particles; 1 = test particles; 2 = low-mass particles. [t * N] array
    radius: radius of each object. [t * N] array
    semi: semi-major axis of each object. [t * N] array
    time: the time vector. [t * 1] vector
    vx: [t * N]
    vy: [t * N]
    vz: [t * N]
    x: [t * N]
    y: [t * N]
    z: [t * N]
/Step#1
    ...
/Step#2
    ...
...
/Step#n

For efficient output, ABIE maintains a buffer to temporarily store its integration data. The default buffer length is set to 1024, which means that it will accumulate 1024 snapshot output until it flushes the data into the HDF5 file and creates a Step#n group. The resulting HDF5 datasets can be loaded easily using the h5py package:

import h5py
h5f = h5py.File('data.hdf5', 'r')
semi = h5f['/Step#0/semi'].value
ecc = h5f['/Step#0/ecc'].value
...
h5f.close()

Sometimes, it is more elegant to get rid of the Step#n data structure in the HDF5 file (i.e. combine Step#0, Step#1, ..., Step#n into flatten arrays. The ABIE package contains a tool to seralize the snapshot. For example, suppose that ABIE generates a data file data.hdf5 contains the Step#n structure, the following command

python snapshot_serialization -f data.hdf5

will generate a flattened file called data (still in hdf5 format). In this case, the data can be accessed in this way:

import h5py
h5f = h5py.File('data.hdf5', 'r')
semi = h5f['/semi'].value  # gets the semi-axis array for the entire simulation
ecc = h5f['/ecc'].value    # gets the eccentricity array for the entire simulation
...
h5f.close()

Integrators and Computational Acceleration

ABIE implements all its integrators in both Python (for educational purpose) and in C (for performance). The currently supported integrators are:

Forward Euler integrator
Leapfrog
Adams-Bashforth
Runge-Kutta
Gauss-Radau15 (default)
Wisdom-Holman

By default, ABIE will execute the C implementation of the Gauss-Radau15 integrator. This integrator is well-optimized and preserves energy to ~ 10^{-15}. To change the integrator and use the python implementation, one could either edit the config file:

 [integration]
 integrator = 'GaussRadau15'
 # integrator = 'RungeKutta'
 # integrator = 'LeapFrog'
 tf = 356
 h = 0.1  # optional for certain integrators
 t0 = 0.0
 acc_method = 'ctypes'
 # acc_method = 'numpy'

Or use the Python script:

from ABIE.abie import ABIE
sim = ABIE()
sim.CONST_G = 1.0
sim.integrator = 'GaussRadau15'

Improve the precision of ABIE

By default, ABIE uses double precision. For some special cases (for example, integrating a Kozai-Lidov system where the eccentricity can be very high), the precision of the integrator can be adjusted by simply changing the following lines in Makefile from

LONGDOUBLE = 0

LONGDOUBLE = 1

And run make clean; make again. This will causes the integrator to use the long double data type. When using the Gauss-Radau15 integrator, the energy conservation can be better than 10^{-16} in this case (shown as dE/E = 0 in the terminal), even after evolving the system through multiple Kozai cycles. This, however, will takes about 2x time to finish evolving the same system.

Accelerate ABIE using CUDA/GPU

ABIE supports GPU acceleration. For large N systems (N>512), using the GPU could result in substential speed up. To enable the GPU support, modify the Makefile from

GPU = 0

GPU = 1

And then recompile the code. Note that it is not recommended to use GPU for small N systems.

maxwelltsai / ABIE