Package org.orekit.propagation.numerical

Class FieldNumericalPropagator<T extends CalculusFieldElement<T>>

java.lang.Object

org.orekit.propagation.FieldAbstractPropagator<T>

org.orekit.propagation.integration.FieldAbstractIntegratedPropagator<T>

org.orekit.propagation.numerical.FieldNumericalPropagator<T>

Type Parameters:

T - type of the field elements

All Implemented Interfaces:

FieldPropagator<T>, FieldPVCoordinatesProvider<T>

public class FieldNumericalPropagator<T extends CalculusFieldElement<T>>
extends FieldAbstractIntegratedPropagator<T>

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(FieldSpacecraftState))
• the central attraction coefficient (setMu(CalculusFieldElement))
• the various force models (addForceModel(ForceModel), removeForceModels())
• the type of orbital parameters to be used for propagation (setOrbitType(OrbitType)),
• the type of position angle to be used in orbital parameters to be used for propagation where it is relevant (setPositionAngleType(PositionAngleType)),
• whether additional derivatives providers should be propagated along with orbital state (FieldAbstractIntegratedPropagator.addAdditionalDerivativesProvider(org.orekit.propagation.integration.FieldAdditionalDerivativesProvider)),
• the discrete events that should be triggered during propagation (FieldAbstractIntegratedPropagator.addEventDetector(FieldEventDetector), FieldAbstractIntegratedPropagator.clearEventsDetectors())
• the binding logic with the rest of the application (FieldAbstractPropagator.getMultiplexer())

From these configuration parameters, only the initial state is mandatory. The default propagation settings are in equinoctial parameters with true longitude argument. 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 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 either:

• the equinoctial orbit parameters (a, e_x, e_y, h_x, h_y, λ_M or λ_E or λ_v) in meters and radians,
• the Keplerian orbit parameters (a, e, i, ω, Ω, M or E or v) in meters and radians,
• the circular orbit parameters (a, e_x, e_y, i, Ω, α_M or α_E or α_v) in meters and radians,
• the Cartesian orbit parameters (x, y, z, v_x, v_y, v_z) in meters and meters per seconds.

The last element is the mass in kilograms.

The following code snippet shows a typical setting for Low Earth Orbit propagation in equinoctial parameters and true longitude argument:

 final T          zero      = field.getZero();
 final T          dP        = zero.add(0.001);
 final T          minStep   = zero.add(0.001);
 final T          maxStep   = zero.add(500);
 final T          initStep  = zero.add(60);
 final double[][] tolerance = FieldNumericalPropagator.tolerances(dP, orbit, OrbitType.EQUINOCTIAL);
 AdaptiveStepsizeFieldIntegrator<T> integrator = new DormandPrince853FieldIntegrator<>(field, minStep, maxStep, tolerance[0], tolerance[1]);
 integrator.setInitialStepSize(initStep);
 propagator = new FieldNumericalPropagator<>(field, integrator);
 

By default, at the end of the propagation, the propagator resets the initial state to the final state, thus allowing a new propagation to be started from there without recomputing the part already performed. This behaviour can be chenged by calling FieldAbstractIntegratedPropagator.setResetAtEnd(boolean).

Beware the same instance cannot be used simultaneously by different threads, the class is not thread-safe.

Author:

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

See Also:

FieldSpacecraftState, ForceModel, FieldOrekitStepHandler, FieldOrekitFixedStepHandler, FieldIntegratedEphemeris, FieldTimeDerivativesEquations

Nested Class Summary

Nested classes/interfaces inherited from class org.orekit.propagation.integration.FieldAbstractIntegratedPropagator

FieldAbstractIntegratedPropagator.MainStateEquations<T extends CalculusFieldElement<T>>

Field Summary

Fields inherited from interface org.orekit.propagation.FieldPropagator

DEFAULT_MASS

Constructor Summary

Constructors

