pycsamt.inversion.config#

Configuration for physics-based EM inversion workflows.

Classes

InversionConfig([method, dimension, ...])

Source-of-truth configuration for pycsamt.inversion.
class pycsamt.inversion.config.InversionConfig(method='mt', dimension='1d', backend='builtin', data=None, workdir='pycsamt_inversion', output_dir=None, n_layers=4, starting_model=None, reference_model=None, error_floor=0.05, include_phase=True, phase_error=3.0, regularization='smooth', max_iter=80, tol=1e-05, bounds=<factory>, run_external=False, backend_options=<factory>, metadata=<factory>)[source]#

Bases: PyCSAMTObject, MetadataMixin

Source-of-truth configuration for pycsamt.inversion.

Parameters:

  • method ({"mt", "amt", "csamt", "emap", "tdem"}, default "mt") – Electromagnetic method to invert. Natural-source methods use frequency, apparent-resistivity, and phase observations. TDEM uses time-gate decay observations. The value is normalized to lower case and is used with dimension to select the backend execution path.

  • dimension ({"1d", "2d", "3d"}, default "1d") – Inversion dimensionality. One-dimensional runs recover layered-earth models. Two-dimensional runs produce section models either by stitched station inversions or by the built-in finite-difference profile mode. Three-dimensional execution is delegated to optional or external engines.

  • backend ({"builtin", "simpeg", "pygimli", "occam2d", "modem"}, default "builtin") – Inversion engine. "builtin" is dependency-light and runnable for local smoke studies. "simpeg" and "pygimli" are optional physics engines imported only when selected. "occam2d" and "modem" prepare, validate, and optionally run external workflows.

  • data (mapping, object, sequence, or path-like, optional) – Observed EM data. Mappings can contain freqs/frequencies, rho_a/phase, or times/values for TDEM. Station collections, response-like objects, and survey objects exposing to_soundings() are coerced through pycsamt.inversion.EMData.

  • workdir (path-like, default "pycsamt_inversion") – Directory used for backend files, logs, and prepared external-run inputs. Local backends store provenance here when they create products. External adapters resolve runner files relative to this folder.

  • n_layers (int, default 4) – Number of layered-earth cells for 1-D style parameterizations, including the final halfspace. Built-in 1-D and stitched 2-D workflows use this value unless a supplied starting model defines its own layer count.

  • starting_model (StartingModel, mapping, or object, optional) – Initial layered model. Resistivities are linear ohm-m values and thicknesses are metres. Mappings may use singular or plural keys such as resistivity/resistivities and thickness/thicknesses.

  • reference_model (StartingModel, mapping, or object, optional) – Model used as the reference for damped or smooth regularization when the selected backend supports it. If omitted, solvers regularize against their starting model or backend-native default.

  • error_floor (float, default 0.05) – Relative error floor for amplitude-like components when explicit errors are unavailable. A value of 0.05 means five percent. More detailed rho, phase, impedance, TDEM, and station-mask rules can be supplied through backend_options["error_model"].

  • include_phase (bool, default True) – Whether built-in natural-source objectives include phase observations in addition to apparent resistivity.

  • phase_error (float, default 3.0) – Absolute phase uncertainty in degrees used by MT/AMT/CSAMT objectives when phase errors are unavailable.

  • regularization ({"none", "smooth", "damped", "blocky"}, default "smooth") – Regularization family used by runnable backends. Shared helpers map this vocabulary to built-in residual penalties, pyGIMLi lam values, and SimPEG weighted least-squares settings where possible.

  • max_iter (int, default 80) – Maximum local optimizer iterations or backend iteration request. External adapters may write this value into native control files or record it as lifecycle metadata depending on the backend.

  • tol (float, default 1e-5) – Local optimizer termination tolerance used by runnable backends.

  • bounds (dict, optional) – Optional parameter bounds. Built-in layered inversions understand log10_rho and log10_thickness bounds. Other engines may interpret backend-specific bound keys through backend_options.

  • run_external (bool, default False) – Whether external adapters are allowed to launch compiled executables. When False, Occam2D and ModEM prepare and validate inputs, assemble commands, and return a ready/prepared result without running the binary.

  • backend_options (dict, optional) – Backend-specific options. Common entries include mesh controls, component selection, profile_mode, error-model overrides, SimPEG/pyGIMLi knobs, and external runner file names or executable settings. Unknown keys are passed through to the selected backend.

  • output_dir (str | None)

  • metadata (dict[str, Any])

Examples

>>> import numpy as np
>>> from pycsamt.inversion import InversionConfig, InversionWorkflow, StartingModel
>>> cfg = InversionConfig(
...     method="mt",
...     dimension="1d",
...     backend="builtin",
...     data={"freqs": np.logspace(-1, 2, 8),
...           "rho_a": np.full(8, 100.0),
...           "phase": np.full(8, 45.0)},
...     starting_model=StartingModel([80.0, 200.0], [500.0]),
...     max_iter=4,
... )
>>> result = InversionWorkflow(cfg).run()
method: str = 'mt'#
dimension: str = '1d'#
backend: str = 'builtin'#
data: Any = None#
workdir: str = 'pycsamt_inversion'#
output_dir: str | None = None#
n_layers: int = 4#
starting_model: Any = None#
reference_model: Any = None#
error_floor: float = 0.05#
include_phase: bool = True#
phase_error: float = 3.0#
regularization: str = 'smooth'#
max_iter: int = 80#
tol: float = 1e-05#
bounds: dict[str, Any]#
run_external: bool = False#
backend_options: dict[str, Any]#
metadata: dict[str, Any]#
property output_path: Path[source]#

Resolved output directory.

validate()[source]#

Validate object state.

Subclasses can override this hook. The base implementation intentionally accepts all states.

Return type:

None

to_backend()[source]#

Instantiate the selected backend.

write_template(path, *, fmt=None)[source]#

Write an editable configuration template.

Parameters:
Return type:

Path

classmethod from_file(path, *, strict=True)[source]#

Load a Python/JSON/YAML configuration file.

Parameters:
Return type:

InversionConfig

classmethod read(path, *, strict=True)#

Load a Python/JSON/YAML configuration file.

Parameters:
Return type:

InversionConfig