FieldNumericalPropagator (ORbit Extrapolation KIT 9.2 API)

java.lang.Object
- org.orekit.propagation.FieldAbstractPropagator<T>
- - org.orekit.propagation.integration.FieldAbstractIntegratedPropagator<T>
  - - org.orekit.propagation.numerical.FieldNumericalPropagator<T>

All Implemented Interfaces:

FieldPropagator<T>, FieldPVCoordinatesProvider<T>
```
public class FieldNumericalPropagator<T extends RealFieldElement<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(double))
- 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(PositionAngle)),
- whether additional equations should be propagated along with orbital state (FieldAbstractIntegratedPropagator.addAdditionalEquations(org.orekit.propagation.integration.FieldAdditionalEquations)),
- the discrete events that should be triggered during propagation (FieldAbstractIntegratedPropagator.addEventDetector(FieldEventDetector), FieldAbstractIntegratedPropagator.clearEventsDetectors())
- the binding logic with the rest of the application (FieldAbstractIntegratedPropagator.setSlaveMode(), FieldAbstractPropagator.setMasterMode(RealFieldElement, org.orekit.propagation.sampling.FieldOrekitFixedStepHandler), FieldAbstractIntegratedPropagator.setMasterMode(org.orekit.propagation.sampling.FieldOrekitStepHandler), FieldAbstractIntegratedPropagator.setEphemerisMode(), FieldAbstractIntegratedPropagator.getGeneratedEphemeris())
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 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 RealFieldElement<T>>

Field Summary
- Fields inherited from interface org.orekit.propagation.FieldPropagator
  DEFAULT_LAW, DEFAULT_MASS, EPHEMERIS_GENERATION_MODE, MASTER_MODE, SLAVE_MODE

Constructor Summary

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
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, double mu, OrbitType orbitType, PositionAngle 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.
`List<ForceModel>`	`getForceModels()`	Deprecated. as of 9.1, this method is deprecated, the perturbing force models are retrieved together with the Newtonian attraction by calling `getAllForceModels()`
`protected FieldAbstractIntegratedPropagator.MainStateEquations<T>`	`getMainStateEquations(FieldODEIntegrator<T> integrator)`	Get the differential equations to integrate (for main state only).
`NewtonianAttraction`	`getNewtonianAttractionForceModel()`	Deprecated. as of 9.1, this method is deprecated, the Newtonian attraction force model (if any) is the last in the `getAllForceModels()`
`OrbitType`	`getOrbitType()`	Get propagation parameter type.
`PositionAngle`	`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`	`setInitialState(FieldSpacecraftState<T> initialState)`	Set the initial state.
`void`	`setMu(double mu)`	Set the central attraction coefficient μ.
`void`	`setOrbitType(OrbitType orbitType)`	Set propagation orbit type.
`void`	`setPositionAngleType(PositionAngle positionAngleType)`	Set position angle type.
`static <T extends RealFieldElement<T>> double[][]`	`tolerances(T dP, FieldOrbit<T> orbit, OrbitType type)`	Estimate tolerance vectors for integrators.

Methods inherited from class org.orekit.propagation.integration.FieldAbstractIntegratedPropagator
addAdditionalEquations, addEventDetector, afterIntegration, beforeIntegration, clearEventsDetectors, getBasicDimension, getCalls, getEventsDetectors, getGeneratedEphemeris, getInitialIntegrationState, getIntegrator, getManagedAdditionalStates, getMu, initMapper, isAdditionalStateManaged, isMeanOrbit, propagate, propagate, propagate, setAttitudeProvider, setEphemerisMode, setMasterMode, setResetAtEnd, setSlaveMode, setUpEventDetector, setUpUserEventDetectors

Methods inherited from class org.orekit.propagation.FieldAbstractPropagator
addAdditionalStateProvider, getAdditionalStateProviders, getAttitudeProvider, getField, getFixedStepSize, getFrame, getInitialState, getMode, getStartDate, getStepHandler, setMasterMode, setStartDate, updateAdditionalStates

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - FieldNumericalPropagator
```
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 PositionAngle.TRUE for position angle type.
    
    Parameters:
    
    integrator - numerical integrator to use for propagation.
    
    field - Field used by default
- Method Detail
  - setMu
```
public void setMu(double mu)
```
    Set the central attraction coefficient μ.
    
    Overrides:
    
    setMu in class FieldAbstractIntegratedPropagator<T extends RealFieldElement<T>>
    
    Parameters:
    
    mu - central attraction coefficient (m³/s²)
    
    See Also:
    
    addForceModel(ForceModel)
  - 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(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)
  - 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(double)
  - getForceModels
