esys.escript.costfunctions Package

General cost functions for minimization

Classes

class esys.escript.costfunctions.CostFunction

A cost function F(m) that can be minimized (base class). Near a solution m in the search space the cost function is approximated in direction p as

F(m+p) ~ F(m) + <grad F(m), p> + < H p, p>

where F(m) is the value of the function at m, grad F is the gradient, H is the Hessian and <.,.> is dual product. These four procedures are defined in this class.

The class distinguishes between the representation of the solution m (m-type) and the cost function gradient (g-type).

Example of usage:

# class DerivedCostFunction(CostFunction)

# overwrite: getArguments, etc.

cf=DerivedCostFunction() # … calculate m … args=cf.getArguments(m) # this could be potentially expensive! f=cf.getValue(m, *args) # … it could be required to update m without using the gradient… # … but then … gf=cf.getGradient(m, *args)

Use the “AndCount” versions (e.g. getValueAndCount) if you want to count calls.

__init__()

Constructor. Initializes logger.

getArguments(m)

returns precalculated values that are shared in the calculation of F(m) and grad F(m) and the Hessian operator.

Note:

Overwrite this method to implement a cost function.

Note:

The tuple returned by this call will be passed back to this CostFunction in other calls(eg: getGradientAndCount). Its contents are not specified at this level because no code, other than the CostFunction which created it, will be interacting with it. That is, the implementor can put whatever information they find useful in it.

Parameters:

m (m-type) – location of derivative

Returns:

pre-calculated arguments

Return type:

tuple

Note:

Overwrite this method to implement a cost function.

getArgumentsAndCount(m)

returns precalculated values that are shared in the calculation of F(m) and grad F(m) and the Hessian operator. The default implementation returns an empty tuple.

When calling this method the calling statistics is updated.

Parameters:

m (m-type) – location of derivative

Return type:

tuple

Note:

The tuple returned by this call will be passed back to this CostFunction in other calls (eg: getGradient). Its contents are not specified at this level because no code, other than the CostFunction which created it, will be interacting with it. That is, the implementor can put whatever information they find useful in it.

getDualProduct(m, r)

returns the dual product of m and r

Return type:

float

Note:

Overwrite this method to implement a cost function.

getDualProductAndCount(m, r)

returns the dual product <.,.> of r and m.

When calling this method the calling statistics is updated.

Return type:

float

getGradient(m, *args)

returns the gradient of F at m using the precalculated values for m.

Parameters:
Return type:

g-type

Note:

Overwrite this method to implement a cost function.

getGradientAndCount(m, *args)

returns the gradient of F at m using the precalculated values for m.

When calling this method the calling statistics is updated.

Parameters:
Return type:

g-type

getInverseHessianApproximation(r, m, *args, initializeHessian=True)

returns an approximate evaluation p of the inverse of the Hessian operator of the cost function for a given gradient r: H p = r :note: by default this method is returning r. In this case it is assumed that m-type==g-type :note: Overwrite this method to implement a cost function.

Parameters:

r (g-type) – a given gradient

Poram initializeHessian:

indicates if the Hessian operator should be initialized using m. If this method provides an approximation only and building the new Hessian approximation is expensive it is typically more efficient to update the Hessian operator occasionally only when on input initializeHessian is True. If the Hessian should be updated in each step ignore the value of initializeHessian.

Returns:

new search direction p.

Return type:

m-type

getInverseHessianApproximationAndCount(r, m, *args, initializeHessian=True)

returns an evaluation p of the inverse of the Hessian operator of the cost function for a given gradient r: H p = r

When calling this method the calling statistics is updated.

Parameters:
Poram initializeHessian:

indicates if the Hessian operator should be initialized using m. If updating the Hessian is expensive it should only be done when initializeHessian is True. If this method provides an approximation only and building the new Hessian approximation is expensive it is typically more efficient to update the Hessian operator occasionally.

Returns:

new search direction p.

Return type:

m-type

getNorm(m)

returns the norm of m. Typically, this is the ‘Lsup’ function.

Return type:

float

Note:

Overwrite this method to implement a cost function.

getNormAndCount(m)

returns the norm of m.

When calling this method the calling statistics is updated.

Return type:

float

getSqueezeFactor(m, p, *args)

The new solution is calculated as m+a*p with a>0. This function allows to provide an upper bound for a to make sure that m+a*p is valid typically to avoid overflow when the cost function is evaluated. the solver will take action to make sure that the value of a is not too small.

Parameters:

  • m (m-type) – a solution approximation

  • p – an increment to the solution

  • args – pre-calculated values for m from getArgumentsAndCount()

Return type:

positive float or None

Note:

Overwrite this method to implement a cost function.

getStatistics()

return the call statistics as a string:

getValue(m, *args)

returns the value F(m) using the precalculated values for m.

Parameters:
Return type:

float or valid argument for sum

Note:

Overwrite this method to implement a cost function.

getValueAndCount(m, *args)

returns the value F(m) using the precalculated values for m.

When calling this method the calling statistics is updated.

Parameters:
Return type:

float or valid argument for sum

resetStatistics()

resets all counters

Functions

Others

Packages