pycsamt.inversion.backends.builtin#

Built-in dependency-light EM inversion backend.

The built-in backend provides a small SciPy-based inversion engine for routine smoke tests, demos, and lightweight studies where optional physics packages such as SimPEG or pyGIMLi are not available. It supports natural-source 1-D soundings, stitched 2-D profiles, finite-difference 2-D MT profile inversion, and 1-D/stitched 2-D TDEM runs.

The backend parameterizes layered soundings in log10 resistivity and log10 thickness. Profile mode either runs each station independently and stitches the recovered columns, or, when profile_mode="fd2d" is selected, solves a finite-difference 2-D natural-source problem against the local pycsamt.forward solver.

Classes

Builtin1DBackend(config)

Run PyCSAMT's built-in EM inversion engine.
class pycsamt.inversion.backends.builtin.Builtin1DBackend(config)[source]#

Bases: BaseInversionBackend

Run PyCSAMT’s built-in EM inversion engine.

Builtin1DBackend is the dependency-light backend used when an inversion should run without SimPEG, pyGIMLi, Occam2D, or ModEM. Despite the historical class name, it supports 1-D soundings and selected 2-D profile workflows for MT, AMT, CSAMT, EMAP, and TDEM data.

The backend minimizes a weighted residual of the form

\[\Phi(m) = \| W_d (d_\mathrm{pred}(m) - d_\mathrm{obs}) \|_2^2 + \lambda \Phi_m(m),\]

where \(W_d\) is built from component errors and \(\Phi_m\) is supplied by pycsamt.inversion.regularization. Natural-source 1-D runs invert log10 apparent resistivity and optional phase. TDEM runs invert log10 absolute transient response. Stitched 2-D mode repeats the 1-D inversion station by station, while finite-difference 2-D mode uses the local MT profile forward solver.

Parameters:

config (pycsamt.inversion.config.InversionConfig) – Normalized inversion configuration. The backend reads method, dimension, data, starting_model, reference_model, bounds, regularization, max_iter, tol, workdir, and backend_options from this object.

Variables:

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

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

Notes

Important backend_options entries include:

profile_mode

For natural-source 2-D runs, use "fd2d" or "finite_difference" to select true finite-difference profile inversion. Any other value uses stitched station-wise 1-D inversion.

components

Natural-source 2-D finite-difference components. Supported values are "te", "tm", or a sequence containing both.

blocky_eps

Small stabilizer used by blocky regularization.

loop_radius, moment, n_freqs, n_lam

TDEM forward-model controls passed to pycsamt.forward.TEM1DForward.

Examples

Run a small MT sounding through the backend directly:

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

Run the same engine through the high-level workflow:

>>> from pycsamt.inversion.workflow import run_inversion
>>> result = run_inversion(
...     method="tdem",
...     dimension="1d",
...     backend="builtin",
...     data={"times": [1e-5, 1e-4],
...           "values": [1e-8, 2e-9]},
...     max_iter=4,
... )

Select finite-difference 2-D MT profile mode:

>>> from pycsamt.inversion.workflow import run_inversion
>>> result = run_inversion(
...     method="mt",
...     dimension="2d",
...     backend="builtin",
...     data={"freqs": [1.0, 10.0],
...           "rho_a": [[100.0, 120.0], [90.0, 110.0]],
...           "phase": [[45.0, 47.0], [44.0, 46.0]],
...           "station_x": [0.0, 500.0]},
...     backend_options={"profile_mode": "fd2d",
...                      "components": ("te",)},
...     max_iter=4,
... )

See also

pycsamt.inversion.workflow.InversionWorkflow

High-level orchestration API that usually instantiates this backend.

pycsamt.inversion.config.InversionConfig

Configuration object consumed by the backend.

pycsamt.inversion.regularization.Regularization

Shared regularization description wired into the residual.

pycsamt.inversion.results.InversionResult

Backend-neutral result returned by run().

References

name = 'builtin'#
supports: tuple[tuple[str, str], ...] = (('mt', '1d'), ('mt', '2d'), ('amt', '1d'), ('amt', '2d'), ('csamt', '1d'), ('csamt', '2d'), ('emap', '2d'), ('tdem', '1d'), ('tdem', '2d'))#
run(data=None)[source]#

Run the configured built-in inversion.

Parameters:

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

Returns:

Backend-neutral result containing the recovered model, predicted response, RMS, objective value, uncertainty proxy, convergence history, and backend metadata.

Return type:

InversionResult

Raises:

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

  • ImportError – If SciPy is unavailable when a runnable least-squares inversion is requested.

  • NotImplementedError – If the configured method/dimension pair is not listed in supports.

Examples

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