agi.foundation.numericalmethods.advanced

(agi.foundation.core-2025r1.jar)

Class DependentVariableDerivatives

java.lang.Object

agi.foundation.numericalmethods.advanced.DependentVariableDerivatives

All Implemented Interfaces:

ICloneWithContext, IThreadAware

Direct Known Subclasses:

DependentVariableDifferentialEquation

public abstract class DependentVariableDerivatives
extends Object
implements IThreadAware

Defines a set of first order differential equations used by a NumericalIntegrator to advance a set of dependent variables over an independent variable step.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DependentVariableDerivatives(DependentVariableDerivatives existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.
protected	DependentVariableDerivatives(int[] orders) Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
abstract void	addDerivatives(double x, double[] y, DerivativeMode mode, double[] derivativeArray) Compute and add the derivatives of the dependent variables to the given derivativeArray.
abstract Object	clone(CopyContext context) Clones this object using the specified context.
void	computeDerivatives(double x, double[] y, double[] derivativeArray) Compute the derivatives of the dependent variables and store them to the given array.
void	computeDerivatives(double x, double[] y, double[] slowDerivatives, double[] derivativeArray) Compute the "fast" derivatives of the dependent variables, add them to the given "slow" derivatives, and store them to the given array.
int	getDimension() Gets the total number of elements in the decomposed first-order derivative array.
int	getDimensionForOrder(int order) Get the number of elements in the dependent variables which are of the given order.
abstract boolean	getIsThreadSafe() Gets a value indicating whether the methods on this instance are safe to call from multiple threads simultaneously.
int[]	getOrders() Gets the orders of the differential equations in the differential equations.
protected void	setOrders(int[] value) Sets the orders of the differential equations in the differential equations.

Methods inherited from class java.lang.Object

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

Constructor Detail

DependentVariableDerivatives

protected DependentVariableDerivatives(int[] orders)

Initializes a new instance.

Parameters:

orders - The orders of the differential equations in the differential equations. Higher order equations are decomposed into first-order derivatives of each dependent variable such that the length of this set of orders corresponds to the sum of the orders of the original equations. So if the original equations were: A first order, B third order, C second order, D first order, then the resulting orders of this system of equations will be: 1, 3, 2, 1, 2, 1, 1

DependentVariableDerivatives

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

Clones this object using the specified context.

This method should be implemented to call a copy constructor on the class of the object being cloned. The copy constructor should take the CopyContext as a parameter in addition to the existing instance to copy. The copy constructor should first call CopyContext.addObjectMapping(T, T) to identify the newly constructed instance as a copy of the existing instance. It should then copy all fields, using CopyContext.updateReference(T) to copy any reference fields.

A typical implementation of ICloneWithContext:

public static class MyClass implements ICloneWithContext {
    public MyClass(MyClass existingInstance, CopyContext context) {
        context.addObjectMapping(existingInstance, this);
        someReference = context.updateReference(existingInstance.someReference);
    }

    @Override
    public final Object clone(CopyContext context) {
        return new MyClass(this, context);
    }

    private Object someReference;
}

In general, all fields that are reference types should be copied with a call to CopyContext.updateReference(T). There are a couple of exceptions:

1. Fields that are aggregate parts of the object should always be copied. A referenced object is an aggregate if properties or methods on the object being copied can modify the externally-visible value of the referenced object.
2. If the semantics of the referenced object require that it have a single parent, owner, context, etc., and the object being copied is that parent, owner, or context, then the referenced object should always be copied.

If one of these exceptions applies, the CopyContext should be given an opportunity to update the reference before the reference is copied explicitly. Use CopyContext.updateReference(T) to update the reference. If CopyContext.updateReference(T) returns the original object, indicating that the context does not have a replacement registered, then copy the object manually by invoking a Clone method, a copy constructor, or by manually constructing a new instance and copying the values.

alwaysCopy = context.updateReference(existingInstance.alwaysCopy);
if (existingInstance.alwaysCopy != null && alwaysCopy == existingInstance.alwaysCopy) {
    alwaysCopy = (AlwaysCopy) existingInstance.alwaysCopy.clone(context);
}

If you are implementing an evaluator (a class that implements IEvaluator), the IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) method shares some responsibilities with the copy context constructor. Code duplication can be avoided by doing the following:

