agi.foundation.numericalmethods

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

Class DoubleFunctionExplorer

java.lang.Object

agi.foundation.numericalmethods.DoubleFunctionExplorer

public class DoubleFunctionExplorer
extends Object

Explores one or more functions where the independent variable is double and the dependent variable is double, looking for one or more threshold crossings or local extrema. Interesting findings while exploring the function are reported via events. A supplied callback is used to determine how the function is sampled.

Constructor Summary

Constructors

Constructor and Description
DoubleFunctionExplorer() Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
void	addFunctionSampled(EventHandler<DoubleFunctionSampledEventArgs> value) Adds a handler for an event that is raised each time a function is sampled.
void	addLocalExtremumFound(EventHandler<DoubleExtremumFoundEventArgs> value) Raised when a precise local minimum or maximum has been found.
void	addLocalExtremumIndicated(EventHandler<DoubleExtremumIndicatedEventArgs> value) Adds a handler for an event that is raised when three points are found that indicate the existence of a local extremum (minimum or maximum).
void	addThresholdCrossingFound(EventHandler<DoubleThresholdCrossingFoundEventArgs> value) Adds a handler for an event that is raised when a precise threshold crossing has been found.
void	addThresholdCrossingIndicated(EventHandler<DoubleThresholdCrossingIndicatedEventArgs> value) Adds a handler for an event that is raised when two points are found that indicate a threshold was crossed.
void	explore(double start, double stop) Explores the function, raising events for each finding.
void	explore(double start, double stop, ITrackCalculationProgress tracker) Explores the function, raising events for each finding.
double	getCrossingVariableTolerance() Gets the tolerance with which to converge on Variable when finding a precise crossing of a threshold.
double	getCurrentVariable() Gets the current Variable, which is the Variable of the most recent sample.
boolean	getCurrentVariableIsValid() Gets a value indicating whether CurrentVariable (get) is valid.
HierarchicalLogger	getDebuggingLogger() Gets a logger to which debugging information will be written.
boolean	getExploreExtremaToFindCrossings() Gets a value indicating whether extrema should be explored if exploring those extrema could lead to additional threshold crossings being identified.
double	getExtremaCrossingUncertaintyFactor() Gets a value determining how finely to explore an extremum with the potential to cross a threshold.
double	getExtremumVariableTolerance() Gets the tolerance with which to converge on Variable when precisely finding a local extremum.
boolean	getFindAllCrossingsPrecisely() Gets a value indicating whether all crossings should be found precisely.
boolean	getFindAllExtremaPrecisely() Gets a value indicating whether all extrema should be found precisely.
DoubleFunctionCollection	getFunctions() Gets the collection of functions to be explored.
double	getPreviousPreviousVariable() Gets the Variable of the previous, previous sample.
boolean	getPreviousPreviousVariableIsValid() Gets a value indicating whether PreviousPreviousVariable (get) is valid.
double	getPreviousVariable() Gets the Variable of the previous sample.
boolean	getPreviousVariableIsValid() Gets a value indicating whether PreviousVariable (get) is valid.
boolean	getReportExtremaAtEndpoints() Gets a value indicating whether extrema should be reported at the start and stop times given to DoubleFunctionExplorer.explore(double,double) when the function is not flat at those endpoints.
DoubleSampleSuggestionCallback	getSampleSuggestionCallback() Gets the callback to use to determine the times at which to sample the Functions (get) when the DoubleFunctionExplorer.explore(double,double) method is called.
void	removeFunctionSampled(EventHandler<DoubleFunctionSampledEventArgs> value) Removes a handler for an event that is raised each time a function is sampled.
void	removeLocalExtremumFound(EventHandler<DoubleExtremumFoundEventArgs> value) Raised when a precise local minimum or maximum has been found.
void	removeLocalExtremumIndicated(EventHandler<DoubleExtremumIndicatedEventArgs> value) Removes a handler for an event that is raised when three points are found that indicate the existence of a local extremum (minimum or maximum).
void	removeThresholdCrossingFound(EventHandler<DoubleThresholdCrossingFoundEventArgs> value) Removes a handler for an event that is raised when a precise threshold crossing has been found.
void	removeThresholdCrossingIndicated(EventHandler<DoubleThresholdCrossingIndicatedEventArgs> value) Removes a handler for an event that is raised when two points are found that indicate a threshold was crossed.
void	reset() Resets exploration.
void	setCrossingVariableTolerance(double value) Sets the tolerance with which to converge on Variable when finding a precise crossing of a threshold.
void	setDebuggingLogger(HierarchicalLogger value) Sets a logger to which debugging information will be written.
void	setExploreExtremaToFindCrossings(boolean value) Sets a value indicating whether extrema should be explored if exploring those extrema could lead to additional threshold crossings being identified.
void	setExtremaCrossingUncertaintyFactor(double value) Sets a value determining how finely to explore an extremum with the potential to cross a threshold.
void	setExtremumVariableTolerance(double value) Sets the tolerance with which to converge on Variable when precisely finding a local extremum.
void	setFindAllCrossingsPrecisely(boolean value) Sets a value indicating whether all crossings should be found precisely.
void	setFindAllExtremaPrecisely(boolean value) Sets a value indicating whether all extrema should be found precisely.
void	setReportExtremaAtEndpoints(boolean value) Sets a value indicating whether extrema should be reported at the start and stop times given to DoubleFunctionExplorer.explore(double,double) when the function is not flat at those endpoints.
void	setSampleSuggestionCallback(DoubleSampleSuggestionCallback value) Sets the callback to use to determine the times at which to sample the Functions (get) when the DoubleFunctionExplorer.explore(double,double) method is called.
void	step(double next) Explores the function through one step, raising events for any findings over the step.
Iterable<DoubleFunctionFinding>	stepInteractively(double next) Steps exploration to a specified Variable.

Methods inherited from class java.lang.Object

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

Constructor Detail

DoubleFunctionExplorer

public DoubleFunctionExplorer()

Initializes a new instance.

Method Detail

addThresholdCrossingIndicated

public final void addThresholdCrossingIndicated(EventHandler<DoubleThresholdCrossingIndicatedEventArgs> value)

Adds a handler for an event that is raised when two points are found that indicate a threshold was crossed. When this event is raised, the exact crossing has not yet been identified.

Parameters:

value - The handler.

removeThresholdCrossingIndicated

public final void removeThresholdCrossingIndicated(EventHandler<DoubleThresholdCrossingIndicatedEventArgs> value)

Removes a handler for an event that is raised when two points are found that indicate a threshold was crossed. When this event is raised, the exact crossing has not yet been identified.

Parameters:

value - The handler.

addLocalExtremumIndicated

public final void addLocalExtremumIndicated(EventHandler<DoubleExtremumIndicatedEventArgs> value)

Adds a handler for an event that is raised when three points are found that indicate the existence of a local extremum (minimum or maximum). When this event is raised, the exact extremum has not yet been identified.

Parameters:

value - The handler.

removeLocalExtremumIndicated

public final void removeLocalExtremumIndicated(EventHandler<DoubleExtremumIndicatedEventArgs> value)

Removes a handler for an event that is raised when three points are found that indicate the existence of a local extremum (minimum or maximum). When this event is raised, the exact extremum has not yet been identified.

Parameters:

value - The handler.

addThresholdCrossingFound

public final void addThresholdCrossingFound(EventHandler<DoubleThresholdCrossingFoundEventArgs> value)

Adds a handler for an event that is raised when a precise threshold crossing has been found. This event will only be raised if FindAllCrossingsPrecisely (get / set) is true or DoubleFunctionThresholdCrossingIndicated.findPreciseCrossing() is called during the handling of the ThresholdCrossingIndicated (add / remove) event.

Parameters:

value - The handler.

removeThresholdCrossingFound

public final void removeThresholdCrossingFound(EventHandler<DoubleThresholdCrossingFoundEventArgs> value)