Constructor	Description
FieldNumericalPropagator(Field<T> field, FieldODEIntegrator<T> integrator)	Create a new instance of NumericalPropagator, based on orbit definition mu.
FieldNumericalPropagator(Field<T> field, FieldODEIntegrator<T> integrator, AttitudeProvider attitudeProvider)	Create a new instance of NumericalPropagator, based on orbit definition mu.

Method Summary

Modifier and Type	Method	Description
void	addForceModel(ForceModel model)	Add a force model to the global perturbation model.
protected FieldStateMapper<T>	createMapper(FieldAbsoluteDate<T> referenceDate, T mu, OrbitType orbitType, PositionAngleType positionAngleType, AttitudeProvider attitudeProvider, Frame frame)	Create a mapper between raw double components and spacecraft state.
List<ForceModel>	getAllForceModels()	Get all the force models, perturbing forces and Newtonian attraction included.
protected FieldAbstractIntegratedPropagator.MainStateEquations<T>	getMainStateEquations(FieldODEIntegrator<T> integrator)	Get the differential equations to integrate (for main state only).
OrbitType	getOrbitType()	Get propagation parameter type.
PositionAngleType	getPositionAngleType()	Get propagation parameter type.
TimeStampedFieldPVCoordinates<T>	getPVCoordinates(FieldAbsoluteDate<T> date, Frame frame)	Get the FieldPVCoordinates of the body in the selected frame.
void	removeForceModels()	Remove all perturbing force models from the global perturbation model.
void	resetInitialState(FieldSpacecraftState<T> state)	Reset the propagator initial state.
void	setIgnoreCentralAttraction(boolean ignoreCentralAttraction)	Set the flag to ignore or not the creation of a NewtonianAttraction.
void	setInitialState(FieldSpacecraftState<T> initialState)	Set the initial state.
void	setMu(T mu)	Set the central attraction coefficient μ.
void	setOrbitType(OrbitType orbitType)	Set propagation orbit type.
void	setPositionAngleType(PositionAngleType positionAngleType)	Set position angle type.
static <T extends CalculusFieldElement<T>> double[][]	tolerances(T dP, FieldOrbit<T> orbit, OrbitType type)	Estimate tolerance vectors for integrators.
static <T extends CalculusFieldElement<T>> double[][]	tolerances(T dP, T dV, FieldOrbit<T> orbit, OrbitType type)	Estimate tolerance vectors for integrators when propagating in orbits.

Methods inherited from class org.orekit.propagation.integration.FieldAbstractIntegratedPropagator

addAdditionalDerivativesProvider, addEventDetector, afterIntegration, beforeIntegration, clearEventsDetectors, getAdditionalDerivativesProviders, getBasicDimension, getCalls, getEphemerisGenerator, getEventsDetectors, getInitialIntegrationState, getIntegrator, getIntegratorName, getManagedAdditionalStates, getMu, getPropagationType, getResetAtEnd, initMapper, isAdditionalStateManaged, isMeanOrbit, propagate, propagate, setAttitudeProvider, setResetAtEnd, setUpEventDetector, setUpUserEventDetectors

Methods inherited from class org.orekit.propagation.FieldAbstractPropagator

addAdditionalStateProvider, getAdditionalStateProviders, getAttitudeProvider, getField, getFrame, getInitialState, getMultiplexer, getStartDate, initializeAdditionalStates, initializePropagation, setStartDate, stateChanged, updateAdditionalStates, updateUnmanagedStates

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.orekit.propagation.FieldPropagator

clearStepHandlers, setStepHandler, setStepHandler

Methods inherited from interface org.orekit.utils.FieldPVCoordinatesProvider

getPosition

Constructor Detail

FieldNumericalPropagator

@DefaultDataContext
public FieldNumericalPropagator(Field<T> field,
                                FieldODEIntegrator<T> integrator)

