agi.foundation.numericalmethods

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

Class BulirschStoerIntegrator

java.lang.Object

agi.foundation.numericalmethods.NumericalIntegrator

agi.foundation.numericalmethods.advanced.AdaptiveNumericalIntegrator

agi.foundation.numericalmethods.BulirschStoerIntegrator

All Implemented Interfaces:

ICloneWithContext, IThreadAware

public class BulirschStoerIntegrator
extends AdaptiveNumericalIntegrator

An adaptive numerical integrator which uses successive subdivisions of the specified step size in order to measure the relative error in order to update the step size.

Note that the Tolerance (get / set) will affect both how accurate the integrator will be as well as how small the step size will be to achieve the desired accuracy. Having a really small tolerance in relation to large dependent variables may not be best, since it may drive the step size to values near zero over the course of the integration when a higher tolerance will still yield accurate results.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
boolean	adaptStep() This method updates the CurrentStepSize (get) to account for error in the state and its derivatives.
Object	clone(CopyContext context) Create a copy of this integrator.
int	getLastNumberOfSubdivisionsUsed() Gets the current maximum number of subdivisions used during the last iteration step.
double	getSafetyFactorOne() Gets a safety factor used when analyzing roundoff error and determining the new step size.
double	getSafetyFactorTwo() Gets a safety factor used when analyzing roundoff error and determining the new step size.
int[]	getSubdivisions() Gets or sets the set of successive subdivisions used to take steps.
double	getTolerance() Gets the value for the tolerance used to scale the error control, which will control both how accurate the integrator is and the step size used during integration.
void	initialize(double x, double[] y) Initialize the integrator's initial independent and dependent variables and reset the integration parameters.
void	reintegrate(double stepSize) Repeats the last integration of the differential equations.
void	setSafetyFactorOne(double value) Sets a safety factor used when analyzing roundoff error and determining the new step size.
void	setSafetyFactorTwo(double value) Sets a safety factor used when analyzing roundoff error and determining the new step size.
void	setSubdivisions(int[] value) Gets or sets the set of successive subdivisions used to take steps.
void	setTolerance(double value) Sets the value for the tolerance used to scale the error control, which will control both how accurate the integrator is and the step size used during integration.
protected void	startNextStep() This performs the task of setting the Initial values to the previous Final values prior to taking the next step.

Methods inherited from class agi.foundation.numericalmethods.advanced.AdaptiveNumericalIntegrator

adjustStep, boundAndTruncateStepSize, getAdaptiveWeights, getCurrentStepSize, getIterations, getMaximumIterations, getMaximumStepSize, getMinimumStepSize, getStepDeflationExponent, getStepDeflationFactor, getStepInflationExponent, getStepInflationFactor, getStepSizeBehavior, getStepTruncationOrder, integrate, integrate, setAdaptiveWeights, setCurrentStepSize, setIterations, setMaximumIterations, setMaximumStepSize, setMinimumStepSize, setStepDeflationExponent, setStepDeflationFactor, setStepInflationExponent, setStepInflationFactor, setStepSizeBehavior, setStepTruncationOrder

Methods inherited from class agi.foundation.numericalmethods.NumericalIntegrator

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

Methods inherited from class java.lang.Object

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

Constructor Detail

BulirschStoerIntegrator

public BulirschStoerIntegrator()

Initializes a new instance. Be sure to set the SystemOfEquations (get / set) before integrating.

BulirschStoerIntegrator

public BulirschStoerIntegrator(DependentVariableDerivatives system)

Initializes a new instance.

Parameters:

system - The system of equations to integrate.

BulirschStoerIntegrator

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

clone

public Object clone(CopyContext context)

Create a copy of this integrator.

Specified by:

clone in interface ICloneWithContext

Specified by:

clone in class NumericalIntegrator

Parameters:

context - The context in which to create the copy.

Returns:

The copy of this integrator.

getTolerance