1. For references to other evaluators ONLY, simply assign the reference in the constructor instead of calling CopyContext.updateReference(T). You should still call CopyContext.updateReference(T) on any references to non-evaluators.
2. Call IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as the last line in the constructor and pass it the same CopyContext passed to the constructor.
3. Implement IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as normal. See the reference documentation for IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) for more information on implementing that method.

public MyClass(MyClass existingInstance, CopyContext context) {
    super(existingInstance, context);
    someReference = context.updateReference(existingInstance.someReference);
    evaluatorReference = existingInstance.evaluatorReference;
    updateEvaluatorReferences(context);
}

@Override
public void updateEvaluatorReferences(CopyContext context) {
    evaluatorReference = context.updateReference(evaluatorReference);
}

@Override
public Object clone(CopyContext context) {
    return new MyClass(this, context);
}

private Object someReference;
private IEvaluator evaluatorReference;

Specified by:

clone in interface ICloneWithContext

Parameters:

context - The context to use to perform the copy.

Returns:

A new instance which is a copy of this object.

getIsThreadSafe

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

getOrders

public final int[] getOrders()

Gets the orders of the differential equations in the differential equations. Higher order equations are decomposed into first-order derivatives of each dependent variable such that the length of this set of orders corresponds to the sum of the orders of the original equations. So if the original equations were: A first order, B third order, C second order, D first order, then the resulting orders of this system of equations will be: 1, 3, 2, 1, 2, 1, 1

setOrders

protected final void setOrders(int[] value)

Sets the orders of the differential equations in the differential equations. Higher order equations are decomposed into first-order derivatives of each dependent variable such that the length of this set of orders corresponds to the sum of the orders of the original equations. So if the original equations were: A first order, B third order, C second order, D first order, then the resulting orders of this system of equations will be: 1, 3, 2, 1, 2, 1, 1

getDimension

public final int getDimension()

Gets the total number of elements in the decomposed first-order derivative array.

getDimensionForOrder

public final int getDimensionForOrder(int order)

Get the number of elements in the dependent variables which are of the given order.

Parameters:

order - The order of the elements to count.

Returns:

The number of elements of the given order in the dependent variables.

computeDerivatives

public void computeDerivatives(double x,
                               double[] y,
                               @Nonnull
                               double[] derivativeArray)

Compute the derivatives of the dependent variables and store them to the given array.

Parameters:

x - The current independent variable value.

y - The current dependent variable values.

derivativeArray - The derivative array as output. Upon returning, each element in the array should represent the first derivative of the corresponding element in the y.

computeDerivatives

public void computeDerivatives(double x,
                               double[] y,
                               @Nonnull
                               double[] slowDerivatives,
                               @Nonnull
                               double[] derivativeArray)

Compute the "fast" derivatives of the dependent variables, add them to the given "slow" derivatives, and store them to the given array. "Fast" derivatives are ones which are most important for the dynamics of the system and can be computed quickly. Some integrators optimize performance by only computing "fast" intervals when only an approximation of the overall derivative is required.

Parameters:

x - The current independent variable value.

y - The current dependent variable values.

slowDerivatives - The cached "slow" derivatives to add to the derivativeArray.

derivativeArray - The derivative array as output. Upon returning, each element in the array should represent the first derivative of the corresponding element in the y.

addDerivatives

public abstract void addDerivatives(double x,
                                    double[] y,
                                    @Nonnull
                                    DerivativeMode mode,
                                    double[] derivativeArray)

Compute and add the derivatives of the dependent variables to the given derivativeArray. Since the derivativeArray may already contain derivative information from other sources, do not overwrite existing values but instead add the derivatives of the given mode to the existing values.

Parameters:

x - The current independent variable value.

y - The current dependent variable values.

mode - The mode in which to compute the derivatives. Make sure to only compute and add the derivatives requested by the given mode or it may cause each derivative to be added more than once.

derivativeArray - The derivative array as output. Upon returning, each element in the array should represent the first derivative of the corresponding element in the y.