agi.foundation.propagators

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

Class NumericalPropagator

java.lang.Object

agi.foundation.propagators.NumericalPropagator

All Implemented Interfaces:

IDisposable, ICloneWithContext, IThreadAware, AutoCloseable

public final class NumericalPropagator
extends Object
implements IThreadAware, IDisposable

A propagator which can advance the state from initial conditions by either taking individual integration steps or by propagating over a given time span. Note that a given instance of a propagator is NOT thread safe. So if there is a need to propagate a given state in different threads, make sure to clone the propagator for another thread using CopyForAnotherThread.copy(T).

A NumericalPropagator is created by configuring a NumericalPropagatorDefinition and then calling NumericalPropagatorDefinition.createPropagator().

Method Summary

Modifier and Type	Method and Description
void	addExceptionDuringPropagation(EventHandler<ExceptionDuringPropagationEventArgs> value) Gets the instance of the event handler which will be triggered after the propagator throws an exception.
void	addStepTaken(EventHandler<PropagationEventArgs> value) Gets the instance of the event handler which will be triggered after every time the propagator takes an integration step.
Object	clone(CopyContext context) Clones this object using the specified context.
void	dispose() Releases any resources associated with this instance.
PropagationStateConverter	getConverter() Gets an instance of a converter which can convert the overall raw output into the output corresponding to a particular PropagationStateElement or AuxiliaryStateElement based on a string identifier and output type.
double[]	getCurrentState() Gets a copy of the raw state at the end of the last step taken.
double	getCurrentStepSize() Gets the current step size in seconds that the integrator will take when advancing to the next time.
JulianDate	getCurrentTime() Gets the time at the end of the last step taken.
boolean	getIncludeIntegratorInformationInOutput() Gets a value indicating whether the NumericalIntegrationInformation produced by the integrator will be stored in the output produced by this propagator when it creates a NumericalPropagationStateHistory.
JulianDate	getInitialEpoch() Gets the time at which the InitialState (get) is defined.
double[]	getInitialState() Gets a copy of the raw initial state used to start propagation.
boolean	getIsThreadSafe() Gets a value indicating whether the methods on this instance are safe to call from multiple threads simultaneously.
double	getPreviousStepSize() Gets the last step size in seconds that was taken by the integrator to produce the CurrentTime (get) and CurrentState (get).
IntegrationSense	getPropagationDirection() Gets the direction of propagation with regard to time, either increasing or decreasing.
StepSizeInformation	getStepSizeInformation() Gets information about the last step that was taken by the integrator.
double[]	propagate(Duration propagationTime) Propagates the state from the CurrentTime (get) and CurrentState (get).
NumericalPropagationStateHistory	propagate(Duration propagationTime, int outputSparsity) Propagates the state from the CurrentTime (get) and CurrentState (get).
NumericalPropagationStateHistory	propagate(Duration propagationTime, int outputSparsity, ITrackCalculationProgress tracker) Propagates the state from the CurrentTime (get) and CurrentState (get).
double[]	propagate(Duration propagationTime, ITrackCalculationProgress tracker) Propagates the state from the CurrentTime (get) and CurrentState (get).
StoppableNumericalPropagatorResults	propagateUntilStop(Iterable<? extends StoppingConditionEvaluator> conditions, IntegrationSense direction, boolean initializeStoppingCondition, int outputSparsity, ITrackCalculationProgress progressTracker) Propagates until one of the conditions are tripped.
StoppableNumericalPropagatorResults	propagateUntilStop(Iterable<? extends StoppingConditionEvaluator> conditions, IntegrationSense direction, boolean initializeStoppingCondition, ITrackCalculationProgress progressTracker) Propagates until one of the conditions are tripped.
StoppableNumericalPropagatorResults	propagateUntilStop(Iterable<? extends StoppingConditionEvaluator> conditions, IntegrationSense direction, ITrackCalculationProgress progressTracker) Propagates until one of the conditions are tripped.
StoppableNumericalPropagatorResults	propagateUntilStop(Iterable<? extends StoppingConditionEvaluator> conditions, ITrackCalculationProgress progressTracker) Propagates forward until one of the conditions are tripped.
void	removeExceptionDuringPropagation(EventHandler<ExceptionDuringPropagationEventArgs> value) Gets the instance of the event handler which will be triggered after the propagator throws an exception.
void	removeStepTaken(EventHandler<PropagationEventArgs> value) Gets the instance of the event handler which will be triggered after every time the propagator takes an integration step.
void	reset() Resets the propagation back to the initial conditions.
void	reset(JulianDate newEpoch, double[] newInitialState) Resets the propagation to a new set of initial conditions at the epoch time.
PropagationEventIndication	restep(double stepSize) Instead of advancing from the CurrentState (get), reintegrate the last step that was taken by the integrator by the given step size to produce a new CurrentState (get) and CurrentTime (get).
PropagationEventIndication	takeStep() Advance the state from the CurrentState (get) by taking a single integration step.
PropagationEventIndication	takeStep(double maxStepSize) Advance the state from the CurrentState (get) by taking a single integration step bounded by a maximum.

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

