agi.foundation.numericalmethods

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

Class TimeIntervalFinder

java.lang.Object

agi.foundation.numericalmethods.TimeIntervalFinder

public class TimeIntervalFinder
extends Object

Finds the time intervals during which a constraint on a function of time is satisfied. This is a convenient way to use the capabilities of JulianDateFunctionExplorer.

Constructor Summary

Constructors

Constructor and Description
TimeIntervalFinder() Initializes a new instance with default parameters.
TimeIntervalFinder(Function2<JulianDate,Double> function, double constraintValue) Initializes a new instance using the specified function and constraint value.
TimeIntervalFinder(Function2<JulianDate,Double> function, double constraintValue, Duration samplingInterval) Initializes a new instance using the specified function, constraint value, and sampling interval.

Method Summary

Modifier and Type	Method and Description
TimeIntervalCollection	findIntervals(JulianDate start, boolean isStartIncluded, JulianDate stop, boolean isStopIncluded) Finds the intervals on which the Function (get / set) satisfies the ConstraintValue (get / set) over the specified interval.
TimeIntervalCollection	findIntervals(JulianDate start, boolean isStartIncluded, JulianDate stop, boolean isStopIncluded, ITrackCalculationProgress tracker) Finds the intervals on which the Function (get / set) satisfies the ConstraintValue (get / set) over the specified interval.
TimeIntervalCollection	findIntervals(JulianDate start, JulianDate stop) Finds the intervals on which the Function (get / set) satisfies the ConstraintValue (get / set) over the specified interval.
TimeIntervalCollection	findIntervals(JulianDate start, JulianDate stop, ITrackCalculationProgress tracker) Finds the intervals on which the Function (get / set) satisfies the ConstraintValue (get / set) over the specified interval.
double	getConstraintValue() Gets the desired constraint value.
HierarchicalLogger	getDebuggingLogger() Gets a logger to which debugging information will be written.
double	getExtremaCrossingUncertaintyFactor() Gets a value determining how finely to explore an extremum with the potential to cross a threshold.
Function2<JulianDate,Double>	getFunction() Gets the function to evaluate.
boolean	getMultithreadFindIntervals() Gets a value indicating whether or not a call to TimeIntervalFinder.findIntervals(agi.foundation.time.JulianDate,agi.foundation.time.JulianDate,ITrackCalculationProgress) should be run in multithreaded mode.
IJulianDateFunctionSampler	getSampler() Gets the sampler that controls the times at which the function is sampled while searching for satisfaction intervals.
Duration	getSamplingInterval() Gets the independent variable sampling increment.
Duration	getTimeTolerance() Gets the convergence tolerance on the time when finding function extremum and crossings of the constraint threshold.
double	getValueTolerance() Gets the convergence tolerance on the function value when finding function extremum and crossings of the constraint threshold.
void	setConstraintValue(double value) Sets the desired constraint value.
void	setDebuggingLogger(HierarchicalLogger value) Sets a logger to which debugging information will be written.
void	setExtremaCrossingUncertaintyFactor(double value) Sets a value determining how finely to explore an extremum with the potential to cross a threshold.
void	setFunction(Function2<JulianDate,Double> value) Sets the function to evaluate.
void	setMultithreadFindIntervals(boolean value) Sets a value indicating whether or not a call to TimeIntervalFinder.findIntervals(agi.foundation.time.JulianDate,agi.foundation.time.JulianDate,ITrackCalculationProgress) should be run in multithreaded mode.
void	setSampler(IJulianDateFunctionSampler value) Sets the sampler that controls the times at which the function is sampled while searching for satisfaction intervals.
void	setSamplingInterval(Duration value) Sets the independent variable sampling increment.
void	setTimeTolerance(Duration value) Sets the convergence tolerance on the time when finding function extremum and crossings of the constraint threshold.
void	setValueTolerance(double value) Sets the convergence tolerance on the function value when finding function extremum and crossings of the constraint threshold.

Methods inherited from class java.lang.Object

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

Constructor Detail

TimeIntervalFinder

public TimeIntervalFinder()

Initializes a new instance with default parameters.

TimeIntervalFinder

public TimeIntervalFinder(Function2<JulianDate,Double> function,
                          double constraintValue)

Initializes a new instance using the specified function and constraint value.

Parameters:

function - The function to evaluate.

constraintValue - The desired constraint value.

TimeIntervalFinder

public TimeIntervalFinder(Function2<JulianDate,Double> function,
                          double constraintValue,
                          @Nonnull
                          Duration samplingInterval)

Initializes a new instance using the specified function, constraint value, and sampling interval.

Parameters:

function - The function to evaluate.

constraintValue - The desired constraint value.

samplingInterval - The maximum interval on which to sample the function.

Method Detail

getFunction

public final Function2<JulianDate,Double> getFunction()

Gets the function to evaluate.

setFunction

public final void setFunction(Function2<JulianDate,Double> value)

Sets the function to evaluate.

getConstraintValue

public final double getConstraintValue()

Gets the desired constraint value.

setConstraintValue

public final void setConstraintValue(double value)

Sets the desired constraint value.

getSamplingInterval

@Nonnull
public final Duration getSamplingInterval()

Gets the independent variable sampling increment. If Sampler (get / set) is null, this is the fixed step that is used to sample the entire interval. If Sampler (get / set) is non-null, this property is ignored.

setSamplingInterval

public final void setSamplingInterval(@Nonnull
                                      Duration value)

Sets the independent variable sampling increment. If Sampler (get / set) is null, this is the fixed step that is used to sample the entire interval. If Sampler (get / set) is non-null, this property is ignored.

getSampler

public final IJulianDateFunctionSampler getSampler()

