agi.foundation.propagators

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

Class StoppablePropagator

java.lang.Object

agi.foundation.propagators.StoppablePropagator

All Implemented Interfaces:

IDisposable, IEvaluator, ICloneWithContext, IThreadAware, IAvailability, AutoCloseable

Direct Known Subclasses:

SinglePointStoppablePropagator

public abstract class StoppablePropagator
extends Object
implements IEvaluator

A propagator that wraps some type that generates states and will sample some derived value from those states searching for events and eventually an event that will stop propagation with StoppingConditionEvaluators.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
protected void	addEndOfAvailabilityStoppingConditions(EvaluatorGroup group) Gets a pair of StoppingConditions based on the availability of this propagator.
void	addStepTaken(EventHandler<StoppablePropagatorStepTakenArgs> value) Gets the instance of the event handler which will be triggered after every time this StoppablePropagator takes an integration step.
abstract Object	clone(CopyContext context) Clones this object using the specified context.
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.
void	dispose() Releases any resources associated with this instance.
protected void	dispose(boolean disposing) Releases any resources associated with this instance.
List<StateElementAdapter>	getAdapters() Gets the list of StateElementAdapters that must be applied to the passed in initial state.
abstract TimeIntervalCollection	getAvailabilityIntervals(TimeIntervalCollection consideredIntervals) Gets the intervals over which data is available.
IEvaluator	getCachingWrapper() Gets a version of this evaluator that caches the previously computed value so that if it is evaluated twice at the same date the computation is done only once.
JulianDate	getCurrentDate() Gets the date of the current state.
ITimeBasedState	getCurrentState() Gets the most recently computed state from the propagator.
EvaluatorGroup	getGroup() Gets the group that contains this evaluator.
protected IntegrationSense	getInitialPropagationDirection() Gets the direction of propagation once StoppablePropagator.propagateUntilStop(ITimeBasedState,Iterable,IntegrationSense,boolean,int,ITrackCalculationProgress) has been called.
ITimeBasedState	getInitialState(IntegrationSense direction) Creates the initial state from the wrapped propagator.
boolean	getIsThreadSafe() Gets a value indicating whether the methods on this instance are safe to call from multiple threads simultaneously.
JulianDate	getPreviousDate() Gets the date of the previously propagated state.
protected abstract Duration	getPropagatorsRecommendedStep() Gets the step size that the underlying propagator recommends to step.
List<StoppingConditionEvaluator>	getStoppingConditionEvaluators() Gets a read only collection of the stopping conditions that will be used by this propagator.
abstract void	initializePropagator(ITimeBasedState initialState) Initializes the wrapped propagator with the initial state.
abstract boolean	isAvailable(JulianDate date) Determines if valid data is available for the given JulianDate.
StoppablePropagatorResults	propagateUntilStop(ITimeBasedState initialState, IntegrationSense direction, ITrackCalculationProgress progressTracker) Propagates until one of the saved StoppingConditionEvaluators are tripped.
StoppablePropagatorResults	propagateUntilStop(ITimeBasedState initialState, Iterable<? extends StoppingConditionEvaluator> conditions, IntegrationSense direction, boolean initializeStoppingCondition, int outputSparsity, ITrackCalculationProgress progressTracker) Propagates until one of the conditions are tripped.
StoppablePropagatorResults	propagateUntilStop(ITimeBasedState initialState, Iterable<? extends StoppingConditionEvaluator> conditions, IntegrationSense direction, int outputSparsity, ITrackCalculationProgress progressTracker) Propagates until one of the conditions are tripped.
StoppablePropagatorResults	propagateUntilStop(ITimeBasedState initialState, ITrackCalculationProgress progressTracker) Propagates forward until one of the saved StoppingConditionEvaluators are tripped.
void	removeStepTaken(EventHandler<StoppablePropagatorStepTakenArgs> value) Gets the instance of the event handler which will be triggered after every time this StoppablePropagator takes an integration step.
protected ITimeBasedState	restep(Duration step) Resteps the underlying propagator from the PreviousDate (get / set).
protected void	setCurrentState(ITimeBasedState value) Sets the most recently computed state from the propagator.
void	setPreviousDate(JulianDate value) Sets the date of the previously propagated state.
abstract 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 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

StoppablePropagator

