AdditionalStateProvider.java

  1. /* Copyright 2002-2024 CS GROUP
  2.  * Licensed to CS GROUP (CS) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * CS licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *   http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.orekit.propagation;

  18. import org.orekit.time.AbsoluteDate;

  19. /** This interface allows to modify {@link SpacecraftState} and set up additional state data.
  20.  * <p>
  21.  * {@link Propagator Propagators} generate {@link SpacecraftState states} that contain at
  22.  * least orbit, attitude, and mass. These states may however also contain {@link
  23.  * SpacecraftState#addAdditionalState(String, double...) additional states}. Instances of classes
  24.  * implementing this interface are intended to be registered to propagators so they can either
  25.  * modify the basic components (orbit, attitude and mass) or add additional states incrementally
  26.  * after having computed the basic components.
  27.  * </p>
  28.  * <p>
  29.  * Some additional states may depend on previous additional states to
  30.  * be already available the before they can be computed. It may even be impossible to compute some
  31.  * of these additional states at some time if they depend on conditions that are fulfilled only
  32.  * after propagation as started or some event has occurred. As the propagator builds the complete
  33.  * state incrementally, looping over the registered providers, it must call their {@link
  34.  * #update(SpacecraftState) update} methods in an order that fulfill these dependencies that
  35.  * may be time-dependent and are not related to the order in which the providers are registered to
  36.  * the propagator. This reordering is performed each time the complete state is built, using a yield
  37.  * mechanism. The propagator first pushes all providers in a stack and then empty the stack, one provider
  38.  * at a time, taking care to select only providers that do <em>not</em> {@link
  39.  * #yields(SpacecraftState) yield} when asked. Consider for example a case where providers A, B and C
  40.  * have been registered and provider B needs in fact the additional state generated by provider C. Then
  41.  * when a complete state is built, the propagator puts the three providers in a new stack, and then starts the incremental
  42.  * generation of additional states. It first checks provider A which does not yield so it is popped from
  43.  * the stack and the additional state it generates is added. Then provider B is checked, but it yields
  44.  * because state from provider C is not yet available. So propagator checks provider C which does not
  45.  * yield, so it is popped out of the stack and applied. At this stage, provider B is the only remaining one
  46.  * in the stack, so it is checked again, but this time it does not yield because the state from provider
  47.  * C is available as it has just been added, so provider B is popped from the stack and applied. The stack
  48.  * is now empty and the propagator can return the completed state.
  49.  * </p>
  50.  * <p>
  51.  * It is possible that at some stages in the propagation, a subset of the providers registered to a
  52.  * propagator all yield and cannot {@link #update(SpacecraftState) update} the state. This happens
  53.  * for example during the initialization phase of a propagator that
  54.  * computes State Transition Matrices or Jacobian matrices. These features are managed as secondary equations
  55.  * in the ODE integrator, and initialized after the primary equations (which correspond to orbit) have
  56.  * been initialized. So when the primary equation are initialized, the providers that depend on the secondary
  57.  * state will all yield. This behavior is expected. Another case occurs when users set up additional states
  58.  * that induce a dependency loop (state A depending on state B which depends on state C which depends on
  59.  * state A). In this case, the three corresponding providers will wait for each other and indefinitely yield.
  60.  * This second case is a deadlock and results from a design error of the additional states management at
  61.  * application level. The propagator cannot know it in advance if a subset of providers that all yield is
  62.  * normal or not. So at propagator level, when either situation is detected, the propagator just gives up and
  63.  * returns the most complete state it was able to compute, without generating any error. Errors will indeed
  64.  * not be triggered in the first case (once the primary equations have been initialized, the secondary
  65.  * equations will be initialized too), and they will be triggered in the second case as soon as user attempts
  66.  * to retrieve an additional state that was not added.
  67.  * </p>
  68.  * @see org.orekit.propagation.Propagator
  69.  * @see org.orekit.propagation.integration.AdditionalDerivativesProvider
  70.  * @see AbstractStateModifier
  71.  * @author Luc Maisonobe
  72.  */
  73. public interface AdditionalStateProvider {

  74.     /** Get the name of the additional state.
  75.      * <p>
  76.      * If a provider just modifies one of the basic elements (orbit, attitude
  77.      * or mass) without adding any new state, it should return the empty string
  78.      * as its name.
  79.      * </p>
  80.      * @return name of the additional state (names containing "orekit"
  81.      * with any case are reserved for the library internal use)
  82.      */
  83.     String getName();

  84.     /** Initialize the additional state provider at the start of propagation.
  85.      * @param initialState initial state information at the start of propagation
  86.      * @param target       date of propagation
  87.      * @since 11.2
  88.      */
  89.     default void init(final SpacecraftState initialState, final AbsoluteDate target) {
  90.         // nothing by default
  91.     }

  92.     /** Check if this provider should yield so another provider has an opportunity to add missing parts.
  93.      * <p>
  94.      * Decision to yield is often based on an additional state being {@link SpacecraftState#hasAdditionalState(String)
  95.      * already available} in the provided {@code state} (but it could theoretically also depend on
  96.      * an additional state derivative being {@link SpacecraftState#hasAdditionalStateDerivative(String)
  97.      * already available}, or any other criterion). If for example a provider needs the state transition
  98.      * matrix, it could implement this method as:
  99.      * </p>
  100.      * <pre>{@code
  101.      * public boolean yields(final SpacecraftState state) {
  102.      *     return !state.getAdditionalStates().containsKey("STM");
  103.      * }
  104.      * }</pre>
  105.      * <p>
  106.      * The default implementation returns {@code false}, meaning that state data can be
  107.      * {@link #getAdditionalState(SpacecraftState) generated} immediately.
  108.      * </p>
  109.      * @param state state to handle
  110.      * @return true if this provider should yield so another provider has an opportunity to add missing parts
  111.      * as the state is incrementally built up
  112.      * @since 11.1
  113.      */
  114.     default boolean yields(SpacecraftState state) {
  115.         return false;
  116.     }

  117.     /** Get the additional state.
  118.      * @param state spacecraft state to which additional state should correspond
  119.      * @return additional state corresponding to spacecraft state
  120.      */
  121.     double[] getAdditionalState(SpacecraftState state);

  122.     /** Update a state.
  123.      * @param state spacecraft state to update
  124.      * @return updated state
  125.      * @since 12.1
  126.      */
  127.     default SpacecraftState update(final SpacecraftState state) {
  128.         return state.addAdditionalState(getName(), getAdditionalState(state));
  129.     }

  130. }