Commit f554f4d2 authored by Luc Maisonobe's avatar Luc Maisonobe
Browse files

Javadoc.

parent 4918b1e3
......@@ -34,11 +34,11 @@ package org.orekit.propagation;
* #getAdditionalState(SpacecraftState) getAdditionalState} 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 push all providers in a stack and then empty the stack, one provider
* 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 <em>not</em> {@link
* #yield(SpacecraftState) 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 state generated by state C. Then
* when a complete state is built, the propagator puts the three providers, and then starts the incremental
* have been registered and provider B needs in fact the additional state 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 states. It first checks provider A which does not yield so it is popped from
* the stack and the additional state 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
......@@ -51,15 +51,15 @@ package org.orekit.propagation;
* It is possible that at some stages in the propagation, a subset of the providers registered to a
* propagator all yied and cannot {@link #getAdditionalState(SpacecraftState) retrieve} their additional
* state. This happens for example during the initialization phase of a propagator that
* compute State Transition Matrices or Jacobian matrices. These features are managed as secondary equations
* 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 states
* that induces dependency loop (state A depending on state B which depends on state C which depends on
* that induce a dependency loop (state A depending on state B which depends on state C which depends on
* state 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 states management at
* application level. The propagator cannot know it in advance if as subset of providers that all yield is
* normal or not. So at propagator level, when either situation is detected, the propagator just give up and
* 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
......
......@@ -36,11 +36,11 @@ import org.hipparchus.CalculusFieldElement;
* #getAdditionalState(FieldSpacecraftState) getAdditionalState} 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 push all providers in a stack and then empty the stack, one provider
* 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 <em>not</em> {@link
* #yield(FieldSpacecraftState) 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 state generated by state C. Then
* when a complete state is built, the propagator puts the three providers, and then starts the incremental
* have been registered and provider B needs in fact the additional state 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 states. It first checks provider A which does not yield so it is popped from
* the stack and the additional state 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
......@@ -53,15 +53,15 @@ import org.hipparchus.CalculusFieldElement;
* It is possible that at some stages in the propagation, a subset of the providers registered to a
* propagator all yied and cannot {@link #getAdditionalState(FieldSpacecraftState) retrieve} their additional
* state. This happens for example during the initialization phase of a propagator that
* compute State Transition Matrices or Jacobian matrices. These features are managed as secondary equations
* 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 states
* that induces dependency loop (state A depending on state B which depends on state C which depends on
* that induce a dependency loop (state A depending on state B which depends on state C which depends on
* state 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 states management at
* application level. The propagator cannot know it in advance if as subset of providers that all yield is
* normal or not. So at propagator level, when either situation is detected, the propagator just give up and
* 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
......
......@@ -59,7 +59,7 @@ import org.orekit.time.AbsoluteDate;
* @see AbstractIntegratedPropagator
* @see org.orekit.propagation.AdditionalStateProvider
* @author Luc Maisonobe
* @deprecated as of 11.1, repalced by {@link AdditionalDerivativesProvider}
* @deprecated as of 11.1, replaced by {@link AdditionalDerivativesProvider}
*/
@Deprecated
public interface AdditionalEquations {
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment