org.orekit.propagation.numerical
Class NumericalPropagator

java.lang.Object
  org.orekit.propagation.numerical.NumericalPropagator

All Implemented Interfaces:

java.io.Serializable, BasicPropagator, Propagator, PVCoordinatesProvider

Direct Known Subclasses:

NumericalPropagatorWithJacobians

public class NumericalPropagator
extends java.lang.Object
implements Propagator

This class propagates orbits using numerical integration.

Numerical propagation is much more accurate than analytical propagation like for example keplerian or Eckstein-Hechler, but requires a few more steps to set up to be used properly. Whereas analytical propagators are configured only thanks to their various constructors and can be used immediately after construction, numerical propagators configuration involve setting several parameters between construction time and propagation time.

The configuration parameters that can be set are:

• the initial spacecraft state (setInitialState(SpacecraftState))
• the central attraction coefficient (setMu(double))
• the various force models (addForceModel(ForceModel), removeForceModels())
• the discrete events that should be triggered during propagation (addEventDetector(EventDetector), clearEventsDetectors())
• the binding logic with the rest of the application (setSlaveMode(), setMasterMode(double, OrekitFixedStepHandler), setMasterMode(OrekitStepHandler), setEphemerisMode(), getGeneratedEphemeris())

From these configuration parameters, only the initial state is mandatory. If the central attraction coefficient is not explicitly specified, the one used to define the initial orbit will be used. However, specifying only the initial state and perhaps the central attraction coefficient would mean the propagator would use only keplerian forces. In this case, the simpler KeplerianPropagator class would perhaps be more effective. The propagator is only in one mode at a time.

The underlying numerical integrator set up in the constructor may also have its own configuration parameters. Typical configuration 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 state that is seen by the integrator is a simple seven elements double array. The six first elements are the equinoxial orbit parameters (a, e_x, e_y, h_x, h_y, l_v) in meters and radians, and the last element is the mass in kilograms. The following code snippet shows a typical setting for Low Earth Orbit propagation:

 final double minStep  = 0.001;
 final double maxStep  = 1000;
 final double initStep = 60;
 final double[] absTolerance = {
     0.001, 1.0e-9, 1.0e-9, 1.0e-6, 1.0e-6, 1.0e-6, 0.001
 };
 final double[] relTolerance = {
     1.0e-7, 1.0e-4, 1.0e-4, 1.0e-7, 1.0e-7, 1.0e-7, 1.0e-7
 };
 AdaptiveStepsizeIntegrator integrator =
     new DormandPrince853Integrator(minStep, maxStep, absTolerance, relTolerance);
 integrator.setInitialStepSize(initStep);
 propagator = new NumericalPropagator(integrator);
 

The same propagator can be reused for several orbit extrapolations, by resetting the initial state without modifying the other configuration parameters. However, the same instance cannot be used simultaneously by different threads, the class is not thread-safe.

Version:

$Revision: 3246 $ $Date: 2010-05-05 16:17:45 +0200 (mer. 05 mai 2010) $

Author:

Mathieu Roméro, Luc Maisonobe, Guylaine Prat, Fabien Maussion, Véronique Pommier-Maurussane

See Also:

SpacecraftState, ForceModel, OrekitStepHandler, OrekitFixedStepHandler, IntegratedEphemeris, TimeDerivativesEquations, Serialized Form

Field Summary

protected TimeDerivativesEquations	adder Gauss equations handler.
protected AttitudeLaw	attitudeLaw Attitude law.
protected int	calls Counter for differential equations calls.
protected SpacecraftState	currentState Current state to propagate.
protected java.util.List<EventDetector>	detectors Event detectors not related to force models.
protected java.util.List<ForceModel>	forceModels Force models used during the extrapolation of the Orbit.
protected SpacecraftState	initialState Initial state to propagate.
protected org.apache.commons.math.ode.FirstOrderIntegrator	integrator Integrator selected by the user for the orbital extrapolation process.
protected int	mode Current mode.
protected ModeHandler	modeHandler Propagator mode handler.
protected double	mu Central body gravitational constant.
protected AbsoluteDate	startDate Start date.
protected double[]	stateVector State vector.

