agi.foundation.numericalmethods

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

Class DurationFunctionExplorer

java.lang.Object

agi.foundation.numericalmethods.DurationFunctionExplorer

public class DurationFunctionExplorer
extends Object

Explores one or more functions where the independent variable is Duration 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
DurationFunctionExplorer() Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
void	addFunctionSampled(EventHandler<DurationFunctionSampledEventArgs> value) Adds a handler for an event that is raised each time a function is sampled.
void	addLocalExtremumFound(EventHandler<DurationExtremumFoundEventArgs> value) Raised when a precise local minimum or maximum has been found.
void	addLocalExtremumIndicated(EventHandler<DurationExtremumIndicatedEventArgs> 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<DurationThresholdCrossingFoundEventArgs> value) Adds a handler for an event that is raised when a precise threshold crossing has been found.
void	addThresholdCrossingIndicated(EventHandler<DurationThresholdCrossingIndicatedEventArgs> value) Adds a handler for an event that is raised when two points are found that indicate a threshold was crossed.
void	explore(Duration start, Duration stop) Explores the function, raising events for each finding.
void	explore(Duration start, Duration stop, ITrackCalculationProgress tracker) Explores the function, raising events for each finding.
Duration	getCrossingDurationTolerance() Gets the tolerance with which to converge on duration when finding a precise crossing of a threshold.
Duration	getCurrentDuration() Gets the current duration, which is the duration of the most recent sample.
boolean	getCurrentDurationIsValid() Gets a value indicating whether CurrentDuration (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.
Duration	getExtremumDurationTolerance() Gets the tolerance with which to converge on duration 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.
DurationFunctionCollection	getFunctions() Gets the collection of functions to be explored.
Duration	getPreviousDuration() Gets the duration of the previous sample.
boolean	getPreviousDurationIsValid() Gets a value indicating whether PreviousDuration (get) is valid.
Duration	getPreviousPreviousDuration() Gets the duration of the previous, previous sample.
boolean	getPreviousPreviousDurationIsValid() Gets a value indicating whether PreviousPreviousDuration (get) is valid.
boolean	getReportExtremaAtEndpoints() Gets a value indicating whether extrema should be reported at the start and stop times given to DurationFunctionExplorer.explore(Duration,Duration) when the function is not flat at those endpoints.
DurationSampleSuggestionCallback	getSampleSuggestionCallback() Gets the callback to use to determine the times at which to sample the Functions (get) when the DurationFunctionExplorer.explore(Duration,Duration) method is called.
void	removeFunctionSampled(EventHandler<DurationFunctionSampledEventArgs> value) Removes a handler for an event that is raised each time a function is sampled.
void	removeLocalExtremumFound(EventHandler<DurationExtremumFoundEventArgs> value) Raised when a precise local minimum or maximum has been found.
void	removeLocalExtremumIndicated(EventHandler<DurationExtremumIndicatedEventArgs> 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<DurationThresholdCrossingFoundEventArgs> value) Removes a handler for an event that is raised when a precise threshold crossing has been found.
void	removeThresholdCrossingIndicated(EventHandler<DurationThresholdCrossingIndicatedEventArgs> 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	setCrossingDurationTolerance(Duration value) Sets the tolerance with which to converge on duration 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	setExtremumDurationTolerance(Duration value) Sets the tolerance with which to converge on duration 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 DurationFunctionExplorer.explore(Duration,Duration) when the function is not flat at those endpoints.
void	setSampleSuggestionCallback(DurationSampleSuggestionCallback value) Sets the callback to use to determine the times at which to sample the Functions (get) when the DurationFunctionExplorer.explore(Duration,Duration) method is called.
void	step(Duration next) Explores the function through one step, raising events for any findings over the step.
Iterable<DurationFunctionFinding>	stepInteractively(Duration next) Steps exploration to a specified duration.

Methods inherited from class java.lang.Object

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

Constructor Detail

DurationFunctionExplorer

public DurationFunctionExplorer()

Initializes a new instance.

Method Detail

addThresholdCrossingIndicated

public final void addThresholdCrossingIndicated(EventHandler<DurationThresholdCrossingIndicatedEventArgs> 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<DurationThresholdCrossingIndicatedEventArgs> 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<DurationExtremumIndicatedEventArgs> 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<DurationExtremumIndicatedEventArgs> 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<DurationThresholdCrossingFoundEventArgs> 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 DurationFunctionThresholdCrossingIndicated.findPreciseCrossing() is called during the handling of the ThresholdCrossingIndicated (add / remove) event.

Parameters:

value - The handler.

removeThresholdCrossingFound

public final void removeThresholdCrossingFound(EventHandler<DurationThresholdCrossingFoundEventArgs> 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 DurationFunctionThresholdCrossingIndicated.findPreciseCrossing() is called during the handling of the ThresholdCrossingIndicated (add / remove) event.

Parameters:

value - The handler.

addLocalExtremumFound

public final void addLocalExtremumFound(EventHandler<DurationExtremumFoundEventArgs> 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.
• DurationFunctionExtremumIndicated.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<DurationExtremumFoundEventArgs> 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.
• DurationFunctionExtremumIndicated.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<DurationFunctionSampledEventArgs> 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<DurationFunctionSampledEventArgs> 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 DurationFunctionCollection getFunctions()

Gets the collection of functions to be explored.

getSampleSuggestionCallback

public final DurationSampleSuggestionCallback getSampleSuggestionCallback()

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

setSampleSuggestionCallback

public final void setSampleSuggestionCallback(DurationSampleSuggestionCallback value)

Sets the callback to use to determine the times at which to sample the Functions (get) when the DurationFunctionExplorer.explore(Duration,Duration) 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 DurationFunctionThresholdCrossingIndicated.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 DurationFunctionThresholdCrossingIndicated.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 DurationFunctionExtremumIndicated.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 DurationFunctionExtremumIndicated.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 DurationFunctionExplorer.explore(Duration,Duration) 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 DurationFunctionExplorer.explore(Duration,Duration) when the function is not flat at those endpoints. By default, this property has the value true.

getExtremumDurationTolerance

@Nonnull
public final Duration getExtremumDurationTolerance()

Gets the tolerance with which to converge on duration when precisely finding a local extremum. By default, this property has the value 0.005 seconds (5 milliseconds).

setExtremumDurationTolerance

public final void setExtremumDurationTolerance(@Nonnull
                                               Duration value)

Sets the tolerance with which to converge on duration when precisely finding a local extremum. By default, this property has the value 0.005 seconds (5 milliseconds).

getCrossingDurationTolerance

@Nonnull
public final Duration getCrossingDurationTolerance()

Gets the tolerance with which to converge on duration when finding a precise crossing of a threshold. By default, this property has the value 0.005 seconds (5 milliseconds).

setCrossingDurationTolerance

public final void setCrossingDurationTolerance(@Nonnull
                                               Duration value)

Sets the tolerance with which to converge on duration when finding a precise crossing of a threshold. By default, this property has the value 0.005 seconds (5 milliseconds).

getCurrentDuration

@Nonnull
public final Duration getCurrentDuration()

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

Throws:

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

getCurrentDurationIsValid

public final boolean getCurrentDurationIsValid()

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

getPreviousDuration

@Nonnull
public final Duration getPreviousDuration()

Gets the duration of the previous sample.

Throws:

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

getPreviousDurationIsValid

public final boolean getPreviousDurationIsValid()

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

getPreviousPreviousDuration

@Nonnull
public final Duration getPreviousPreviousDuration()

Gets the duration of the previous, previous sample.

Throws:

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

getPreviousPreviousDurationIsValid

public final boolean getPreviousPreviousDurationIsValid()

Gets a value indicating whether PreviousPreviousDuration (get) is valid. PreviousPreviousDuration (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(@Nonnull
                          Duration start,
                          @Nonnull
                          Duration stop)

Explores the function, raising events for each finding.

Parameters:

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

stop - The duration 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(@Nonnull
                          Duration start,
                          @Nonnull
                          Duration stop,
                          @Nullable
                          ITrackCalculationProgress tracker)

Explores the function, raising events for each finding.

Parameters:

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

stop - The duration 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(@Nonnull
                       Duration next)

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

Parameters:

next - The duration of the next step.

stepInteractively

@Nonnull
public final Iterable<DurationFunctionFinding> stepInteractively(@Nonnull
                                                                           Duration next)

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

Parameters:

next - The duration 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, CurrentDurationIsValid (get), PreviousDurationIsValid (get), and PreviousPreviousDurationIsValid (get) all return false.