pycsamt.inversion.backends.pygimli

pyGIMLi backend for EM inversion.

pyGIMLi is optional and imported only when this backend is selected. The backend wraps pygimli.physics.em modelling operators and pg.Inversion for 1-D MT/AMT/CSAMT and TDEM soundings. Two-dimensional runs are represented as stitched station-by-station 1-D inversions so their output can still be used by PyCSAMT interpretation and plotting tools.

The implementation deliberately accepts several pyGIMLi operator names and constructor signatures because the EM API has varied across pyGIMLi releases. Backend options let users force a specific operator when automatic discovery is not enough.

Classes

PyGIMLiBackend(config)

Run optional pyGIMLi EM inversions.

class pycsamt.inversion.backends.pygimli.PyGIMLiBackend(config)

Bases: BaseInversionBackend

Run optional pyGIMLi EM inversions.

PyGIMLiBackend adapts pycsamt.inversion configurations to pyGIMLi’s electromagnetic modelling and inversion APIs. It is an optional backend: importing pycsamt.inversion does not require pyGIMLi, but selecting backend="pygimli" does.

The backend supports two execution patterns:

• 1-D MT/AMT/CSAMT soundings with apparent resistivity and optional phase;

• 1-D TDEM soundings with transient time gates and decay values.

For dimension="2d", the backend performs stitched station-by-station 1-D inversions: each station is inverted independently with the same 1-D machinery and the recovered log10 resistivity columns are assembled into a profile model. This is useful for quick profile interpretation, but it is not a full 2-D finite-element pyGIMLi EM inversion.

Parameters:

config (pycsamt.inversion.config.InversionConfig) – Inversion configuration. Important fields are method, dimension, data, starting_model, regularization, max_iter, tol, error_floor, phase_error, backend_options, workdir, and metadata.

Variables:

• name (str) – Backend registry name, always "pygimli".

• supports (tuple of tuple) – Supported (method, dimension) pairs.

Notes

Natural-source observations are passed to pyGIMLi in the order apparent resistivity followed by phase when both are present. pyGIMLi expects relative error values, so PyCSAMT converts the shared component error model into the form required by pg.Inversion.

backend_options can contain:

mt_operator

Name or ordered sequence of names to try for MT/AMT/CSAMT modelling. Defaults include MT1dSmoothModelling, MT1DSmoothModelling, MT1dBlockModelling, MT1DBlockModelling, MT1dModelling, and MT1DModelling.

tdem_operator

Name or ordered sequence of names to try for TDEM modelling. Defaults include TDEMSmoothModelling, TDEMBlockModelling, TDEM1dModelling, and TDEM1DModelling.

lam

pyGIMLi regularization strength. If omitted, PyCSAMT maps the shared pycsamt.inversion.regularization.Regularization settings through pycsamt.inversion.regularization.pygimli_lambda().

verbose

Forwarded to pyGIMLi operator and inversion construction when supported.

tx_area / txArea and rx_area / rxArea

TDEM transmitter and receiver loop areas passed to the TDEM operator when supported by the installed pyGIMLi version.

Examples

Run a 1-D MT sounding through the backend directly:

>>> from pycsamt.inversion.backends.pygimli import PyGIMLiBackend
>>> from pycsamt.inversion.config import InversionConfig
>>> cfg = InversionConfig(
...     method="mt",
...     dimension="1d",
...     backend="pygimli",
...     data={"freqs": [1.0, 10.0],
...           "rho_a": [100.0, 120.0],
...           "phase": [45.0, 47.0]},
...     max_iter=8,
... )
>>> result = PyGIMLiBackend(cfg).run()

Run a TDEM sounding and pass loop geometry to pyGIMLi:

>>> from pycsamt.inversion.workflow import run_inversion
>>> result = run_inversion(
...     method="tdem",
...     dimension="1d",
...     backend="pygimli",
...     data={"times": [1e-5, 3e-5, 1e-4],
...           "values": [1e-8, 5e-9, 1e-9]},
...     backend_options={"tx_area": 7850.0, "rx_area": 100.0},
...     max_iter=8,
... )

Build a stitched 2-D profile from station-wise MT inversions:

>>> from pycsamt.inversion.workflow import run_inversion
>>> result = run_inversion(
...     method="amt",
...     dimension="2d",
...     backend="pygimli",
...     data={"freqs": [10.0, 100.0],
...           "rho_a": [[80.0, 100.0], [90.0, 110.0]],
...           "phase": [[42.0, 45.0], [43.0, 46.0]],
...           "station_x": [0.0, 250.0],
...           "station_names": ["A01", "A02"]},
...     max_iter=6,
... )
>>> result.metadata["profile_mode"]
'stitched_station_1d'

Force a specific pyGIMLi operator name when needed:

>>> from pycsamt.inversion.workflow import run_inversion
>>> result = run_inversion(
...     method="mt",
...     dimension="1d",
...     backend="pygimli",
...     data={"freqs": [1.0], "rho_a": [100.0]},
...     backend_options={
...         "mt_operator": "MT1DModelling",
...         "lam": 15.0,
...         "verbose": False,
...     },
... )

See also

pycsamt.inversion.workflow.InversionWorkflow

High-level entry point that instantiates this backend.

pycsamt.inversion.backends.builtin.Builtin1DBackend

Dependency-light fallback backend for local smoke inversions.

pycsamt.inversion.backends.simpeg.SimPEGBackend

Optional SimPEG backend for natural-source physics inversion.

pycsamt.inversion.regularization.pygimli_lambda

Helper that maps shared regularization settings to pyGIMLi lam.

pycsamt.inversion.results.InversionResult

Backend-neutral result returned by run().

References

[1]

Rücker, C., Günther, T. and Wagner, F. M. (2017). pyGIMLi: An open-source library for modelling and inversion in geophysics. Computers & Geosciences, 109, 106-123.

[2]

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

[3]

Chave, A. D. and Jones, A. G. (2012). The Magnetotelluric Method: Theory and Practice. Cambridge University Press.

name = 'pygimli'

supports: tuple[tuple[str, str], ...] = (('mt', '1d'), ('mt', '2d'), ('amt', '1d'), ('amt', '2d'), ('csamt', '1d'), ('csamt', '2d'), ('tdem', '1d'), ('tdem', '2d'))

run(data=None)

Run a pyGIMLi-backed EM inversion.

Parameters:

data (mapping, object, sequence, or path-like, optional) – Optional data override for this call. When omitted, the backend uses self.config.data. Values are coerced through pycsamt.inversion.data.EMData.

Returns:

Backend-neutral result. For 1-D runs the result model is a pycsamt.inversion.model.StartingModel containing recovered resistivities and thicknesses. For stitched 2-D profile runs the model is a dictionary with rho_2d, station positions, and depth centres.

Return type:

InversionResult

Raises:

• ImportError – If pygimli is not installed.

• ValueError – If the selected method does not receive the required data components. TDEM requires times and values. Natural-source methods require frequencies plus apparent resistivity and/or phase.

• NotImplementedError – If the configured method/dimension pair is not supported, or if the installed pyGIMLi version does not expose a usable EM modelling operator.

Examples

>>> from pycsamt.inversion.backends.pygimli import PyGIMLiBackend
>>> from pycsamt.inversion.config import InversionConfig
>>> cfg = InversionConfig(
...     method="mt",
...     dimension="1d",
...     backend="pygimli",
...     data={"freqs": [1.0, 10.0],
...           "rho_a": [100.0, 120.0],
...           "phase": [45.0, 47.0]},
...     max_iter=8,
... )
>>> result = PyGIMLiBackend(cfg).run()