protected StoppablePropagator(@Nonnull
                              EvaluatorGroup group,
                              @Nonnull
                              StoppablePropagatorDefinition 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).

StoppablePropagator

protected StoppablePropagator(@Nonnull
                              StoppablePropagator 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

Parameters:

context - The context that specifies the reference mapping.

clone

public abstract Object clone(CopyContext context)

Clones this object using the specified context.

This method should be implemented to call a copy constructor on the class of the object being cloned. The copy constructor should take the CopyContext as a parameter in addition to the existing instance to copy. The copy constructor should first call CopyContext.addObjectMapping(T, T) to identify the newly constructed instance as a copy of the existing instance. It should then copy all fields, using CopyContext.updateReference(T) to copy any reference fields.

A typical implementation of ICloneWithContext:

public static class MyClass implements ICloneWithContext {
    public MyClass(MyClass existingInstance, CopyContext context) {
        context.addObjectMapping(existingInstance, this);
        someReference = context.updateReference(existingInstance.someReference);
    }

    @Override
    public final Object clone(CopyContext context) {
        return new MyClass(this, context);
    }

    private Object someReference;
}

In general, all fields that are reference types should be copied with a call to CopyContext.updateReference(T). There are a couple of exceptions:

1. Fields that are aggregate parts of the object should always be copied. A referenced object is an aggregate if properties or methods on the object being copied can modify the externally-visible value of the referenced object.
2. If the semantics of the referenced object require that it have a single parent, owner, context, etc., and the object being copied is that parent, owner, or context, then the referenced object should always be copied.

If one of these exceptions applies, the CopyContext should be given an opportunity to update the reference before the reference is copied explicitly. Use CopyContext.updateReference(T) to update the reference. If CopyContext.updateReference(T) returns the original object, indicating that the context does not have a replacement registered, then copy the object manually by invoking a Clone method, a copy constructor, or by manually constructing a new instance and copying the values.

alwaysCopy = context.updateReference(existingInstance.alwaysCopy);
if (existingInstance.alwaysCopy != null && alwaysCopy == existingInstance.alwaysCopy) {
    alwaysCopy = (AlwaysCopy) existingInstance.alwaysCopy.clone(context);
}

If you are implementing an evaluator (a class that implements IEvaluator), the IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) method shares some responsibilities with the copy context constructor. Code duplication can be avoided by doing the following:

1. For references to other evaluators ONLY, simply assign the reference in the constructor instead of calling CopyContext.updateReference(T). You should still call CopyContext.updateReference(T) on any references to non-evaluators.
2. Call IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as the last line in the constructor and pass it the same CopyContext passed to the constructor.
3. Implement IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as normal. See the reference documentation for IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) for more information on implementing that method.

public MyClass(MyClass existingInstance, CopyContext context) {
    super(existingInstance, context);
    someReference = context.updateReference(existingInstance.someReference);
    evaluatorReference = existingInstance.evaluatorReference;
    updateEvaluatorReferences(context);
}

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

@Override
public Object clone(CopyContext context) {
    return new MyClass(this, context);
}

private Object someReference;
private IEvaluator evaluatorReference;

Specified by:

clone in interface ICloneWithContext

Parameters:

context - The context to use to perform the copy.

Returns:

A new instance which is a copy of this object.

dispose

public final void dispose()

Releases any resources associated with this instance.

Specified by:

dispose in interface IDisposable

dispose

protected void dispose(boolean disposing)

Releases any resources associated with this instance.

Parameters:

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

getAvailabilityIntervals

public abstract TimeIntervalCollection getAvailabilityIntervals(TimeIntervalCollection consideredIntervals)

Gets the intervals over which data is available.

Specified by:

getAvailabilityIntervals in interface IAvailability

Parameters:

consideredIntervals - The intervals over which availability information is needed. Note that the returned availability intervals may indicate availability outside of these intervals of consideration.

Returns:

The collection of availability intervals.

isAvailable

public abstract boolean isAvailable(@Nonnull
                                    JulianDate date)

Determines if valid data is available for the given JulianDate.

Specified by:

isAvailable in interface IAvailability

Parameters:

date - The date for which to check availability.

Returns:

true if valid data is available for this date; otherwise false.

getIsThreadSafe

public final boolean getIsThreadSafe()

Gets a value indicating whether the methods on this instance are safe to call from multiple threads simultaneously.

