agi.foundation.stoppingconditions

(agi.foundation.models-2024r3.jar)

Class StoppingConditionEvaluator

java.lang.Object

agi.foundation.stoppingconditions.StoppingConditionEvaluator

All Implemented Interfaces:

IDisposable, IEvaluator, ICloneWithContext, IThreadAware, IAvailability, AutoCloseable

public abstract class StoppingConditionEvaluator
extends Object
implements IEvaluator

The type that actually evaluates a value from the state of propagation that can be used to stop the propagation.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	StoppingConditionEvaluator(EvaluatorGroup group, StoppingCondition definition) Initializes a new instance.
protected	StoppingConditionEvaluator(StoppingConditionEvaluator existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.

Method Summary

Modifier and Type	Method and Description
boolean	checkForExactCrossing(double rawValue, double threshold) Checks to see if the state is at the exact threshold to within machine tolerance.
abstract Object	clone(CopyContext context) Clones this object using the specified context.
double	computeThreshold() Computes the threshold for this StoppingConditionEvaluator, or throws an RuntimeException if this evaluator is searching for an extrema.
void	dispose() Releases any resources associated with this instance.
protected void	dispose(boolean disposing) Releases any resources associated with this instance.
abstract double	evaluateRawValue(ITimeBasedState state) Returns the raw value before it is bound by circular constraints.
CircularRange	getAngularSetting() Gets the indication that the value being computed is an angle and, if so, should that angle be between negative PI and PI, or if it should be between 0 and 2*PI.
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.
List<StoppingConditionConstraintEvaluator>	getConstraints() Gets the constraints that must also be satisfied for this stopping condition to stop propagation.
double	getDiscontinuityTolerance() Gets the tolerance to use to detect discontinuities in the value computed by the stopping condition.
StoppingConditionEnabled	getEnabled() Gets if this evaluator should be used during propagation.
double	getFunctionTolerance() Gets how close the function value must get to the Threshold (get) to be considered equal to.
EvaluatorGroup	getGroup() Gets the group that contains this evaluator.
StoppingCondition	getIdentifier() Gets the definition that created this StoppingConditionEvaluator.
boolean	getIsThreadSafe() Gets a value indicating whether the methods on this instance are safe to call from multiple threads simultaneously.
String	getName() Gets an optional name for this StoppingConditionEvaluator.
Duration	getNextSampleSuggestion(JulianDate lastNominalDateSampled, Duration otherSuggestedStep, ITimeBasedState state, IntegrationSense direction) Gets the next step that the thing that is sampling this StoppingConditionEvaluator should take.
boolean	getRequireFunctionTolerance() Gets a value indicating whether the FunctionTolerance (get) does not need to be satisfied.
StoppingTriggeredCallback	getSatisfiedCallback() Gets a delegate that is executed when this condition is satisfied.
int	getStopOnEventNumber() Gets how many times an event should be found before stopping.
protected ValueEvaluator<Double>	getThreshold() Gets the threshold to stop at.
StopType	getTypeOfStoppingCondition() Gets the type of the stop (local extrema, any threshold, ...)
double	getValue(ITimeBasedState state) Compute the value of the stopping condition from the state.
StoppingConditionValueStatus	getValueStatus() Gets which side the currently accepted value of the StoppingCondition is relative to the computed threshold.
void	initialize(ITimeBasedState initialState) Initialize the StoppingConditionEvaluator with the initial state of propagation.
boolean	isAvailable(JulianDate date) Determines if valid data is available for the given JulianDate.
void	setEnabled(StoppingConditionEnabled value) Sets if this evaluator should be used during propagation.
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

StoppingConditionEvaluator

protected StoppingConditionEvaluator(@Nonnull
                                     EvaluatorGroup group,
                                     @Nonnull
                                     StoppingCondition definition)

Initializes a new instance.

Parameters:

group - The EvaluatorGroup used to create this.

definition - The StoppingCondition that defines this.

StoppingConditionEvaluator

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

getSatisfiedCallback

public final StoppingTriggeredCallback getSatisfiedCallback()

Gets a delegate that is executed when this condition is satisfied. Edits to the state that gets sent in this delegate will be ignored unless the returned enumeration is that propagation should stop.

getTypeOfStoppingCondition

@Nonnull
public final StopType getTypeOfStoppingCondition()

Gets the type of the stop (local extrema, any threshold, ...)

getThreshold

protected final ValueEvaluator<Double> getThreshold()

Gets the threshold to stop at. This value is ignored if the TypeOfStoppingCondition (get) is not one of the threshold types. When the StoppablePropagator that contains this condition is propagated, this ScalarEvaluator will be evaluated at that time and that value will be used as the threshold for the extent of the propagation.

getFunctionTolerance

public final double getFunctionTolerance()

Gets how close the function value must get to the Threshold (get) to be considered equal to.

getStopOnEventNumber

public final int getStopOnEventNumber()

Gets how many times an event should be found before stopping.

getConstraints

@Nonnull
public final List<StoppingConditionConstraintEvaluator> getConstraints()

Gets the constraints that must also be satisfied for this stopping condition to stop propagation. If a constraint prevents an event from stopping propagation, it will not increment the count that gets compared to the StopOnEventNumber (get).

getDiscontinuityTolerance

public final double getDiscontinuityTolerance()

Gets the tolerance to use to detect discontinuities in the value computed by the stopping condition. If the difference between two function values is greater than this value, then it should be considered a discontinuity and not counted as an event. It is up to the function sampling the stopping condition value to use this to detect discontinuities. This is Double.POSITIVE_INFINITY if the AngularSetting (get) is CircularRange.NOT_CIRCULAR, or Math.PI for the other CircularRange values.

getAngularSetting

@Nonnull
public final CircularRange getAngularSetting()

Gets the indication that the value being computed is an angle and, if so, should that angle be between negative PI and PI, or if it should be between 0 and 2*PI.

getIdentifier

public final StoppingCondition getIdentifier()

Gets the definition that created this StoppingConditionEvaluator. This is to be used only for identification of this StoppingConditionEvaluator and related items.

getName

public final String getName()

Gets an optional name for this StoppingConditionEvaluator.

getEnabled

@Nonnull
public final StoppingConditionEnabled getEnabled()

Gets if this evaluator should be used during propagation.

setEnabled

public final void setEnabled(@Nonnull
                             StoppingConditionEnabled value)

Sets if this evaluator should be used during propagation.

getValueStatus

@Nonnull
public final StoppingConditionValueStatus getValueStatus()

Gets which side the currently accepted value of the StoppingCondition is relative to the computed threshold. Note that this will not be updated during root finding. Other code can sample this value and make decisions based on if the threshold has been crossed or not without interfering with the root finding.

getRequireFunctionTolerance

public final boolean getRequireFunctionTolerance()

Gets a value indicating whether the FunctionTolerance (get) does not need to be satisfied. The search for an event will still attempt to converge to within the FunctionTolerance (get), but if it is known that an event is there (such as a threshold crossing), the event will be reported and this condition considered satisfied even if the search did not converge within the FunctionTolerance (get). This is true by default.

initialize

public void initialize(ITimeBasedState initialState)

Initialize the StoppingConditionEvaluator with the initial state of propagation. This method is useful if the value that the StoppingConditionEvaluator evaluates is related to the initial state (for example, if this StoppingConditionEvaluator value is the span of time from the start of propagation to whatever the current time is, you will need to store that initial date in the derived type).

When overriding this method, the base method must be called.

Parameters:

initialState - The initial state of propagation.

computeThreshold

public final double computeThreshold()

Computes the threshold for this StoppingConditionEvaluator, or throws an RuntimeException if this evaluator is searching for an extrema.

Returns:

The threshold for this stopping condition.

getValue

public final double getValue(ITimeBasedState state)

Compute the value of the stopping condition from the state. This method will put the raw value into the circular bounds (if the function is circular).

Parameters:

state - The state to check.

Returns:

The value to use when exploring this condition while looking for an event.

evaluateRawValue

public abstract double evaluateRawValue(ITimeBasedState state)

Returns the raw value before it is bound by circular constraints. This method does not need to deal with the AngularSetting (get).

Parameters:

state - The state from which to extract the value.

Returns:

The value before it is bound by circular constraints.

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.

getNextSampleSuggestion

@Nonnull
public Duration getNextSampleSuggestion(@Nonnull
                                                  JulianDate lastNominalDateSampled,
                                                  @Nonnull
                                                  Duration otherSuggestedStep,
                                                  ITimeBasedState state,
                                                  @Nonnull
                                                  IntegrationSense direction)

Gets the next step that the thing that is sampling this StoppingConditionEvaluator should take. The returned Duration must be signed correctly. Override this method if this particular stopping condition has some sense of how it should be sampled, or if it somehow knows at what time it's extrema or thresholds will occur at.

Parameters:

lastNominalDateSampled - The last date that was sampled.

otherSuggestedStep - The current step that the propagator will take if no other stopping condition will return a smaller value. This is returned in the base implementation of this method.

state - The state at the lastNominalDateSampled.

direction - The integration direction.

Returns:

The correctly signed, smallest in magnitude, step that this stopping condition thinks it should take.

checkForExactCrossing

public final boolean checkForExactCrossing(double rawValue,
                                           double threshold)

Checks to see if the state is at the exact threshold to within machine tolerance.

Parameters:

rawValue - The value that the StoppingConditionEvaluator computed.

threshold - The threshold that the state should be at.

Returns:

true if the rawValue is withing machine precision of the threshold.