agi.foundation.numericalmethods

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

Class SolvableMultivariableFunction

java.lang.Object

agi.foundation.numericalmethods.SolvableMultivariableFunction

All Implemented Interfaces:

IDisposable, ICloneWithContext, IThreadAware, AutoCloseable

Direct Known Subclasses:

TargetedSegmentListFunction

public abstract class SolvableMultivariableFunction
extends Object
implements IThreadAware, IDisposable

A function that can be solved for by a MultivariableFunctionSolver.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
void	addDerivativeEvaluationEvent(EventHandler<SolverFunctionDerivativeEvaluatedEventArgs> value) An event that gets raised when the derivative of the function is evaluated.
void	addNormalFunctionEvaluationEvent(EventHandler<SolverFunctionEvaluatedEventArgs> value) An event that gets raised when the nominal function is evaluated.
void	addPerturbedFunctionEvaluationEvent(EventHandler<SolverFunctionEvaluatedEventArgs> value) An event that gets raised when a perturbed function is computed as part of the derivation of the derivative of the function.
void	applyResults(SolvableMultivariableFunctionResults results) For SolvableMultivariableFunctions that have state, there may be times when that state should be manually set on a function (sometimes for performance reasons, when the function will be called multiple times and it should start from where it left off).
protected void	callDerivativeEvaluationEvent(SolvableMultivariableFunctionDerivativeResults derivativeResults) Calls the DerivativeEvaluationEvent (add / remove).
abstract Object	clone(CopyContext context) Clones this object using the specified context.
void	dispose() Releases any resources associated with this instance.
protected void	dispose(boolean disposing) Releases any resources associated with this instance.
MultivariableFunctionEvaluationAndDerivativeResults<SolvableMultivariableFunctionResults,SolvableMultivariableFunctionDerivativeResults>	evaluate(double[] variables, int order, boolean multithreaded, ITrackCalculationProgress progressTracker) Evaluates the function and the Jacobian.
abstract SolvableMultivariableFunctionResults	evaluate(double[] variables, ITrackCalculationProgress progressTracker) Evaluates the function.
SolvableMultivariableFunctionDerivativeResults	evaluateDerivative(double[] variables, boolean multithreaded, ITrackCalculationProgress progressTracker) Evaluates the Jacobian of this function.
SolvableMultivariableFunctionDerivativeResults	evaluateDerivative(double[] variables, boolean multithreaded, SolvableMultivariableFunctionResults valueResults, ITrackCalculationProgress progressTracker) Evaluates the Jacobian of this function.
FiniteDifferenceMethod	getDifferenceMethod() Gets how the default numerically computed derivative of this function should be computed.
abstract boolean	getIsThreadSafe() Gets a value indicating whether the methods on this instance are safe to call from multiple threads simultaneously.
double[]	getPerturbationValues() Gets the values to use to perturb the variables when the derivative is computed numerically.
void	removeDerivativeEvaluationEvent(EventHandler<SolverFunctionDerivativeEvaluatedEventArgs> value) An event that gets raised when the derivative of the function is evaluated.
void	removeNormalFunctionEvaluationEvent(EventHandler<SolverFunctionEvaluatedEventArgs> value) An event that gets raised when the nominal function is evaluated.
void	removePerturbedFunctionEvaluationEvent(EventHandler<SolverFunctionEvaluatedEventArgs> value) An event that gets raised when a perturbed function is computed as part of the derivation of the derivative of the function.
protected void	setDifferenceMethod(FiniteDifferenceMethod value) Sets how the default numerically computed derivative of this function should be computed.
protected void	setPerturbationValues(double[] value) Sets the values to use to perturb the variables when the derivative is computed numerically.

Methods inherited from class java.lang.Object

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

Methods inherited from interface agi.foundation.compatibility.IDisposable

close

Constructor Detail

SolvableMultivariableFunction

protected SolvableMultivariableFunction()

Initializes a new instance.

SolvableMultivariableFunction

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

dispose

public final void dispose()

Releases any resources associated with this instance.

Specified by:

dispose in interface IDisposable

dispose

protected void dispose(boolean disposing)

Releases any resources associated with this instance.

Parameters:

disposing - true to release both managed and unmanaged resources; false to release only unmanaged resources.

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

evaluate

public abstract SolvableMultivariableFunctionResults evaluate(double[] variables,
                                                              @Nullable
                                                              ITrackCalculationProgress progressTracker)

Evaluates the function. The SolvableMultivariableFunctionResults returned must include the computed constraints in the order that they are in the Constraints (get). If your function computes more than just constraint values you should extend SolvableMultivariableFunctionResults to contain those additional results.

Parameters:

variables - The value of the variables to evaluate at.

progressTracker - An optional progress tracker.

Returns:

The constraint values and any other results.

evaluateDerivative

@Nonnull
public SolvableMultivariableFunctionDerivativeResults evaluateDerivative(@Nonnull
                                                                                   double[] variables,
                                                                                   boolean multithreaded,
                                                                                   @Nullable
                                                                                   ITrackCalculationProgress progressTracker)

Evaluates the Jacobian of this function. The default implementation of this method will numerically compute the Jacobian. To do that, the value of the function at the variables will be computed. When using the default implementation, the PerturbationValues (get / set) must be set.

Parameters:

variables - The values to compute the Jacobian at.

multithreaded - Should the evaluation be done using as many cores as possible.

progressTracker - An optional progress tracker.

Returns:

The Jacobian and any other relevant results evaluated while evaluating the derivative of this function.