Gets the sampler that controls the times at which the function is sampled while searching for satisfaction intervals. Consider using JulianDateFunctionSampling and JulianDateFunctionSampling.getFunctionSampler(). If this property is null, the function is sampled at fixed steps defined by the SamplingInterval (get / set) property.

setSampler

public final void setSampler(IJulianDateFunctionSampler value)

Sets the sampler that controls the times at which the function is sampled while searching for satisfaction intervals. Consider using JulianDateFunctionSampling and JulianDateFunctionSampling.getFunctionSampler(). If this property is null, the function is sampled at fixed steps defined by the SamplingInterval (get / set) property.

getTimeTolerance

@Nonnull
public final Duration getTimeTolerance()

Gets the convergence tolerance on the time when finding function extremum and crossings of the constraint threshold.

Throws:

ArgumentOutOfRangeException - Thrown if the user attempts to set a Duration whose TotalSeconds (get) are less than or equal to zero.

setTimeTolerance

public final void setTimeTolerance(@Nonnull
                                   Duration value)

Sets the convergence tolerance on the time when finding function extremum and crossings of the constraint threshold.

Throws:

ArgumentOutOfRangeException - Thrown if the user attempts to set a Duration whose TotalSeconds (get) are less than or equal to zero.

getValueTolerance

public final double getValueTolerance()

Gets the convergence tolerance on the function value when finding function extremum and crossings of the constraint threshold.

Throws:

ArgumentOutOfRangeException - Thrown if the user attempts to set a value less than or equal to zero.

setValueTolerance

public final void setValueTolerance(double value)

Sets the convergence tolerance on the function value when finding function extremum and crossings of the constraint threshold.

Throws:

ArgumentOutOfRangeException - Thrown if the user attempts to set a value less than or equal to zero.

getExtremaCrossingUncertaintyFactor

public final double getExtremaCrossingUncertaintyFactor()

Gets a value determining how finely to explore an extremum with the potential to cross a threshold. This value is passed along to the ExtremaCrossingUncertaintyFactor (get / set) on the JulianDateFunctionExplorer.

setExtremaCrossingUncertaintyFactor

public final void setExtremaCrossingUncertaintyFactor(double value)

Sets a value determining how finely to explore an extremum with the potential to cross a threshold. This value is passed along to the ExtremaCrossingUncertaintyFactor (get / set) on the JulianDateFunctionExplorer.

getMultithreadFindIntervals

public final boolean getMultithreadFindIntervals()

Gets a value indicating whether or not a call to TimeIntervalFinder.findIntervals(agi.foundation.time.JulianDate,agi.foundation.time.JulianDate,ITrackCalculationProgress) should be run in multithreaded mode.

setMultithreadFindIntervals

public final void setMultithreadFindIntervals(boolean value)

Sets a value indicating whether or not a call to TimeIntervalFinder.findIntervals(agi.foundation.time.JulianDate,agi.foundation.time.JulianDate,ITrackCalculationProgress) should be run in multithreaded mode.

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.

findIntervals

public final TimeIntervalCollection findIntervals(@Nonnull
                                                  JulianDate start,
                                                  @Nonnull
                                                  JulianDate stop)

Finds the intervals on which the Function (get / set) satisfies the ConstraintValue (get / set) over the specified interval.

Parameters:

start - The beginning of the interval on which to search.

stop - The end of the interval on which to search.

Returns:

A collection of intervals on which the function satisfies the constraint.

findIntervals

public final TimeIntervalCollection findIntervals(@Nonnull
                                                  JulianDate start,
                                                  @Nonnull
                                                  JulianDate stop,
                                                  @Nullable
                                                  ITrackCalculationProgress tracker)

Finds the intervals on which the Function (get / set) satisfies the ConstraintValue (get / set) over the specified interval.

Parameters:

start - The beginning of the interval on which to search.

stop - The end of the interval on which to search.

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

Returns:

A collection of intervals on which the function satisfies the constraint.

Throws:

IllegalStateException - Thrown when the threshold crossings of the function are not consistent. This usually indicates that a singularity exists near the threshold value.

findIntervals

public final TimeIntervalCollection findIntervals(@Nonnull
                                                  JulianDate start,
                                                  boolean isStartIncluded,
                                                  @Nonnull
                                                  JulianDate stop,
                                                  boolean isStopIncluded)

Finds the intervals on which the Function (get / set) satisfies the ConstraintValue (get / set) over the specified interval.

Parameters:

start - The beginning of the interval on which to search.

isStartIncluded - true if the start date is included in the interval; otherwise false.

stop - The end of the interval on which to search.

isStopIncluded - true if the stop date is included in the interval; otherwise false.

Returns:

A collection of intervals on which the function satisfies the constraint.

Throws:

IllegalStateException - Thrown when the threshold crossings of the function are not consistent. This usually indicates that a singularity exists near the threshold value.

findIntervals

public final TimeIntervalCollection findIntervals(@Nonnull
                                                  JulianDate start,
                                                  boolean isStartIncluded,
                                                  @Nonnull
                                                  JulianDate stop,
                                                  boolean isStopIncluded,
                                                  @Nullable
                                                  ITrackCalculationProgress tracker)

Finds the intervals on which the Function (get / set) satisfies the ConstraintValue (get / set) over the specified interval.

Parameters:

start - The beginning of the interval on which to search.

isStartIncluded - true if the start date is included in the interval; otherwise false.

stop - The end of the interval on which to search.

isStopIncluded - true if the stop date is included in the interval; otherwise false.

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

Returns:

A collection of intervals on which the function satisfies the constraint.

Throws:

IllegalStateException - Thrown when the threshold crossings of the function are not consistent. This usually indicates that a singularity exists near the threshold value.