pycsamt.inversion.model

Model containers used by pycsamt.inversion.

Classes

ReferenceModel
StartingModel(resistivities, thicknesses[, ...])	Starting or recovered layered-earth model.

class pycsamt.inversion.model.StartingModel(resistivities, thicknesses, name='', metadata=<factory>)

Bases: PyCSAMTObject, MetadataMixin

Starting or recovered layered-earth model.

Resistivities are linear ohm-m values. The final layer is a halfspace, so len(thicknesses) must equal len(resistivities) - 1.

ReferenceModel is currently an alias of StartingModel. Use it when the same layer container is being supplied as a regularization reference rather than as an optimizer starting point.

Parameters:

• resistivities (array-like of float) – Layer resistivities in ohm metres. Values must be strictly positive. The last value represents the bottom halfspace.

• thicknesses (array-like of float) – Layer thicknesses in metres. Values must be strictly positive and the array length must be len(resistivities) - 1 because the final layer is a halfspace.

• name (str, optional) – Human-readable model label recorded with the object and passed to forward model adapters where supported.

• metadata (dict, optional) – Free-form provenance metadata attached to the model.

Notes

The model is deliberately small and backend-neutral. Built-in solvers optimize log10(resistivity) and log10(thickness) internally, but this public container stores physical linear values in ohm metres and metres.

Examples

Build a three-layer model with a conductive target over a resistive basement:

>>> from pycsamt.inversion.model import StartingModel
>>> start = StartingModel([100.0, 30.0, 800.0], [200.0, 900.0])
>>> start.n_layers
3
>>> start.depths.tolist()
[0.0, 200.0, 1100.0]

Coerce a mapping supplied in a configuration file:

>>> from pycsamt.inversion.model import StartingModel
>>> start = StartingModel.coerce({
...     "resistivities": [80.0, 250.0],
...     "thicknesses": [500.0],
... })
>>> start.resistivities.tolist()
[80.0, 250.0]

References

[1]

Constable, S. C., Parker, R. L. and Constable, C. G. (1987). Occam’s inversion: A practical algorithm for generating smooth models from electromagnetic sounding data. Geophysics, 52(3), 289-300.

[2]

Aster, R. C., Borchers, B. and Thurber, C. H. (2018). Parameter Estimation and Inverse Problems, 3rd edition. Elsevier.

resistivities: Any

thicknesses: Any

name: str = ''

metadata: dict[str, Any]

classmethod default(n_layers=4)

Return a conservative layered starting model.

Parameters:

n_layers (int, default 4) – Number of layers, including the bottom halfspace.

Returns:

Default model with 100 ohm-m layers and geometrically increasing thicknesses between 100 m and 2000 m.

Return type:

StartingModel

Raises:

ValueError – If n_layers < 2.

Examples

>>> from pycsamt.inversion.model import StartingModel
>>> start = StartingModel.default(n_layers=3)
>>> start.resistivities.tolist()
[100.0, 100.0, 100.0]
>>> start.thicknesses.size
2

classmethod from_dict(data)

Build from singular or plural mapping keys.

Parameters:

data (mapping) – Model mapping. Accepted keys are resistivity or resistivities for layer resistivity, thickness or thicknesses for layer thickness, plus optional name and metadata.

Returns:

Validated layered-earth model.

Return type:

StartingModel

Examples

>>> from pycsamt.inversion.model import StartingModel
>>> start = StartingModel.from_dict({
...     "resistivity": [100.0, 500.0],
...     "thickness": [250.0],
...     "name": "two_layer",
... })
>>> start.name
'two_layer'

classmethod coerce(value, *, n_layers=4)

Return value as a StartingModel.

Parameters:

• value (StartingModel, mapping, object, or None) – Input model. Existing StartingModel instances are returned unchanged. Mappings are read by from_dict(). Generic objects may expose resistivity/resistivities and thickness/thicknesses attributes.

• n_layers (int, default 4) – Number of layers used only when value is None and a default model must be created.

Returns:

Validated layered-earth model.

Return type:

StartingModel

Examples

>>> from pycsamt.inversion.model import StartingModel
>>> StartingModel.coerce(None, n_layers=2).n_layers
2
>>> StartingModel.coerce({
...     "resistivities": [80.0, 250.0],
...     "thicknesses": [500.0],
... }).depths.tolist()
[0.0, 500.0]

property n_layers: int

property depths: ndarray

Top-of-layer depths in metres.

Examples

>>> from pycsamt.inversion.model import StartingModel
>>> StartingModel([100.0, 300.0, 800.0], [50.0, 150.0]).depths.tolist()
[0.0, 50.0, 200.0]

to_layered_model()

Return the existing pycsamt.forward.LayeredModel.

This adapter lets inversion starting/recovered models reuse the forward modelling API without duplicating layer containers.

Returns:

Forward-model-compatible layered earth.

Return type:

pycsamt.forward.LayeredModel

Examples

>>> from pycsamt.inversion.model import StartingModel
>>> layered = StartingModel([100.0, 300.0], [500.0]).to_layered_model()
>>> layered.n_layers
2

validate()

Validate layer shape and positivity.

Raises:

ValueError – If resistivities or thicknesses are not 1-D, if fewer than two resistivity layers are supplied, if thickness count does not equal len(resistivities) - 1, or if any value is non-positive.

Return type:

None

Examples

>>> from pycsamt.inversion.model import StartingModel
>>> StartingModel([100.0, 300.0], [500.0]).validate() is None
True

pycsamt.inversion.model.ReferenceModel

alias of StartingModel