Removes a handler for an event that is raised when a precise threshold crossing has been found. This event will only be raised if FindAllCrossingsPrecisely (get / set) is true or DoubleFunctionThresholdCrossingIndicated.findPreciseCrossing() is called during the handling of the ThresholdCrossingIndicated (add / remove) event.

Parameters:

value - The handler.

addLocalExtremumFound

public final void addLocalExtremumFound(EventHandler<DoubleExtremumFoundEventArgs> value)

Raised when a precise local minimum or maximum has been found. This event will only be raised if the local extremum is found precisely. Local extrema are found precisely if:

• FindAllExtremaPrecisely (get / set) is true.
• DoubleFunctionExtremumIndicated.findPreciseExtremum() is called during the handling of the LocalExtremumIndicated (add / remove) event.
• ExploreExtremaToFindCrossings (get / set) is true and the extrema could have lead to additional threshold crossings being indicated.
• ReportExtremaAtEndpoints (get / set) is true and the function is not flat at the endpoints.

removeLocalExtremumFound

public final void removeLocalExtremumFound(EventHandler<DoubleExtremumFoundEventArgs> value)

Raised when a precise local minimum or maximum has been found. This event will only be raised if the local extremum is found precisely. Local extrema are found precisely if:

• FindAllExtremaPrecisely (get / set) is true.
• DoubleFunctionExtremumIndicated.findPreciseExtremum() is called during the handling of the LocalExtremumIndicated (add / remove) event.
• ExploreExtremaToFindCrossings (get / set) is true and the extrema could have lead to additional threshold crossings being indicated.
• ReportExtremaAtEndpoints (get / set) is true and the function is not flat at the endpoints.

addFunctionSampled

public final void addFunctionSampled(EventHandler<DoubleFunctionSampledEventArgs> value)

Adds a handler for an event that is raised each time a function is sampled. Note that this NOT raised when the function is sampled for the purpose of precisely finding a threshold crossing or extremum.

Parameters:

value - The handler.

removeFunctionSampled

public final void removeFunctionSampled(EventHandler<DoubleFunctionSampledEventArgs> value)

Removes a handler for an event that is raised each time a function is sampled. Note that this NOT raised when the function is sampled for the purpose of precisely finding a threshold crossing or extremum.

Parameters:

value - The handler.

getFunctions

@Nonnull
public final DoubleFunctionCollection getFunctions()

Gets the collection of functions to be explored.

getSampleSuggestionCallback

public final DoubleSampleSuggestionCallback getSampleSuggestionCallback()

Gets the callback to use to determine the times at which to sample the Functions (get) when the DoubleFunctionExplorer.explore(double,double) method is called.

setSampleSuggestionCallback

public final void setSampleSuggestionCallback(DoubleSampleSuggestionCallback value)

Sets the callback to use to determine the times at which to sample the Functions (get) when the DoubleFunctionExplorer.explore(double,double) method is called.

getFindAllCrossingsPrecisely

public final boolean getFindAllCrossingsPrecisely()

Gets a value indicating whether all crossings should be found precisely. If this property is false, precise crossings will only be found if DoubleFunctionThresholdCrossingIndicated.findPreciseCrossing() is called during the ThresholdCrossingIndicated (add / remove) event. By default, this property has the value false.

setFindAllCrossingsPrecisely

public final void setFindAllCrossingsPrecisely(boolean value)

Sets a value indicating whether all crossings should be found precisely. If this property is false, precise crossings will only be found if DoubleFunctionThresholdCrossingIndicated.findPreciseCrossing() is called during the ThresholdCrossingIndicated (add / remove) event. By default, this property has the value false.

getFindAllExtremaPrecisely

public final boolean getFindAllExtremaPrecisely()

Gets a value indicating whether all extrema should be found precisely. If this property is false, precise extrema will only be found if DoubleFunctionExtremumIndicated.findPreciseExtremum() is called during the ThresholdCrossingIndicated (add / remove) event, or if ExploreExtremaToFindCrossings (get / set) is true and the indicated extrema might cross the threshold. By default, this property has the value false.

