pycsamt.inversion.backends.simpeg

SimPEG backend for physics-based EM inversion.

SimPEG is optional and imported only when this backend is selected. The backend wraps SimPEG’s natural-source electromagnetic API for MT, AMT, and CSAMT inversion. It supports 1-D soundings, stitched station-by-station 2-D profiles, and a 3-D primary-secondary natural-source path when the installed SimPEG version exposes the required classes.

The model parameter is log conductivity on SimPEG mesh cells. PyCSAMT converts user-facing layered resistivity starting models into log-conductivity cells, runs the inversion, and converts recovered models back to resistivity-oriented InversionResult payloads.

Classes

SimPEGBackend(config)

Run optional SimPEG natural-source EM inversions.

class pycsamt.inversion.backends.simpeg.SimPEGBackend(config)

Bases: BaseInversionBackend

Run optional SimPEG natural-source EM inversions.

SimPEGBackend adapts PyCSAMT’s inversion configuration objects to SimPEG’s natural-source electromagnetic machinery. It is intended for users who want a physics-backed inversion engine while keeping the same pycsamt.inversion.workflow.InversionWorkflow and pycsamt.inversion.results.InversionResult API used by the built-in and external backends.

The backend supports MT, AMT, and CSAMT. One-dimensional runs use Simulation1DElectricField. Two-dimensional runs are stitched station-by-station 1-D inversions, not full 2-D SimPEG EM inversion. Three- dimensional runs use Simulation3DPrimarySecondary with plane-wave natural- source survey objects when available in the installed SimPEG version.

Parameters:

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

Variables:

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

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

Notes

The inversion model is log conductivity, \(m = \log(\sigma)\), on SimPEG mesh cells. Starting and recovered models exposed through PyCSAMT are resistivity oriented. For 1-D output, recovered cell conductivities are compressed back into a layered pycsamt.inversion.model.StartingModel. For 3-D output, the result stores rho_3d as linear resistivity.

backend_options can contain:

mesh controls

Options consumed by pycsamt.inversion.mesh.build_1d_tensor_mesh() and pycsamt.inversion.mesh.build_3d_tensor_mesh(), such as core cell widths, padding, depth extent, and station padding.

max_iter_ls

Maximum line-search iterations passed to optimization.InexactGaussNewton.

beta0, estimate_beta, beta0_ratio

Initial trade-off and beta-estimation controls.

target_chifact

Target misfit directive chi factor.

cooling_factor and cooling_rate

Beta schedule directive controls.

sigma_primary

Background conductivity for 3-D primary-secondary simulation.

reference_model

Cell-sized reference model. Positive values are treated as resistivity and converted to log conductivity; otherwise values are assumed already in the SimPEG model domain.

alpha_y

Optional y-direction smoothness weight for 3-D regularization.

Examples

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

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

Run a stitched 2-D AMT profile through the high-level workflow:

>>> from pycsamt.inversion.workflow import run_inversion
>>> result = run_inversion(
...     method="amt",
...     dimension="2d",
...     backend="simpeg",
...     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'

Configure a small 3-D natural-source run:

>>> from pycsamt.inversion.workflow import run_inversion
>>> result = run_inversion(
...     method="mt",
...     dimension="3d",
...     backend="simpeg",
...     data={"freqs": [1.0],
...           "rho_a": [[100.0], [120.0]],
...           "phase": [[45.0], [47.0]],
...           "station_x": [0.0, 500.0],
...           "station_names": ["M01", "M02"],
...           "metadata": {"station_y": [0.0, 250.0]}},
...     backend_options={
...         "sigma_primary": 0.01,
...         "beta0": 1.0,
...         "target_chifact": 1.0,
...     },
...     max_iter=4,
... )

Pass SimPEG directive and optimization controls:

>>> from pycsamt.inversion.workflow import run_inversion
>>> result = run_inversion(
...     method="csamt",
...     dimension="1d",
...     backend="simpeg",
...     data={"freqs": [1.0, 10.0], "rho_a": [100.0, 120.0]},
...     backend_options={
...         "estimate_beta": True,
...         "beta0_ratio": 2.0,
...         "cooling_factor": 2.0,
...         "cooling_rate": 1,
...         "max_iter_ls": 10,
...     },
... )

See also

pycsamt.inversion.workflow.InversionWorkflow

High-level entry point that instantiates this backend.

pycsamt.inversion.backends.builtin.Builtin1DBackend

Dependency-light fallback backend.

pycsamt.inversion.backends.pygimli.PyGIMLiBackend

Optional pyGIMLi backend for 1-D EM inversions.

pycsamt.inversion.mesh.build_1d_tensor_mesh

Mesh helper used by the 1-D SimPEG path.

pycsamt.inversion.mesh.build_3d_tensor_mesh

Mesh helper used by the 3-D SimPEG path.

pycsamt.inversion.results.InversionResult

Backend-neutral result returned by run().

References

[1]

Cockett, R., Kang, S., Heagy, L. J., Pidlisecky, A. and Oldenburg, D. W. (2015). SimPEG: An open source framework for simulation and gradient based parameter estimation in geophysical applications. Computers & Geosciences, 85, 142-154.

[2]

Heagy, L. J., Cockett, R., Kang, S., Rosenkjaer, G. K. and Oldenburg, D. W. (2017). A framework for simulation and inversion in electromagnetics. Computers & Geosciences, 107, 1-19.

[3]

Haber, E. (2015). Computational Methods in Geophysical Electromagnetics. SIAM.

name = 'simpeg'

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

run(data=None)

Run a SimPEG natural-source 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, model is a recovered pycsamt.inversion.model.StartingModel. For stitched 2-D runs, model is a dictionary containing rho_2d and profile coordinates. For 3-D runs, model contains rho_3d and x_centers, y_centers, and z_centers arrays.

Return type:

InversionResult

Raises:

• ImportError – If SimPEG or discretize is not installed.

• ValueError – If data do not contain frequencies plus apparent resistivity and/or phase.

• NotImplementedError – If the configured method/dimension pair is unsupported by this backend or by the installed SimPEG natural-source API.

Examples

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