Method Detail

clone

public final 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

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

getCurrentTime

@Nonnull
public final JulianDate getCurrentTime()

Gets the time at the end of the last step taken.

getCurrentState

@Nonnull
public final double[] getCurrentState()

Gets a copy of the raw state at the end of the last step taken. For processed state data use the PropagationStateConverter.convertState(java.lang.String, double[]) method on the Converter (get) property.

getInitialEpoch

@Nonnull
public final JulianDate getInitialEpoch()

Gets the time at which the InitialState (get) is defined.

getInitialState

public final double[] getInitialState()

Gets a copy of the raw initial state used to start propagation. For processed state data use the PropagationStateConverter.convertState(java.lang.String, double[]) method on the Converter (get) property.

getStepSizeInformation

@Nonnull
public final StepSizeInformation getStepSizeInformation()

Gets information about the last step that was taken by the integrator.

getCurrentStepSize

public final double getCurrentStepSize()

Gets the current step size in seconds that the integrator will take when advancing to the next time.

getPreviousStepSize

public final double getPreviousStepSize()

Gets the last step size in seconds that was taken by the integrator to produce the CurrentTime (get) and CurrentState (get).

getIncludeIntegratorInformationInOutput

public final boolean getIncludeIntegratorInformationInOutput()

Gets a value indicating whether the NumericalIntegrationInformation produced by the integrator will be stored in the output produced by this propagator when it creates a NumericalPropagationStateHistory.

getPropagationDirection

@Nonnull
public final IntegrationSense getPropagationDirection()

Gets the direction of propagation with regard to time, either increasing or decreasing. To reverse the direction of propagation, call either 'Propagate' or 'TakeStep' with a duration which has the opposite sign.

getConverter

@Nonnull
public final PropagationStateConverter getConverter()

Gets an instance of a converter which can convert the overall raw output into the output corresponding to a particular PropagationStateElement or AuxiliaryStateElement based on a string identifier and output type. This is also the object to use when producing ephemeris data to create interpolated Point or Vector objects.

addStepTaken

public final void addStepTaken(EventHandler<PropagationEventArgs> value)

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

removeStepTaken

public final void removeStepTaken(EventHandler<PropagationEventArgs> value)

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

addExceptionDuringPropagation

public final void addExceptionDuringPropagation(EventHandler<ExceptionDuringPropagationEventArgs> value)

Gets the instance of the event handler which will be triggered after the propagator throws an exception. If no event handler is specified then the propagator will throw a NumericalPropagationException that wraps the underlying exception.

removeExceptionDuringPropagation

public final void removeExceptionDuringPropagation(EventHandler<ExceptionDuringPropagationEventArgs> value)

Gets the instance of the event handler which will be triggered after the propagator throws an exception. If no event handler is specified then the propagator will throw a NumericalPropagationException that wraps the underlying exception.

reset

public final void reset()

Resets the propagation back to the initial conditions.

reset

public final void reset(@Nonnull
                        JulianDate newEpoch,
                        double[] newInitialState)

Resets the propagation to a new set of initial conditions at the epoch time.

Parameters:

newEpoch - The new epoch corresponding to the initial state.

newInitialState - The new initial state corresponding to the propagation epoch. Use the PropagationStateConverter.adjustState(java.lang.String, double[], agi.foundation.Motion1<T>) method on the Converter (get) property to easily create a new initial state vector.

propagate

public final double[] propagate(@Nonnull
                                Duration propagationTime)

Propagates the state from the CurrentTime (get) and CurrentState (get). The direction of propagation is determined by the sign of the Duration specified.

Parameters:

propagationTime - The (positive or negative) total time, measured from the CurrentTime (get), over which to propagate. A negative duration will indicate that the propagator should propagate backwards in time.

Returns:

The raw state vector at the given propagationTime away from the Epoch (get / set) on the state, and if IncludeIntegratorInformationInOutput (get) is true it also contains the combined integration information over the propagation and the average step size. Use PropagationStateConverter.convertState(java.lang.String, double[]) to process this raw state into a useful form.

propagate

public final double[] propagate(@Nonnull
                                Duration propagationTime,
                                ITrackCalculationProgress tracker)

Propagates the state from the CurrentTime (get) and CurrentState (get). The direction of propagation is determined by the sign of the Duration specified.

Parameters:

propagationTime - The (positive or negative) total time, measured from the CurrentTime (get), over which to propagate. A negative duration will indicate that the propagator should propagate backwards in time.