setFindAllExtremaPrecisely

public final void setFindAllExtremaPrecisely(boolean value)

Sets a value indicating whether all extrema should be found precisely. If this property is false, precise extrema will only be found if DoubleFunctionExtremumIndicated.findPreciseExtremum() is called during the ThresholdCrossingIndicated (add / remove) event, or if ExploreExtremaToFindCrossings (get / set) is true and the indicated extrema might cross the threshold. By default, this property has the value false.

getExploreExtremaToFindCrossings

public final boolean getExploreExtremaToFindCrossings()

Gets a value indicating whether extrema should be explored if exploring those extrema could lead to additional threshold crossings being identified. Consider three sample points where the middle sampled value is higher than the other two so that the three points form two line segments with opposite slope. This configuration indicates that a local maximum exists somewhere between the three points. If all three points are below a threshold, it's possible that the local maximum, if found, will lie above the threshold. When this property is true, that extremum is explored until it is found precisely, or it is determined based on ExtremaCrossingUncertaintyFactor (get / set) that the extremum is unlikely to cross any threshold values. Such an extrema is explored even if FindAllExtremaPrecisely (get / set) is false. By default, this property has the value true.

setExploreExtremaToFindCrossings

public final void setExploreExtremaToFindCrossings(boolean value)

Sets a value indicating whether extrema should be explored if exploring those extrema could lead to additional threshold crossings being identified. Consider three sample points where the middle sampled value is higher than the other two so that the three points form two line segments with opposite slope. This configuration indicates that a local maximum exists somewhere between the three points. If all three points are below a threshold, it's possible that the local maximum, if found, will lie above the threshold. When this property is true, that extremum is explored until it is found precisely, or it is determined based on ExtremaCrossingUncertaintyFactor (get / set) that the extremum is unlikely to cross any threshold values. Such an extrema is explored even if FindAllExtremaPrecisely (get / set) is false. By default, this property has the value true.

getExtremaCrossingUncertaintyFactor

public final double getExtremaCrossingUncertaintyFactor()

Gets a value determining how finely to explore an extremum with the potential to cross a threshold. At each iteration exploring the extremum this factor is multiplied against that iteration's Error (get) to determine the tolerance to compare against the difference between the current guess of the extrema and the closest applicable threshold value. This property is only used if FindAllExtremaPrecisely (get / set) is set to false and ExploreExtremaToFindCrossings (get / set) is set to true. By default, this property has the value Double.POSITIVE_INFINITY which effectively causes a complete search of all extrema. If you do not desire to completely search all extrema with the potential to cross a threshold, set this to a value greater than 1.0.

setExtremaCrossingUncertaintyFactor

public final void setExtremaCrossingUncertaintyFactor(double value)

Sets a value determining how finely to explore an extremum with the potential to cross a threshold. At each iteration exploring the extremum this factor is multiplied against that iteration's Error (get) to determine the tolerance to compare against the difference between the current guess of the extrema and the closest applicable threshold value. This property is only used if FindAllExtremaPrecisely (get / set) is set to false and ExploreExtremaToFindCrossings (get / set) is set to true. By default, this property has the value Double.POSITIVE_INFINITY which effectively causes a complete search of all extrema. If you do not desire to completely search all extrema with the potential to cross a threshold, set this to a value greater than 1.0.

getReportExtremaAtEndpoints

public final boolean getReportExtremaAtEndpoints()

Gets a value indicating whether extrema should be reported at the start and stop times given to DoubleFunctionExplorer.explore(double,double) when the function is not flat at those endpoints. By default, this property has the value true.

setReportExtremaAtEndpoints

public final void setReportExtremaAtEndpoints(boolean value)

Sets a value indicating whether extrema should be reported at the start and stop times given to DoubleFunctionExplorer.explore(double,double) when the function is not flat at those endpoints. By default, this property has the value true.

getExtremumVariableTolerance

public final double getExtremumVariableTolerance()