public final double getTolerance()

Gets the value for the tolerance used to scale the error control, which will control both how accurate the integrator is and the step size used during integration.

setTolerance

public final void setTolerance(double value)

Sets the value for the tolerance used to scale the error control, which will control both how accurate the integrator is and the step size used during integration.

getSafetyFactorOne

public final double getSafetyFactorOne()

Gets a safety factor used when analyzing roundoff error and determining the new step size. The equation for the step size update is: Hnew = S1 * H * (S2 / Error)^-(2k+1) where "H" is the step size, "Error" is the roundoff error, and "k" is the iteration index into the Subdivisions (get / set) array. The default value is 1/4.

setSafetyFactorOne

public final void setSafetyFactorOne(double value)

Sets a safety factor used when analyzing roundoff error and determining the new step size. The equation for the step size update is: Hnew = S1 * H * (S2 / Error)^-(2k+1) where "H" is the step size, "Error" is the roundoff error, and "k" is the iteration index into the Subdivisions (get / set) array. The default value is 1/4.

getSafetyFactorTwo

public final double getSafetyFactorTwo()

Gets a safety factor used when analyzing roundoff error and determining the new step size. The equation for the step size update is: Hnew = S1 * H * (S2 / Error)^-(2k+1) where "H" is the step size, "Error" is the roundoff error, and "k" is the iteration index into the Subdivisions (get / set) array. The default value is 7/10.

setSafetyFactorTwo

public final void setSafetyFactorTwo(double value)

Sets a safety factor used when analyzing roundoff error and determining the new step size. The equation for the step size update is: Hnew = S1 * H * (S2 / Error)^-(2k+1) where "H" is the step size, "Error" is the roundoff error, and "k" is the iteration index into the Subdivisions (get / set) array. The default value is 7/10.

getSubdivisions

public final int[] getSubdivisions()

Gets or sets the set of successive subdivisions used to take steps. For each step the Bulirsch-Stoer integrator takes, it will divide the step size according to the subdivisions and analyze the error. If the error doesn't converge, it will continue to subdivide until it either converges or decides that the step size itself is problematic and starts over with a new step size.

The default set is derived from the work of Deuflhard: { 2, 4, 6, 8, 10 }

When changing the set, make sure to check for stability as having too few or too many subdivisions can change the behavior of the algorithm.

setSubdivisions

public final void setSubdivisions(int[] value)

Gets or sets the set of successive subdivisions used to take steps. For each step the Bulirsch-Stoer integrator takes, it will divide the step size according to the subdivisions and analyze the error. If the error doesn't converge, it will continue to subdivide until it either converges or decides that the step size itself is problematic and starts over with a new step size.

The default set is derived from the work of Deuflhard: { 2, 4, 6, 8, 10 }

When changing the set, make sure to check for stability as having too few or too many subdivisions can change the behavior of the algorithm.

getLastNumberOfSubdivisionsUsed

public final int getLastNumberOfSubdivisionsUsed()

Gets the current maximum number of subdivisions used during the last iteration step.

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 AdaptiveNumericalIntegrator

Parameters:

x - The value of the initial independent variable.

y - The values for the initial dependent variables.

adaptStep

public 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).

Specified by:

adaptStep in class AdaptiveNumericalIntegrator

Returns:

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

reintegrate

public void reintegrate(double stepSize)

Repeats the last integration of the differential equations.

When overriding this method, note that the CurrentStepSize (get) property should be unaffected by the stepSize parameter.

Specified by:

reintegrate in class NumericalIntegrator

Parameters:

stepSize - The increment made to the InitialIndependentVariableValue (get / set) to transition to the new FinalIndependentVariableValue (get / set).

startNextStep

protected void startNextStep()

This performs the task of setting the Initial values to the previous Final values prior to taking the next step. This method is called prior to integrating the step but not called during reintegration.

Overrides:

startNextStep in class NumericalIntegrator