esys.downunder.splitinversioncostfunctions Package¶
Classes¶
-
class
esys.downunder.splitinversioncostfunctions.
ArithmeticTuple
(*args)¶ Tuple supporting inplace update x+=y and scaling x=a*y where
x,y
is an ArithmeticTuple anda
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
-
__init__
(*args)¶ Initializes object with elements
args
.- Parameters
args – tuple of objects that support inplace add (x+=y) and scaling (x=a*y)
-
-
class
esys.downunder.splitinversioncostfunctions.
Data
¶ Represents a collection of datapoints. It is used to store the values of a function. For more details please consult the c++ class documentation.
-
__init__
((object)arg1) → None¶ __init__( (object)arg1, (object)value [, (object)p2 [, (object)p3 [, (object)p4]]]) -> None
-
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 inmask
will be copied fromother
-
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 processdataPointNo (int) – datapoint to access
-
hasInf
((Data)arg1) → bool :¶ Returns return true if data contains +-Inf. [Note that for complex values, hasNaN and hasInf are not mutually exclusive.]
-
hasNaN
((Data)arg1) → bool :¶ Returns return true if data contains NaN. [Note that for complex values, hasNaN and hasInf are not mutually exclusive.]
-
internal_maxGlobalDataPoint
((Data)arg1) → tuple :¶ Please consider using getSupLocator() from pdetools instead.
-
internal_minGlobalDataPoint
((Data)arg1) → tuple :¶ Please consider using getInfLocator() from pdetools instead.
-
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
- 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
interpolateTable( (Data)arg1, (object)table, (float)Amin, (float)Astep [, (float)undef=1e+50 [, (bool)check_boundaries=False]]) -> Data
-
isComplex
((Data)arg1) → bool :¶ - Return type
bool
- Returns
True if this
Data
stores complex values.
-
isConstant
((Data)arg1) → bool :¶ - Return type
bool
- Returns
True if this
Data
is an instance ofDataConstant
- 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.
-
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
-
promote
((Data)arg1) → None¶
-
replaceInf
((Data)arg1, (object)value) → None :¶ Replaces +-Inf values with value. [Note, for complex Data, both real and imaginary components are replaced even if only one part is Inf].
-
replaceNaN
((Data)arg1, (object)value) → None :¶ Replaces NaN values with value. [Note, for complex Data, both real and imaginary components are replaced even if only one part is NaN].
-
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
orlist
-
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
orlist
- 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.splitinversioncostfunctions.
ForwardModel
¶ An abstract forward model that can be plugged into a cost function. Subclasses need to implement
getDefect()
,getGradient()
, and possiblygetArguments()
and ‘getCoordinateTransformation’.-
__init__
()¶ Initialize self. See help(type(self)) for accurate signature.
-
getArguments
(x)¶
-
getCoordinateTransformation
()¶
-
getDefect
(x, *args)¶
-
getGradient
(x, *args)¶
-
-
class
esys.downunder.splitinversioncostfunctions.
FunctionJob
(fn, *args, **kwargs)¶ Takes a python function (with only self and keyword params) to be called as the work method
-
__init__
(fn, *args, **kwargs)¶ It ignores all of its parameters, except that, it requires the following as keyword arguments
- Variables
domain – Domain to be used as the basis for all
Data
and PDEs in this Job.jobid – sequence number of this job. The first job has id=1
-
work
()¶ Need to be overloaded for the job to actually do anthing. A return value of True indicates this job thinks it is done. A return value of False indicates work still to be done
-
-
class
esys.downunder.splitinversioncostfunctions.
Job
(*args, **kwargs)¶ Describes a sequence of work to be carried out in a subworld. The instances of this class used in the subworlds will be constructed by the system. To do specific work, this class should be subclassed and the work() (and possibly __init__ methods overloaded). The majority of the work done by the job will be in the overloaded work() method. The work() method should retrieve values from the outside using importValue() and pass values to the rest of the system using exportValue(). The rest of the methods should be considered off limits.
-
__init__
(*args, **kwargs)¶ It ignores all of its parameters, except that, it requires the following as keyword arguments
- Variables
domain – Domain to be used as the basis for all
Data
and PDEs in this Job.jobid – sequence number of this job. The first job has id=1
-
clearExports
()¶ Remove exported values from the map
-
clearImports
()¶ Remove imported values from their map
-
declareImport
(name)¶ Adds name to the list of imports
-
exportValue
(name, v)¶ Make value v available to other Jobs under the label name. name must have already been registered with the SplitWorld instance. For use inside the work() method.
- Variables
name – registered label for exported value
v – value to be imported
-
importValue
(name)¶ For use inside the work() method.
- Variables
name – label for imported value.
-
setImportValue
(name, v)¶ Use to make a value available to the job (ie called from outside the job)
- Variables
name – label used to identify this import
v – value to be imported
-
work
()¶ Need to be overloaded for the job to actually do anthing. A return value of True indicates this job thinks it is done. A return value of False indicates work still to be done
-
-
class
esys.downunder.splitinversioncostfunctions.
Mapping
(*args)¶ An abstract mapping class to map level set functions m to physical parameters p.
-
__init__
(*args)¶ Initialize self. See help(type(self)) for accurate signature.
-
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.splitinversioncostfunctions.
MeteredCostFunction
¶ 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.-
__init__
()¶ the base constructor initializes the counters so subclasses should ensure the super class constructor is called.
-
getArguments
(x)¶ returns precalculated values that are shared in the calculation of f(x) and grad f(x) and the Hessian operator
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 theCostFunction
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
andr
- 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
fromgetArguments()
- 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
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.
- Parameters
x (x-type) – location of Hessian operator to be evaluated.
r (r-type) – a given gradient
args – pre-calculated values for
x
fromgetArguments()
- Return type
x-type
-
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
-
resetCounters
()¶ resets all statistical counters
-
-
class
esys.downunder.splitinversioncostfunctions.
SplitInversionCostFunction
(numLevelSets=None, numModels=None, numMappings=None, splitworld=None, worldsinit_fn=None)¶ 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 3 (two forward models on 2-valued level set)
m0=Mapping() m1=Mapping() f0=ForwardModel() f1=ForwardModel()
J=InversionCostFunction(Regularization(self.numLevelSets=2), mappings=[(m0,0), (m1,0)], forward_models=[(f0, 0), (f1,1)])
- Note
If provides_inverse_Hessian_approximation is true, then the class provides an approximative inverse of the Hessian operator.
-
__init__
(numLevelSets=None, numModels=None, numMappings=None, splitworld=None, worldsinit_fn=None)¶ fill this in.
-
calculateGradient
(vnames1, vnames2)¶ The gradient operation produces two components (designated (Y^,X) in the non-split version). vnames1 gives the variable name(s) where the first component should be stored. vnames2 gives the variable name(s) where the second component should be stored.
-
static
calculatePropertiesHelper
(self, m, mappings)¶ returns a list of the physical properties from a given level set function m using the mappings of the cost function.
-
calculateValue
(vname)¶
-
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 themappings
arguments in the constructor. UseNone
for properties for which no value is given.
-
static
createLevelSetFunctionHelper
(self, regularization, mappings, *props)¶ Returns an object (init-ed) with 0s. Components can be overwritten by physical properties
props
. If present entries must correspond to themappings
arguments in the constructor. UseNone
for properties for which no value is given.
-
static
formatMappings
(mappings, numLevelSets)¶
-
static
formatModels
(forward_models, numMappings)¶
-
getComponentValues
(m, *args)¶
-
getDomain
()¶ returns the domain of the cost function
- Return type
Domain
-
getForwardModel
(idx=None)¶ returns the idx-th forward model.
- Parameters
idx (
int
) – model index. If cost function contains one model onlyidx
can be omitted.
-
static
getModelArgs
(self, fwdmodels)¶ Attempts to import the arguments for forward models, if they are not available, Computes and exports them
-
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.
-
getRegularization
()¶ returns the regularization
- Return type
Regularization
-
getTradeOffFactors
(mu=None)¶ returns a list of the trade-off factors.
- Return type
list
offloat
-
getTradeOffFactorsModels
()¶ returns the trade-off factors for the forward models
- Return type
float
orlist
offloat
-
provides_inverse_Hessian_approximation
= True¶
-
setPoint
()¶
-
setTradeOffFactors
(mu=None)¶ sets the trade-off factors for the forward model and regularization terms.
- Parameters
mu (
list
offloat
) – 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 alist
offloat
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
-
static
subworld_setMu_model
(self, **args)¶
-
updateHessian
()¶ notifies the class that the Hessian operator needs to be updated.
-
static
update_point_helper
(self, newpoint)¶ Call within a subworld to set ‘current_point’ to newpoint and update all the cached args info
Functions¶
-
esys.downunder.splitinversioncostfunctions.
inner
(arg0, arg1)¶ Inner product of the two arguments. The inner product is defined as:
out=Sigma_s arg0[s]*arg1[s]
where s runs through
arg0.Shape
.arg0
andarg1
must have the same shape.- Parameters
arg0 (
numpy.ndarray
,escript.Data
,Symbol
,float
,int
) – first argumentarg1 (
numpy.ndarray
,escript.Data
,Symbol
,float
,int
) – second argument
- Returns
the inner product of
arg0
andarg1
at each data point- Return type
numpy.ndarray
,escript.Data
,Symbol
,float
depending on the input- Raises
ValueError – if the shapes of the arguments are not identical
-
esys.downunder.splitinversioncostfunctions.
updateHessianWorker
(self, **kwargs)¶