If this property is true, all methods and properties are guaranteed to be thread safe. Conceptually, an object that returns true for this method acts as if there is a lock protecting each method and property such that only one thread at a time can be inside any method or property in the class. In reality, such locks are generally not used and are in fact discouraged. However, the user must not experience any exceptions or inconsistent behavior that would not be experienced if such locks were used.

If this property is false, the behavior when using this class from multiple threads simultaneously is undefined and may include inconsistent results and exceptions. Clients wishing to use multiple threads should call CopyForAnotherThread.copy(T) to get a separate instance of the object for each thread.

Specified by:

getIsThreadSafe in interface IThreadAware

getGroup

public final EvaluatorGroup getGroup()

Gets the group that contains this evaluator.

Specified by:

getGroup in interface IEvaluator

getCachingWrapper

public final IEvaluator getCachingWrapper()

Gets a version of this evaluator that caches the previously computed value so that if it is evaluated twice at the same date the computation is done only once.

This method is called by EvaluatorGroup to create a caching version of an evaluator that is shared between multiple computations.

To implement this method in your own evaluator, construct and return a caching version of the evaluator's base class. For example, if your evaluator implements IEvaluator1 directly, return an instance of CachingEvaluator. In many cases, such as when implementing a PointEvaluator this method does not need to be overridden because the default implementation returns an appropriate caching wrapper already. If you do not want the last value computed by your evaluator to ever be cached, or if your evaluator does its own caching internally, this method can return this.

Shows an example implementation in an evaluator that implements IEvaluator1 directly, where T is double.

@Override
public IEvaluator getCachingWrapper() {
    return new CachingEvaluator<Double>(this);
}

Specified by:

getCachingWrapper in interface IEvaluator

Returns:

A caching version of this evaluator. If a caching version is not available, or if this object does its own caching, this should be returned by this method.

getAdapters

public final List<StateElementAdapter> getAdapters()

Gets the list of StateElementAdapters that must be applied to the passed in initial state. Note these should not be applied to the stored initial state if no initial state was passed in.

getInitialState

@Nullable
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.

Parameters:

direction - Which direction the propagation is going.

Returns:

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

propagateUntilStop

public final StoppablePropagatorResults propagateUntilStop(ITimeBasedState initialState,
                                                           ITrackCalculationProgress progressTracker)

Propagates forward until one of the saved StoppingConditionEvaluators are tripped. This will propagate forward in time.

Parameters:

initialState - The initial state to begin propagating from.

progressTracker - An optional progress tracker. How long the segment will take to propagate generally is not known ahead of time, so the reported progress completed is set to -1. But you can cancel propagation with the tracker.

Returns:

The ephemeris and information about the stopping event.

propagateUntilStop

public final StoppablePropagatorResults propagateUntilStop(ITimeBasedState initialState,
                                                           @Nonnull
                                                           IntegrationSense direction,
                                                           ITrackCalculationProgress progressTracker)

Propagates until one of the saved StoppingConditionEvaluators are tripped.

Parameters:

initialState - The initial state to begin propagating from.

direction - The direction to search for an event.

progressTracker - An optional progress tracker. How long the segment will take to propagate generally is not known ahead of time, so the reported progress completed is set to -1. But you can cancel propagation with the tracker.

Returns:

The ephemeris and information about the stopping event.

propagateUntilStop

public final StoppablePropagatorResults propagateUntilStop(ITimeBasedState initialState,
                                                           Iterable<? extends StoppingConditionEvaluator> conditions,
                                                           @Nonnull
                                                           IntegrationSense direction,
                                                           int outputSparsity,
                                                           ITrackCalculationProgress progressTracker)

Propagates until one of the conditions are tripped.

Parameters:

initialState - The initial state to start propagating from.

conditions - The conditions to stop on.

direction - The direction to search for an event.

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. How long the segment will take to propagate generally is not known ahead of time, so the reported progress completed is set to -1. But you can cancel propagation with the tracker.

Returns:

The ephemeris and information about the stopping event.

propagateUntilStop

public final StoppablePropagatorResults propagateUntilStop(ITimeBasedState initialState,
                                                           Iterable<? extends StoppingConditionEvaluator> conditions,
                                                           @Nonnull
                                                           IntegrationSense direction,
                                                           boolean initializeStoppingCondition,
                                                           int outputSparsity,
                                                           ITrackCalculationProgress progressTracker)

