agi.foundation.numericalmethods.advanced

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

Class AdaptiveNumericalIntegrator

java.lang.Object

agi.foundation.numericalmethods.NumericalIntegrator

agi.foundation.numericalmethods.advanced.AdaptiveNumericalIntegrator

All Implemented Interfaces:

ICloneWithContext, IThreadAware

Direct Known Subclasses:

BulirschStoerIntegrator, RungeKuttaAdaptiveStepIntegrator

public abstract class AdaptiveNumericalIntegrator
extends NumericalIntegrator

Base class for all NumericalIntegrator objects who can use error information produced during integration to adapt the size of the step in order to adjust the amount of error introduced into the dependent variables over successive integration steps. This also allows varying the size of the step to arrive at a final stopping time.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AdaptiveNumericalIntegrator() Initializes a new instance.
protected	AdaptiveNumericalIntegrator(AdaptiveNumericalIntegrator existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.

Method Summary

Modifier and Type	Method and Description
abstract boolean	adaptStep() This method updates the CurrentStepSize (get) to account for error in the state and its derivatives.
protected double	adjustStep(double step, double errorRatio) Adjusts a given step by increasing it or decreasing it based on the given error.
protected double	boundAndTruncateStepSize(double stepSize) A method which should be called before updating the CurrentStepSize (get) which will bound the size based on the MinimumStepSize (get / set) and MaximumStepSize (get / set), and will truncate it based on the StepTruncationOrder (get / set).
double[]	getAdaptiveWeights() Gets the weights to be applied to the state elements when computing the error which determines how to adapt the step size.
double	getCurrentStepSize() Gets the current (positive) size of the step which the integrator will use for the next integration step.
int	getIterations() Gets the number of iteration required to adapt the CurrentStepSize (get) to within error tolerance.
int	getMaximumIterations() Gets the maximum number of Iterations (get / set) to allow before forcing the integrator to accept the CurrentStepSize (get) and proceed to the next step.
double	getMaximumStepSize() Gets the maximum size of the CurrentStepSize (get).
double	getMinimumStepSize() Gets the (positive) minimum size of the CurrentStepSize (get).
double	getStepDeflationExponent() Gets the exponent to apply to the error when calculating the amount to decrease the size of the step.
double	getStepDeflationFactor() Gets a scalar multiplier to apply to the step when decreasing it.
double	getStepInflationExponent() Gets the exponent to apply to the error when calculating the amount to increase the size of the step.
double	getStepInflationFactor() Gets a scalar multiplier to apply to the step when increasing it.
KindOfStepSize	getStepSizeBehavior() Gets whether to avoid adapting the step size and instead fix the value of CurrentStepSize (get).
int	getStepTruncationOrder() Gets the integer exponent specifying the order of magnitude at which to truncate the significant digits in the CurrentStepSize (get).
void	initialize(double x, double[] y) Initialize the integrator's initial independent and dependent variables and reset the integration parameters.
void	integrate() Perform an integration step moving the independent and dependent variables from their initial (the final values of the previous step) to their new final values, using the CurrentStepSize (get).
void	integrate(double stepSize) Integrate the current integration step with the given step size.
void	setAdaptiveWeights(double[] value) Sets the weights to be applied to the state elements when computing the error which determines how to adapt the step size.
protected void	setCurrentStepSize(double value) Sets the value of the CurrentStepSize (get) which the integrator will use for the next integration step.
protected void	setIterations(int value) Sets the number of iteration required to adapt the CurrentStepSize (get) to within error tolerance.
void	setMaximumIterations(int value) Sets the maximum number of Iterations (get / set) to allow before forcing the integrator to accept the CurrentStepSize (get) and proceed to the next step.
void	setMaximumStepSize(double value) Sets the maximum size of the CurrentStepSize (get).
void	setMinimumStepSize(double value) Sets the (positive) minimum size of the CurrentStepSize (get).
void	setStepDeflationExponent(double value) Sets the exponent to apply to the error when calculating the amount to decrease the size of the step.
void	setStepDeflationFactor(double value) Sets a scalar multiplier to apply to the step when decreasing it.
void	setStepInflationExponent(double value) Sets the exponent to apply to the error when calculating the amount to increase the size of the step.
void	setStepInflationFactor(double value) Sets a scalar multiplier to apply to the step when increasing it.
void	setStepSizeBehavior(KindOfStepSize value) Sets whether to avoid adapting the step size and instead fix the value of CurrentStepSize (get).
void	setStepTruncationOrder(int value) Sets the integer exponent specifying the order of magnitude at which to truncate the significant digits in the CurrentStepSize (get).

Methods inherited from class agi.foundation.numericalmethods.NumericalIntegrator

clone, getDimension, getDirection, getFinalDependentVariableValues, getFinalIndependentVariableValue, getInitialDependentVariableValues, getInitialIndependentVariableValue, getInitialStepSize, getIsThreadSafe, getPreviousStepSize, getStepSizeInformation, getSystemOfEquations, reintegrate, setDirection, setFinalDependentVariableValues, setFinalIndependentVariableValue, setInitialDependentVariableValues, setInitialIndependentVariableValue, setInitialStepSize, setStepSizeInformation, setSystemOfEquations, startNextStep

Methods inherited from class java.lang.Object

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

Constructor Detail

AdaptiveNumericalIntegrator

protected AdaptiveNumericalIntegrator()

Initializes a new instance.

AdaptiveNumericalIntegrator

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

getMinimumStepSize

public final double getMinimumStepSize()

Gets the (positive) minimum size of the CurrentStepSize (get).

setMinimumStepSize

public final void setMinimumStepSize(double value)

Sets the (positive) minimum size of the CurrentStepSize (get).

getMaximumStepSize

public final double getMaximumStepSize()

Gets the maximum size of the CurrentStepSize (get).

setMaximumStepSize

public final void setMaximumStepSize(double value)

Sets the maximum size of the CurrentStepSize (get).

getStepTruncationOrder

public final int getStepTruncationOrder()

Gets the integer exponent specifying the order of magnitude at which to truncate the significant digits in the CurrentStepSize (get). For instance, to truncate the value to three decimal places, specify a truncation order of -3. To truncate the value to an order of 100, specify a truncation order of 2. To specify the step size should be an integer value, specify a truncation order of 0.

setStepTruncationOrder

public final void setStepTruncationOrder(int value)

Sets the integer exponent specifying the order of magnitude at which to truncate the significant digits in the CurrentStepSize (get). For instance, to truncate the value to three decimal places, specify a truncation order of -3. To truncate the value to an order of 100, specify a truncation order of 2. To specify the step size should be an integer value, specify a truncation order of 0.

getStepSizeBehavior

@Nonnull
public final KindOfStepSize getStepSizeBehavior()

Gets whether to avoid adapting the step size and instead fix the value of CurrentStepSize (get).

setStepSizeBehavior

public final void setStepSizeBehavior(@Nonnull
                                      KindOfStepSize value)

Sets whether to avoid adapting the step size and instead fix the value of CurrentStepSize (get).

getStepDeflationFactor

public final double getStepDeflationFactor()

Gets a scalar multiplier to apply to the step when decreasing it.

setStepDeflationFactor

public final void setStepDeflationFactor(double value)

Sets a scalar multiplier to apply to the step when decreasing it.

getStepDeflationExponent

public final double getStepDeflationExponent()

Gets the exponent to apply to the error when calculating the amount to decrease the size of the step.

setStepDeflationExponent

public final void setStepDeflationExponent(double value)

Sets the exponent to apply to the error when calculating the amount to decrease the size of the step.

getStepInflationFactor

public final double getStepInflationFactor()

Gets a scalar multiplier to apply to the step when increasing it.

setStepInflationFactor

public final void setStepInflationFactor(double value)

Sets a scalar multiplier to apply to the step when increasing it.

getStepInflationExponent

public final double getStepInflationExponent()

Gets the exponent to apply to the error when calculating the amount to increase the size of the step.

setStepInflationExponent

public final void setStepInflationExponent(double value)

Sets the exponent to apply to the error when calculating the amount to increase the size of the step.

getCurrentStepSize

public double getCurrentStepSize()

Gets the current (positive) size of the step which the integrator will use for the next integration step.

Specified by:

getCurrentStepSize in class NumericalIntegrator

setCurrentStepSize

protected final void setCurrentStepSize(double value)

Sets the value of the CurrentStepSize (get) which the integrator will use for the next integration step.

Parameters:

value - The (positive) value to add to the independent variable for the next integration step.

getIterations

public final int getIterations()

Gets the number of iteration required to adapt the CurrentStepSize (get) to within error tolerance.

setIterations

protected final void setIterations(int value)

Sets the number of iteration required to adapt the CurrentStepSize (get) to within error tolerance.

getMaximumIterations

public final int getMaximumIterations()

Gets the maximum number of Iterations (get / set) to allow before forcing the integrator to accept the CurrentStepSize (get) and proceed to the next step.

setMaximumIterations

public final void setMaximumIterations(int value)

Sets the maximum number of Iterations (get / set) to allow before forcing the integrator to accept the CurrentStepSize (get) and proceed to the next step.

getAdaptiveWeights

public final double[] getAdaptiveWeights()

Gets the weights to be applied to the state elements when computing the error which determines how to adapt the step size. This is in addition to any weights used in the integration algorithm itself. If these weights have not been initialized before AdaptiveNumericalIntegrator.initialize(double, double[]) is called, they will be set to a default value of one.

setAdaptiveWeights

public final void setAdaptiveWeights(double[] value)

Sets the weights to be applied to the state elements when computing the error which determines how to adapt the step size. This is in addition to any weights used in the integration algorithm itself. If these weights have not been initialized before AdaptiveNumericalIntegrator.initialize(double, double[]) is called, they will be set to a default value of one.

initialize

public void initialize(double x,
                       double[] y)

Initialize the integrator's initial independent and dependent variables and reset the integration parameters. This should be called by the user prior to performing the first integration step.

Overrides:

initialize in class NumericalIntegrator

Parameters:

x - The value of the initial independent variable.

y - The values for the initial dependent variables.

integrate

public final void integrate()

Perform an integration step moving the independent and dependent variables from their initial (the final values of the previous step) to their new final values, using the CurrentStepSize (get).

When overriding this method, NumericalIntegrator.startNextStep() should be called prior to integration.

Overrides:

integrate in class NumericalIntegrator

integrate

public void integrate(double stepSize)

Integrate the current integration step with the given step size.

Overrides:

integrate in class NumericalIntegrator

Parameters:

stepSize - The step size at which to take the integration step.

adaptStep

public abstract boolean adaptStep()

This method updates the CurrentStepSize (get) to account for error in the state and its derivatives. It returns true if the integrator should reintegrate with the updated step size or false if the integrator should continue to the next integration step (potentially with a different step size).

Returns:

True if the integrator should reintegrate. False if the integrator should continue to the next step.

boundAndTruncateStepSize

protected final double boundAndTruncateStepSize(double stepSize)

A method which should be called before updating the CurrentStepSize (get) which will bound the size based on the MinimumStepSize (get / set) and MaximumStepSize (get / set), and will truncate it based on the StepTruncationOrder (get / set).

Parameters:

stepSize - The size of the previous step to bound and truncate.

Returns:

The new value within the minimum and maximum and only containing significant digits to the specified order.

adjustStep

protected final double adjustStep(double step,
                                  double errorRatio)

Adjusts a given step by increasing it or decreasing it based on the given error. If the error is greater than one, the step will increase. Otherwise, it will decrease. After adjusting the step, AdaptiveNumericalIntegrator.boundAndTruncateStepSize(double) is called.

Parameters:

step - The size of the step to adjust.

errorRatio - The error ratio factor.

Returns:

The new size of the step.