Choosing an integrator method

The Console offers a number of integration algorithms, which can be selected using the toolbar “Integrators” combo box. In a script session, the method Kernel.setIntMethod() selects the integration method to be used in the calculations following the method call. The following algorithms are available by default:

intMethod flag	Name
0	Keplerian
1	Runge-Kutta (adaptive stepsize)
5	Hermite 4th order
6	Hermite 4th order (fast variant)
7	Gragg-Bulirsch-Stoer

Writing a custom integrator

When accuracy or speed goals are not met by the default integrator, the Console can be extended with user-written code for integration. An integrator routine for the Systemic console is a compiled Java class that implements the '''Integrator''' interface (see any introductory Java book for a definition of interfaces). The code for the Integrator.java interface is included in the integrators/ directory and is reproduced as follows:

package stellarDynamics;

public interface Integrator {
    public double advance(double[][] xyzParam, double timeInterval, double tstep);
    public boolean hasCloseEncounter();

    public String getAuthor();
    public String getVersion();
    public String getDesc();
    
    public Object getProperty(int property);
    public void setProperty(int property, Object value);    
}

A class that implements the Integrator interface must implement the following methods:

• getAuthor(), getVersion() and getDesc() must return a String containing the name of the author, the version and a description of the integration routine.
• getProperty() and setProperty() are not required to be implemented and are reserved for future versions of the console (write an empty method definition).

The advance() and hasCloseEncounter() methods

double advance(double[][] xyzParam, double timeInterval, double tstep);

The advance method is advances the cartesian configuration for a time span timeInterval, given the vector of masses, cartesian coordinates and velocities xyzParam. The tstep parameter can be used as a hint for timestep and must be returned at the end of the routine.

xyzParam is a double[][] matrix containing, for each object (central star + N planets), the following information:

• [i][0]: mass of object i
• [i][1]...[3]: position coordinates of object i
• [i][4]...[6]: velocity coordinates of object i

xyzParam should be updated with the new positions and velocities at time ''timeInterval''. timeInterval represents, for instance, the distance between RV data points, sampling times for stability analysis or difference in time between two transits observations.

If a close encounter with the star or between planets is encountered within timeInterval, then the method hasCloseEncounter() should return true, otherwise false.

The first lines for a custom integration class '''MyIntegratorClass''' should read as follow:

package stellarDynamics;

public class MyIntegratorClass implements Integrator {

... code here ...
}

Compilation

The following command will compile the class:

javac MyIntegratorClass.java Integrator.java

and will produce a MyIntegratorClass.class file. This file should be copied to the integrators directory.

Hooking into the console

The GUI reads the file integrators.ini at startup, which is a return-separated list in the following format:

STRING NAME OF CLASS *TAB* CLASS_FILE

For our MyIntegrator.class, the entry would read:

My Custom Integrator *TAB* MyIntegratorClass

(notice no .class extension). At the next restart, the console will read the integrator and append it to the drop-down list of integrators.