esys.downunder.splitregularizations Package

Classes

class esys.downunder.splitregularizations.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).

Note:The provides_inverse_Hessian_approximation class member should be set to True in subclasses that provide a valid implementation of getInverseHessianApproximation()
__init__()

Constructor. Initializes logger.

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.

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.

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.splitregularizations.SplitRegularization(domain, numLevelSets=1, w0=None, w1=None, wc=None, location_of_set_m=<esys.escriptcore.escriptcpp.Data object>, useDiagonalHessianApproximation=False, tol=1e-08, coordinates=None, scale=None, scale_c=None)

Bases: esys.downunder.costfunctions.CostFunction

The regularization term for the level set function m within the cost function J for an inversion:

J(m)=1/2 * sum_k integrate( mu[k] * ( w0[k] * m_k**2 * w1[k,i] * m_{k,i}**2) + sum_l<k mu_c[l,k] wc[l,k] * | curl(m_k) x curl(m_l) |^2

where w0[k], w1[k,i] and wc[k,l] are non-negative weighting factors and mu[k] and mu_c[l,k] are trade-off factors which may be altered during the inversion. The weighting factors are normalized such that their integrals over the domain are constant:

integrate(w0[k] + inner(w1[k,:],1/L[:]**2))=scale[k] volume(domain)* integrate(wc[l,k]*1/L**4)=scale_c[k] volume(domain) *

__init__(domain, numLevelSets=1, w0=None, w1=None, wc=None, location_of_set_m=<esys.escriptcore.escriptcpp.Data object>, useDiagonalHessianApproximation=False, tol=1e-08, coordinates=None, scale=None, scale_c=None)

initialization.

Parameters:
  • domain (Domain) – domain
  • numLevelSets (int) – number of level sets
  • w0 (Scalar if numLevelSets == 1 or Data object of shape (numLevelSets ,) if numLevelSets > 1) – weighting factor for the m**2 term. If not set zero is assumed.
  • w1 (Vector if numLevelSets == 1 or Data object of shape (numLevelSets , DIM) if numLevelSets > 1) – weighting factor for the grad(m_i) terms. If not set zero is assumed
  • wc (Data object of shape (numLevelSets , numLevelSets)) – weighting factor for the cross gradient terms. If not set zero is assumed. Used for the case if numLevelSets > 1 only. Only values wc[l,k] in the lower triangle (l<k) are used.
  • location_of_set_m (Scalar if numLevelSets == 1 or Data object of shape (numLevelSets ,) if numLevelSets > 1) – marks location of zero values of the level set function m by a positive entry.
  • useDiagonalHessianApproximation (bool) – if True cross gradient terms between level set components are ignored when calculating approximations of the inverse of the Hessian Operator. This can speed-up the calculation of the inverse but may lead to an increase of the number of iteration steps in the inversion.
  • tol (positive float) – tolerance when solving the PDE for the inverse of the Hessian Operator
  • coordinates (ReferenceSystem` or SpatialCoordinateTransformation) – defines coordinate system to be used
  • scale (Scalar if numLevelSets == 1 or Data object of shape (numLevelSets ,) if numLevelSets > 1) – weighting factor for level set function variation terms. If not set one is used.
  • scale_c (Data object of shape (numLevelSets,``numLevelSets``)) – scale for the cross gradient terms. If not set one is assumed. Used for the case if numLevelSets > 1 only. Only values scale_c[l,k] in the lower triangle (l<k) are used.
getArguments(m)
getCoordinateTransformation()

returns the coordinate transformation being used

Return type:CoordinateTransformation
getDomain()

returns the domain of the regularization term

Return type:Domain
getDualProduct(m, r)

returns the dual product of a gradient represented by X=r[1] and Y=r[0] with a level set function m:

Y_i*m_i + X_ij*m_{i,j}
Return type:float
getGradient()

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
getGradientAtPoint()

returns the gradient of the cost function J with respect to m.

Note:This implementation returns Y_k=dPsi/dm_k and X_kj=dPsi/dm_kj
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.
getInverseHessianApproximationAtPoint(r, solve=True)
getNorm(m)

returns the norm of m.

Parameters:m (Data) – level set function
Return type:float
getNumLevelSets()

returns the number of level set functions

Return type:int
getNumTradeOffFactors()

returns the number of trade-off factors being used.

Return type:int
getPDE()

returns the linear PDE to be solved for the Hessian Operator inverse

Return type:linearPDEs.LinearPDE
getValue(m, grad_m)

returns the value of the cost function J with respect to m. This equation is specified in the inversion cookbook.

Return type:float
getValueAtPoint()

returns the value of the cost function J with respect to m. This equation is specified in the inversion cookbook.

Return type:float
provides_inverse_Hessian_approximation = False
setPoint(m)

sets the point which this function will work with

Parameters:m (Data) – level set function
setTradeOffFactors(mu=None)

sets the trade-off factors for the level-set variation and the cross-gradient.

Parameters:mu (list of float or `numpy.array`) – new values for the trade-off factors where values mu[:numLevelSets] are the trade-off factors for the level-set variation and the remaining values for the cross-gradient part with mu_c[l,k]=mu[numLevelSets+l+((k-1)*k)/2] (l<k). If no values for mu are given ones are used. Values must be positive.
setTradeOffFactorsForCrossGradient(mu_c=None)

sets the trade-off factors for the cross-gradient terms.

Parameters:mu_c (float, list of float or numpy.array) – new values for the trade-off factors for the cross-gradient terms. Values must be positive. If no value is given ones are used. Only value mu_c[l,k] for l<k are used.
setTradeOffFactorsForVariation(mu=None)

sets the trade-off factors for the level-set variation part.

Parameters:mu (float, list of float or `numpy.array`) – new values for the trade-off factors. Values must be positive.
updateHessian()

notifies the class to recalculate the Hessian operator.

Functions

esys.downunder.splitregularizations.makeTransformation(domain, coordinates=None)

returns a SpatialCoordinateTransformation for the given domain

Parameters:
  • domain (esys.escript.AbstractDomain) – domain in the domain of the coordinate transformation
  • coordinates (ReferenceSystem or SpatialCoordinateTransformation) – the reference system or spatial coordinate system.
Returns:

the spatial coordinate system for the given domain of the specified reference system coordinates. If coordinates is already spatial coordinate system based on the riven domain coordinates is returned. Otherwise an appropriate spatial coordinate system is created.
Return type:

SpatialCoordinateTransformation

Others

Packages