Fields inherited from interface org.orekit.propagation.Propagator

EPHEMERIS_GENERATION_MODE, MASTER_MODE, SLAVE_MODE

Constructor Summary

NumericalPropagator(org.apache.commons.math.ode.FirstOrderIntegrator integrator)
Create a new instance of NumericalPropagator, based on orbit definition mu.

Method Summary

void	addEventDetector(EventDetector detector) Add an event detector.
void	addForceModel(ForceModel model) Add a force model to the global perturbation model.
void	clearEventsDetectors() Remove all events detectors.
int	getCalls() Get the number of calls to the differential equations computation method.
java.util.Collection<EventDetector>	getEventsDetectors() Get all the events detectors that have been added.
BoundedPropagator	getGeneratedEphemeris() Get the ephemeris generated during propagation.
SpacecraftState	getInitialState() Get the propagator initial state.
int	getMode() Get the current operating mode of the propagator.
double	getMu() Get the central attraction coefficient μ.
PVCoordinates	getPVCoordinates(AbsoluteDate date, Frame frame) Get the PVCoordinates of the body in the selected frame.
SpacecraftState	propagate(AbsoluteDate finalDate) Propagate towards a target date.
void	removeForceModels() Remove all perturbing force models from the global perturbation model.
void	resetInitialState(SpacecraftState state) Reset the propagator initial state.
void	setAttitudeLaw(AttitudeLaw attitudeLaw) Set the attitude law.
void	setEphemerisMode() Set the propagator to ephemeris generation mode.
void	setInitialState(SpacecraftState initialState) Set the initial state.
void	setIntegrator(org.apache.commons.math.ode.FirstOrderIntegrator integrator) Set the integrator.
void	setMasterMode(double h, OrekitFixedStepHandler handler) Set the propagator to master mode with fixed steps.
void	setMasterMode(OrekitStepHandler handler) Set the propagator to master mode with variable steps.
void	setMu(double mu) Set the central attraction coefficient μ.
void	setSlaveMode() Set the propagator to slave mode.
protected void	setUpEventDetector(EventDetector osf) Wrap an Orekit event detector and register it to the integrator.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

attitudeLaw

protected AttitudeLaw attitudeLaw

Attitude law.

mu

protected double mu

Central body gravitational constant.

forceModels

protected final java.util.List<ForceModel> forceModels

Force models used during the extrapolation of the Orbit.

detectors

protected final java.util.List<EventDetector> detectors

Event detectors not related to force models.

stateVector

protected final double[] stateVector

State vector.

startDate

protected AbsoluteDate startDate

Start date.

initialState

protected SpacecraftState initialState

Initial state to propagate.

currentState

protected SpacecraftState currentState

Current state to propagate.

integrator

protected transient org.apache.commons.math.ode.FirstOrderIntegrator integrator

Integrator selected by the user for the orbital extrapolation process.

calls

protected int calls

Counter for differential equations calls.

adder

protected TimeDerivativesEquations adder

Gauss equations handler.

modeHandler

protected ModeHandler modeHandler

Propagator mode handler.

mode

protected int mode

Current mode.

Constructor Detail

NumericalPropagator

public NumericalPropagator(org.apache.commons.math.ode.FirstOrderIntegrator integrator)

Create a new instance of NumericalPropagator, based on orbit definition mu. After creation, the instance is empty, i.e. the attitude law is set to an unspecified default law and there are no perturbing forces at all. This means that if addForceModel is not called after creation, the integrated orbit will follow a keplerian evolution only.

Parameters:

integrator - numerical integrator to use for propagation.

Method Detail

setIntegrator

