agi.foundation.numericalmethods

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

Class NumericalIntegrator

java.lang.Object

agi.foundation.numericalmethods.NumericalIntegrator

All Implemented Interfaces:

ICloneWithContext, IThreadAware

Direct Known Subclasses:

AdaptiveNumericalIntegrator, MultipleStepIntegrator, RungeKuttaFixedStepIntegrator

public abstract class NumericalIntegrator
extends Object
implements IThreadAware

A numerical integrator which can be used to update a set of dependent variables over a given step of an independent variable by using a differential equation defining the derivatives.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
abstract Object	clone(CopyContext context) Create a copy of this integrator.
abstract double	getCurrentStepSize() Gets the current (positive) size of the step which the integrator will use for the next integration step.
int	getDimension() Gets the number of dependent variables based on the Dimension (get) of the SystemOfEquations (get / set).
IntegrationSense	getDirection() Gets whether to integrate forward, increasing the independent variable, or backward, decreasing the independent variable.
double[]	getFinalDependentVariableValues() Gets the values of the dependent variables resulting from the last integration step.
double	getFinalIndependentVariableValue() Gets the value of the independent variable after an integration step.
double[]	getInitialDependentVariableValues() Gets the values of the dependent variables prior to an integration step.
double	getInitialIndependentVariableValue() Gets the value of the independent variable prior to an integration step.
double	getInitialStepSize() Gets the initial (positive) size of the step to add to the InitialIndependentVariableValue (get / set) when performing an integration.
boolean	getIsThreadSafe() Gets a value indicating whether the methods on this instance are safe to call from multiple threads simultaneously.
double	getPreviousStepSize() Gets the size of the last step taken by the integrator.
StepSizeInformation	getStepSizeInformation() Gets a value indicating whether the CurrentStepSize (get) was changed from the InitialStepSize (get / set) and, if so, the nature of how it was changed.
DependentVariableDerivatives	getSystemOfEquations() Gets the system of differential equations corresponding to the derivatives of the dependent variables.
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) 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.
abstract void	reintegrate(double stepSize) Repeats the last integration of the differential equations.
void	setDirection(IntegrationSense value) Sets whether to integrate forward, increasing the independent variable, or backward, decreasing the independent variable.
protected void	setFinalDependentVariableValues(double[] value) Sets the values of the dependent variables resulting from the last integration step.
protected void	setFinalIndependentVariableValue(double value) Sets the value of the independent variable after an integration step.
protected void	setInitialDependentVariableValues(double[] value) Sets the values of the dependent variables prior to an integration step.
protected void	setInitialIndependentVariableValue(double value) Sets the value of the independent variable prior to an integration step.
void	setInitialStepSize(double value) Sets the initial (positive) size of the step to add to the InitialIndependentVariableValue (get / set) when performing an integration.
protected void	setStepSizeInformation(StepSizeInformation value) Sets a value indicating whether the CurrentStepSize (get) was changed from the InitialStepSize (get / set) and, if so, the nature of how it was changed.
void	setSystemOfEquations(DependentVariableDerivatives value) Sets the system of differential equations corresponding to the derivatives of the dependent variables.
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 java.lang.Object

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

Constructor Detail

NumericalIntegrator

protected NumericalIntegrator()

Initializes a new instance.

NumericalIntegrator

