agi.foundation.propagators

(agi.foundation.models-2025r1.jar)

Class SinglePointStoppablePropagator

java.lang.Object

agi.foundation.propagators.StoppablePropagator

agi.foundation.propagators.SinglePointStoppablePropagator

All Implemented Interfaces:

IDisposable, IEvaluator, ICloneWithContext, IThreadAware, IAvailability, AutoCloseable

public abstract class SinglePointStoppablePropagator
extends StoppablePropagator

Samples a Point at a specified time step until a StoppingCondition is satisfied, returning the ephemeris computed and all events found by the StoppingConditions (get).

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SinglePointStoppablePropagator(EvaluatorGroup group, SinglePointStoppablePropagatorDefinition definition, List<StateElementAdapterDefinition> previousAdapters) Initializes a new instance.
protected	SinglePointStoppablePropagator(SinglePointStoppablePropagator existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.

Method Summary

Modifier and Type	Method and Description
protected StoppablePropagatorResults	createStoppedPropagatorResult(StoppingConditionEvent stoppingEvent, List<StoppingConditionEvent> detectedEvents, List<ITimeBasedState> savedStates, boolean aborted) Creates the results of the overall propagation after the stopping event has been found.
protected void	dispose(boolean disposing) Releases any resources associated with this instance.
ITimeBasedState	getInitialState(IntegrationSense direction) Creates the initial state from the wrapped propagator.
protected ReferenceFrame	getPropagationFrame() Gets the ReferenceFrame to propagate the point in.
protected Duration	getPropagatorsRecommendedStep() Gets the step size that the underlying propagator recommends to step.
protected abstract PointEvaluator	initializePropagationPoint(JulianDate date, Motion1<Cartesian> motion) Creates the PointEvaluator that will be sampled for propagation.
void	initializePropagator(ITimeBasedState initialState) Initializes the wrapped propagator with the initial state.
SinglePointStoppablePropagatorResults	propagateUntilStop(JulianDate initialDate, Motion1<Cartesian> initialState, IntegrationSense direction, ITrackCalculationProgress progressTracker) Propagates a Point forward in time from the initial conditions.
SinglePointStoppablePropagatorResults	propagateUntilStop(JulianDate initialDate, Motion1<Cartesian> initialState, Iterable<? extends StoppingConditionEvaluator> conditions, IntegrationSense direction, int outputSparsity, ITrackCalculationProgress progressTracker) Propagates a Point forward in time from the initial conditions.
ITimeBasedState	takeStep(Duration step, boolean createNewState) Makes the propagator take a step.
void	updateEvaluatorReferences(CopyContext context) Updates the evaluator references held by this object using the reference-to-reference mapping in the specified CopyContext.

Methods inherited from class agi.foundation.propagators.StoppablePropagator

addEndOfAvailabilityStoppingConditions, addStepTaken, clone, dispose, getAdapters, getAvailabilityIntervals, getCachingWrapper, getCurrentDate, getCurrentState, getGroup, getInitialPropagationDirection, getIsThreadSafe, getPreviousDate, getStoppingConditionEvaluators, isAvailable, propagateUntilStop, propagateUntilStop, propagateUntilStop, propagateUntilStop, removeStepTaken, restep, setCurrentState, setPreviousDate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface agi.foundation.compatibility.IDisposable

close

Constructor Detail

SinglePointStoppablePropagator

protected SinglePointStoppablePropagator(@Nonnull
                                         EvaluatorGroup group,
                                         @Nonnull
                                         SinglePointStoppablePropagatorDefinition definition,
                                         @Nonnull
                                         List<StateElementAdapterDefinition> previousAdapters)

Initializes a new instance.

Parameters:

group - The EvaluatorGroup to use when creating any needed evaluators.

definition - The StoppablePropagatorDefinition creating this propagator.

previousAdapters - The adapters to use to configure this propagators Adapters (get).

SinglePointStoppablePropagator

protected SinglePointStoppablePropagator(@Nonnull
                                         SinglePointStoppablePropagator existingInstance,
                                         @Nonnull
                                         CopyContext context)

Initializes a new instance as a copy of an existing instance.

See ICloneWithContext.clone(CopyContext) for more information about how to implement this constructor in a derived class.

Parameters:

existingInstance - The existing instance to copy.

context - A CopyContext that controls the depth of the copy.

Throws:

ArgumentNullException - Thrown when existingInstance or context is null.

Method Detail

updateEvaluatorReferences

public void updateEvaluatorReferences(CopyContext context)

Updates the evaluator references held by this object using the reference-to-reference mapping in the specified CopyContext.

The following example shows how to implement this method for an evaluator that contains a nested evaluator:

@Override
public final void updateEvaluatorReferences(CopyContext context) {
    m_nestedEvaluator = context.updateReference(m_nestedEvaluator);
}

This method is called by EvaluatorGroup and usually does not need to be called directly by users. EvaluatorGroup uses this method to replace references to shared evaluators with references to caching versions of the evaluators.

To implement this method, call CopyContext.updateReference(T) on each evaluator reference held by your evaluator and assign the return value back to the field.

Specified by:

updateEvaluatorReferences in interface IEvaluator

Overrides:

updateEvaluatorReferences in class StoppablePropagator

Parameters:

context - The context that specifies the reference mapping.

dispose

protected void dispose(boolean disposing)

Releases any resources associated with this instance.

Overrides:

dispose in class StoppablePropagator

Parameters:

disposing - true to release both managed and unmanaged resources; false to release only unmanaged resources.

getInitialState

public ITimeBasedState getInitialState(@Nonnull
                                       IntegrationSense direction)

Creates the initial state from the wrapped propagator. Normal use cases will have the initial state passed into the StoppablePropagator.propagateUntilStop(ITimeBasedState,Iterable,IntegrationSense,boolean,int,ITrackCalculationProgress) method. However should the propagator be configured to have an initial state it should be returned here.

Overrides:

getInitialState in class StoppablePropagator

Parameters:

direction - Which direction the propagation is going.

Returns:

null, or the initial state of the wrapped propagator as initially configured.

propagateUntilStop

public final SinglePointStoppablePropagatorResults propagateUntilStop(@Nonnull
                                                                      JulianDate initialDate,
                                                                      @Nonnull
                                                                      Motion1<Cartesian> initialState,
                                                                      @Nonnull
                                                                      IntegrationSense direction,
                                                                      ITrackCalculationProgress progressTracker)

Propagates a Point forward in time from the initial conditions.

Parameters:

initialDate - The date to start propagating from.

initialState - The initial Motion1 to start propagating from.

direction - Should propagation go forward or backward.

progressTracker - An optional progress tracker.

Returns:

The ephemeris and found events for this propagation run.

propagateUntilStop

public final SinglePointStoppablePropagatorResults propagateUntilStop(@Nonnull
                                                                      JulianDate initialDate,
                                                                      @Nonnull
                                                                      Motion1<Cartesian> initialState,
                                                                      Iterable<? extends StoppingConditionEvaluator> conditions,
                                                                      @Nonnull
                                                                      IntegrationSense direction,
                                                                      int outputSparsity,
                                                                      ITrackCalculationProgress progressTracker)

Propagates a Point forward in time from the initial conditions.

Parameters:

initialDate - The date to start propagating from.

initialState - The initial Motion1 to start propagating from.

conditions - Additional stopping conditions to consider for just this propagation.

direction - Should propagation go forward or backward.

outputSparsity - The interval at which to produce output samples. By default this should be set to one, meaning that output will be saved in the saved states for every step. If a thinner (but less accurate) ephemeris is desired you can set this to a higher number. Two means that output is saved every other integration step, etc, etc.

progressTracker - An optional progress tracker.

Returns:

The ephemeris and found events for this propagation run.

getPropagatorsRecommendedStep

@Nonnull
protected Duration getPropagatorsRecommendedStep()

Gets the step size that the underlying propagator recommends to step. Note that StoppingConditions can know how to sample themselves and if their step size will be used if it is smaller than the propagators recommended value. Also when this StoppablePropagator is restepping to find the exact event, this value will be ignored.

Specified by:

getPropagatorsRecommendedStep in class StoppablePropagator

Returns:

The step size recommended by the wrapped propagator.

initializePropagationPoint

protected abstract PointEvaluator initializePropagationPoint(@Nonnull
                                                             JulianDate date,
                                                             @Nonnull
                                                             Motion1<Cartesian> motion)

Creates the PointEvaluator that will be sampled for propagation. Note that it is possible, and sometimes required, to make this PointEvaluator with a different EvaluatorGroup than the one that made this propagator. Do not cache the group that made this propagator, and design your derived propagator to have no undesired side effects or dependencies on the PointEvaluator returned from this method.

Parameters:

date - The initial date of the point.

motion - The initial Motion1 of the returned point.

Returns:

The PointEvaluator that will be sampled by this stoppable propagator.

initializePropagator

public void initializePropagator(ITimeBasedState initialState)

Initializes the wrapped propagator with the initial state. If the initialState is null, then it is the responsibility of the calling code for the initial state passed into the StoppablePropagator.propagateUntilStop(ITimeBasedState,Iterable,IntegrationSense,boolean,int,ITrackCalculationProgress) method to already be in the correct ReferenceFrame or Axes.

Specified by:

initializePropagator in class StoppablePropagator

Parameters:

initialState - The new initial state to propagate from. This state will be processed by the Adapters (get).

takeStep

public ITimeBasedState takeStep(@Nonnull
                                Duration step,
                                boolean createNewState)

Makes the propagator take a step. You do not need to update any other properties on the base type in the overridden method. Note that the sign of the step matters, if is it negative then the step should be taken backwards.

Specified by:

takeStep in class StoppablePropagator

Parameters:

step - The step to take from the CurrentDate (get). You do not need to update the CurrentDate (get) or any other properties on the base type in the overridden method.

createNewState - For performance reasons, it is not always desirable to create a new ITimeBasedState at every step. If this is true, you must create a new instance of a state. If this is false, then this method can return a mutable state that has just been updated with the current information.

Returns:

The state at the CurrentDate (get) plus the step.

createStoppedPropagatorResult

protected StoppablePropagatorResults createStoppedPropagatorResult(StoppingConditionEvent stoppingEvent,
                                                                   List<StoppingConditionEvent> detectedEvents,
                                                                   List<ITimeBasedState> savedStates,
                                                                   boolean aborted)

Creates the results of the overall propagation after the stopping event has been found. This should be overridden when your propagator stores additional data during propagation that should be returned. When overriding this method, do not call the base implementation.

Overrides:

createStoppedPropagatorResult in class StoppablePropagator

Parameters:

stoppingEvent - The event that actually stopped propagation.

detectedEvents - All of the events found during propagation.

savedStates - All the states saved during propagation.

aborted - If the run was aborted.

Returns:

The results for a propagation run.

getPropagationFrame

protected final ReferenceFrame getPropagationFrame()

Gets the ReferenceFrame to propagate the point in.