esys.downunder.inversioncostfunctions Package

Classes

class esys.downunder.inversioncostfunctions.ArithmeticTuple(*args)

Bases: object

Tuple supporting inplace update x+=y and scaling x=a*y where x,y is an ArithmeticTuple and a is a float.

Example of usage:

from esys.escript import Data
from numpy import array
a=eData(...)
b=array([1.,4.])
x=ArithmeticTuple(a,b)
y=5.*x
class esys.downunder.inversioncostfunctions.Data

Bases: Boost.Python.instance

Represents a collection of datapoints. It is used to store the values of a function. For more details please consult the c++ class documentation.

copy((Data)arg1, (Data)other) → None :

Make this object a copy of other

note:The two objects will act independently from now on. That is, changing other after this call will not change this object and vice versa.
copy( (Data)arg1) -> Data :
note:In the no argument form, a new object will be returned which is an independent copy of this object.
copyWithMask((Data)arg1, (Data)other, (Data)mask) → None :

Selectively copy values from other Data.Datapoints which correspond to positive values in mask will be copied from other

Parameters:
  • other (Data) – source of values
  • mask (Scalar Data) –
delay((Data)arg1) → Data :

Convert this object into lazy representation

dump((Data)arg1, (str)fileName) → None :

Save the data as a netCDF file

Parameters:fileName (string) –
expand((Data)arg1) → None :

Convert the data to expanded representation if it is not expanded already.

getDomain((Data)arg1) → Domain :
Return type:Domain
getFunctionSpace((Data)arg1) → FunctionSpace :
Return type:FunctionSpace
getNumberOfDataPoints((Data)arg1) → int :
Return type:int
Returns:Number of datapoints in the object
getRank((Data)arg1) → int :
Returns:the number of indices required to address a component of a datapoint
Return type:positive int
getShape((Data)arg1) → tuple :

Returns the shape of the datapoints in this object as a python tuple. Scalar data has the shape ()

Return type:tuple
getTagNumber((Data)arg1, (int)dpno) → int :

Return tag number for the specified datapoint

Return type:int
Parameters:dpno (int) – datapoint number
getTupleForDataPoint((Data)arg1, (int)dataPointNo) → object :
Returns:Value of the specified datapoint
Return type:tuple
Parameters:dataPointNo (int) – datapoint to access
getTupleForGlobalDataPoint((Data)arg1, (int)procNo, (int)dataPointNo) → object :

Get a specific datapoint from a specific process

Return type:

tuple

Parameters:
  • procNo (positive int) – MPI rank of the process
  • dataPointNo (int) – datapoint to access
interpolate((Data)arg1, (FunctionSpace)functionspace) → Data :

Interpolate this object’s values into a new functionspace.

interpolateTable((Data)arg1, (object)table, (float)Amin, (float)Astep, (Data)B, (float)Bmin, (float)Bstep[, (float)undef=1e+50[, (bool)check_boundaries=False]]) → Data :

Creates a new Data object by interpolating using the source data (which are looked up in table) A must be the outer dimension on the table

param table:two dimensional collection of values
param Amin:The base of locations in table
type Amin:float
param Astep:size of gap between each item in the table
type Astep:float
param undef:upper bound on interpolated values
type undef:float
param B:Scalar representing the second coordinate to be mapped into the table
type B:Data
param Bmin:The base of locations in table for 2nd dimension
type Bmin:float
param Bstep:size of gap between each item in the table for 2nd dimension
type Bstep:float
param check_boundaries:
 if true, then values outside the boundaries will be rejected. If false, then boundary values will be used.
raise RuntimeError(DataException):
 if the coordinates do not map into the table or if the interpolated value is above undef
rtype:Data

interpolateTable( (Data)arg1, (object)table, (float)Amin, (float)Astep [, (float)undef=1e+50 [, (bool)check_boundaries=False]]) -> Data

isConstant((Data)arg1) → bool :
Return type:bool
Returns:True if this Data is an instance of DataConstant
Note :This does not mean the data is immutable.
isEmpty((Data)arg1) → bool :

Is this object an instance of DataEmpty

Return type:bool
Note :This is not the same thing as asking if the object contains datapoints.
isExpanded((Data)arg1) → bool :
Return type:bool
Returns:True if this Data is expanded.
isLazy((Data)arg1) → bool :
Return type:bool
Returns:True if this Data is lazy.
isProtected((Data)arg1) → bool :

Can this instance be modified. :rtype: bool

isReady((Data)arg1) → bool :
Return type:bool
Returns:True if this Data is not lazy.
isTagged((Data)arg1) → bool :
Return type:bool
Returns:True if this Data is expanded.
maxGlobalDataPoint((Data)arg1) → tuple :

Please consider using getSupLocator() from pdetools instead.

minGlobalDataPoint((Data)arg1) → tuple :

Please consider using getInfLocator() from pdetools instead.

nonuniformInterpolate((Data)arg1, (object)in, (object)out, (bool)check_boundaries) → Data :

1D interpolation with non equally spaced points

nonuniformSlope((Data)arg1, (object)in, (object)out, (bool)check_boundaries) → Data :

1D interpolation of slope with non equally spaced points

resolve((Data)arg1) → None :

Convert the data to non-lazy representation.

setProtection((Data)arg1) → None :

Disallow modifications to this data object

Note :This method does not allow you to undo protection.
setTaggedValue((Data)arg1, (int)tagKey, (object)value) → None :

Set the value of tagged Data.

param tagKey:tag to update
type tagKey:int
setTaggedValue( (Data)arg1, (str)name, (object)value) -> None :
param name:tag to update
type name:string
param value:value to set tagged data to
type value:object which acts like an array, tuple or list
setToZero((Data)arg1) → None :

After this call the object will store values of the same shape as before but all components will be zero.

setValueOfDataPoint((Data)arg1, (int)dataPointNo, (object)value) → None

setValueOfDataPoint( (Data)arg1, (int)arg2, (object)arg3) -> None

setValueOfDataPoint( (Data)arg1, (int)arg2, (float)arg3) -> None :

Modify the value of a single datapoint.

param dataPointNo:
 
type dataPointNo:
 int
param value:
type value:float or an object which acts like an array, tuple or list
warning:Use of this operation is discouraged. It prevents some optimisations from operating.
tag((Data)arg1) → None :

Convert data to tagged representation if it is not already tagged or expanded

toListOfTuples((Data)arg1[, (bool)scalarastuple=False]) → object :

Return the datapoints of this object in a list. Each datapoint is stored as a tuple.

Parameters:scalarastuple – if True, scalar data will be wrapped as a tuple. True => [(0), (1), (2)]; False => [0, 1, 2]
class esys.downunder.inversioncostfunctions.ForwardModel

Bases: object

An abstract forward model that can be plugged into a cost function. Subclasses need to implement getValue(), getGradient(), and possibly getArguments().

getArguments(x)
getGradient(x, *args)
getValue(x, *args)
class esys.downunder.inversioncostfunctions.InversionCostFunction(regularization, mappings, forward_models)

Bases: esys.downunder.costfunctions.MeteredCostFunction

Class to define cost function J(m) for inversion with one or more forward models based on a multi-valued level set function m:

J(m) = J_reg(m) + sum_f mu_f * J_f(p)

where J_reg(m) is the regularization and cross gradient component of the cost function applied to a level set function m, J_f(p) are the data defect cost functions involving a physical forward model using the physical parameter(s) p and mu_f is the trade-off factor for model f.

A forward model depends on a set of physical parameters p which are constructed from components of the level set function m via mappings.

Example 1 (single forward model):
m=Mapping() f=ForwardModel() J=InversionCostFunction(Regularization(), m, f)
Example 2 (two forward models on a single valued level set)

m0=Mapping() m1=Mapping() f0=ForwardModel() f1=ForwardModel()

J=InversionCostFunction(Regularization(), mappings=[m0, m1], forward_models=[(f0, 0), (f1,1)])

Example 2 (two forward models on 2-valued level set)

m0=Mapping() m1=Mapping() f0=ForwardModel() f1=ForwardModel()

J=InversionCostFunction(Regularization(numLevelSets=2), mappings=[(m0,0), (m1,0)], forward_models=[(f0, 0), (f1,1)])

Variables:provides_inverse_Hessian_approximation – if true the class provides an approximative inverse of the Hessian operator.
createLevelSetFunction(*props)

returns an instance of an object used to represent a level set function initialized with zeros. Components can be overwritten by physical properties props. If present entries must correspond to the mappings arguments in the constructor. Use None for properties for which no value is given.

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

returns the domain of the cost function :rtype: ‘Domain`

getDualProduct(x, r)

returns the dual product of x and r

Return type:float
getForwardModel(idx=None)

returns the idx-th forward model.

Parameters:idx (int) – model index. If cost function contains one model only idx can be omitted.
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
getNumTradeOffFactors()

returns the number of trade-off factors being used including the trade-off factors used in the regularization component.

Return type:int
getProperties(m, return_list=False)

returns a list of the physical properties from a given level set function m using the mappings of the cost function.

Parameters:
  • m (Data) – level set function
  • return_list (bool) – if True a list is returned.
Return type:

list of Data

getRegularization()

returns the regularization

Return type:Regularization
getTradeOffFactors(mu=None)

returns a list of the trade-off factors.

Return type:list of float
getTradeOffFactorsModels()

returns the trade-off factors for the forward models

Return type:float or list of 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 = True
resetCounters()

resets all statistical counters

setTradeOffFactors(mu=None)

sets the trade-off factors for the forward model and regularization terms.

Parameters:mu (list of float) – list of trade-off factors.
setTradeOffFactorsModels(mu=None)

sets the trade-off factors for the forward model components.

Parameters:mu (float in case of a single model or a list of float with the length of the number of models.) – list of the trade-off factors. If not present ones are used.
setTradeOffFactorsRegularization(mu=None, mu_c=None)

sets the trade-off factors for the regularization component of the cost function, see Regularization for details.

Parameters:
  • mu – trade-off factors for the level-set variation part
  • mu_c – trade-off factors for the cross gradient variation part
updateHessian()

notifies the class that the Hessian operator needs to be updated.

class esys.downunder.inversioncostfunctions.Mapping(*args)

Bases: object

An abstract mapping class to map level set functions m to physical parameters p.

getDerivative(m)

returns the value for the derivative of the mapping for m

getInverse(s)

returns the value of the inverse of the mapping for physical parameter p

getTypicalDerivative()

returns a typical value for the derivative

getValue(m)

returns the value of the mapping for m

class esys.downunder.inversioncostfunctions.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__