protected NumericalIntegrator(@Nonnull
                              NumericalIntegrator 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 abstract Object clone(CopyContext context)

Create a copy of this integrator.

Specified by:

clone in interface ICloneWithContext

Parameters:

context - The context in which to create the copy.

Returns:

The copy of this integrator.

getIsThreadSafe

public final boolean getIsThreadSafe()

Gets a value indicating whether the methods on this instance are safe to call from multiple threads simultaneously.

If this property is true, all methods and properties are guaranteed to be thread safe. Conceptually, an object that returns true for this method acts as if there is a lock protecting each method and property such that only one thread at a time can be inside any method or property in the class. In reality, such locks are generally not used and are in fact discouraged. However, the user must not experience any exceptions or inconsistent behavior that would not be experienced if such locks were used.

If this property is false, the behavior when using this class from multiple threads simultaneously is undefined and may include inconsistent results and exceptions. Clients wishing to use multiple threads should call CopyForAnotherThread.copy(T) to get a separate instance of the object for each thread.

Specified by:

getIsThreadSafe in interface IThreadAware

getSystemOfEquations

public final DependentVariableDerivatives getSystemOfEquations()

Gets the system of differential equations corresponding to the derivatives of the dependent variables.

setSystemOfEquations

public final void setSystemOfEquations(DependentVariableDerivatives value)

Sets the system of differential equations corresponding to the derivatives of the dependent variables.

getDimension

public final int getDimension()

Gets the number of dependent variables based on the Dimension (get) of the SystemOfEquations (get / set).

getDirection

@Nonnull
public final IntegrationSense getDirection()

Gets whether to integrate forward, increasing the independent variable, or backward, decreasing the independent variable.

setDirection

public final void setDirection(@Nonnull
                               IntegrationSense value)

Sets whether to integrate forward, increasing the independent variable, or backward, decreasing the independent variable.

getStepSizeInformation

@Nonnull
public final StepSizeInformation getStepSizeInformation()

Gets a value indicating whether the CurrentStepSize (get) was changed from the InitialStepSize (get / set) and, if so, the nature of how it was changed.

setStepSizeInformation

protected final void setStepSizeInformation(@Nonnull
                                            StepSizeInformation value)

Sets a value indicating whether the CurrentStepSize (get) was changed from the InitialStepSize (get / set) and, if so, the nature of how it was changed.

getInitialStepSize

public final double getInitialStepSize()

Gets the initial (positive) size of the step to add to the InitialIndependentVariableValue (get / set) when performing an integration. By default, the initial value is one.

setInitialStepSize

public final void setInitialStepSize(double value)

Sets the initial (positive) size of the step to add to the InitialIndependentVariableValue (get / set) when performing an integration. By default, the initial value is one.

getPreviousStepSize

public final double getPreviousStepSize()

Gets the size of the last step taken by the integrator. This returns the difference between the FinalIndependentVariableValue (get / set) and the InitialIndependentVariableValue (get / set).

getCurrentStepSize

public abstract double getCurrentStepSize()

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

getInitialIndependentVariableValue

public final double getInitialIndependentVariableValue()

Gets the value of the independent variable prior to an integration step.

setInitialIndependentVariableValue

protected final void setInitialIndependentVariableValue(double value)

Sets the value of the independent variable prior to an integration step.

getInitialDependentVariableValues

public final double[] getInitialDependentVariableValues()

Gets the values of the dependent variables prior to an integration step. These values will be updated to the previous FinalDependentVariableValues (get / set) at the beginning of each integration step.

setInitialDependentVariableValues

protected final void setInitialDependentVariableValues(double[] value)

Sets the values of the dependent variables prior to an integration step. These values will be updated to the previous FinalDependentVariableValues (get / set) at the beginning of each integration step.

getFinalIndependentVariableValue

public final double getFinalIndependentVariableValue()

Gets the value of the independent variable after an integration step.

setFinalIndependentVariableValue

protected final void setFinalIndependentVariableValue(double value)

Sets the value of the independent variable after an integration step.

getFinalDependentVariableValues

public final double[] getFinalDependentVariableValues()

Gets the values of the dependent variables resulting from the last integration step.

setFinalDependentVariableValues

protected final void setFinalDependentVariableValues(double[] value)

Sets the values of the dependent variables resulting from the last integration step.

integrate

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

integrate

public void integrate(double stepSize)

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.

When overriding this method, NumericalIntegrator.startNextStep() should be called prior to integration. Also note that the CurrentStepSize (get) property should be unaffected by the stepSize parameter.

Parameters:

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

reintegrate

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

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.

initialize

public void initialize(double x,
                       @Nonnull
                       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.

Parameters:

x - The value of the initial independent variable.

y - The values for the initial dependent variables.