Gets the tolerance with which to converge on Variable when precisely finding a local extremum. By default, this property has the value 0.005.

setExtremumVariableTolerance

public final void setExtremumVariableTolerance(double value)

Sets the tolerance with which to converge on Variable when precisely finding a local extremum. By default, this property has the value 0.005.

getCrossingVariableTolerance

public final double getCrossingVariableTolerance()

Gets the tolerance with which to converge on Variable when finding a precise crossing of a threshold. By default, this property has the value 0.005.

setCrossingVariableTolerance

public final void setCrossingVariableTolerance(double value)

Sets the tolerance with which to converge on Variable when finding a precise crossing of a threshold. By default, this property has the value 0.005.

getCurrentVariable

public final double getCurrentVariable()

Gets the current Variable, which is the Variable of the most recent sample.

Throws:

IllegalStateException - The current Variable is not available because the explorer has not yet been stepped for the first time.

getCurrentVariableIsValid

public final boolean getCurrentVariableIsValid()

Gets a value indicating whether CurrentVariable (get) is valid. CurrentVariable (get) is invalid before the explorer is stepped for the first time.

getPreviousVariable

public final double getPreviousVariable()

Gets the Variable of the previous sample.

Throws:

IllegalStateException - The previous Variable is not available because the explorer has not yet been stepped for the second time.

getPreviousVariableIsValid

public final boolean getPreviousVariableIsValid()

Gets a value indicating whether PreviousVariable (get) is valid. PreviousVariable (get) is invalid before the explorer is stepped for the second time.

getPreviousPreviousVariable

public final double getPreviousPreviousVariable()

Gets the Variable of the previous, previous sample.

Throws:

IllegalStateException - The previous previous Variable is not available because the explorer has not yet been stepped for the third time.

getPreviousPreviousVariableIsValid

public final boolean getPreviousPreviousVariableIsValid()

Gets a value indicating whether PreviousPreviousVariable (get) is valid. PreviousPreviousVariable (get) is invalid before the explorer is stepped for the third time.

getDebuggingLogger

public final HierarchicalLogger getDebuggingLogger()

Gets a logger to which debugging information will be written.

setDebuggingLogger

public final void setDebuggingLogger(HierarchicalLogger value)

Sets a logger to which debugging information will be written.

explore

public final void explore(double start,
                          double stop)

Explores the function, raising events for each finding.

Parameters:

start - The Variable at which to start exploring the function.

stop - The Variable at which to stop exploring the function.

Throws:

PropertyInvalidException - Thrown when Functions (get) is empty or SampleSuggestionCallback (get / set) is null.

IllegalStateException - Thrown when SampleSuggestionCallback (get / set) suggests a zero-length step.

explore

public final void explore(double start,
                          double stop,
                          @Nullable
                          ITrackCalculationProgress tracker)

Explores the function, raising events for each finding.

Parameters:

start - The Variable at which to start exploring the function.

stop - The Variable at which to stop exploring the function.

tracker - The object to which progress is reported and that is able to cancel this operation before it is complete, or null.

Throws:

PropertyInvalidException - Thrown when Functions (get) is empty or SampleSuggestionCallback (get / set) is null.

IllegalStateException - Thrown when SampleSuggestionCallback (get / set) suggests a zero-length step.

step

public final void step(double next)

Explores the function through one step, raising events for any findings over the step.

Parameters:

next - The Variable of the next step.

stepInteractively

@Nonnull
public final Iterable<DoubleFunctionFinding> stepInteractively(double next)

Steps exploration to a specified Variable. Any findings during the step are reported in an enumerable collection of DoubleFunctionFindings. Events are not raised for the findings.

Parameters:

next - The Variable to which to step.

Returns:

An enumerable collection of findings over the step. This collection becomes invalid the next time the function explorer is stepped.

reset

public final void reset()

Resets exploration. After calling this method, CurrentVariableIsValid (get), PreviousVariableIsValid (get), and PreviousPreviousVariableIsValid (get) all return false.