pygimli.frameworks

Unified and method independent inversion frameworks.

Overview

Functions

fit(funct, data[, err])	Generic function fitter.
harmfit(y[, x, error, nc, resample, lam, …])	HARMFIT - GIMLi based curve-fit by harmonic functions
harmfitNative(y[, x, nc, xc, err])	python based curve-fit by harmonic functions yc = harmfitNativ(x,y[,nc,xc,err]) y ..

Classes

Block1DInversion([fop])	ivar ~Block1DInversion.nLayers
Block1DModelling([nPara, nLayers])	General forward operator for 1D layered models.
HarmFunctor(A, coeff, xmin, xSpan)
Inversion([fop, inv])	Basic inversion framework.
JointModelling(fopList)	Cumulative (joint) forward operator.
JointPetroInversionManager(petros, mgrs)
LCInversion([fop])	2D Laterally constrained inversion LCI framework.
LCModelling(fop, **kwargs)	2D Laterally constrained (LC) modelling.
MarquardtInversion([fop])	Marquardt scheme (local damping with decreasing regularization strength
MeshMethodManager(**kwargs)
MeshModelling(**kwargs)
MethodManager([fop, fw, data])	General manager to maintenance a measurement method.
MethodManager1d([fop])	Method Manager base class for managers on a 1d discretization.
Modelling(**kwargs)	Abstract Forward Operator.
ParameterInversionManager([funct, fop])	Framework to invert unconstrained parameters.
ParameterModelling([funct])	Model with symbolic parameter names instead of numbers
PetroInversionManager(petro[, mgr])
PetroModelling(fop, petro, **kwargs)	Combine petrophysical relation with the modelling class f(p).

Functions

fit

pygimli.frameworks.fit(funct, data, err=None, **kwargs)

Generic function fitter.

Fit data to a given function.

Parameters

• funct (callable) – Function with the first argmument as data space, e.g., x, t, f, Nr. .. Any following arguments are the parameters to be fit. Except a verbose flag if used.

• data (iterable (float)) – Data values

• err (iterable (float) [None]) – Data error values in %/100. Default is 1% if None are given.

Other Parameters

*dataSpace* (iterable) – Keyword argument of the data space of len(data). The name need to fit the first argument of funct.

Returns

• model (array) – Fitted model parameter.

• response (array) – Model response.

Example

>>> import pygimli as pg
>>>
>>> func = lambda t, a, b: a*np.exp(b*t)
>>> t = np.linspace(1, 2, 20)
>>> data = func(t, 1.1, 2.2)
>>> model, response = pg.frameworks.fit(func, data, t=t)
>>> print(pg.core.round(model, 1e-5))
2 [1.1, 2.2]
>>> _ = pg.plt.plot(t, data, 'o', label='data')
>>> _ = pg.plt.plot(t, response, label='response')
>>> _ = pg.plt.legend()

harmfit

pygimli.frameworks.harmfit(y, x=None, error=None, nc=42, resample=None, lam=0.1, window=None, verbose=False, dosave=False, lineSearch=True, robust=False, maxiter=20)

HARMFIT - GIMLi based curve-fit by harmonic functions

Parameters

• y (1d-array - values to be fitted) –

• x (1d-array(len(y)) - data abscissa data. default: [0 .. len(y))) –

• error (1d-array(len(y)) error of y. default (absolute error = 0.01)) –

• nc (int - Number of harmonic coefficients) –

• resample (1d-array - resample y to x using fitting coeffients) –

• window (int - just fit data inside window bounds) –

Returns

• response (1d-array(len(resample) or len(x)) - smoothed values)

• coefficients (1d-array - fitting coefficients)

harmfitNative

pygimli.frameworks.harmfitNative(y, x=None, nc=None, xc=None, err=None)

python based curve-fit by harmonic functions yc = harmfitNativ(x,y[,nc,xc,err]) y .. values of a curve to be fitted x .. abscissa, if none [0..len(y)) nc .. number of coefficients xc .. abscissa to fit on (otherwise equal to x) err .. data error

Classes

Block1DInversion

class pygimli.frameworks.Block1DInversion(fop=None, **kwargs)

Bases: pygimli.frameworks.inversion.MarquardtInversion

Variables

nLayers (int) –

__init__(fop=None, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

fixLayers(fixLayers)

Fix layer thicknesses.

Parameters

fixLayers (bool | [float]) – Fix all layers to the last value or set the fix layer thickness for all layers

run(dataVals, errorVals, nLayers=None, fixLayers=None, layerLimits=None, paraLimits=None, **kwargs)

Parameters

• nLayers (int [4]) – Number of layers.

• fixLayers (bool | [thicknesses]) – See: pygimli.modelling.Block1DInversion.fixLayers For fixLayers=None, preset or defaults are uses.

• layerLimits ([min, max]) – Limits the thickness off all layers. For layerLimits=None, preset or defaults are uses.

• paraLimits ([min, max] | [[min, max],..]) – Limits the range of the model parameter. If you have multiple parameters you can set them with a list of limits.

• **kwargs – Forwarded to the parent class. See: pygimli.modelling.MarquardtInversion

setForwardOperator(fop)

setLayerLimits(limits)

Set min and max layer thickness.

Parameters

limits (False | [min, max]) –

setParaLimits(limits)

Set the limits for each parameter region.

Block1DModelling

class pygimli.frameworks.Block1DModelling(nPara=1, nLayers=4, **kwargs)

Bases: pygimli.frameworks.modelling.Modelling

General forward operator for 1D layered models.

Model space: [thickness_i, parameter_jk], with i = 0 - nLayers-1, j = (0 .. nLayers), k=(0 .. nPara)

__init__(nPara=1, nLayers=4, **kwargs)

Constructor

Parameters

• nLayers (int [4]) – Number of layers.

• nPara (int [1]) – Number of parameters per layer (e.g. nPara=2 for resistivity and phase)

drawData(ax, data, err=None, label=None, **kwargs)

Default data view.

Modelling creates the data and should know best how to draw them.

Probably ugly and you should overwrite it in your derived forward operator.

drawModel(ax, model, **kwargs)

initModelSpace(nLayers)

Set number of layers for the 1D block model

property nLayers

property nPara

HarmFunctor

class pygimli.frameworks.HarmFunctor(A, coeff, xmin, xSpan)

Bases: object

__init__(A, coeff, xmin, xSpan)

Initialize self. See help(type(self)) for accurate signature.

Inversion

class pygimli.frameworks.Inversion(fop=None, inv=None, **kwargs)

Bases: object

Basic inversion framework.

Changes to prior Versions (remove me)

• holds the starting model itself, fop only provide a creator for SM

fop.createStartModel(dataValues)

Variables

• verbose (bool) – Give verbose output

• debug (bool) – Give debug output

• startModel (array) – Holds the current starting model

• model (array) – Holds the last active model

• maxIter (int [20]) – Maximal interation number.

• stopAtChi1 (bool [True]) – Stop iteration when chi² is one. If set to false the iteration stops after maxIter or convergence reached (self.inv.deltaPhiAbortPercent())

__init__(fop=None, inv=None, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

chi2(response=None)

property dataErrs

property dataTrans

property dataVals

property debug

echoStatus()

property errorVals

property fop

property inv

property maxIter

property minDPhi

property model

The last active model.

property modelTrans

property parameterCount

phi(model=None, response=None)

phiData(response=None)

phiModel(model=None)

relrms()

Relative root-mean-square misfit.

reset()

property response

property robustData

run(dataVals, errorVals, **kwargs)

Run inversion.

The inversion will always start from the starting model taken from the forward operator. If you want to run the inversion from a specified prior model, e.g., from a other run, set this model as starting model to the FOP (fop.setStartModel). Any self.inv.setModel() settings will be overwritten.

Parameters

• dataVals (iterable) – Data values

• errorVals (iterable) – Relative error values. dv / v

Keyword Arguments

• maxIter (int) – Overwrite class settings for maximal iterations number.

• dPhi (float [1]) – Overwrite class settings for delta data phi aborting criteria. Default is 1%

setData(data)

setDeltaChiStop(it)

setForwardOperator(fop)

setPostStep(p)

setPreStep(p)

showProgress(style='all')

Called if showProgress=True is set for the inversion run.

TODO

*Discuss .. its a useful function but breaks a little

the FrameWork work only concept.

property startModel

Gives the current default starting model.

Returns the current default starting model or call fop.createStartmodel() if non is defined.

property stopAtChi1

property verbose

JointModelling

class pygimli.frameworks.JointModelling(fopList)

Bases: pygimli.frameworks.modelling.MeshModelling

Cumulative (joint) forward operator.

__init__(fopList)

Initialize with lists of forward operators

createJacobian(model)

Fill the individual Jacobian matrices.

createStartModel(data)

Use inverse transformation to get m(p) for the starting model.

response(model)

Concatenate responses for all fops.

setData(data)

Distribute list of data to the forward operators

setMesh(mesh, **kwargs)

Set the parameter mesh to all fops

JointPetroInversionManager

class pygimli.frameworks.JointPetroInversionManager(petros, mgrs)

Bases: pygimli.frameworks.methodManager.MeshMethodManager

__init__(petros, mgrs)

Initialize with lists of managers and transformations

checkData(data)

Collect data values.

checkError(err, data=None)

Collect error values.

invert(data, **kwargs)

Run inversion

LCInversion

class pygimli.frameworks.LCInversion(fop=None, **kwargs)

Bases: pygimli.frameworks.inversion.Inversion

2D Laterally constrained inversion LCI framework.

__init__(fop=None, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

prepare(dataVals, errorVals, nLayers=4, **kwargs)

run(dataVals, errorVals, nLayers=4, **kwargs)

Run inversion.

The inversion will always start from the starting model taken from the forward operator. If you want to run the inversion from a specified prior model, e.g., from a other run, set this model as starting model to the FOP (fop.setStartModel). Any self.inv.setModel() settings will be overwritten.

Parameters

• dataVals (iterable) – Data values

• errorVals (iterable) – Relative error values. dv / v

Keyword Arguments

• maxIter (int) – Overwrite class settings for maximal iterations number.

• dPhi (float [1]) – Overwrite class settings for delta data phi aborting criteria. Default is 1%

LCModelling

class pygimli.frameworks.LCModelling(fop, **kwargs)

Bases: pygimli.frameworks.modelling.Modelling

2D Laterally constrained (LC) modelling.

2D Laterally constrained (LC) modelling based on BlockMatrices.

__init__(fop, **kwargs)

Parameters: fop class .

createDefaultStartModel(models)

Create the default startmodel as the median of the data values.

createJacobian(par)

Create Jacobian matrix by creating individual Jacobians.

createParametrization(nSoundings, nLayers=4, nPar=1)

Create LCI mesh and suitable constraints informations.

Parameters

• nLayers (int) – Numbers of depth layers

• nSoundings (int) – Numbers of 1D measurements to laterally constrain

• nPar (int) – Numbers of independent parameter types, e.g., nPar = 1 for VES (invert for resisitivies), nPar = 2 for VESC (invert for resisitivies and phases)

drawModel(ax, model, **kwargs)

initJacobian(dataVals, nLayers, nPar=None)

Parameters

dataVals (ndarray | RMatrix | list) – Data values of size (nSounding x Data per sounding). All data per sounding need to be equal in length. If they don’t fit into a matrix use list of sounding data.

initModelSpace(nLayers)

API

response(par)

Cut together forward responses of all soundings.

setDataBasis(**kwargs)

Set homogeneous data basis.

Set a common data basis to all forward operators. If you want individual you need to set them manually.

MarquardtInversion

class pygimli.frameworks.MarquardtInversion(fop=None, **kwargs)

Bases: pygimli.frameworks.inversion.Inversion

Marquardt scheme (local damping with decreasing regularization strength

__init__(fop=None, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

run(dataVals, errorVals, **kwargs)

Parameters

**kwargs – Forwarded to the parent class. See: pygimli.modelling.Inversion

MeshMethodManager

class pygimli.frameworks.MeshMethodManager(**kwargs)

Bases: pygimli.frameworks.methodManager.MethodManager

__init__(**kwargs)

Constructor.

applyData(data)

applyMesh(mesh, ignoreRegionManager=False, **kwargs)

coverage()

Return coverage vector considering the logarithmic transformation.

createMesh(data=None, **kwargs)

API, implement in derived classes.

invert(data=None, mesh=None, zWeight=1.0, startModel=None, **kwargs)

Run the full inversion.

Parameters

• data (pg.DataContainer) –

• mesh (pg.Mesh [None]) –

• zWeight (float [1.0]) –

• startModel (float | iterable [None]) – If set to None fop.createDefaultStartModel(dataValues) is called.

Keyword Arguments

to Inversion.run (forwarded) –

Returns

model – Model mapped for match the paraDomain Cell markers. The calculated model is in self.fw.model.

Return type

array

property paraDomain

paraModel(model=None)

Give the model parameter regarding the parameter mesh.

showFit(axs=None, **kwargs)

Show data and the inversion result model response.

standardizedCoverage(threshhold=0.01)

Return standardized coverage vector (0|1) using thresholding.

MeshModelling

class pygimli.frameworks.MeshModelling(**kwargs)

Bases: pygimli.frameworks.modelling.Modelling

__init__(**kwargs)

Variables

• fop (pg.frameworks.Modelling) –

• data (pg.DataContainer) –

• modelTrans ([pg.trans.TransLog()]) –

Parameters

**kwargs – fop : Modelling

createFwdMesh_()

createRefinedFwdMesh(mesh)

Refine the current mesh for higher accuracy.

This is called automatic when accessing self.mesh() so it ensures any effect of changing region properties (background, single).

drawModel(ax, model, **kwargs)

ensureContent()

mesh()

property paraDomain

paraModel(model)

setDefaultBackground()

setMesh(mesh, ignoreRegionManager=False)

setMeshPost(data)

Called when the mesh has been set successfully.

MethodManager

class pygimli.frameworks.MethodManager(fop=None, fw=None, data=None, **kwargs)

Bases: object

General manager to maintenance a measurement method.

Method Manager are the interface to end-user interaction and can be seen as simple but complete application classes which manage all tasks of geophysical data processing.

The method manager holds one instance of a forward operator and an appropriate inversion framework to handle modelling and data inversion.

Method Manager also helps with data import and export, handle measurement data error estimation as well as model and data visualization.

Variables

• verbose (bool) – Give verbose output.

• debug (bool) – Give debug output.

• fop (pygimli.frameworks.Modelling) – Forward Operator instance .. knows the physics. fop is initialized by pygimli.manager.MethodManager.initForwardOperator and calls a valid pygimli.manager.MethodManager.createForwardOperator method in any derived classes.

• inv (pygimli.frameworks.Inversion.) – Inversion framework instance .. knows the reconstruction approach. The attribute inv is initialized by default but can be changed overwriting pygimli.manager.MethodManager.initInversionFramework

__init__(fop=None, fw=None, data=None, **kwargs)

Constructor.

checkData(data)

Overwrite for special checks to return data values

checkError(err, dataVals=None)

Return relative error. Default we assume ‘err’ are relative values. Overwrite is derived class if needed.

static createArgParser(dataSuffix='dat')

Create default argument parser.

TODO move this to some kind of app class

Create default argument parser for the following options:

-Q, –quiet -R, –robustData: options.robustData -B, –blockyModel: options.blockyModel -l, –lambda: options.lam -i, –maxIter: options.maxIter –depth: options.depth

createForwardOperator(**kwargs)

Mandatory interface for derived classes.

Here you need to specify which kind of forward operator FOP you want to use. This is called by any initForwardOperator() call.

Parameters

**kwargs – Any arguments that are necessary for your FOP creation.

Returns

Instance of any kind of pygimli.framework.Modelling.

Return type

Modelling

createInversionFramework(**kwargs)

Create default Inversion framework.

Derived classes may overwrite this method.

Parameters

**kwargs – Any arguments that are necessary for your creation.

Returns

Instance of any kind of pygimli.framework.Inversion.

Return type

Inversion

property debug

estimateError(data, errLevel=0.01, absError=None)

Estimate data error.

Create an error of estimated measurement error. On default it returns an array of constant relative errors. More sophisticated error estimation should be done in specialized derived classes.

TODO check, rel or abs in return.

Parameters

• data (iterable) – Data values for which the errors should be estimated.

• errLevel (float (0.01)) – Error level in percent/100.

• absoluteError (float (None)) – TODO

Returns

err – Returning array of size len(data)

Return type

array

property fop

property fw

property inv

invert(data=None, err=None, **kwargs)

Invert the data.

Invert the data by calling self.inv.run() with mandatory data and error values.

TODO

*need dataVals mandatory? what about already loaded data

Parameters

• dataVals (iterable) – Data values to be inverted.

• errVals (iterable | float) – Error value for the given data. If errVals is float we assume this means to be a global relative error and force self.estimateError to be called.

load(fileName)

API, overwrite in derived classes.

property model

postRun(*args, **kwargs)

Called just after the inversion run.

preRun(*args, **kwargs)

Called just before the inversion run starts.

reinitForwardOperator(**kwargs)

Reinitialize the forward operator.

Sometimes it can be useful to reinitialize the forward operator. Keyword arguments will be forwarded to ‘self.createForwardOperator’.

showData(data=None, ax=None, **kwargs)

Shows the data.

Draw data values into a given axes or show the data values from the last run. Forwards on default to the self.fop.drawData function of the modelling operator. If there is no given function given, you have to override this method.

Parameters

• ax (mpl axes) – Axes object to draw into. Create a new if its not given.

• data (iterable | pg.DataContainer) – Data values to be draw.

showFit(ax=None, **kwargs)

Show the last inversion data and response.

showModel(model, ax=None, **kwargs)

Shows a model.

Draw model into a given axes or show inversion result from last run. Forwards on default to the self.fop.drawModel function of the modelling operator. If there is no function given, you have to override this method.

Parameters

• ax (mpl axes) – Axes object to draw into. Create a new if its not given.

• model (iterable) – Model data to be draw.

Returns

Return type

ax, cbar

showResult(model=None, ax=None, **kwargs)

Show the last inversion result.

Parameters

• ax (mpl axes) – Axes object to draw into. Create a new if its not given.

• model (iterable [None]) – Model values to be draw. Default is self.model from the last run

Returns

Return type

ax, cbar

showResultAndFit(**kwargs)

Calls showResults and showFit.

simulate(model, **kwargs)

property verbose

MethodManager1d

class pygimli.frameworks.MethodManager1d(fop=None, **kwargs)

Bases: pygimli.frameworks.methodManager.MethodManager

Method Manager base class for managers on a 1d discretization.

__init__(fop=None, **kwargs)

Constructor.

createInversionFramework(**kwargs)

invert(data=None, err=None, **kwargs)

Modelling

class pygimli.frameworks.Modelling(**kwargs)

Bases: pygimli.core.ModellingBaseMT__

Abstract Forward Operator.

Abstract Forward Operator that is or can use a Modelling instance. Can be seen as some kind of proxy Forward Operator.

__init__(**kwargs)

Variables

• fop (pg.frameworks.Modelling) –

• data (pg.DataContainer) –

• modelTrans ([pg.trans.TransLog()]) –

Parameters

**kwargs – fop : Modelling

clearRegionProperties()

Clear all region parameter.

createDefaultStartModel(dataVals)

Create the default startmodel as the median of the data values.

createStartModel(dataVals=None)

Create the default startmodel as the median of the data values.

Overwriting might be a good idea. Its used by inversion to create a valid startmodel if there are no starting values from the regions.

property data

Return the associated data container.

C++ signature :

GIMLI::DataContainer {lvalue} data(GIMLI::ModellingBase {lvalue})

drawData(ax, data, **kwargs)

drawModel(ax, model, **kwargs)

ensureContent()

estimateError(data, **kwargs)

Create data error fallback when the data error is not known. Should be implemented method depending.

property fop

initModelSpace(**kwargs)

API

property modelTrans

regionManager()

regionProperties(regionNr=None)

Return dictionary of all properties for region number regionNr.

setData(data)

setDataContainer(data)

setDataPost(data)

Called when the dataContainer has been set sucessfully.

setDataSpace(**kwargs)

Set data space, e.g., DataContainer, times, coordinates.

setRegionProperties(regionNr, **kwargs)

Set region properties. regionNr can be wildcard ‘*’ for all regions.

startModel=None, limits=None, trans=None, cType=None, zWeight=None, modelControl=None, background=None, single=None, fix=None

ParameterInversionManager

class pygimli.frameworks.ParameterInversionManager(funct=None, fop=None, **kwargs)

Bases: pygimli.frameworks.methodManager.MethodManager

Framework to invert unconstrained parameters.

__init__(funct=None, fop=None, **kwargs)

Constructor.

createInversionFramework(**kwargs)

invert(data=None, err=None, **kwargs)

Parameters

• limits ({str: [min, max]}) – Set limits for parameter by parameter name.

• startModel ({str: startModel}) – Set the start value for parameter by parameter name.

ParameterModelling

class pygimli.frameworks.ParameterModelling(funct=None, **kwargs)

Bases: pygimli.frameworks.modelling.Modelling

Model with symbolic parameter names instead of numbers

__init__(funct=None, **kwargs)

Variables

• fop (pg.frameworks.Modelling) –

• data (pg.DataContainer) –

• modelTrans ([pg.trans.TransLog()]) –

Parameters

**kwargs – fop : Modelling

addParameter(name, id=None, **kwargs)

drawModel(ax, model)

property params

response((object)arg1, (object)model) → object :

C++ signature :

GIMLI::Vector<double> response(GIMLI::ModellingBase {lvalue},GIMLI::Vector<double>)

response( (object)arg1, (object)model) -> object :

C++ signature :

GIMLI::Vector<double> response(ModellingBase_wrapper {lvalue},GIMLI::Vector<double>)

setRegionProperties(k, **kwargs)

Set Region Properties by parameter name.

PetroInversionManager

class pygimli.frameworks.PetroInversionManager(petro, mgr=None, **kwargs)

Bases: pygimli.frameworks.methodManager.MeshMethodManager

__init__(petro, mgr=None, **kwargs)

Constructor.

PetroModelling

class pygimli.frameworks.PetroModelling(fop, petro, **kwargs)

Bases: pygimli.frameworks.modelling.MeshModelling

Combine petrophysical relation with the modelling class f(p).

Combine petrophysical relation \(p(m)\) with a modelling class \(f(p)\) to invert for the petrophysical model \(p\) instead of the geophysical model \(m\).

\(p\) be the petrophysical model, e.g., porosity, saturation, … \(m\) be the geophysical model, e.g., slowness, resistivity, …

__init__(fop, petro, **kwargs)

Save forward class and transformation, create Jacobian matrix.

createJacobian(model)

Fill the individual jacobian matrices. J = dF(m) / dm = dF(m) / dp * dp / dm

createStartModel(data)

Use inverse transformation to get m(p) for the starting model.

property petro

response(model)

Use transformation to get p(m) and compute response f(p).

setDataPost(data)

setMeshPost(mesh)