tracker - A progress tracker which will report the progress of the propagation from 0 percent to 100 percent.

Returns:

The raw state vector at the given propagationTime away from the Epoch (get / set) on the state, and if IncludeIntegratorInformationInOutput (get) is true it also contains the combined integration information over the propagation and the average step size. Use PropagationStateConverter.convertState(java.lang.String, double[]) to process this raw state into a useful form.

propagate

public final NumericalPropagationStateHistory propagate(@Nonnull
                                                        Duration propagationTime,
                                                        int outputSparsity)

Propagates the state from the CurrentTime (get) and CurrentState (get). The direction of propagation is determined by the sign of the Duration specified.

Parameters:

propagationTime - The (positive or negative) total time, measured from the CurrentTime (get), over which to propagate. A negative duration will indicate that the propagator should propagate backwards in time.

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 state history for every integration 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.

Returns:

A collection of arrays containing the raw state information, and if IncludeIntegratorInformationInOutput (get) is true it also contains the combined integration information over the propagation and the average step size.

propagate

public final NumericalPropagationStateHistory propagate(@Nonnull
                                                        Duration propagationTime,
                                                        int outputSparsity,
                                                        ITrackCalculationProgress tracker)

Propagates the state from the CurrentTime (get) and CurrentState (get). The direction of propagation is determined by the sign of the Duration specified.

Parameters:

propagationTime - The (positive or negative) total time, measured from the CurrentTime (get), over which to propagate. A negative duration will indicate that the propagator should propagate backwards in time.

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 state history for every integration 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.

tracker - A progress tracker which will report the progress of the propagation from 0 percent to 100 percent.

Returns:

A collection of arrays containing the raw state information, and if IncludeIntegratorInformationInOutput (get) is true it also contains the combined integration information over the propagation and the average step size.

takeStep

@Nonnull
public final PropagationEventIndication takeStep()

Advance the state from the CurrentState (get) by taking a single integration step. CurrentState (get) and CurrentTime (get) will be updated to reflect the new values.

This step will be in the current PropagationDirection (get).

Returns:

The indication of how propagation should proceed after this step, as produced by the StepTaken (add / remove) event handler.

takeStep

@Nonnull
public final PropagationEventIndication takeStep(double maxStepSize)

Advance the state from the CurrentState (get) by taking a single integration step bounded by a maximum. CurrentState (get) and CurrentTime (get) will be updated to reflect the new values.

Parameters:

maxStepSize - The maximum step size the integrator can take while advancing the state. The sign of this maximum step size will determine (set) the PropagationDirection (get). If positive, it will be IntegrationSense.INCREASING and if negative it will be IntegrationSense.DECREASING from the CurrentTime (get).

Returns:

The indication of how propagation should proceed after this step, as produced by the StepTaken (add / remove) event handler.

restep

@Nonnull
public final PropagationEventIndication restep(double stepSize)

Instead of advancing from the CurrentState (get), reintegrate the last step that was taken by the integrator by the given step size to produce a new CurrentState (get) and CurrentTime (get).

Parameters:

stepSize - The exact size of the step to take since the last time, which will replace PreviousStepSize (get). The sign of the step will determine (set) the PropagationDirection (get). If the sign is positive, time will be IntegrationSense.INCREASING and if negative it will be IntegrationSense.DECREASING from the CurrentTime (get).

Returns:

The indication of how propagation should proceed after this step, as produced by the StepTaken (add / remove) event handler.

propagateUntilStop

public final StoppableNumericalPropagatorResults propagateUntilStop(Iterable<? extends StoppingConditionEvaluator> conditions,
                                                                    ITrackCalculationProgress progressTracker)

Propagates forward until one of the conditions are tripped. This will propagate IntegrationSense.INCREASING by default.

Parameters:

conditions - The conditions to stop on.

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 StoppableNumericalPropagatorResults propagateUntilStop(Iterable<? extends StoppingConditionEvaluator> conditions,
                                                                    @Nonnull
                                                                    IntegrationSense direction,
                                                                    ITrackCalculationProgress progressTracker)

Propagates until one of the conditions are tripped.

Parameters:

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.

Returns:

The ephemeris and information about the stopping event.

propagateUntilStop

public final StoppableNumericalPropagatorResults propagateUntilStop(Iterable<? extends StoppingConditionEvaluator> conditions,
                                                                    @Nonnull
                                                                    IntegrationSense direction,
                                                                    boolean initializeStoppingCondition,
                                                                    ITrackCalculationProgress progressTracker)

Propagates until one of the conditions are tripped.

Parameters:

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.

propagateUntilStop

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

Propagates until one of the conditions are tripped.

Parameters:

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.

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 state history for every integration step. If a coarser (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.

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.