Propagates until one of the conditions are tripped.

Parameters:

initialState - The initial state to start propagating from.

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.

conditions - The conditions to stop on.

direction - The direction to search for an event.

progressTracker - An optional progress tracker. How long the segment will take to propagate generally is not known ahead of time, so the reported progress completed is set to -1. But you can cancel propagation with the tracker.

initializeStoppingCondition - Indicates if the conditions should be initialized. Set this to false if the conditions have been initialized prior to this method being called.

Returns:

The ephemeris and information about the stopping event.

initializePropagator

public abstract 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.

Parameters:

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

takeStep

public abstract 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.

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.

restep

protected ITimeBasedState restep(@Nonnull
                                 Duration step)

Resteps the underlying propagator from the PreviousDate (get / set). This only needs to be overridden if the wrapped propagator keeps state and cares about taking a step vs. restepping. Do not call the base method if you override this method. A new instance of a state should always be returned by this method. Like the StoppablePropagator.takeStep(agi.foundation.time.Duration, boolean) method, no properties on this base type needs to be updated in this method. Note that the sign of the step matters, if is it negative then the step should be taken backwards.

Parameters:

step - The step to take from the PreviousDate (get / set).

Returns:

The state at the PreviousDate (get / set) plus the step.

getPropagatorsRecommendedStep

@Nonnull
protected abstract 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.

Returns:

The step size recommended by the wrapped propagator.

createStoppedPropagatorResult

@Nonnull
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.

Parameters:

stoppingEvent - The event that actually stopped propagation.

detectedEvents - All of the events found during propagation.

savedStates - All of the states saved during propagation.

aborted - If the run was aborted.

Returns:

The results for a propagation run.

getCurrentState

public final ITimeBasedState getCurrentState()

Gets the most recently computed state from the propagator. Assume that this state is mutable and that the instance will be updated at every step and restep. For performance considerations, make the derived state type mutable and update a single instance if possible.

setCurrentState

protected final void setCurrentState(ITimeBasedState value)

Sets the most recently computed state from the propagator. Assume that this state is mutable and that the instance will be updated at every step and restep. For performance considerations, make the derived state type mutable and update a single instance if possible.

addStepTaken

public final void addStepTaken(EventHandler<StoppablePropagatorStepTakenArgs> value)

Gets the instance of the event handler which will be triggered after every time this StoppablePropagator takes an integration step.

removeStepTaken

public final void removeStepTaken(EventHandler<StoppablePropagatorStepTakenArgs> value)

Gets the instance of the event handler which will be triggered after every time this StoppablePropagator takes an integration step.

getCurrentDate

@Nonnull
public final JulianDate getCurrentDate()

Gets the date of the current state. This will get updated automatically after StoppablePropagator.takeStep(agi.foundation.time.Duration, boolean) and StoppablePropagator.restep(agi.foundation.time.Duration) is called.

getPreviousDate

@Nonnull
public final JulianDate getPreviousDate()

Gets the date of the previously propagated state. This will get updated automatically right after StoppablePropagator.takeStep(agi.foundation.time.Duration, boolean) is called.

setPreviousDate

public final void setPreviousDate(@Nonnull
                                  JulianDate value)

Sets the date of the previously propagated state. This will get updated automatically right after StoppablePropagator.takeStep(agi.foundation.time.Duration, boolean) is called.

getStoppingConditionEvaluators

@Nonnull
public final List<StoppingConditionEvaluator> getStoppingConditionEvaluators()

Gets a read only collection of the stopping conditions that will be used by this propagator.

getInitialPropagationDirection

@Nonnull
protected final IntegrationSense getInitialPropagationDirection()

Gets the direction of propagation once StoppablePropagator.propagateUntilStop(ITimeBasedState,Iterable,IntegrationSense,boolean,int,ITrackCalculationProgress) has been called.

addEndOfAvailabilityStoppingConditions

protected final void addEndOfAvailabilityStoppingConditions(EvaluatorGroup group)

Gets a pair of StoppingConditions based on the availability of this propagator. If the availability of this propagator is Infinite (get) then no conditions will be returned. It is intended that this will be called when the concrete propagator is constructed if needed these conditions will be added to the propagator at that time. It is up types to decide if this needs to be called or not.

Parameters:

group - The EvaluatorGroup to use when creating the StoppingConditions