agi.foundation.numericalmethods

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

Class OptimizerMultivariableFunction

java.lang.Object

agi.foundation.numericalmethods.OptimizerMultivariableFunction

All Implemented Interfaces:

IDisposable, ICloneWithContext, IThreadAware, AutoCloseable

Direct Known Subclasses:

TargetedSegmentListOptimizerFunction

public abstract class OptimizerMultivariableFunction
extends Object
implements IThreadAware, IDisposable

A function that can be optimized by a ParameterOptimizer.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	OptimizerMultivariableFunction() Initializes a new instance.
protected	OptimizerMultivariableFunction(OptimizerMultivariableFunction 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<OptimizerFunctionDerivativeEvaluatedEventArgs> value) An event that gets raised when the derivative of the function is evaluated.
void	addNormalFunctionEvaluationEvent(EventHandler<OptimizerFunctionEvaluatedEventArgs> value) An event that gets raised when the nominal function is evaluated.
void	addPerturbedFunctionEvaluationEvent(EventHandler<OptimizerFunctionEvaluatedEventArgs> 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(OptimizerMultivariableFunctionResults results) For OptimizerMultivariableFunctions 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(OptimizerMultivariableFunctionDerivativeResults derivativeResults) Calls the DerivativeEvaluationEvent (add / remove).
abstract Object	clone(CopyContext context) Clones this object using the specified context.
static NumericallyComputedOptimizerFunctionDerivativeResults	computeGradientsNumerically(OptimizerMultivariableFunction function, double[] variables, double[] perturbationValues, FiniteDifferenceMethod differenceMethod, boolean multithreaded, OptimizerMultivariableFunctionResults precomputedValueResults, ITrackCalculationProgress progressTracker) Computes the gradients of an OptimizerMultivariableFunction numerically.
void	dispose() Releases any resources associated with this instance.
protected void	dispose(boolean disposing) Releases any resources associated with this instance.
MultivariableFunctionEvaluationAndDerivativeResults<OptimizerMultivariableFunctionResults,OptimizerMultivariableFunctionDerivativeResults>	evaluate(double[] variables, int order, boolean multithreaded, ITrackCalculationProgress progressTracker) Evaluates the function and the gradients.
abstract OptimizerMultivariableFunctionResults	evaluate(double[] variables, ITrackCalculationProgress progressTracker) Evaluates the function.
OptimizerMultivariableFunctionDerivativeResults	evaluateDerivative(double[] variables, boolean multithreaded, ITrackCalculationProgress progressTracker) Evaluates the gradients of this function.
OptimizerMultivariableFunctionDerivativeResults	evaluateDerivative(double[] variables, boolean multithreaded, OptimizerMultivariableFunctionResults valueResults, ITrackCalculationProgress progressTracker) Evaluates the gradients of this function.
FiniteDifferenceMethod	getDifferenceMethod() Gets how the default numerically computed derivatives 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<OptimizerFunctionDerivativeEvaluatedEventArgs> value) An event that gets raised when the derivative of the function is evaluated.
void	removeNormalFunctionEvaluationEvent(EventHandler<OptimizerFunctionEvaluatedEventArgs> value) An event that gets raised when the nominal function is evaluated.
void	removePerturbedFunctionEvaluationEvent(EventHandler<OptimizerFunctionEvaluatedEventArgs> 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 derivatives 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

OptimizerMultivariableFunction

protected OptimizerMultivariableFunction()

Initializes a new instance.

OptimizerMultivariableFunction

protected OptimizerMultivariableFunction(@Nonnull
                                         OptimizerMultivariableFunction 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 OptimizerMultivariableFunctionResults evaluate(double[] variables,
                                                               @Nullable
                                                               ITrackCalculationProgress progressTracker)

Evaluates the function. The OptimizerMultivariableFunctionResults returned must include the computed equality constraints in the order that they are in the Equalities (get) and the computed inequality constraints in the order that they are in the Inequalities (get). If there are no equality constraints, the function should return a zero-length array of doubles for the equality constraint values. The same should be done for the inequality constraint values if there are no inequality constraint.

If the CostFunction (get / set) is null, the results should include a null cost function value. Otherwise, the results should return a double as the cost function value.

Parameters:

variables - The value of the variables that are used to evaluate the function.

progressTracker - An optional progress tracker.

Returns:

The cost function, equality constraint values, and the inequality constraint values.

evaluateDerivative

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

Evaluates the gradients of this function. The default implementation of this method will numerically compute the gradients. 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 gradients at.

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

progressTracker - An optional progress tracker.

Returns:

The gradients of the cost function, equality constraints, and inequality constraints.

evaluateDerivative

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

Evaluates the gradients of this function. The default implementation of this method will numerically compute the gradients. 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 gradients 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 gradients.

progressTracker - An optional progress tracker.

Returns:

The gradients of the cost function, equality constraints, and inequality constraints.

evaluate

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

Evaluates the function and the gradients. 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 cost function value, equality constraint values, inequality constraint values, and gradients of all those values.

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<OptimizerFunctionEvaluatedEventArgs> 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<OptimizerFunctionEvaluatedEventArgs> 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<OptimizerFunctionEvaluatedEventArgs> 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 OptimizerMultivariableFunction.evaluate(double[],ITrackCalculationProgress) method.

removeNormalFunctionEvaluationEvent

public final void removeNormalFunctionEvaluationEvent(EventHandler<OptimizerFunctionEvaluatedEventArgs> 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 OptimizerMultivariableFunction.evaluate(double[],ITrackCalculationProgress) method.

addDerivativeEvaluationEvent

public final void addDerivativeEvaluationEvent(EventHandler<OptimizerFunctionDerivativeEvaluatedEventArgs> 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 OptimizerMultivariableFunction.evaluateDerivative(double[],boolean,OptimizerMultivariableFunctionResults,ITrackCalculationProgress) method, you should call this event.

removeDerivativeEvaluationEvent

public final void removeDerivativeEvaluationEvent(EventHandler<OptimizerFunctionDerivativeEvaluatedEventArgs> 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 OptimizerMultivariableFunction.evaluateDerivative(double[],boolean,OptimizerMultivariableFunctionResults,ITrackCalculationProgress) method, you should call this event.

callDerivativeEvaluationEvent

protected final void callDerivativeEvaluationEvent(OptimizerMultivariableFunctionDerivativeResults derivativeResults)

Calls the DerivativeEvaluationEvent (add / remove).

Parameters:

derivativeResults - The functions derivative results.

getDifferenceMethod

@Nonnull
public final FiniteDifferenceMethod getDifferenceMethod()

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

setDifferenceMethod

protected final void setDifferenceMethod(@Nonnull
                                         FiniteDifferenceMethod value)

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

applyResults

public void applyResults(OptimizerMultivariableFunctionResults results)

For OptimizerMultivariableFunctions 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.

computeGradientsNumerically

@Nonnull
public static NumericallyComputedOptimizerFunctionDerivativeResults computeGradientsNumerically(@Nonnull
                                                                                                          OptimizerMultivariableFunction function,
                                                                                                          @Nonnull
                                                                                                          double[] variables,
                                                                                                          @Nonnull
                                                                                                          double[] perturbationValues,
                                                                                                          @Nonnull
                                                                                                          FiniteDifferenceMethod differenceMethod,
                                                                                                          boolean multithreaded,
                                                                                                          @Nullable
                                                                                                          OptimizerMultivariableFunctionResults precomputedValueResults,
                                                                                                          @Nullable
                                                                                                          ITrackCalculationProgress progressTracker)

Computes the gradients of an OptimizerMultivariableFunction numerically. This will call the appropriate events on the functions as they are computed.

Parameters:

function - The OptimizerMultivariableFunction to compute the gradients for.

variables - The independent variables that are used to compute the gradients.

perturbationValues - How much each of the variables should be perturbed while computing the gradients.

differenceMethod - The differencing method to use to numerically compute the derivatives.

multithreaded - Should this routine use a multithreaded algorithm. Usually the multithreaded algorithm will be faster, however in cases where there are very few variables and the function evaluates very quickly, it may be faster to set this to false.

precomputedValueResults - The function results at the variables. This is optional; if this is null then the function will be evaluated at the variables.

progressTracker - An optional progress tracker.

Returns:

The evaluated gradients of the cost function, equality constraints, and inequality constraints.