org.orekit.propagation

Interface Propagator

All Superinterfaces:

PVCoordinatesProvider

All Known Subinterfaces:

BoundedPropagator

All Known Implementing Classes:

AbstractAnalyticalPropagator, AbstractGNSSPropagator, AbstractIntegratedPropagator, AbstractPropagator, AdapterPropagator, AggregateBoundedPropagator, BeidouPropagator, DeepSDP4, DSSTPropagator, EcksteinHechlerPropagator, Ephemeris, GalileoPropagator, GLONASSAnalyticalPropagator, GLONASSNumericalPropagator, GPSPropagator, IntegratedEphemeris, IRNSSPropagator, KeplerianPropagator, NumericalPropagator, QZSSPropagator, SBASPropagator, SGP4, TLEPropagator

public interface Propagator
extends PVCoordinatesProvider

This interface provides a way to propagate an orbit at any time.

This interface is the top-level abstraction for orbit propagation. It only allows propagation to a predefined date. It is implemented by analytical models which have no time limit, by orbit readers based on external data files, by numerical integrators using rich force models and by continuous models built after numerical integration has been completed and dense output data as been gathered.

Note that one single propagator cannot be called from multiple threads. Its configuration can be changed as there is at least a resetInitialState(SpacecraftState) method, and even propagators that do not support resetting state (like the TLEPropagator do cache some internal data during computation. However, as long as they are configured with independent building blocks (mainly event handlers and step handlers that may preserve some internal state), and as long as they are called from one thread only, they can be used in multi-threaded applications. Synchronizing several propagators to run in parallel is also possible using PropagatorsParallelizer.

Author:

Luc Maisonobe, Véronique Pommier-Maurussane

Field Summary

Fields

Modifier and Type	Field and Description
static AttitudeProvider	DEFAULT_LAW Default attitude provider.
static double	DEFAULT_MASS Default mass.
static int	EPHEMERIS_GENERATION_MODE Indicator for ephemeris generation mode.
static int	MASTER_MODE Indicator for master mode.
static int	SLAVE_MODE Indicator for slave mode.

Method Summary

Modifier and Type	Method and Description
void	addAdditionalStateProvider(AdditionalStateProvider additionalStateProvider) Add a set of user-specified state parameters to be computed along with the orbit propagation.
<T extends EventDetector> void	addEventDetector(T detector) Add an event detector.
void	clearEventsDetectors() Remove all events detectors.
List<AdditionalStateProvider>	getAdditionalStateProviders() Get an unmodifiable list of providers for additional state.
AttitudeProvider	getAttitudeProvider() Get attitude provider.
static AttitudeProvider	getDefaultLaw(Frames frames) Get a default law using the given frames.
Collection<EventDetector>	getEventsDetectors() Get all the events detectors that have been added.
Frame	getFrame() Get the frame in which the orbit is propagated.
BoundedPropagator	getGeneratedEphemeris() Get the ephemeris generated during propagation.
SpacecraftState	getInitialState() Get the propagator initial state.
String[]	getManagedAdditionalStates() Get all the names of all managed states.
int	getMode() Get the current operating mode of the propagator.
boolean	isAdditionalStateManaged(String name) Check if an additional state is managed.
SpacecraftState	propagate(AbsoluteDate target) Propagate towards a target date.
SpacecraftState	propagate(AbsoluteDate start, AbsoluteDate target) Propagate from a start date towards a target date.
void	resetInitialState(SpacecraftState state) Reset the propagator initial state.
void	setAttitudeProvider(AttitudeProvider attitudeProvider) Set attitude provider.
void	setEphemerisMode() Set the propagator to ephemeris generation mode.
void	setEphemerisMode(OrekitStepHandler handler) Set the propagator to ephemeris generation mode with the specified handler for each integration step.
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	setSlaveMode() Set the propagator to slave mode.

Methods inherited from interface org.orekit.utils.PVCoordinatesProvider

getPVCoordinates

Field Detail

DEFAULT_MASS

static final double DEFAULT_MASS

Default mass.

See Also:

Constant Field Values

DEFAULT_LAW

@DefaultDataContext
static final AttitudeProvider DEFAULT_LAW

Default attitude provider.

This field uses the default data context.

See Also:

InertialProvider.InertialProvider(Rotation, Frame), getDefaultLaw(Frames)

SLAVE_MODE

static final int SLAVE_MODE

Indicator for slave mode.

See Also:

Constant Field Values

MASTER_MODE

static final int MASTER_MODE

Indicator for master mode.

See Also:

Constant Field Values

EPHEMERIS_GENERATION_MODE

static final int EPHEMERIS_GENERATION_MODE

Indicator for ephemeris generation mode.

See Also:

Constant Field Values

Method Detail

getDefaultLaw

static AttitudeProvider getDefaultLaw(Frames frames)

Get a default law using the given frames. A data context aware replacement for DEFAULT_LAW.

Parameters:

frames - the set of frames to use.

Returns:

attitude law.

getMode

int getMode()

Get the current operating mode of the propagator.

Returns:

one of SLAVE_MODE, MASTER_MODE, EPHEMERIS_GENERATION_MODE

See Also:

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

setSlaveMode

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.

See Also:

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

setMasterMode

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.

Parameters:

h - fixed stepsize (s)

handler - handler called at the end of each finalized step

See Also:

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

setMasterMode

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.

Parameters:

handler - handler called at the end of each finalized step

See Also:

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

setEphemerisMode

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.

See Also:

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

setEphemerisMode

void setEphemerisMode(OrekitStepHandler handler)

Set the propagator to ephemeris generation mode with the specified handler for each integration step.

This mode is used when the user needs random access to the orbit state at any time between the initial and target times, as well as access to the steps computed by the integrator as in Master Mode. 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.

Parameters:

handler - handler called at the end of each finalized step

See Also:

setEphemerisMode(), getGeneratedEphemeris(), setSlaveMode(), setMasterMode(double, OrekitFixedStepHandler), setMasterMode(OrekitStepHandler), getMode(), EPHEMERIS_GENERATION_MODE

getGeneratedEphemeris

BoundedPropagator getGeneratedEphemeris()
                                 throws IllegalStateException

Get the ephemeris generated during propagation.

Returns:

generated ephemeris

Throws:

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

See Also:

setEphemerisMode()

getInitialState

SpacecraftState getInitialState()

Get the propagator initial state.

Returns:

initial state

resetInitialState

void resetInitialState(SpacecraftState state)

Reset the propagator initial state.

Parameters:

state - new initial state to consider

addAdditionalStateProvider

void addAdditionalStateProvider(AdditionalStateProvider additionalStateProvider)

Add a set of user-specified state parameters to be computed along with the orbit propagation.

Parameters:

additionalStateProvider - provider for additional state

getAdditionalStateProviders

List<AdditionalStateProvider> getAdditionalStateProviders()

Get an unmodifiable list of providers for additional state.

Returns:

providers for the additional states

isAdditionalStateManaged

boolean isAdditionalStateManaged(String name)

Check if an additional state is managed.

Managed states are states for which the propagators know how to compute its evolution. They correspond to additional states for which an additional state provider has been registered by calling the addAdditionalStateProvider method. If the propagator is an integrator-based propagator, the states for which a set of additional equations has been registered by calling the addAdditionalEquations method are also counted as managed additional states.

Additional states that are present in the initial state but have no evolution method registered are not considered as managed states. These unmanaged additional states are not lost during propagation, though. Their value are piecewise constant between state resets that may change them if some event handler resetState method is called at an event occurrence and happens to change the unmanaged additional state.

Parameters:

name - name of the additional state

Returns:

true if the additional state is managed

getManagedAdditionalStates

String[] getManagedAdditionalStates()

Get all the names of all managed states.

Returns:

names of all managed states

addEventDetector

<T extends EventDetector> void addEventDetector(T detector)

Add an event detector.

Type Parameters:

T - class type for the generic version

Parameters:

detector - event detector to add

See Also:

clearEventsDetectors(), getEventsDetectors()

getEventsDetectors

Collection<EventDetector> getEventsDetectors()

Get all the events detectors that have been added.

Returns:

an unmodifiable collection of the added detectors

See Also:

addEventDetector(EventDetector), clearEventsDetectors()

clearEventsDetectors

void clearEventsDetectors()

Remove all events detectors.

See Also:

addEventDetector(EventDetector), getEventsDetectors()

getAttitudeProvider

AttitudeProvider getAttitudeProvider()

Get attitude provider.

Returns:

attitude provider

setAttitudeProvider

void setAttitudeProvider(AttitudeProvider attitudeProvider)

Set attitude provider.

Parameters:

attitudeProvider - attitude provider

getFrame

Frame getFrame()

Get the frame in which the orbit is propagated.

The propagation frame is the definition frame of the initial state, so this method should be called after this state has been set, otherwise it may return null.

Returns:

frame in which the orbit is propagated

See Also:

resetInitialState(SpacecraftState)

propagate

SpacecraftState propagate(AbsoluteDate target)

Propagate towards a target date.

Simple propagators use only the target date as the specification for computing the propagated state. More feature rich propagators 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.

Parameters:

target - target date towards which orbit state should be propagated

Returns:

propagated state

propagate

SpacecraftState propagate(AbsoluteDate start,
                          AbsoluteDate target)

Propagate from a start date towards a target date.

Those propagators use a start date and a target date to compute the propagated state. For propagators using event detection mechanism, if the provided start date is different from the initial state date, a first, simple propagation is performed, without processing any event computation. Then complete propagation is performed from start date to target date.

Parameters:

start - start date from which orbit state should be propagated

target - target date to which orbit state should be propagated

Returns:

propagated state