Create a new instance of NumericalPropagator, based on orbit definition mu. After creation, the instance is empty, i.e. the attitude provider 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. The defaults are OrbitType.EQUINOCTIAL for propagation orbit type and PositionAngleType.TRUE for position angle type.

This constructor uses the default data context.

Parameters:

integrator - numerical integrator to use for propagation.

field - Field used by default

See Also:

FieldNumericalPropagator(Field, FieldODEIntegrator, AttitudeProvider)

FieldNumericalPropagator

public FieldNumericalPropagator(Field<T> field,
                                FieldODEIntegrator<T> integrator,
                                AttitudeProvider attitudeProvider)

Create a new instance of NumericalPropagator, based on orbit definition mu. After creation, the instance is empty, i.e. the attitude provider 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. The defaults are OrbitType.EQUINOCTIAL for propagation orbit type and PositionAngleType.TRUE for position angle type.

Parameters:

field - Field used by default

integrator - numerical integrator to use for propagation.

attitudeProvider - attitude law to use.

Since:

10.1

Method Detail

setIgnoreCentralAttraction

public void setIgnoreCentralAttraction(boolean ignoreCentralAttraction)

Set the flag to ignore or not the creation of a NewtonianAttraction.

Parameters:

ignoreCentralAttraction - if true, NewtonianAttraction is not added automatically if missing

setMu

public void setMu(T mu)

Set the central attraction coefficient μ.

Setting the central attraction coefficient is equivalent to add a NewtonianAttraction force model.

Overrides:

setMu in class FieldAbstractIntegratedPropagator<T extends CalculusFieldElement<T>>

Parameters:

mu - central attraction coefficient (m³/s²)

See Also:

addForceModel(ForceModel), getAllForceModels()

addForceModel

public void addForceModel(ForceModel model)

Add a force model to the global perturbation model.

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(CalculusFieldElement)

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)

getAllForceModels

public List<ForceModel> getAllForceModels()

Get all the force models, perturbing forces and Newtonian attraction included.

Returns:

list of perturbing force models, with Newtonian attraction being the last one

Since:

9.1

See Also:

addForceModel(ForceModel), setMu(CalculusFieldElement)

setOrbitType

public void setOrbitType(OrbitType orbitType)

Set propagation orbit type.

Overrides:

setOrbitType in class FieldAbstractIntegratedPropagator<T extends CalculusFieldElement<T>>

Parameters:

orbitType - orbit type to use for propagation

getOrbitType

public OrbitType getOrbitType()

Get propagation parameter type.

Overrides:

getOrbitType in class FieldAbstractIntegratedPropagator<T extends CalculusFieldElement<T>>

Returns:

orbit type used for propagation

setPositionAngleType

public void setPositionAngleType(PositionAngleType positionAngleType)

Set position angle type.

The position parameter type is meaningful only if propagation orbit type support it. As an example, it is not meaningful for propagation in Cartesian parameters.

Overrides:

setPositionAngleType in class FieldAbstractIntegratedPropagator<T extends CalculusFieldElement<T>>

Parameters:

positionAngleType - angle type to use for propagation

getPositionAngleType

public PositionAngleType getPositionAngleType()

Get propagation parameter type.

Overrides:

getPositionAngleType in class FieldAbstractIntegratedPropagator<T extends CalculusFieldElement<T>>

Returns:

angle type to use for propagation

setInitialState

public void setInitialState(FieldSpacecraftState<T> initialState)

Set the initial state.

Parameters:

initialState - initial state

resetInitialState

public void resetInitialState(FieldSpacecraftState<T> state)

Reset the propagator initial state.

Specified by:

resetInitialState in interface FieldPropagator<T extends CalculusFieldElement<T>>

Overrides:

resetInitialState in class FieldAbstractPropagator<T extends CalculusFieldElement<T>>

Parameters:

state - new initial state to consider

getPVCoordinates