public void setIntegrator(org.apache.commons.math.ode.FirstOrderIntegrator integrator)

Set the integrator.

Parameters:

integrator - numerical integrator to use for propagation.

setMu

public void setMu(double mu)

Set the central attraction coefficient μ.

Parameters:

mu - central attraction coefficient (m^3/s^2)

See Also:

getMu(), addForceModel(ForceModel)

getMu

public double getMu()

Get the central attraction coefficient μ.

Returns:

mu central attraction coefficient (m^3/s^2)

See Also:

setMu(double)

setAttitudeLaw

public void setAttitudeLaw(AttitudeLaw attitudeLaw)

Set the attitude law.

Parameters:

attitudeLaw - attitude law

addEventDetector

public void addEventDetector(EventDetector detector)

Add an event detector.

Specified by:

addEventDetector in interface Propagator

Parameters:

detector - event detector to add

See Also:

Propagator.clearEventsDetectors(), Propagator.getEventsDetectors()

getEventsDetectors

public java.util.Collection<EventDetector> getEventsDetectors()

Get all the events detectors that have been added.

Specified by:

getEventsDetectors in interface Propagator

Returns:

an unmodifiable collection of the added detectors

See Also:

Propagator.addEventDetector(EventDetector), Propagator.clearEventsDetectors()

clearEventsDetectors

public void clearEventsDetectors()

Remove all events detectors.

Specified by:

clearEventsDetectors in interface Propagator

See Also:

Propagator.addEventDetector(EventDetector), Propagator.getEventsDetectors()

addForceModel

public void addForceModel(ForceModel model)

Add a force model to the global perturbation model.

If the force models is associated to discrete events, these events will be handled automatically, they must not be added using the addEventDetector method.

If this method is not called at all, the integrated orbit will follow a keplerian evolution only.

Parameters:

model - perturbing ForceModel to add

See Also:

removeForceModels(), setMu(double)

removeForceModels

public void removeForceModels()

Remove all perturbing force models from the global perturbation model.

Once all perturbing forces have been removed (and as long as no new force model is added), the integrated orbit will follow a keplerian evolution only.

See Also:

addForceModel(ForceModel)

getMode

public int getMode()

Get the current operating mode of the propagator.

Specified by:

getMode in interface Propagator

Returns:

one of Propagator.SLAVE_MODE, Propagator.MASTER_MODE, Propagator.EPHEMERIS_GENERATION_MODE

See Also:

Propagator.setSlaveMode(), Propagator.setMasterMode(double, OrekitFixedStepHandler), Propagator.setMasterMode(OrekitStepHandler), Propagator.setEphemerisMode()

setSlaveMode

public void setSlaveMode()

Set the propagator to slave mode.

This mode is used when the user needs only the final orbit at the target time. The (slave) propagator computes this result and return it to the calling (master) application, without any intermediate feedback.

This is the default mode.

Note that this method has the side effect of replacing the step handlers of the underlying integrator set up in the constructor or the setIntegrator method. So if a specific step handler is needed, it should be added after this method has been callled.

Specified by:

setSlaveMode in interface Propagator

See Also:

Propagator.setMasterMode(double, OrekitFixedStepHandler), Propagator.setMasterMode(OrekitStepHandler), Propagator.setEphemerisMode(), Propagator.getMode(), Propagator.SLAVE_MODE

setMasterMode

public void setMasterMode(double h,
                          OrekitFixedStepHandler handler)

Set the propagator to master mode with fixed steps.

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 integration loop calls the (slave) application callback methods at each finalized step.

Note that this method has the side effect of replacing the step handlers of the underlying integrator set up in the constructor or the setIntegrator method. So if a specific step handler is needed, it should be added after this method has been callled.

Specified by:

setMasterMode in interface Propagator

Parameters:

h - fixed stepsize (s)

handler - handler called at the end of each finalized step

See Also:

Propagator.setSlaveMode(), Propagator.setMasterMode(OrekitStepHandler), Propagator.setEphemerisMode(), Propagator.getMode(), Propagator.MASTER_MODE

setMasterMode

public void setMasterMode(OrekitStepHandler handler)

Set the propagator to master mode with variable steps.

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 integration loop calls the (slave) application callback methods at each finalized step.

Note that this method has the side effect of replacing the step handlers of the underlying integrator set up in the constructor or the setIntegrator method. So if a specific step handler is needed, it should be added after this method has been callled.

Specified by:

setMasterMode in interface Propagator

Parameters:

handler - handler called at the end of each finalized step

See Also:

Propagator.setSlaveMode(), Propagator.setMasterMode(double, OrekitFixedStepHandler), Propagator.setEphemerisMode(), Propagator.getMode(), Propagator.MASTER_MODE

setEphemerisMode

public void setEphemerisMode()

Set the propagator to 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 since this mode stores all intermediate results, it may be memory intensive for long integration ranges and high precision/short time steps.

Note that this method has the side effect of replacing the step handlers of the underlying integrator set up in the constructor or the setIntegrator method. So if a specific step handler is needed, it should be added after this method has been callled.

Specified by:

setEphemerisMode in interface Propagator

See Also:

Propagator.getGeneratedEphemeris(), Propagator.setSlaveMode(), Propagator.setMasterMode(double, OrekitFixedStepHandler), Propagator.setMasterMode(OrekitStepHandler), Propagator.getMode(), Propagator.EPHEMERIS_GENERATION_MODE

getGeneratedEphemeris

public BoundedPropagator getGeneratedEphemeris()
                                        throws java.lang.IllegalStateException

Get the ephemeris generated during propagation.

Specified by:

getGeneratedEphemeris in interface Propagator

Returns:

generated ephemeris

Throws:

java.lang.IllegalStateException - if the propagator was not set in ephemeris generation mode before propagation

See Also:

Propagator.setEphemerisMode()

getInitialState

public SpacecraftState getInitialState()

Get the propagator initial state.

Specified by:

getInitialState in interface Propagator

Returns:

initial state

setInitialState

public void setInitialState(SpacecraftState initialState)

Set the initial state.

Parameters:

initialState - initial state

See Also:

propagate(AbsoluteDate)

resetInitialState

public void resetInitialState(SpacecraftState state)

Reset the propagator initial state.

Specified by:

resetInitialState in interface Propagator

Parameters:

state - new initial state to consider

propagate

public SpacecraftState propagate(AbsoluteDate finalDate)
                          throws PropagationException

Propagate towards a target date.

Simple propagators use only the target date as the specification for computing the propagated state. More feature rich propagators like the ones implemented the extended interface Propagator can consider other information and provide different operating modes or G-stop facilities to stop at pinpointed events occurrences. In these cases, the target date is only a hint, not a mandatory objective.

Specified by:

propagate in interface BasicPropagator

Parameters:

finalDate - target date towards which orbit state should be propagated

Returns:

propagated state

Throws:

PropagationException - if state cannot be propagated

getPVCoordinates

public PVCoordinates getPVCoordinates(AbsoluteDate date,
                                      Frame frame)
                               throws OrekitException

Get the PVCoordinates of the body in the selected frame.

Specified by:

getPVCoordinates in interface PVCoordinatesProvider

Parameters:

date - current date

frame - the frame where to define the position

Returns:

position/velocity of the body (m and m/s)

Throws:

OrekitException - if position cannot be computed in given frame

getCalls

public int getCalls()

Get the number of calls to the differential equations computation method.

The number of calls is reset each time the propagate(AbsoluteDate) method is called.

Returns:

number of calls to the differential equations computation method

setUpEventDetector

protected void setUpEventDetector(EventDetector osf)

Wrap an Orekit event detector and register it to the integrator.

Parameters:

osf - event handler to wrap