evaluateDerivative

@Nonnull
public SolvableMultivariableFunctionDerivativeResults evaluateDerivative(@Nonnull
                                                                                   double[] variables,
                                                                                   boolean multithreaded,
                                                                                   SolvableMultivariableFunctionResults valueResults,
                                                                                   @Nullable
                                                                                   ITrackCalculationProgress progressTracker)

Evaluates the Jacobian of this function. The default implementation of this method will numerically compute the Jacobian. To do that, the value of the function at the variables will be computed.

Parameters:

variables - The values to compute the Jacobian at.

multithreaded - Should the evaluation be done using as many cores as possible.

valueResults - The evaluated value of the function at the variables. If this is null then this function will be evaluated at the variables as part of the default evaluation of the Jacobian.

progressTracker - An optional progress tracker.

Returns:

The Jacobian and any other relevant results evaluated while evaluating the derivative of this function.

evaluate

@Nonnull
public MultivariableFunctionEvaluationAndDerivativeResults<SolvableMultivariableFunctionResults,SolvableMultivariableFunctionDerivativeResults> evaluate(@Nonnull
                                                                                                                                                                   double[] variables,
                                                                                                                                                                   int order,
                                                                                                                                                                   boolean multithreaded,
                                                                                                                                                                   @Nullable
                                                                                                                                                                   ITrackCalculationProgress progressTracker)

Evaluates the function and the Jacobian. This will call both the DerivativeEvaluationEvent (add / remove) and the NormalFunctionEvaluationEvent (add / remove) events.

Parameters:

variables - The values of the variables to evaluate at.

order - The highest order of the function that should be evaluated. By default, this can be 0 or 1.

multithreaded - Should the evaluation be done using as many cores as possible.

progressTracker - An optional progress tracker.

Returns:

The constraint values, Jacobian, and any other results.

getPerturbationValues

public final double[] getPerturbationValues()

Gets the values to use to perturb the variables when the derivative is computed numerically. This can be ignored if the concrete function computes its derivative analytically.

setPerturbationValues

protected final void setPerturbationValues(double[] value)

Sets the values to use to perturb the variables when the derivative is computed numerically. This can be ignored if the concrete function computes its derivative analytically.

addPerturbedFunctionEvaluationEvent

public final void addPerturbedFunctionEvaluationEvent(EventHandler<SolverFunctionEvaluatedEventArgs> value)

An event that gets raised when a perturbed function is computed as part of the derivation of the derivative of the function. This event will be raised in whatever thread the function was evaluated in. This can be ignored if the concrete function computes its derivative analytically.

removePerturbedFunctionEvaluationEvent

public final void removePerturbedFunctionEvaluationEvent(EventHandler<SolverFunctionEvaluatedEventArgs> value)

An event that gets raised when a perturbed function is computed as part of the derivation of the derivative of the function. This event will be raised in whatever thread the function was evaluated in. This can be ignored if the concrete function computes its derivative analytically.

addNormalFunctionEvaluationEvent

public final void addNormalFunctionEvaluationEvent(EventHandler<SolverFunctionEvaluatedEventArgs> value)

An event that gets raised when the nominal function is evaluated. This event will be raised in whatever thread the nominal function run was. This should be called in the concrete SolvableMultivariableFunction.evaluate(double[],ITrackCalculationProgress) method.

removeNormalFunctionEvaluationEvent

public final void removeNormalFunctionEvaluationEvent(EventHandler<SolverFunctionEvaluatedEventArgs> value)

An event that gets raised when the nominal function is evaluated. This event will be raised in whatever thread the nominal function run was. This should be called in the concrete SolvableMultivariableFunction.evaluate(double[],ITrackCalculationProgress) method.

addDerivativeEvaluationEvent

public final void addDerivativeEvaluationEvent(EventHandler<SolverFunctionDerivativeEvaluatedEventArgs> value)

An event that gets raised when the derivative of the function is evaluated. This event will be raised in whatever thread the derivative is evaluated in. If you override the SolvableMultivariableFunction.evaluateDerivative(double[],boolean,SolvableMultivariableFunctionResults,ITrackCalculationProgress) method, you should call this event.

removeDerivativeEvaluationEvent

public final void removeDerivativeEvaluationEvent(EventHandler<SolverFunctionDerivativeEvaluatedEventArgs> value)

An event that gets raised when the derivative of the function is evaluated. This event will be raised in whatever thread the derivative is evaluated in. If you override the SolvableMultivariableFunction.evaluateDerivative(double[],boolean,SolvableMultivariableFunctionResults,ITrackCalculationProgress) method, you should call this event.

callDerivativeEvaluationEvent

protected final void callDerivativeEvaluationEvent(SolvableMultivariableFunctionDerivativeResults derivativeResults)

Calls the DerivativeEvaluationEvent (add / remove).

Parameters:

derivativeResults - The functions derivative results.

getDifferenceMethod

@Nonnull
public final FiniteDifferenceMethod getDifferenceMethod()

Gets how the default numerically computed derivative of this function should be computed.

setDifferenceMethod

protected final void setDifferenceMethod(@Nonnull
                                         FiniteDifferenceMethod value)

Sets how the default numerically computed derivative of this function should be computed.

applyResults

public void applyResults(SolvableMultivariableFunctionResults results)

For SolvableMultivariableFunctions that have state, there may be times when that state should be manually set on a function (sometimes for performance reasons, when the function will be called multiple times and it should start from where it left off). This method will manually set that state, if needed.

Parameters:

results - The results to apply.