agi.foundation.stoppingconditions

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

Class StoppingCondition

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.stoppingconditions.StoppingCondition

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

Direct Known Subclasses:

AccessStoppingCondition, DelegateStoppingCondition, DurationStoppingCondition, EpochSecondsStoppingCondition, ScalarStoppingCondition, ValueInStateStoppingCondition

public abstract class StoppingCondition
extends DefinitionalObject

A stopping condition will get evaluated at every step of propagation, and treat some value based on the computed state as a function. That function will then be sampled to find events such as thresholds and extrema, and propagation will be signaled to stop when a specified event is found. This is the definition of the Evaluator that will actually produce the value.

See the Stopping Conditions topic for more detail on how to use stopping conditions.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	StoppingCondition() Initializes a new instance.
protected	StoppingCondition(double valueTolerance, StopType type) Initializes a new instance.
protected	StoppingCondition(StoppingCondition existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.

Method Summary

Modifier and Type	Method and Description
protected boolean	checkForSameDefinition(DefinitionalObject other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected abstract boolean	checkForSameDefinition(StoppingCondition other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected int	computeCurrentDefinitionHashCode() Computes a hash code based on the current properties of this object.
abstract ValueDefinition<Double>	createDoubleThreshold() Creates a ValueDefinition of type double.
void	enumerateDependencies(DependencyEnumerator enumerator) Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon.
protected void	freezeAggregatedObjects() Called by DefinitionalObject.freeze() to also freeze any objects that are considered to be a part of this object.
CircularRange	getAngularSetting() Gets the range a value should be cropped to if the value computed is a angle, or indicates that the value computed is not an angle.
List<StoppingConditionConstraint>	getConstraints() Gets additional constraints on the stopping condition.
StoppingConditionEnabled	getEnabled() Gets if this StoppingCondition will be considered during propagation.
abstract StoppingConditionEvaluator	getEvaluator(EvaluatorGroup group) Gets a StoppingConditionEvaluator for use in the NumericalPropagator.
double	getFunctionTolerance() Gets how close the function value must get to the threshold to be considered equal to.
String	getName() Gets an optional name for this stopping condition.
boolean	getRequireFunctionTolerance() Gets a value indicating whether the FunctionTolerance (get / set) does not need to be satisfied.
StoppingTriggeredCallback	getSatisfiedCallback() Gets a callback that is executed when this condition is satisfied.
int	getStopOnEventNumber() Gets how many times the threshold must be met, or how many extrema must be found before stopping.
StopType	getTypeOfStoppingCondition() Gets the type of the event to stop on (extrema, threshold, ...).
void	setAngularSetting(CircularRange value) Sets the range a value should be cropped to if the value computed is a angle, or indicates that the value computed is not an angle.
void	setEnabled(StoppingConditionEnabled value) Sets if this StoppingCondition will be considered during propagation.
void	setFunctionTolerance(double value) Sets how close the function value must get to the threshold to be considered equal to.
void	setName(String value) Sets an optional name for this stopping condition.
void	setRequireFunctionTolerance(boolean value) Sets a value indicating whether the FunctionTolerance (get / set) does not need to be satisfied.
void	setSatisfiedCallback(StoppingTriggeredCallback value) Sets a callback that is executed when this condition is satisfied.
void	setStopOnEventNumber(int value) Sets how many times the threshold must be met, or how many extrema must be found before stopping.
void	setTypeOfStoppingCondition(StopType value) Sets the type of the event to stop on (extrema, threshold, ...).
protected void	validateProperties() Validates that required properties are configured correctly in order to get an evaluator for this instance.

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, clone, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, freeze, getCollectionHashCode, getCollectionHashCode, getCollectionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDictionaryHashCode, getIsFrozen, isSameDefinition, throwIfFrozen

Methods inherited from class java.lang.Object

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

Constructor Detail

StoppingCondition

protected StoppingCondition()

Initializes a new instance.

StoppingCondition

protected StoppingCondition(double valueTolerance,
                            @Nonnull
                            StopType type)

Initializes a new instance.

Parameters:

valueTolerance - The tolerance between the value computed and the threshold.

type - Specifies what type of threshold or extrema this stopping condition is attempting to stop on.

StoppingCondition

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

checkForSameDefinition

protected final boolean checkForSameDefinition(DefinitionalObject other)

Checks to determine if another instance has the same definition as this instance and returns true if it does. Derived classes MUST override this method and check all new fields introduced by the derived class for definitional equivalence. It is NOT necessary to check base class fields because the base class will already have done that. When overriding this method, you should NOT call the base implementation because it will return false for all derived-class instances. Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).

Specified by:

checkForSameDefinition in class DefinitionalObject

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

checkForSameDefinition

protected abstract boolean checkForSameDefinition(StoppingCondition other)

Checks to determine if another instance has the same definition as this instance and returns true if it does. Derived classes MUST override this method and check all new fields introduced by the derived class for definitional equivalence. It is NOT necessary to check base class fields because the base class will already have done that. When overriding this method, you should NOT call the base implementation because it will return false for all derived-class instances. Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

computeCurrentDefinitionHashCode

protected int computeCurrentDefinitionHashCode()

Computes a hash code based on the current properties of this object. Derived classes MUST override this method and compute a hash code that combines: a unique hash code seed, the base implementation result, and the hash codes of all new fields introduced by the derived class which are used in the StoppingCondition.checkForSameDefinition(agi.foundation.infrastructure.DefinitionalObject) method.

Overrides:

computeCurrentDefinitionHashCode in class DefinitionalObject

Returns:

The computed hash code.

enumerateDependencies

public void enumerateDependencies(DependencyEnumerator enumerator)

Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon. Derived classes which contain additional dependencies MUST override this method, call the base implementation, and enumerate dependencies introduced by the derived class.

Specified by:

enumerateDependencies in interface IEnumerateDependencies

Overrides:

enumerateDependencies in class DefinitionalObject

Parameters:

enumerator - The enumerator that is informed of the dependencies of this object.

freezeAggregatedObjects

protected void freezeAggregatedObjects()

Called by DefinitionalObject.freeze() to also freeze any objects that are considered to be a part of this object. Derived classes which contain additional aggregated objects MUST override this method, call the base implementation, and freeze aggregated objects introduced by the derived class. The objects that need to be frozen in this method are frequently created in this object's constructor and are not settable via properties.

Overrides:

freezeAggregatedObjects in class DefinitionalObject

getName

public final String getName()

Gets an optional name for this stopping condition.

setName

public final void setName(String value)

Sets an optional name for this stopping condition.

getSatisfiedCallback

public final StoppingTriggeredCallback getSatisfiedCallback()

Gets a callback that is executed when this condition is satisfied.

setSatisfiedCallback

public final void setSatisfiedCallback(StoppingTriggeredCallback value)

Sets a callback that is executed when this condition is satisfied.

getTypeOfStoppingCondition

@Nonnull
public final StopType getTypeOfStoppingCondition()

Gets the type of the event to stop on (extrema, threshold, ...).

setTypeOfStoppingCondition

public final void setTypeOfStoppingCondition(@Nonnull
                                             StopType value)

Sets the type of the event to stop on (extrema, threshold, ...).

createDoubleThreshold

public abstract ValueDefinition<Double> createDoubleThreshold()

Creates a ValueDefinition of type double. If the derived StoppingCondition defines its threshold to be of a different type than a double, it can use a ValueDefinition of that other type in its StoppingConditionEvaluator. However it is required that the threshold can be represented as a double and this must return such a value. If the specified StoppingCondition threshold is just a ValueDefinition of type double, that property can simply be returned here.

Returns:

The threshold as a ValueDefinition where the type is a double.

getFunctionTolerance

public final double getFunctionTolerance()

Gets how close the function value must get to the threshold to be considered equal to. Note that even if there is unquestionably a threshold, if the event search can not converge to a value at or below this value, it will not satisfy the stopping condition and no event will be logged. This must be larger than machine precision of values near the threshold.

setFunctionTolerance

public final void setFunctionTolerance(double value)

Sets how close the function value must get to the threshold to be considered equal to. Note that even if there is unquestionably a threshold, if the event search can not converge to a value at or below this value, it will not satisfy the stopping condition and no event will be logged. This must be larger than machine precision of values near the threshold.

getRequireFunctionTolerance

public final boolean getRequireFunctionTolerance()

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

setRequireFunctionTolerance

public final void setRequireFunctionTolerance(boolean value)

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

getStopOnEventNumber

public final int getStopOnEventNumber()

Gets how many times the threshold must be met, or how many extrema must be found before stopping. If a StoppingConditionEvaluator finds a valid stop except for a constraint being unsatisfied, that will not count as a crossing.

setStopOnEventNumber

public final void setStopOnEventNumber(int value)

Sets how many times the threshold must be met, or how many extrema must be found before stopping. If a StoppingConditionEvaluator finds a valid stop except for a constraint being unsatisfied, that will not count as a crossing.

getAngularSetting

@Nonnull
public final CircularRange getAngularSetting()

Gets the range a value should be cropped to if the value computed is a angle, or indicates that the value computed is not an angle. By default this is set to CircularRange.NOT_CIRCULAR.

setAngularSetting

public final void setAngularSetting(@Nonnull
                                    CircularRange value)

Sets the range a value should be cropped to if the value computed is a angle, or indicates that the value computed is not an angle. By default this is set to CircularRange.NOT_CIRCULAR.

getEnabled

@Nonnull
public final StoppingConditionEnabled getEnabled()

Gets if this StoppingCondition will be considered during propagation.

setEnabled

public final void setEnabled(@Nonnull
                             StoppingConditionEnabled value)

Sets if this StoppingCondition will be considered during propagation.

getConstraints

@Nonnull
public final List<StoppingConditionConstraint> getConstraints()

Gets additional constraints on the stopping condition. The constraints allow you to add extra criteria to whether an event should be considered valid to stop on. See their help for more information.

getEvaluator

@Nonnull
public abstract StoppingConditionEvaluator getEvaluator(@Nonnull
                                                                  EvaluatorGroup group)

Gets a StoppingConditionEvaluator for use in the NumericalPropagator.

Derived classes should call StoppingCondition.validateProperties() to check properties owned by this base class, as well as validate their own properties.

Parameters:

group - The group to use to initialize any evaluators that will be used by the condition and its Constraints (get).

Returns:

An evaluator for this StoppingCondition.

validateProperties

protected void validateProperties()

Validates that required properties are configured correctly in order to get an evaluator for this instance. Derived classes should call this method when implementing StoppingCondition.getEvaluator(agi.foundation.EvaluatorGroup), as well as validate their own properties.

Throws:

PropertyInvalidException - Thrown when StopOnEventNumber (get / set) is not positive.

PropertyInvalidException - Thrown when FunctionTolerance (get / set) is not positive.