AdditionalDerivativesProvider (ORbit Extrapolation KIT 11.2 API)

All Known Implementing Classes:

AbsolutePartialDerivativesEquations, AdditionalEquationsAdapter, DSSTPartialDerivativesEquations, EpochDerivativesEquations, MassDepletionDelay, PartialDerivativesEquations, STMEquations
```
public interface AdditionalDerivativesProvider
```
Provider for additional derivatives.
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 or a DSST propagator. Users provide the equations as an implementation of this interface and register it to the propagator thanks to its AbstractIntegratedPropagator.addAdditionalDerivativesProvider(AdditionalDerivativesProvider) 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.

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 or DSST propagator.

Since:

11.1

Author:

Luc Maisonobe

See Also:

AbstractIntegratedPropagator

Method Summary

All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`default CombinedDerivatives`	`combinedDerivatives(SpacecraftState s)` Compute the derivatives related to the additional state (and optionally main state increments).
`double[]`	`derivatives(SpacecraftState s)` Deprecated. as of 11.2, replaced by `combinedDerivatives(SpacecraftState)`
`int`	`getDimension()` Get the dimension of the generated derivative.
`String`	`getName()` Get the name of the additional derivatives (which will become state once integrated).
`default void`	`init(SpacecraftState initialState, AbsoluteDate target)` Initialize the generator at the start of propagation.
`default boolean`	`yield(SpacecraftState state)` Check if this provider should yield so another provider has an opportunity to add missing parts.

- Method Detail
  - getName
```
String getName()
```
    Get the name of the additional derivatives (which will become state once integrated).
    
    Returns:
    
    name of the additional state (names containing "orekit" with any case are reserved for the library internal use)
  - getDimension
```
int getDimension()
```
    Get the dimension of the generated derivative.
    
    Returns:
    
    dimension of the generated
  - init
```
default void init(SpacecraftState initialState,
                  AbsoluteDate target)
```
    Initialize the generator at the start of propagation.
    
    Parameters:
    
    initialState - initial state information at the start of propagation
    
    target - date of propagation
  - yield
```
default boolean yield(SpacecraftState state)
```
    Check if this provider should yield so another provider has an opportunity to add missing parts.
    Decision to yield is often based on an additional state being already available in the provided state (but it could theoretically also depend on an additional state derivative being already available, or any other criterion). If for example a provider needs the state transition matrix, it could implement this method as:
```
 public boolean yield(final SpacecraftState state) {
     return !state.getAdditionalStates().containsKey("STM");
 }
 
```
    The default implementation returns false, meaning that derivative data can be computed immediately.
    Parameters:
    
    state - state to handle
    
    Returns:
    
    true if this provider should yield so another provider has an opportunity to add missing parts as the state is incrementally built up
  - derivatives
```
@Deprecated
double[] derivatives(SpacecraftState s)
```
    Deprecated. as of 11.2, replaced by combinedDerivatives(SpacecraftState)
    
    Compute the derivatives related to the additional state parameters.
    
    Parameters:
    
    s - current state information: date, kinematics, attitude, and additional states this equations depend on (according to the yield method)
    
    Returns:
    
    computed derivatives
  - combinedDerivatives
```
default CombinedDerivatives combinedDerivatives(SpacecraftState s)
```
    Compute the derivatives related to the additional state (and optionally main state increments).
    As of 11.2, there is a default implementation that calls the deprecated derivatives(SpacecraftState) method. This has been done for backward compatibility only and will be removed in 12.0.
    
    Parameters:
    
    s - current state information: date, kinematics, attitude, and additional states this equations depend on (according to the yield method)
    
    Returns:
    
    computed combined derivatives, which may include some incremental coupling effect to add to main state derivatives
    
    Since:
    
    11.2

Interface AdditionalDerivativesProvider

Method Summary

Method Detail

getName

getDimension

init

yield

derivatives

combinedDerivatives