esys.downunder.costfunctions Package

Classes

class esys.downunder.costfunctions.CostFunction

Bases: object

A function f(x) that can be minimized (base class).

Example of usage:

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

The class distinguishes between the representation of the solution x (x-type) and the gradients (r-type).

Variables:provides_inverse_Hessian_approximation – This member should be set to True in subclasses that provide a valid implementation of getInverseHessianApproximation()
getArguments(x)

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

Parameters:x (x-type) – location of derivative
Return type:tuple
getDualProduct(x, r)

returns the dual product of x and r

Return type:float
getGradient(x, *args)

returns the gradient of f at x using the precalculated values for x.

Parameters:
  • x (x-type) – location of derivative
  • args – pre-calculated values for x from getArguments()
Return type:

r-type

getInverseHessianApproximation(x, r, *args)

returns an approximative evaluation p of the inverse of the Hessian operator of the cost function for a given gradient r at a given location x: H(x) p = r

Parameters:
  • x (x-type) – location of Hessian operator to be evaluated
  • r (r-type) – a given gradient
  • args – pre-calculated values for x from getArguments()
Return type:

x-type

Note :

In general it is assumed that the Hessian H(x) needs to be calculated in each call for a new location x. However, the solver may suggest that this is not required, typically when the iteration is close to completeness.

Note :

Subclasses that implement this method should set the class variable provides_inverse_Hessian_approximation to True to enable the solver to call this method.

getNorm(x)

returns the norm of x

Return type:float
getValue(x, *args)

returns the value f(x) using the precalculated values for x.

Parameters:x (x-type) – a solution approximation
Return type:float
provides_inverse_Hessian_approximation = False
updateHessian()

notifies the class that the Hessian operator needs to be updated. This method is called by the solver class.

class esys.downunder.costfunctions.MeteredCostFunction

Bases: esys.downunder.costfunctions.CostFunction

This an intrumented version of the CostFunction class. The function calls update statistical information. The actual work is done by the methods with corresponding name and a leading underscore. These functions need to be overwritten for a particular cost function implementation.

getArguments(x)

returns precalculated values that are shared in the calculation of f(x) and grad f(x) and the Hessian operator

Parameters:x (x-type) – location of derivative
getDualProduct(x, r)

returns the dual product of x and r

Return type:float
getGradient(x, *args)

returns the gradient of f at x using the precalculated values for x.

Parameters:
  • x (x-type) – location of derivative
  • args – pre-calculated values for x from getArguments()
Return type:

r-type

getInverseHessianApproximation(x, r, *args)

returns an approximative evaluation p of the inverse of the Hessian operator of the cost function for a given gradient r at a given location x: H(x) p = r

Parameters:
  • x (x-type) – location of Hessian operator to be evaluated.
  • r (r-type) – a given gradient
  • args – pre-calculated values for x from getArguments()
Return type:

x-type

Note :

In general it is assumed that the Hessian H(x) needs to be calculate in each call for a new location x. However, the solver may suggest that this is not required, typically when the iteration is close to completeness.

getNorm(x)

returns the norm of x

Return type:float
getValue(x, *args)

returns the value f(x) using the precalculated values for x.

Parameters:x (x-type) – a solution approximation
Return type:float
provides_inverse_Hessian_approximation = False
resetCounters()

resets all statistical counters

updateHessian()

notifies the class that the Hessian operator needs to be updated. This method is called by the solver class.

Functions

Others

  • __all__
  • __builtins__
  • __copyright__
  • __doc__
  • __file__
  • __license__
  • __name__
  • __package__
  • __url__