Package org.orekit.propagation.integration

Interface AdditionalEquations

All Known Implementing Classes:

PartialDerivativesEquations

public interface AdditionalEquations

This interface allows users to add their own differential equations to a numerical propagator.

In some cases users may need to integrate some problem-specific equations along with classical spacecraft equations of motions. One example is optimal control in low thrust where adjoint parameters linked to the minimized Hamiltonian must be integrated. Another example is formation flying or rendez-vous which use the Clohessy-Whiltshire equations for the relative motion.

This interface allows users to add such equations to a numerical propagator. Users provide the equations as an implementation of this interface and register it to the propagator thanks to its AbstractIntegratedPropagator.addAdditionalEquations(AdditionalEquations) method. Several such objects can be registered with each numerical propagator, but it is recommended to gather in the same object the sets of parameters which equations can interact on each others states.

The additional parameters are gathered in a simple p array. The additional equations compute the pDot array, which is the time-derivative of the p array. Since the additional parameters p may also have an influence on the equations of motion themselves that should be accumulated to the main state derivatives (for example an equation linked to a complex thrust model may induce an acceleration and a mass change), the computeDerivatives method can return a double array that will be added to the main state derivatives. This means these equations can be used as an additional force model if needed. If the additional parameters have no influence at all on the main spacecraft state, a null reference may be returned.

This interface is the numerical (read not already integrated) counterpart of the AdditionalStateProvider interface. It allows to append various additional state parameters to any numerical propagator.

Author:

Luc Maisonobe

See Also:

AbstractIntegratedPropagator, AdditionalStateProvider

Method Summary

Modifier and Type	Method	Description
double[]	computeDerivatives(SpacecraftState s, double[] pDot)	Compute the derivatives related to the additional state parameters.
String	getName()	Get the name of the additional state.
default void	init(SpacecraftState initialState, AbsoluteDate target)	Initialize the equations at the start of propagation.

Method Detail

getName

String getName()

Get the name of the additional state.

Returns:

name of the additional state

init

default void init(SpacecraftState initialState,
                  AbsoluteDate target)
           throws OrekitException

Initialize the equations at the start of propagation.

This method will be called once at propagation start, before any calls to #computeDerivatives(SpacecraftState).

The default implementation of this method does nothing.

Parameters:

initialState - initial state information at the start of propagation.

target - date of propagation. Not equal to initialState.getDate().

Throws:

OrekitException - if there is an Orekit related error during initialization.

computeDerivatives

double[] computeDerivatives(SpacecraftState s,
                            double[] pDot)
                     throws OrekitException

Compute the derivatives related to the additional state parameters.

When this method is called, the spacecraft state contains the main state (orbit, attitude and mass), all the states provided through the additional state providers registered to the propagator, and the additional state integrated using this equation. It does not contains any other states to be integrated alongside during the same propagation.

Parameters:

s - current state information: date, kinematics, attitude, and additional state

pDot - placeholder where the derivatives of the additional parameters should be put

Returns:

cumulative effect of the equations on the main state (may be null if equations do not change main state at all)

Throws:

OrekitException - if some specific error occurs