agi.foundation.numericalmethods

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

Class JulianDateFunctionExplorer

java.lang.Object

agi.foundation.numericalmethods.JulianDateFunctionExplorer

public class JulianDateFunctionExplorer
extends Object

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

Method Summary

Modifier and Type	Method and Description
void	addFunctionSampled(EventHandler<JulianDateFunctionSampledEventArgs> value) Adds a handler for an event that is raised each time a function is sampled.
void	addLocalExtremumFound(EventHandler<JulianDateExtremumFoundEventArgs> value) Raised when a precise local minimum or maximum has been found.
void	addLocalExtremumIndicated(EventHandler<JulianDateExtremumIndicatedEventArgs> 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<JulianDateThresholdCrossingFoundEventArgs> value) Adds a handler for an event that is raised when a precise threshold crossing has been found.
void	addThresholdCrossingIndicated(EventHandler<JulianDateThresholdCrossingIndicatedEventArgs> value) Adds a handler for an event that is raised when two points are found that indicate a threshold was crossed.
void	explore(JulianDate start, JulianDate stop) Explores the function, raising events for each finding.
void	explore(JulianDate start, JulianDate stop, ITrackCalculationProgress tracker) Explores the function, raising events for each finding.
Duration	getCrossingDateTolerance() Gets the tolerance with which to converge on date when finding a precise crossing of a threshold.
JulianDate	getCurrentDate() Gets the current date, which is the date of the most recent sample.
boolean	getCurrentDateIsValid() Gets a value indicating whether CurrentDate (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	getExtremumDateTolerance() Gets the tolerance with which to converge on date 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.
JulianDateFunctionCollection	getFunctions() Gets the collection of functions to be explored.
JulianDate	getPreviousDate() Gets the date of the previous sample.
boolean	getPreviousDateIsValid() Gets a value indicating whether PreviousDate (get) is valid.
JulianDate	getPreviousPreviousDate() Gets the date of the previous, previous sample.
boolean	getPreviousPreviousDateIsValid() Gets a value indicating whether PreviousPreviousDate (get) is valid.
boolean	getReportExtremaAtEndpoints() Gets a value indicating whether extrema should be reported at the start and stop times given to JulianDateFunctionExplorer.explore(JulianDate,JulianDate) when the function is not flat at those endpoints.
JulianDateSampleSuggestionCallback	getSampleSuggestionCallback() Gets the callback to use to determine the times at which to sample the Functions (get) when the JulianDateFunctionExplorer.explore(JulianDate,JulianDate) method is called.
void	removeFunctionSampled(EventHandler<JulianDateFunctionSampledEventArgs> value) Removes a handler for an event that is raised each time a function is sampled.
void	removeLocalExtremumFound(EventHandler<JulianDateExtremumFoundEventArgs> value) Raised when a precise local minimum or maximum has been found.
void	removeLocalExtremumIndicated(EventHandler<JulianDateExtremumIndicatedEventArgs> 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<JulianDateThresholdCrossingFoundEventArgs> value) Removes a handler for an event that is raised when a precise threshold crossing has been found.
void	removeThresholdCrossingIndicated(EventHandler<JulianDateThresholdCrossingIndicatedEventArgs> 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	setCrossingDateTolerance(Duration value) Sets the tolerance with which to converge on date 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	setExtremumDateTolerance(Duration value) Sets the tolerance with which to converge on date 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 JulianDateFunctionExplorer.explore(JulianDate,JulianDate) when the function is not flat at those endpoints.
void	setSampleSuggestionCallback(JulianDateSampleSuggestionCallback value) Sets the callback to use to determine the times at which to sample the Functions (get) when the JulianDateFunctionExplorer.explore(JulianDate,JulianDate) method is called.
void	step(JulianDate next) Explores the function through one step, raising events for any findings over the step.
Iterable<JulianDateFunctionFinding>	stepInteractively(JulianDate next) Steps exploration to a specified date.

Methods inherited from class java.lang.Object

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

Constructor Detail

JulianDateFunctionExplorer

public JulianDateFunctionExplorer()

Initializes a new instance.

Method Detail

addThresholdCrossingIndicated

public final void addThresholdCrossingIndicated(EventHandler<JulianDateThresholdCrossingIndicatedEventArgs> 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<JulianDateThresholdCrossingIndicatedEventArgs> 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<JulianDateExtremumIndicatedEventArgs> 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<JulianDateExtremumIndicatedEventArgs> 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<JulianDateThresholdCrossingFoundEventArgs> 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 JulianDateFunctionThresholdCrossingIndicated.findPreciseCrossing() is called during the handling of the ThresholdCrossingIndicated (add / remove) event.

Parameters:

value - The handler.

removeThresholdCrossingFound

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

Parameters:

value - The handler.

addLocalExtremumFound

public final void addLocalExtremumFound(EventHandler<JulianDateExtremumFoundEventArgs> 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.
• JulianDateFunctionExtremumIndicated.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<JulianDateExtremumFoundEventArgs> 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.
• JulianDateFunctionExtremumIndicated.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<JulianDateFunctionSampledEventArgs> 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<JulianDateFunctionSampledEventArgs> 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 JulianDateFunctionCollection getFunctions()

Gets the collection of functions to be explored.

getSampleSuggestionCallback

public final JulianDateSampleSuggestionCallback getSampleSuggestionCallback()

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

setSampleSuggestionCallback

public final void setSampleSuggestionCallback(JulianDateSampleSuggestionCallback value)

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

getExtremumDateTolerance

@Nonnull
public final Duration getExtremumDateTolerance()

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

setExtremumDateTolerance

public final void setExtremumDateTolerance(@Nonnull
                                           Duration value)

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

getCrossingDateTolerance

@Nonnull
public final Duration getCrossingDateTolerance()

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

setCrossingDateTolerance

public final void setCrossingDateTolerance(@Nonnull
                                           Duration value)

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

getCurrentDate

@Nonnull
public final JulianDate getCurrentDate()

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

Throws:

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

getCurrentDateIsValid

public final boolean getCurrentDateIsValid()

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

getPreviousDate

@Nonnull
public final JulianDate getPreviousDate()

Gets the date of the previous sample.

Throws:

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

getPreviousDateIsValid

public final boolean getPreviousDateIsValid()

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

getPreviousPreviousDate

@Nonnull
public final JulianDate getPreviousPreviousDate()

Gets the date of the previous, previous sample.

Throws:

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

getPreviousPreviousDateIsValid

public final boolean getPreviousPreviousDateIsValid()

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

Explores the function, raising events for each finding.

Parameters:

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

stop - The date 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
                          JulianDate start,
                          @Nonnull
                          JulianDate stop,
                          @Nullable
                          ITrackCalculationProgress tracker)

Explores the function, raising events for each finding.

Parameters:

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

stop - The date 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
                       JulianDate next)

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

Parameters:

next - The date of the next step.

stepInteractively

@Nonnull
public final Iterable<JulianDateFunctionFinding> stepInteractively(@Nonnull
                                                                             JulianDate next)

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

Parameters:

next - The date 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, CurrentDateIsValid (get), PreviousDateIsValid (get), and PreviousPreviousDateIsValid (get) all return false.