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 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)
        Initialize the equations at the start of propagation.

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

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

      • computeDerivatives

        double[] computeDerivatives​(SpacecraftState s,
                            double[] pDot)
        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)