public TimeStampedFieldPVCoordinates<T> getPVCoordinates(FieldAbsoluteDate<T> date,
                                                         Frame frame)

Get the FieldPVCoordinates of the body in the selected frame.

Specified by:

getPVCoordinates in interface FieldPVCoordinatesProvider<T extends CalculusFieldElement<T>>

Overrides:

getPVCoordinates in class FieldAbstractPropagator<T extends CalculusFieldElement<T>>

Parameters:

date - current date

frame - the frame where to define the position

Returns:

time-stamped position/velocity of the body (m and m/s)

createMapper

protected FieldStateMapper<T> createMapper(FieldAbsoluteDate<T> referenceDate,
                                           T mu,
                                           OrbitType orbitType,
                                           PositionAngleType positionAngleType,
                                           AttitudeProvider attitudeProvider,
                                           Frame frame)

Create a mapper between raw double components and spacecraft state. /** Simple constructor.

The position parameter type is meaningful only if propagation orbit type support it. As an example, it is not meaningful for propagation in Cartesian parameters.

Specified by:

createMapper in class FieldAbstractIntegratedPropagator<T extends CalculusFieldElement<T>>

Parameters:

referenceDate - reference date

mu - central attraction coefficient (m³/s²)

orbitType - orbit type to use for mapping

positionAngleType - angle type to use for propagation

attitudeProvider - attitude provider

frame - inertial frame

Returns:

new mapper

getMainStateEquations

protected FieldAbstractIntegratedPropagator.MainStateEquations<T> getMainStateEquations(FieldODEIntegrator<T> integrator)

Get the differential equations to integrate (for main state only).

Specified by:

getMainStateEquations in class FieldAbstractIntegratedPropagator<T extends CalculusFieldElement<T>>

Parameters:

integrator - numerical integrator to use for propagation.

Returns:

differential equations for main state

tolerances

public static <T extends CalculusFieldElement<T>> double[][] tolerances(T dP,
                                                                        FieldOrbit<T> orbit,
                                                                        OrbitType type)

Estimate tolerance vectors for integrators.

The errors are estimated from partial derivatives properties of orbits, starting from a scalar position error specified by the user. Considering the energy conservation equation V = sqrt(mu (2/r - 1/a)), we get at constant energy (i.e. on a Keplerian trajectory):

 V r² |dV| = mu |dr|
 

So we deduce a scalar velocity error consistent with the position error. From here, we apply orbits Jacobians matrices to get consistent errors on orbital parameters.

The tolerances are only orders of magnitude, and integrator tolerances are only local estimates, not global ones. So some care must be taken when using these tolerances. Setting 1mm as a position error does NOT mean the tolerances will guarantee a 1mm error position after several orbits integration.

Type Parameters:

T - elements type

Parameters:

dP - user specified position error

orbit - reference orbit

type - propagation type for the meaning of the tolerance vectors elements (it may be different from orbit.getType())

Returns:

a two rows array, row 0 being the absolute tolerance error and row 1 being the relative tolerance error

tolerances

public static <T extends CalculusFieldElement<T>> double[][] tolerances(T dP,
                                                                        T dV,
                                                                        FieldOrbit<T> orbit,
                                                                        OrbitType type)

Estimate tolerance vectors for integrators when propagating in orbits.

The errors are estimated from partial derivatives properties of orbits, starting from scalar position and velocity errors specified by the user.

The tolerances are only orders of magnitude, and integrator tolerances are only local estimates, not global ones. So some care must be taken when using these tolerances. Setting 1mm as a position error does NOT mean the tolerances will guarantee a 1mm error position after several orbits integration.

Type Parameters:

T - elements type

Parameters:

dP - user specified position error

dV - user specified velocity error

orbit - reference orbit

type - propagation type for the meaning of the tolerance vectors elements (it may be different from orbit.getType())

Returns:

a two rows array, row 0 being the absolute tolerance error and row 1 being the relative tolerance error

Since:

10.3