Package org.orekit.propagation.semianalytical.dsst

Class DSSTPropagator

java.lang.Object

org.orekit.propagation.AbstractPropagator

org.orekit.propagation.integration.AbstractIntegratedPropagator

org.orekit.propagation.semianalytical.dsst.DSSTPropagator

All Implemented Interfaces:

Propagator, PVCoordinatesProvider

public class DSSTPropagator
extends AbstractIntegratedPropagator

This class propagates orbits using the DSST theory.

Whereas analytical propagators are configured only thanks to their various constructors and can be used immediately after construction, such a semianalytical propagator configuration involves setting several parameters between construction time and propagation time, just as numerical propagators.

The configuration parameters that can be set are:

• the initial spacecraft state (setInitialState(SpacecraftState))
• the various force models (addForceModel(DSSTForceModel), removeForceModels())
• the discrete events that should be triggered during propagation ( AbstractIntegratedPropagator.addEventDetector(org.orekit.propagation.events.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. The central attraction coefficient used to define the initial orbit will be used. However, specifying only the initial state would mean the propagator would use only Keplerian forces. In this case, the simpler KeplerianPropagator class would 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 six elements double array. These six elements are:

• the equinoctial orbit parameters (a, e_x, e_y, h_x, h_y, λ_m) in meters and radians,

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 AbstractIntegratedPropagator.setResetAtEnd(boolean).

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

Author:

Romain Di Costanzo, Pascal Parraud

See Also:

• SpacecraftState
• DSSTForceModel

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
DSSTPropagator(ODEIntegrator integrator)	Create a new instance of DSSTPropagator.
DSSTPropagator(ODEIntegrator integrator, PropagationType propagationType)	Create a new instance of DSSTPropagator.
DSSTPropagator(ODEIntegrator integrator, PropagationType propagationType, AttitudeProvider attitudeProvider)	Create a new instance of DSSTPropagator.

Method Summary

Modifier and Type	Method	Description
void	addForceModel(DSSTForceModel force)	Add a force model to the global perturbation model.
protected void	afterIntegration()	Method called just after integration.
protected void	beforeIntegration(SpacecraftState initialState, AbsoluteDate tEnd)	Method called just before integration.
static SpacecraftState	computeMeanState(SpacecraftState osculating, AttitudeProvider attitudeProvider, Collection<DSSTForceModel> forceModels)	Conversion from osculating to mean orbit.
static SpacecraftState	computeMeanState(SpacecraftState osculating, AttitudeProvider attitudeProvider, Collection<DSSTForceModel> forceModels, double epsilon, int maxIterations)	Conversion from osculating to mean orbit.
static SpacecraftState	computeMeanState(SpacecraftState osculating, AttitudeProvider attitudeProvider, Collection<DSSTForceModel> forceModels, OsculatingToMeanConverter converter)	Conversion from osculating to mean orbit.
static SpacecraftState	computeOsculatingState(SpacecraftState mean, AttitudeProvider attitudeProvider, Collection<DSSTForceModel> forces)	Conversion from mean to osculating orbit.
protected DSSTHarvester	createHarvester(String stmName, RealMatrix initialStm, DoubleArrayDictionary initialJacobianColumns)	Create the harvester suitable for propagator.
protected StateMapper	createMapper(AbsoluteDate referenceDate, double mu, OrbitType ignoredOrbitType, PositionAngleType ignoredPositionAngleType, AttitudeProvider attitudeProvider, Frame frame)	Create a mapper between raw double components and spacecraft state. /** Simple constructor.
List<DSSTForceModel>	getAllForceModels()	Get all the force models, perturbing forces and Newtonian attraction included.
protected DSSTHarvester	getHarvester()	Get the harvester.
protected SpacecraftState	getInitialIntegrationState()	Get the initial state for integration.
protected List<String>	getJacobiansColumnsNames()	Get the names of the parameters in the matrix returned by MatricesHarvester.getParametersJacobian(org.orekit.propagation.SpacecraftState).
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.
int	getSatelliteRevolution()	Get the number of satellite revolutions to use for converting osculating to mean elements.
Set<String>	getSelectedCoefficients()	Get the selected short periodic coefficients that must be stored as additional states.
List<ShortPeriodTerms>	getShortPeriodTerms()	Get the short periodic terms.
double[]	getShortPeriodTermsValue(SpacecraftState meanState)	Get the short period terms value.
boolean	initialIsOsculating()	Check if the initial state is provided in osculating elements.
void	removeForceModels()	Remove all perturbing force models from the global perturbation model (except central attraction).
void	resetInitialState(SpacecraftState state)	Reset the initial state.
void	resetInitialState(SpacecraftState state, PropagationType stateType)	Reset initial state with a given propagation type.
void	setAttitudeProvider(AttitudeProvider attitudeProvider)	Set attitude provider.
void	setInitialState(SpacecraftState initialState)	Set the initial state with osculating orbital elements.
void	setInitialState(SpacecraftState initialState, PropagationType stateType)	Set the initial state.
void	setInterpolationGridToFixedNumberOfPoints(int interpolationPoints)	Set the interpolation grid generator.
void	setInterpolationGridToMaxTimeGap(double maxGap)	Set the interpolation grid generator.
void	setMu(double mu)	Set the central attraction coefficient μ.
void	setSatelliteRevolution(int satelliteRevolution)	Override the default value of the parameter.
void	setSelectedCoefficients(Set<String> selectedCoefficients)	Set the selected short periodic coefficients that must be stored as additional states.
void	setShortPeriodTerms(List<ShortPeriodTerms> shortPeriodTerms)	Override the default value short periodic terms.
DSSTHarvester	setupMatricesComputation(String stmName, RealMatrix initialStm, DoubleArrayDictionary initialJacobianColumns)	Set up computation of State Transition Matrix and Jacobians matrix with respect to parameters.
protected void	setUpStmAndJacobianGenerators()	Set up State Transition Matrix and Jacobian matrix handling.

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

addAdditionalDerivativesProvider, addEventDetector, clearEphemerisGenerators, clearEventsDetectors, clearMatricesComputation, getAdditionalDerivativesProviders, getBasicDimension, getCalls, getEphemerisGenerator, getEventDetectors, getFrozenAttitudeProvider, getIntegrator, getIntegratorName, getManagedAdditionalData, getMu, getPropagationType, getResetAtEnd, initializeAttitudeProviderForDerivatives, initMapper, isAdditionalDataManaged, propagate, propagate, removeAdditionalDerivativesProvider, setOrbitType, setPositionAngleType, setResetAtEnd, setUpEventDetector, setUpUserEventDetectors

Methods inherited from class org.orekit.propagation.AbstractPropagator

addAdditionalDataProvider, getAdditionalDataProviders, getAttitudeProvider, getFrame, getInitialState, getMultiplexer, getStartDate, initializeAdditionalData, initializePropagation, removeAdditionalDataProvider, setStartDate, stateChanged, updateAdditionalData, updateUnmanagedData

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, getVelocity, setStepHandler, setStepHandler

Constructor Details

DSSTPropagator

@DefaultDataContext
public DSSTPropagator(ODEIntegrator integrator,
 PropagationType propagationType)

Create a new instance of DSSTPropagator.

After creation, 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.

This constructor uses the default data context.

Parameters:

integrator - numerical integrator to use for propagation.

propagationType - type of orbit to output (mean or osculating).

See Also:

• DSSTPropagator(ODEIntegrator, PropagationType, AttitudeProvider)

DSSTPropagator

public DSSTPropagator(ODEIntegrator integrator,
 PropagationType propagationType,
 AttitudeProvider attitudeProvider)

Create a new instance of DSSTPropagator.

After creation, 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.

propagationType - type of orbit to output (mean or osculating).

attitudeProvider - the attitude law.

Since:

10.1

DSSTPropagator

@DefaultDataContext
public DSSTPropagator(ODEIntegrator integrator)

Create a new instance of DSSTPropagator.

After creation, 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. Only the mean orbits will be generated.

This constructor uses the default data context.

Parameters:

integrator - numerical integrator to use for propagation.

See Also:

• DSSTPropagator(ODEIntegrator, PropagationType, AttitudeProvider)

Method Details

setMu

public void setMu(double mu)

Set the central attraction coefficient μ.

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

Overrides:

setMu in class AbstractIntegratedPropagator

Parameters:

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

See Also:

• addForceModel(DSSTForceModel)
• getAllForceModels()

setInitialState

public void setInitialState(SpacecraftState initialState)

Set the initial state with osculating orbital elements.

Parameters:

initialState - initial state (defined with osculating elements)

setInitialState

public void setInitialState(SpacecraftState initialState,
 PropagationType stateType)

Set the initial state.

Parameters:

initialState - initial state

stateType - defined if the orbital state is defined with osculating or mean elements

resetInitialState

public void resetInitialState(SpacecraftState state)

Reset the initial state.

Specified by:

resetInitialState in interface Propagator

Overrides:

resetInitialState in class AbstractPropagator

Parameters:

state - new initial state

resetInitialState

public void resetInitialState(SpacecraftState state,
 PropagationType stateType)

Reset initial state with a given propagation type.

By default this method returns the same as AbstractPropagator.resetInitialState(SpacecraftState)

Its purpose is mostly to be derived in DSSTPropagator.

Change parameter initialIsOsculating() accordingly

Overrides:

resetInitialState in class AbstractIntegratedPropagator

Parameters:

state - new initial state to consider

stateType - type of the new state (mean or osculating)

Since:

12.1.3

setSelectedCoefficients

public void setSelectedCoefficients(Set<String> selectedCoefficients)

Set the selected short periodic coefficients that must be stored as additional states.

Parameters:

selectedCoefficients - short periodic coefficients that must be stored as additional states (null means no coefficients are selected, empty set means all coefficients are selected)

getSelectedCoefficients

public Set<String> getSelectedCoefficients()

Get the selected short periodic coefficients that must be stored as additional states.

Returns:

short periodic coefficients that must be stored as additional states (null means no coefficients are selected, empty set means all coefficients are selected)

getJacobiansColumnsNames

protected List<String> getJacobiansColumnsNames()

Get the names of the parameters in the matrix returned by MatricesHarvester.getParametersJacobian(org.orekit.propagation.SpacecraftState).

Returns:

names of the parameters (i.e. columns) of the Jacobian matrix

setupMatricesComputation

public DSSTHarvester setupMatricesComputation(String stmName,
 RealMatrix initialStm,
 DoubleArrayDictionary initialJacobianColumns)

Set up computation of State Transition Matrix and Jacobians matrix with respect to parameters.

If this method is called, both State Transition Matrix and Jacobians with respect to the force models parameters that will be selected when propagation starts will be automatically computed, and the harvester will allow to retrieve them.

The arguments for initial matrices must be compatible with the orbit type and position angle that will be used by the propagator.

Specified by:

setupMatricesComputation in interface Propagator

Overrides:

setupMatricesComputation 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

createHarvester

protected DSSTHarvester 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

getHarvester

protected DSSTHarvester getHarvester()

Get the harvester.

Overrides:

getHarvester in class AbstractPropagator

Returns:

harvester, or null if it was not created

setUpStmAndJacobianGenerators

protected void setUpStmAndJacobianGenerators()

Set up State Transition Matrix and Jacobian matrix handling.

Overrides:

setUpStmAndJacobianGenerators in class AbstractIntegratedPropagator

initialIsOsculating

public boolean initialIsOsculating()

Check if the initial state is provided in osculating elements.

Returns:

true if initial state is provided in osculating elements

setInterpolationGridToFixedNumberOfPoints

public void setInterpolationGridToFixedNumberOfPoints(int interpolationPoints)

Set the interpolation grid generator.

The generator will create an interpolation grid with a fixed number of points for each mean element integration step.

If neither setInterpolationGridToFixedNumberOfPoints(int) nor setInterpolationGridToMaxTimeGap(double) has been called, by default the propagator is set as to 3 interpolations points per step.

Parameters:

interpolationPoints - number of interpolation points at each integration step

Since:

7.1

See Also:

• setInterpolationGridToMaxTimeGap(double)

setInterpolationGridToMaxTimeGap

public void setInterpolationGridToMaxTimeGap(double maxGap)

Set the interpolation grid generator.

The generator will create an interpolation grid with a maximum time gap between interpolation points.

If neither setInterpolationGridToFixedNumberOfPoints(int) nor setInterpolationGridToMaxTimeGap(double) has been called, by default the propagator is set as to 3 interpolations points per step.

Parameters:

maxGap - maximum time gap between interpolation points (seconds)

Since:

7.1

See Also:

• setInterpolationGridToFixedNumberOfPoints(int)

addForceModel

public void addForceModel(DSSTForceModel force)

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:

force - perturbing force to add

See Also:

• removeForceModels()
• setMu(double)

removeForceModels

public void removeForceModels()

Remove all perturbing force models from the global perturbation model (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(DSSTForceModel)

getAllForceModels

public List<DSSTForceModel> 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(DSSTForceModel)
• setMu(double)

getOrbitType

public OrbitType getOrbitType()

Get propagation parameter type.

Overrides:

getOrbitType in class AbstractIntegratedPropagator

Returns:

orbit type used for propagation

getPositionAngleType

public PositionAngleType getPositionAngleType()

Get propagation parameter type.

Overrides:

getPositionAngleType in class AbstractIntegratedPropagator

Returns:

angle type to use for propagation

computeOsculatingState

public static SpacecraftState computeOsculatingState(SpacecraftState mean,
 AttitudeProvider attitudeProvider,
 Collection<DSSTForceModel> forces)

Conversion from mean to osculating orbit.

Compute osculating state in a DSST sense, corresponding to the mean SpacecraftState in input, and according to the Force models taken into account.

Since the osculating state is obtained by adding short-periodic variation of each force model, the resulting output will depend on the force models parameterized in input.

Parameters:

mean - Mean state to convert

attitudeProvider - attitude provider (may be null if there are no Gaussian force models like atmospheric drag, radiation pressure or specific user-defined models)

forces - Forces to take into account

Returns:

osculating state in a DSST sense

computeMeanState

public static SpacecraftState computeMeanState(SpacecraftState osculating,
 AttitudeProvider attitudeProvider,
 Collection<DSSTForceModel> forceModels)

Conversion from osculating to mean orbit.

Compute mean state in a DSST sense, corresponding to the osculating SpacecraftState in input, and according to the Force models taken into account.

Since the osculating state is obtained with the computation of short-periodic variation of each force model, the resulting output will depend on the force models parameterized in input.

The computation is done through a fixed-point iteration process.

Parameters:

osculating - Osculating state to convert

attitudeProvider - attitude provider (may be null if there are no Gaussian force models like atmospheric drag, radiation pressure or specific user-defined models)

forceModels - Forces to take into account

Returns:

mean state in a DSST sense

computeMeanState

public static SpacecraftState computeMeanState(SpacecraftState osculating,
 AttitudeProvider attitudeProvider,
 Collection<DSSTForceModel> forceModels,
 double epsilon,
 int maxIterations)

Conversion from osculating to mean orbit.

Compute mean state in a DSST sense, corresponding to the osculating SpacecraftState in input, and according to the Force models taken into account.

Since the osculating state is obtained with the computation of short-periodic variation of each force model, the resulting output will depend on the force models parameterized in input.

The computation is done through a fixed-point iteration process.

Parameters:

osculating - Osculating state to convert

attitudeProvider - attitude provider (may be null if there are no Gaussian force models like atmospheric drag, radiation pressure or specific user-defined models)

forceModels - Forces to take into account

epsilon - convergence threshold for mean parameters conversion

maxIterations - maximum iterations for mean parameters conversion

Returns:

mean state in a DSST sense

Since:

10.1

computeMeanState

public static SpacecraftState computeMeanState(SpacecraftState osculating,
 AttitudeProvider attitudeProvider,
 Collection<DSSTForceModel> forceModels,
 OsculatingToMeanConverter converter)

Conversion from osculating to mean orbit.

Compute mean state in a DSST sense, corresponding to the osculating SpacecraftState in input, and according to the Force models taken into account.

Since the osculating state is obtained with the computation of short-periodic variation of each force model, the resulting output will depend on the force models parameterized in input.

The computation is done using the given osculating to mean orbit converter.

Parameters:

osculating - osculating state to convert

attitudeProvider - attitude provider (may be null if there are no Gaussian force models like atmospheric drag, radiation pressure or specific user-defined models)

forceModels - forces to take into account

converter - osculating to mean orbit converter

Returns:

mean state in a DSST sense

Since:

13.0

setSatelliteRevolution

public void setSatelliteRevolution(int satelliteRevolution)

Override the default value of the parameter.

By default, if the initial orbit is defined as osculating, it will be averaged over 2 satellite revolutions. This can be changed by using this method.

Parameters:

satelliteRevolution - number of satellite revolutions to use for converting osculating to mean elements

getSatelliteRevolution

public int getSatelliteRevolution()

Get the number of satellite revolutions to use for converting osculating to mean elements.

Returns:

number of satellite revolutions to use for converting osculating to mean elements

setShortPeriodTerms

public void setShortPeriodTerms(List<ShortPeriodTerms> shortPeriodTerms)

Override the default value short periodic terms.

By default, short periodic terms are initialized before the numerical integration of the mean orbital elements.

Parameters:

shortPeriodTerms - short periodic terms

getShortPeriodTerms

public List<ShortPeriodTerms> getShortPeriodTerms()

Get the short periodic terms.

Returns:

the short periodic terms

setAttitudeProvider

public void setAttitudeProvider(AttitudeProvider attitudeProvider)

Set attitude provider.

Specified by:

setAttitudeProvider in interface Propagator

Overrides:

setAttitudeProvider in class AbstractIntegratedPropagator

Parameters:

attitudeProvider - attitude provider

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

afterIntegration

protected void afterIntegration()

Method called just after integration.

The default implementation does nothing, it may be specialized in subclasses.

Overrides:

afterIntegration in class AbstractIntegratedPropagator

getInitialIntegrationState

protected SpacecraftState getInitialIntegrationState()

Get the initial state for integration.

Overrides:

getInitialIntegrationState in class AbstractIntegratedPropagator

Returns:

initial state for integration

createMapper

protected StateMapper createMapper(AbsoluteDate referenceDate,
 double mu,
 OrbitType ignoredOrbitType,
 PositionAngleType ignoredPositionAngleType,
 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.

Note that for DSST, orbit type is hardcoded to OrbitType.EQUINOCTIAL and position angle type is hardcoded to PositionAngleType.MEAN, so the corresponding parameters are ignored.

Specified by:

createMapper in class AbstractIntegratedPropagator

Parameters:

referenceDate - reference date

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

ignoredOrbitType - orbit type to use for mapping

ignoredPositionAngleType - angle type to use for propagation

attitudeProvider - attitude provider

frame - inertial frame

Returns:

new mapper

getShortPeriodTermsValue

public double[] getShortPeriodTermsValue(SpacecraftState meanState)

Get the short period terms value.

Parameters:

meanState - the mean state

Returns:

shortPeriodTerms short period terms

Since:

7.1

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