Package de.labathome.trustconstr

Class ScalarFunction.ScalarFunctionFactory

java.lang.Object

de.labathome.trustconstr.ScalarFunction.ScalarFunctionFactory

Enclosing class:

ScalarFunction

public static class ScalarFunction.ScalarFunctionFactory
extends Object

Builder for ScalarFunction.

Constructor Summary

Constructors

Constructor	Description
ScalarFunctionFactory()	Default-construct an empty factory.

Method Summary

Modifier and Type	Method	Description
ScalarFunction.ScalarFunctionFactory	args(Object args)	Provide any additional fixed parameters needed to specify the scalar function (the args argument forwarded to fun/grad/hess).
ScalarFunction	build()
ScalarFunction.ScalarFunctionFactory	epsilon(Matrix epsilon)	Absolute step size for FD gradient/Hessian, taking precedence over the relative step.
ScalarFunction.ScalarFunctionFactory	finiteDiffBounds(FiniteDifferenceBounds finiteDiffBounds)	Bounds within which FD perturbations must stay.
ScalarFunction.ScalarFunctionFactory	finiteDiffRelStep(Matrix finiteDiffRelStep)	Per-component relative step size for the FD gradient/Hessian.
ScalarFunction.ScalarFunctionFactory	fun(ToDoubleBiFunction<Matrix,Object> fun)	Set the objective function to optimize.
ScalarFunction.ScalarFunctionFactory	grad(FiniteDifferenceMethod grad)	Compute the gradient by finite differences instead of analytically.
ScalarFunction.ScalarFunctionFactory	grad(BiFunction<Matrix,Object,Matrix> grad)	Provide an analytic gradient grad(x, args) -> gradf(x).
ScalarFunction.ScalarFunctionFactory	hess(FiniteDifferenceMethod hess)	Compute the Hessian by finite differences instead of analytically.
ScalarFunction.ScalarFunctionFactory	hess(HessianUpdateStrategy hess)	Approximate the Hessian via a quasi-Newton update strategy (e.g.
ScalarFunction.ScalarFunctionFactory	hess(BiFunction<Matrix,Object,Matrix> hess)	Provide an analytic Hessian hess(x, args) -> grad^2f(x).
ScalarFunction.ScalarFunctionFactory	x0(Matrix x0)	Provide the initial point for evaluating fun.

Methods inherited from class java.lang.Object

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

Constructor Details

ScalarFunctionFactory

public ScalarFunctionFactory()

Default-construct an empty factory.

Method Details

fun

public ScalarFunction.ScalarFunctionFactory fun(ToDoubleBiFunction<Matrix,Object> fun)

Set the objective function to optimize.

Parameters:

fun - objective (x, args) -> f(x)

Returns:

this factory, for chaining

x0

public ScalarFunction.ScalarFunctionFactory x0(Matrix x0)

Provide the initial point for evaluating fun.

Parameters:

x0 - starting iterate (n x 1)

Returns:

this factory, for chaining

args

public ScalarFunction.ScalarFunctionFactory args(Object args)

Provide any additional fixed parameters needed to specify the scalar function (the args argument forwarded to fun/grad/hess).

Parameters:

args - fixed parameters (may be null)

Returns:

this factory, for chaining

grad

public ScalarFunction.ScalarFunctionFactory grad(BiFunction<Matrix,Object,Matrix> grad)

Provide an analytic gradient grad(x, args) -> gradf(x). Mutually exclusive with grad(FiniteDifferenceMethod).

Parameters:

grad - analytic gradient

Returns:

this factory, for chaining

Throws:

RuntimeException - if a gradient (analytic or FD) was already specified

grad

public ScalarFunction.ScalarFunctionFactory grad(FiniteDifferenceMethod grad)

Compute the gradient by finite differences instead of analytically. Mutually exclusive with grad(BiFunction).

Parameters:

grad - FD scheme to use

Returns:

this factory, for chaining

Throws:

RuntimeException - if a gradient was already specified

hess

public ScalarFunction.ScalarFunctionFactory hess(BiFunction<Matrix,Object,Matrix> hess)

Provide an analytic Hessian hess(x, args) -> grad^2f(x). Mutually exclusive with the FD and quasi-Newton overloads.

Parameters:

hess - analytic Hessian evaluator

Returns:

this factory, for chaining

Throws:

RuntimeException - if a Hessian was already specified

hess

public ScalarFunction.ScalarFunctionFactory hess(FiniteDifferenceMethod hess)

Compute the Hessian by finite differences instead of analytically. Note: cannot be combined with an FD gradient.

Parameters:

hess - FD scheme to use for the Hessian

Returns:

this factory, for chaining

Throws:

RuntimeException - if a Hessian was already specified

hess

public ScalarFunction.ScalarFunctionFactory hess(HessianUpdateStrategy hess)

Approximate the Hessian via a quasi-Newton update strategy (e.g. BFGS, SR1).

Parameters:

hess - Hessian-update strategy instance

Returns:

this factory, for chaining

Throws:

RuntimeException - if a Hessian was already specified

finiteDiffRelStep

public ScalarFunction.ScalarFunctionFactory finiteDiffRelStep(Matrix finiteDiffRelStep)

Per-component relative step size for the FD gradient/Hessian. The absolute step is h = relStep * sign(x0) * max(1, |x0|), clamped to finiteDiffBounds(FiniteDifferenceBounds). May be null to derive a default from machine epsilon.

Parameters:

finiteDiffRelStep - relative step size (n x 1); may be null

Returns:

this factory, for chaining

finiteDiffBounds

public ScalarFunction.ScalarFunctionFactory finiteDiffBounds(FiniteDifferenceBounds finiteDiffBounds)

Bounds within which FD perturbations must stay. Defaults to unbounded.

Parameters:

finiteDiffBounds - box bounds for FD perturbations

Returns:

this factory, for chaining

epsilon

public ScalarFunction.ScalarFunctionFactory epsilon(Matrix epsilon)

Absolute step size for FD gradient/Hessian, taking precedence over the relative step. May be null (use relative step instead).

Parameters:

epsilon - absolute step size (n x 1); may be null

Returns:

this factory, for chaining

build

public ScalarFunction build()

Returns:

a fully-configured ScalarFunction ready for use

Throws:

RuntimeException - if neither analytic nor FD gradient/Hessian was set