Propagation modes

Depending on the needs of the calling application, all propagators can be used in different modes:

• slave mode: This mode is used when the user needs only the final orbit at the target time. The (slave) propagator is passive: it computes this result and return it to the calling (master) application, without any intermediate feedback. In that case the events detection is made but the step handler does nothing, actions are managed directly by the calling application.
• master mode: This mode is used when the user needs to have some custom function called at the end of each finalized step during integration. The (master) propagator is active: the integration loop calls the (slave) application callback methods at each finalized step, through the step handler .
• ephemeris generation mode: This mode is used when the user needs random access to the orbit state at any time between the initial and target times, and in no sequential order. A typical example is the implementation of search and iterative algorithms that may navigate forward and backward inside the propagation range before finding their result. Beware that this mode cannot support events that modify spacecraft initial state. Beware that since this mode stores all intermediate results, it may be memory intensive for long integration ranges and high precision/short time steps.

Events management

All propagators, including analytical ones, support discrete events handling during propagation. This feature is activated by registering events detectors as defined by the EventDetector interface to the propagator. At each propagation step, the propagator checks the registered events detectors for the occurrence of some event. If an event occurs, then the corresponding action is triggered, which can ask the propagator to resume propagation, possibly with an updated state or to stop propagation.

Resuming propagation with changed state is used for example in the ImpulseManeuver class. When the maneuver is triggered, the orbit is changed according to the velocity increment associated with the maneuver and the mass is reduced according to the consumption. This allows to handle simple maneuvers transparently even inside basic propagators like Kepler or Eckstein-Heschler.

Stopping propagation is useful when some specific state is desired but its real occurrence time is unknown in advance. A typical example would be to find the next ascending node or the next apogee. In this case, we can register a NodeDetector or an ApsideDetector object and launch a propagation with a target time far away in the future. When the event is triggered, it asks the propagator to stop and the returned value is the state exactly at the event time.

Three other available events detectors are a simple DateDetector which is simply triggered at a predefined date, an ElevationDetector which is triggered at raising or setting time of a satellite with respect to a ground point and an AltitudeDetector which is triggered when satellite crosses a predefined altitude limit. The latter can be used to compute easily operational forecasts.

Keplerian propagation

The KeplerianPropagator implements the Propagator interface, which ensures that we can obtain a propagated SpacecraftState at any time once the instance is initialized with an initial state. This model is based on Keplerian only motion. It depends on µ.

Eckstein-Hechler propagation

This analytical model is suited for near circular orbits and inclination neither equatorial nor critical. It considers J2 to J6 potential zonal coefficients, and uses mean parameters to compute the new position. As the keplerian propagator, it implements the Propagator interface.

Numerical propagation

It is the most important part of the Orekit project. Based on commons-math integrators, the NumericalPropagator class realizes the interface between space mechanics and mathematical resolutions. If its utilization seems difficult on first sight, it is in fact quite clear and intuitive.

The mathematical problem to integrate is a dimension seven time derivative equations system. The six first elements of the state vector are the EquinoctialOrbit parameters, i.e a, ex, ey, hx, hy, lv in meters and radians, and the last element is the mass in kilograms. The time derivatives are computed automatically by the Orekit using the Gauss equations for the first parameters and the flow rate for mass evolution during maneuvers. The users only needs to register the various force models needed for the simulation. Various force models are already available in the library and specialized ones can be added by users easily for specific needs.

The integrators (first order integrators ) provided by commons-math need the state vector at t0, the state vector first time derivative at t0, and then calculates the next step state vector, and ask for the next first time derivative, etc. until it reaches the final asked date. These underlying numerical integrators can also be configured. Typical tuning parameters for adaptive stepsize integrators are the min, max and perhaps start step size as well as the absolute and/or relative errors thresholds. The following code snippet shows a typical setting for Low Earth Orbit propagation:

// steps limits
final double minStep  = 0.001;
final double maxStep  = 1000;
final double initStep = 60;

// error control parameters (absolute and relative)
final double[] absoluteTolerance = {
    0.001, 1.0e-9, 1.0e-9, 1.0e-6, 1.0e-6, 1.0e-6, 0.001
};
final double[] relativeTolerance = {
    1.0e-7, 1.0e-4, 1.0e-4, 1.0e-7, 1.0e-7, 1.0e-7, 1.0e-7
};

// set up mathematical integrator
AdaptiveStepsizeIntegrator integrator =
    new DormandPrince853Integrator(minStep, maxStep,
                                   absoluteTolerance, relativeTolerance);
integrator.setInitialStepSize(initStep);

// set up space dynamics propagator
propagator = new NumericalPropagator(integrator);