```
@Deprecated
public List<ForceModel> getForceModels()
```
    Deprecated. as of 9.1, this method is deprecated, the perturbing force models are retrieved together with the Newtonian attraction by calling getAllForceModels()
    
    Get perturbing force models list.
    
    Returns:
    
    list of perturbing force models
  - getNewtonianAttractionForceModel
```
@Deprecated
public NewtonianAttraction getNewtonianAttractionForceModel()
```
    Deprecated. as of 9.1, this method is deprecated, the Newtonian attraction force model (if any) is the last in the getAllForceModels()
    
    Get the Newtonian attraction from the central body force model.
    
    Returns:
    
    Newtonian attraction force model
  - setOrbitType
```
public void setOrbitType(OrbitType orbitType)
```
    Set propagation orbit type.
    
    Overrides:
    
    setOrbitType in class FieldAbstractIntegratedPropagator<T extends RealFieldElement<T>>
    
    Parameters:
    
    orbitType - orbit type to use for propagation
  - getOrbitType
```
public OrbitType getOrbitType()
```
    Get propagation parameter type.
    
    Overrides:
    
    getOrbitType in class FieldAbstractIntegratedPropagator<T extends RealFieldElement<T>>
    
    Returns:
    
    orbit type used for propagation
  - setPositionAngleType
```
public void setPositionAngleType(PositionAngle 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 RealFieldElement<T>>
    
    Parameters:
    
    positionAngleType - angle type to use for propagation
  - getPositionAngleType
```
public PositionAngle getPositionAngleType()
```
    Get propagation parameter type.
    
    Overrides:
    
    getPositionAngleType in class FieldAbstractIntegratedPropagator<T extends RealFieldElement<T>>
    
    Returns:
    
    angle type to use for propagation
  - setInitialState
```
public void setInitialState(FieldSpacecraftState<T> initialState)
                     throws OrekitException
```
    Set the initial state.
    
    Parameters:
    
    initialState - initial state
    
    Throws:
    
    OrekitException - if initial state cannot be set
  - resetInitialState
```
public void resetInitialState(FieldSpacecraftState<T> state)
                       throws OrekitException
```
    Reset the propagator initial state.
    
    Specified by:
    
    resetInitialState in interface FieldPropagator<T extends RealFieldElement<T>>
    
    Overrides:
    
    resetInitialState in class FieldAbstractPropagator<T extends RealFieldElement<T>>
    
    Parameters:
    
    state - new initial state to consider
    
    Throws:
    
    OrekitException - if initial state cannot be reset
  - getPVCoordinates
```
public TimeStampedFieldPVCoordinates<T> getPVCoordinates(FieldAbsoluteDate<T> date,
                                                         Frame frame)
                                                  throws OrekitException
```
    Get the FieldPVCoordinates of the body in the selected frame.
    
    Specified by:
    
    getPVCoordinates in interface FieldPVCoordinatesProvider<T extends RealFieldElement<T>>
    
    Overrides:
    
    getPVCoordinates in class FieldAbstractPropagator<T extends RealFieldElement<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)
    
    Throws:
    
    OrekitException - if position cannot be computed in given frame
  - createMapper
```
protected FieldStateMapper<T> createMapper(FieldAbsoluteDate<T> referenceDate,
                                           double mu,
                                           OrbitType orbitType,
                                           PositionAngle 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 RealFieldElement<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 RealFieldElement<T>>
    
    Parameters:
    
    integrator - numerical integrator to use for propagation.
    
    Returns:
    
    differential equations for main state
  - tolerances
```
public static <T extends RealFieldElement<T>> double[][] tolerances(T dP,
                                                                    FieldOrbit<T> orbit,
                                                                    OrbitType type)
                                                             throws OrekitException
```
    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
    
    Throws:
    
    OrekitException - if Jacobian is singular

Class FieldNumericalPropagator<T extends RealFieldElement<T>>

Nested Class Summary

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

Field Summary

Fields inherited from interface org.orekit.propagation.FieldPropagator

Constructor Summary

Method Summary

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

Methods inherited from class org.orekit.propagation.FieldAbstractPropagator

Methods inherited from class java.lang.Object

Constructor Detail

FieldNumericalPropagator

Method Detail

setMu

addForceModel

removeForceModels

getAllForceModels

getForceModels

getNewtonianAttractionForceModel

setOrbitType

getOrbitType

setPositionAngleType

getPositionAngleType

setInitialState

resetInitialState

getPVCoordinates

createMapper

getMainStateEquations

tolerances