Package org.orekit.propagation

Interface AdditionalDataProvider<T>

Type Parameters:
T - type of the additional data
All Known Implementing Classes:
AbstractAnalyticalMatricesHarvester, AbstractStateModifier, ClockCorrectionsProvider, Duration, MedianDate, StateCovarianceMatrixProvider, TriggerDate
public interface AdditionalDataProvider<T>
This interface allows to modify SpacecraftState and set up additional data.

A data can be any type of java Object (i.e., double[], String, class, etc.)

Propagators generate states that contain at least orbit, attitude, and mass. These states may however also contain additional data. Instances of classes implementing this interface are intended to be registered to propagators so they can either modify the basic components (orbit, attitude and mass) or add additional data incrementally after having computed the basic components.

Some additional data may depend on previous additional data to be already available the before they can be computed. It may even be impossible to compute some of these additional data at some time if they depend on conditions that are fulfilled only after propagation as started or some event has occurred. As the propagator builds the complete state incrementally, looping over the registered providers, it must call their update methods in an order that fulfill these dependencies that may be time-dependent and are not related to the order in which the providers are registered to the propagator. This reordering is performed each time the complete state is built, using a yield mechanism. The propagator first pushes all providers in a stack and then empty the stack, one provider at a time, taking care to select only providers that do not yield when asked. Consider for example a case where providers A, B and C have been registered and provider B needs in fact the additional data generated by provider C. Then when a complete state is built, the propagator puts the three providers in a new stack, and then starts the incremental generation of additional data. It first checks provider A which does not yield so it is popped from the stack and the additional data it generates is added. Then provider B is checked, but it yields because state from provider C is not yet available. So propagator checks provider C which does not yield, so it is popped out of the stack and applied. At this stage, provider B is the only remaining one in the stack, so it is checked again, but this time it does not yield because the state from provider C is available as it has just been added, so provider B is popped from the stack and applied. The stack is now empty and the propagator can return the completed state.

It is possible that at some stages in the propagation, a subset of the providers registered to a propagator all yield and cannot update the data. This happens for example during the initialization phase of a propagator that computes State Transition Matrices or Jacobian matrices. These features are managed as secondary equations in the ODE integrator, and initialized after the primary equations (which correspond to orbit) have been initialized. So when the primary equation are initialized, the providers that depend on the secondary state will all yield. This behavior is expected. Another case occurs when users set up additional data that induce a dependency loop (data A depending on data B which depends on data C which depends on data A). In this case, the three corresponding providers will wait for each other and indefinitely yield. This second case is a deadlock and results from a design error of the additional data management at application level. The propagator cannot know it in advance if a subset of providers that all yield is normal or not. So at propagator level, when either situation is detected, the propagator just gives up and returns the most complete state it was able to compute, without generating any error. Errors will indeed not be triggered in the first case (once the primary equations have been initialized, the secondary equations will be initialized too), and they will be triggered in the second case as soon as user attempts to retrieve an additional data that was not added.

Since:
13.0
Author:
Luc Maisonobe
See Also:

  • Method Details

    • getName

      String getName()
      Get the name of the additional data.

      If a provider just modifies one of the basic elements (orbit, attitude or mass) without adding any new data, it should return the empty string as its name.

      Returns:
      name of the additional data (names containing "orekit" with any case are reserved for the library internal use)

    • init

      default void init(SpacecraftState initialState, AbsoluteDate target)
      Initialize the additional data provider at the start of propagation.
      Parameters:
      initialState - initial spacecraft state information at the start of propagation
      target - date of propagation

    • yields

      default boolean yields(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 data 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 yields(final SpacecraftState state) {
     return !state.hasAdditionalData("STM");
 }

      The default implementation returns false, meaning that state data can be generated 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

    • getAdditionalData

      T getAdditionalData(SpacecraftState state)
      Get the additional data.
      Parameters:
      state - spacecraft state to which additional data should correspond
      Returns:
      additional state corresponding to spacecraft state

    • update

      default SpacecraftState update(SpacecraftState state)
      Update a state.
      Parameters:
      state - spacecraft state to update
      Returns:
      updated state