net.von_gagern.martin.confoo.opt
Interface Functional

public interface Functional

Interface of a functional.

An implementation of this interface represents a function taking a fixed number of real input values to compute a single real output value. The gradient (first derivative) and hessian (second derivative) of the function can be calculated as well.

The design of this class is intended to faciliate optimization. To calculate the function itself, its gradient or its hessian at a given location in input space, one first has to move the whole function to that location using setArgument(no.uib.cipr.matrix.Vector). Subsequent calls to return given values will always assume that location to be the function input. It is up to the function implementation to split work between setArgument and the other methods in a suitable fashion. An implementation may throw an IllegalStateException if there was no call to setArgument preceding any of the result calculation methods, but is not required to do so.

A common way to use this interface woule look like this:

 Functional functional = constructFunctional();
 int size = functional.getInputDimension(size);
 Vector x = constructInitialValue(size);
 double value;
 Vector gradient = null;
 Matrix hessian = null;
 while (/* condition */) {
     functional.setArgument(x);
     value = functional.value();
     gradient = functional.gradient(gradient);
     hessian = functional.hessian(hessian);
     // work with results, modify x appropriately
 }
 

Since:

1.0

Author:

Martin von Gagern

Method Summary

int	getInputDimension() Return the dimension of the input space.
no.uib.cipr.matrix.Vector	gradient(no.uib.cipr.matrix.Vector g) Calculate gradient.
no.uib.cipr.matrix.Matrix	hessian(no.uib.cipr.matrix.Matrix h) Calculate hessian.
void	setArgument(no.uib.cipr.matrix.Vector x) Set function arguments for subsequent calls.
double	value() Calculate function value.
double	valueChange() Calculate change in function value.

Method Detail

getInputDimension

int getInputDimension()

Return the dimension of the input space. This is the number of real argument values the functional takes as an input.

Returns:

the number of expected argument values

setArgument

void setArgument(no.uib.cipr.matrix.Vector x)

Set function arguments for subsequent calls.

Parameters:

x - the argument vecotor of the function

value

double value()

Calculate function value.

Calculates the function value at the position given by the most recent call to setArgument(Vector).

Returns:

the function value

Throws:

IllegalStateException - if there was no preceding call to setArgument

valueChange

double valueChange()

Calculate change in function value.

Calculates the difference between the function value at the position given by the most recent call to setArgument(Vector) and the function value returned by the last call to value().

Returns:

the function value

Throws:

IllegalStateException - if there was no preceding call to setArgument or value

gradient

no.uib.cipr.matrix.Vector gradient(no.uib.cipr.matrix.Vector g)

Calculate gradient.

Calculates the gradient of the function at the position given by the most recent call to setArgument(Vector).

The caller may provide a preallocated vector as an argument, and the implementation of the function may choose whether or not to use that object instead of allocating a new one. Passing null will cause the implementation to always allocate a suitable vector object. The caller is encouraged to pass the result of a previous invocation to reuse such objects.

Parameters:

g - a preallocated vector that may be used for the result

Returns:

the gradient of the function

Throws:

IllegalStateException - if there was no preceding call to setArgument

hessian

no.uib.cipr.matrix.Matrix hessian(no.uib.cipr.matrix.Matrix h)

Calculate hessian.

Calculates the function value at the position given by the most recent call to setArgument(Vector). The caller may provide a preallocated matrix as an argument, and the implementation of the function may choose whether or not to use that object instead of allocating a new one. Passing null will cause the implementation to always allocate a suitable matrix object. The caller is encouraged to pass the result of a previous invocation to reuse such objects.

Parameters:

h - a preallocated matrix that may be used for the result

Returns:

the hessian of the function

Throws:

IllegalStateException - if there was no preceding call to setArgument