java.lang.Object
- org.orekit.propagation.AbstractPropagator
- - org.orekit.propagation.integration.AbstractIntegratedPropagator
  - - org.orekit.propagation.numerical.NumericalPropagator

All Implemented Interfaces:

Propagator, PVCoordinatesProvider
```
public class NumericalPropagator
extends AbstractIntegratedPropagator
```
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 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 state transition matrices and Jacobians matrices should be propagated along with orbital state (AbstractPropagator.setupMatricesComputation(String, RealMatrix, DoubleArrayDictionary)),
- whether additional derivatives should be propagated along with orbital state (AbstractIntegratedPropagator.addAdditionalDerivativesProvider(AdditionalDerivativesProvider)),
- the discrete events that should be triggered during propagation (AbstractIntegratedPropagator.addEventDetector(EventDetector), AbstractIntegratedPropagator.clearEventsDetectors())
- the binding logic with the rest of the application (AbstractPropagator.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 and changes only during thrusters firings
The following code snippet shows a typical setting for Low Earth Orbit propagation in equinoctial parameters and true longitude argument:
```
 final double dP       = 0.001;
 final double minStep  = 0.001;
 final double maxStep  = 500;
 final double initStep = 60;
 final double[][] tolerance = NumericalPropagator.tolerances(dP, orbit, OrbitType.EQUINOCTIAL);
 AdaptiveStepsizeIntegrator integrator = new DormandPrince853Integrator(minStep, maxStep, tolerance[0], tolerance[1]);
 integrator.setInitialStepSize(initStep);
 propagator = new NumericalPropagator(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 changed by calling AbstractIntegratedPropagator.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:

SpacecraftState, ForceModel, OrekitStepHandler, OrekitFixedStepHandler, IntegratedEphemeris, TimeDerivativesEquations

Nested Class Summary
- Nested classes/interfaces inherited from class org.orekit.propagation.integration.AbstractIntegratedPropagator
  AbstractIntegratedPropagator.MainStateEquations

Field Summary
- Fields inherited from interface org.orekit.propagation.Propagator
  DEFAULT_MASS

Constructor Summary

Constructors
Constructor	Description
`NumericalPropagator(ODEIntegrator integrator)`	Create a new instance of NumericalPropagator, based on orbit definition mu.
`NumericalPropagator(ODEIntegrator integrator, AttitudeProvider attitudeProvider)`	Create a new instance of NumericalPropagator, based on orbit definition mu.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`addForceModel(ForceModel model)`	Add a force model.
`protected void`	`beforeIntegration(SpacecraftState initialState, AbsoluteDate tEnd)`	Method called just before integration.
`protected AbstractMatricesHarvester`	`createHarvester(String stmName, RealMatrix initialStm, DoubleArrayDictionary initialJacobianColumns)`	Create the harvester suitable for propagator.
`protected StateMapper`	`createMapper(AbsoluteDate referenceDate, double 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 AbstractIntegratedPropagator.MainStateEquations`	`getMainStateEquations(ODEIntegrator integrator)`	Get the differential equations to integrate (for main state only).
`OrbitType`	`getOrbitType()`	Get propagation parameter type.
`PositionAngleType`	`getPositionAngleType()`	Get propagation parameter type.
`protected AttitudeProvider`	`initializeAttitudeProviderForDerivatives()`	Method called when initializing the attitude provider used when evaluating derivatives.
`void`	`removeForceModels()`	Remove all force models (except central attraction).
`void`	`resetInitialState(SpacecraftState state)`	Reset the propagator initial state.
`void`	`setIgnoreCentralAttraction(boolean ignoreCentralAttraction)`	Set the flag to ignore or not the creation of a `NewtonianAttraction`.
`void`	`setInitialState(SpacecraftState initialState)`	Set the initial state.
`void`	`setMu(double mu)`	Set the central attraction coefficient μ.
`void`	`setOrbitType(OrbitType orbitType)`	Set propagation orbit type.
`void`	`setPositionAngleType(PositionAngleType positionAngleType)`	Set position angle type.
`protected void`	`setUpStmAndJacobianGenerators()`	Set up State Transition Matrix and Jacobian matrix handling.
`static double[][]`	`tolerances(double dP, double dV, Orbit orbit, OrbitType type)`	Estimate tolerance vectors for integrators when propagating in orbits.
`static double[][]`	`tolerances(double dP, Orbit orbit, OrbitType type)`	Estimate tolerance vectors for integrators when propagating in orbits.
`static double[][]`	`tolerances(double dP, AbsolutePVCoordinates absPva)`	Estimate tolerance vectors for integrators when propagating in absolute position-velocity-acceleration.

Methods inherited from class org.orekit.propagation.integration.AbstractIntegratedPropagator
addAdditionalDerivativesProvider, addEventDetector, afterIntegration, clearEventsDetectors, getAdditionalDerivativesProviders, getBasicDimension, getCalls, getEphemerisGenerator, getEventsDetectors, getInitialIntegrationState, getIntegrator, getIntegratorName, getManagedAdditionalStates, getMu, getPropagationType, getResetAtEnd, initMapper, isAdditionalStateManaged, propagate, propagate, setAttitudeProvider, setResetAtEnd, setUpEventDetector, setUpUserEventDetectors

Methods inherited from class org.orekit.propagation.AbstractPropagator
addAdditionalStateProvider, getAdditionalStateProviders, getAttitudeProvider, getFrame, getHarvester, getInitialState, getMultiplexer, getStartDate, initializeAdditionalStates, initializePropagation, setStartDate, setupMatricesComputation, 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.Propagator
clearStepHandlers, getPosition, getPVCoordinates, setStepHandler, setStepHandler

- Constructor Detail
  - NumericalPropagator
```
@DefaultDataContext
public NumericalPropagator(ODEIntegrator 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.
    
    See Also:
    
    NumericalPropagator(ODEIntegrator, AttitudeProvider)
  - NumericalPropagator
```
public NumericalPropagator(ODEIntegrator 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:
    
    integrator - numerical integrator to use for propagation.
    
    attitudeProvider - the attitude law.
    
    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(double mu)
```
    Set the central attraction coefficient μ.
    Setting the central attraction coefficient is equivalent to add a NewtonianAttraction force model. *
    
    Overrides:
    
    setMu in class AbstractIntegratedPropagator
    
    Parameters:
    
    mu - central attraction coefficient (m³/s²)
    
    See Also:
    
    addForceModel(ForceModel), getAllForceModels()
  - addForceModel
```
public void addForceModel(ForceModel model)
```
    Add a force model.
    If this method is not called at all, the integrated orbit will follow a Keplerian evolution only.
    
    Parameters:
    
    model - ForceModel to add (it can be either a perturbing force model or an instance of NewtonianAttraction)
    
    See Also:
    
    removeForceModels(), setMu(double)
  - removeForceModels
```
public void removeForceModels()
```
    Remove all force models (except central attraction).
    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
    
    See Also:
    
    addForceModel(ForceModel), setMu(double)
  - setOrbitType
```
public void setOrbitType(OrbitType orbitType)
```
    Set propagation orbit type.
    
    Overrides:
    
    setOrbitType in class AbstractIntegratedPropagator
    
    Parameters:
    
    orbitType - orbit type to use for propagation, null for propagating using AbsolutePVCoordinates rather than Orbit
  - getOrbitType
```
public OrbitType getOrbitType()
```
    Get propagation parameter type.
    
    Overrides:
    
    getOrbitType in class AbstractIntegratedPropagator
    
    Returns:
    
    orbit type used for propagation, null for propagating using AbsolutePVCoordinates rather than Orbit
  - 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 AbstractIntegratedPropagator
    
    Parameters:
    
    positionAngleType - angle type to use for propagation
  - getPositionAngleType
```
public PositionAngleType getPositionAngleType()
```
    Get propagation parameter type.
    
    Overrides:
    
    getPositionAngleType in class AbstractIntegratedPropagator
    
    Returns:
    
    angle type to use for propagation
  - setInitialState
```
public void setInitialState(SpacecraftState initialState)
```
    Set the initial state.
    
    Parameters:
    
    initialState - initial state
  - resetInitialState
```
public void resetInitialState(SpacecraftState state)
```
    Reset the propagator initial state.
    
    Specified by:
    
    resetInitialState in interface Propagator
    
    Overrides:
    
    resetInitialState in class AbstractPropagator
    
    Parameters:
    
    state - new initial state to consider
  - createHarvester
```
protected AbstractMatricesHarvester createHarvester(String stmName,
                                                    RealMatrix initialStm,
                                                    DoubleArrayDictionary initialJacobianColumns)
```
    Create the harvester suitable for propagator.
    
    Overrides:
    
    createHarvester in class AbstractPropagator
    
    Parameters:
    
    stmName - State Transition Matrix state name
    
    initialStm - initial State Transition Matrix ∂Y/∂Y₀, if null (which is the most frequent case), assumed to be 6x6 identity
    
    initialJacobianColumns - initial columns of the Jacobians matrix with respect to parameters, if null or if some selected parameters are missing from the dictionary, the corresponding initial column is assumed to be 0
    
    Returns:
    
    harvester to retrieve computed matrices during and after propagation
  - setUpStmAndJacobianGenerators
```
protected void setUpStmAndJacobianGenerators()
```
    Set up State Transition Matrix and Jacobian matrix handling.
    
    Overrides:
    
    setUpStmAndJacobianGenerators in class AbstractIntegratedPropagator
  - initializeAttitudeProviderForDerivatives
```
protected AttitudeProvider initializeAttitudeProviderForDerivatives()
```
    Method called when initializing the attitude provider used when evaluating derivatives.
    
    Overrides:
    
    initializeAttitudeProviderForDerivatives in class AbstractIntegratedPropagator
    
    Returns:
    
    attitude provider for derivatives
  - createMapper
```
protected StateMapper createMapper(AbsoluteDate referenceDate,
                                   double 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 AbstractIntegratedPropagator
    
    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 AbstractIntegratedPropagator.MainStateEquations getMainStateEquations(ODEIntegrator integrator)
```
    Get the differential equations to integrate (for main state only).
    
    Specified by:
    
    getMainStateEquations in class AbstractIntegratedPropagator
    
    Parameters:
    
    integrator - numerical integrator to use for propagation.
    
    Returns:
    
    differential equations for main state
  - tolerances
```
public static double[][] tolerances(double dP,
                                    AbsolutePVCoordinates absPva)
```
    Estimate tolerance vectors for integrators when propagating in absolute position-velocity-acceleration.
    
    Parameters:
    
    dP - user specified position error
    
    absPva - reference absolute position-velocity-acceleration
    
    Returns:
    
    a two rows array, row 0 being the absolute tolerance error and row 1 being the relative tolerance error
    
    See Also:
    
    tolerances(double, Orbit, OrbitType)
  - tolerances
```
public static double[][] tolerances(double dP,
                                    Orbit orbit,
                                    OrbitType type)
```
    Estimate tolerance vectors for integrators when propagating in orbits.
    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.
    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 double[][] tolerances(double dP,
                                    double dV,
                                    Orbit 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.
    
    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
  - beforeIntegration
```
protected void beforeIntegration(SpacecraftState initialState,
                                 AbsoluteDate tEnd)
```
    Method called just before integration.
    The default implementation does nothing, it may be specialized in subclasses.
    
    Overrides:
    
    beforeIntegration in class AbstractIntegratedPropagator
    
    Parameters:
    
    initialState - initial state
    
    tEnd - target date at which state should be propagated

Class NumericalPropagator

Nested Class Summary

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

Field Summary

Fields inherited from interface org.orekit.propagation.Propagator

Constructor Summary

Method Summary

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

Methods inherited from class org.orekit.propagation.AbstractPropagator

Methods inherited from class java.lang.Object

Methods inherited from interface org.orekit.propagation.Propagator

Constructor Detail

NumericalPropagator

NumericalPropagator

Method Detail

setIgnoreCentralAttraction

setMu

addForceModel

removeForceModels

getAllForceModels

setOrbitType

getOrbitType

setPositionAngleType

getPositionAngleType

setInitialState

resetInitialState

createHarvester

setUpStmAndJacobianGenerators

initializeAttitudeProviderForDerivatives

createMapper

getMainStateEquations

tolerances

tolerances

tolerances

beforeIntegration