pycsamt.inversion.results

Unified inversion result container.

Classes

InversionHistory([records, metadata])	Common convergence-history container.
InversionResult(method, dimension, backend)	Backend-neutral post-inversion result.
InversionUncertainty([model_std, ...])	Backend-neutral uncertainty and sensitivity diagnostics.

class pycsamt.inversion.results.InversionHistory(records=<factory>, metadata=<factory>)

Bases: PyCSAMTObject, MetadataMixin

Common convergence-history container.

InversionHistory stores backend-neutral iteration diagnostics. Built-in solvers record fields such as iteration, phi_d, phi_m, objective, rms, regularization weight, and model norm. Optional or external backends can map native logs into the same record structure.

Parameters:

• records (list of dict, optional) – One dictionary per iteration or residual evaluation. Numeric fields can be converted to arrays with arrays().

• metadata (dict, optional) – Free-form provenance metadata such as backend mode or station index.

Examples

Build convergence history from backend records:

>>> from pycsamt.inversion.results import InversionHistory
>>> history = InversionHistory(records=[
...     {"iteration": 0, "objective": 5.0, "rms": 2.0},
...     {"iteration": 1, "objective": 2.5, "rms": 1.2},
... ])
>>> history.arrays()["objective"].tolist()
[5.0, 2.5]

See also

InversionResult.history

Result field that carries convergence diagnostics.

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.

records: list[dict[str, Any]]

metadata: dict[str, Any]

property n_records: int

Number of convergence records.

Examples

>>> from pycsamt.inversion.results import InversionHistory
>>> InversionHistory(records=[{"iteration": 0}]).n_records
1

arrays()

Return numeric history fields as arrays.

Non-numeric fields are skipped. Missing numeric fields are represented by nan so arrays have one value per record.

Returns:

Mapping from numeric history field name to a float array.

Return type:

dict of ndarray

Examples

>>> from pycsamt.inversion.results import InversionHistory
>>> history = InversionHistory(records=[
...     {"iteration": 0, "objective": 5.0},
...     {"iteration": 1, "objective": 2.5},
... ])
>>> history.arrays()["objective"].tolist()
[5.0, 2.5]

class pycsamt.inversion.results.InversionResult(method, dimension, backend, status='success', model=None, mesh=None, data=None, predicted=None, rms=nan, objective=nan, n_iter=0, workdir=None, files=<factory>, native=None, uncertainty=None, history=None, warnings=<factory>, metadata=<factory>)

Bases: PyCSAMTObject, MetadataMixin

Backend-neutral post-inversion result.

InversionResult is the common result object returned by every inversion backend. It stores recovered models, predicted responses, misfit diagnostics, uncertainty, convergence history, generated files, backend-native objects, and free-form metadata while exposing conversion hooks for plotting, exporting, and hydrogeophysical interpretation.

Parameters:

• method (str) – EM method label such as "mt", "amt", "csamt", "emap", or "tdem".

• dimension (('1d', '2d', '3d')) – Inversion dimensionality.

• backend (str) – Backend name such as "builtin", "simpeg", "pygimli", "occam2d", or "modem".

• status (str, default "success") – Backend status. Common values include "success", "converged", "needs_review", "prepared", "ready", and "loaded".

• model (object, optional) – Recovered model. Accepted conversion forms include a layered model or a dictionary with rho_2d and coordinate arrays.

• mesh (InversionMesh, optional) – Common mesh descriptor.

• data (object, optional) – Observed and predicted response containers.

• predicted (object, optional) – Observed and predicted response containers.

• rms (float, default nan) – Weighted RMS misfit.

• objective (float, default nan) – Final objective-function value.

• n_iter (int, default 0) – Number of backend iterations or residual evaluations.

• workdir (str, optional) – Backend working directory.

• files (dict, optional) – Generated or backend-native file paths.

• native (object, optional) – Backend-native result object retained for advanced users.

• uncertainty (InversionUncertainty or dict, optional) – Uncertainty diagnostics. Dictionaries are coerced automatically.

• history (InversionHistory, dict, or list, optional) – Convergence history. Dictionaries and record lists are coerced automatically.

• warnings (list of str, optional) – Backend warnings and lifecycle messages.

• metadata (dict, optional) – Free-form result provenance.

Examples

Create a minimal 2-D result and convert it to an interpretation model:

>>> import numpy as np
>>> from pycsamt.inversion.results import InversionResult
>>> result = InversionResult(
...     method="mt",
...     dimension="2d",
...     backend="builtin",
...     model={
...         "rho_2d": np.array([[2.0, 2.2]]),
...         "x_centers": np.array([0.0, 500.0]),
...         "z_centers": np.array([100.0]),
...     },
... )
>>> result.to_resistivity_model().rho_2d.shape
(1, 2)

Summarize a result in logs or notebooks:

>>> from pycsamt.inversion.results import InversionResult
>>> InversionResult("mt", "1d", "builtin", rms=1.2).summary()
"InversionResult(method='mt', dimension='1d', backend='builtin', status='success', rms=1.2)"

See also

pycsamt.inversion.export

Export helpers that consume InversionResult.

pycsamt.inversion.plot

Plotting helpers that consume InversionResult.

pycsamt.interp.ResistivityModel

Interpretation model returned by to_resistivity_model().

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.

method: str

dimension: str

backend: str

status: str = 'success'

model: Any = None

mesh: InversionMesh | None = None

data: Any = None

predicted: Any = None

rms: float = nan

objective: float = nan

n_iter: int = 0

workdir: str | None = None

files: dict[str, str]

native: Any = None

uncertainty: InversionUncertainty | None = None

history: InversionHistory | None = None

warnings: list[str]

metadata: dict[str, Any]

property converged: bool

Whether the backend reported a usable result.

Returns:

True for statuses "success", "converged", "prepared", and "loaded".

Return type:

bool

Examples

>>> from pycsamt.inversion.results import InversionResult
>>> InversionResult("mt", "1d", "builtin", status="converged").converged
True

to_resistivity_model()

Convert the result to pycsamt.interp.ResistivityModel.

2-D result arrays are passed through directly. A recovered 1-D layered model is expanded to one column so the interpretation API can consume it uniformly.

Returns:

Unified 2-D log10 resistivity model with profile and depth coordinates.

Return type:

pycsamt.interp.ResistivityModel

Raises:

ValueError – If no model is attached or if the attached model cannot be adapted to a resistivity section.

Notes

The conversion accepts three result forms:

• backend-native Occam-like objects exposing rho_2d;

• dictionaries containing rho_2d plus coordinate arrays;

• layered models exposing resistivities and thicknesses.

Examples

>>> import numpy as np
>>> from pycsamt.inversion.results import InversionResult
>>> result = InversionResult(
...     method="mt",
...     dimension="2d",
...     backend="builtin",
...     model={
...         "rho_2d": np.array([[2.0, 2.2]]),
...         "x_centers": np.array([0.0, 500.0]),
...         "z_centers": np.array([100.0]),
...     },
... )
>>> result.to_resistivity_model().n_x
2

summary(*, max_fields=None)

Return a compact one-line result summary.

Parameters:

max_fields (int, optional) – Reserved for future expanded summaries. Currently ignored.

Returns:

Human-readable summary containing method, dimension, backend, status, and RMS.

Return type:

str

Examples

>>> from pycsamt.inversion.results import InversionResult
>>> InversionResult("mt", "1d", "builtin", rms=1.2).summary()
"InversionResult(method='mt', dimension='1d', backend='builtin', status='success', rms=1.2)"

class pycsamt.inversion.results.InversionUncertainty(model_std=None, covariance_diag=None, sensitivity=None, confidence=None, station_confidence=None, depth_confidence=None, metadata=<factory>)

Bases: PyCSAMTObject, MetadataMixin

Backend-neutral uncertainty and sensitivity diagnostics.

InversionUncertainty stores uncertainty products in a common shape for exports, plots, and interpretation. Built-in solvers currently provide proxy diagnostics from least-squares Jacobians; optional engines may attach richer posterior or sensitivity products over time.

Parameters:

• model_std (array-like, optional) – Per-model-cell standard-deviation proxy.

• covariance_diag (array-like, optional) – Diagonal covariance or covariance-like proxy.

• sensitivity (array-like, optional) – Relative model sensitivity map.

• confidence (array-like, optional) – Normalized confidence map, typically scaled to [0, 1].

• station_confidence (array-like, optional) – One confidence value per station.

• depth_confidence (array-like, optional) – One confidence value per depth cell.

• metadata (dict, optional) – Free-form uncertainty provenance.

Examples

Store model confidence and sensitivity maps:

>>> from pycsamt.inversion.results import InversionUncertainty
>>> uncertainty = InversionUncertainty(
...     confidence=[[0.9, 0.8]],
...     sensitivity=[[1.0, 0.5]],
... )
>>> uncertainty.confidence.shape
(1, 2)

References

[1]

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

model_std: Any = None

covariance_diag: Any = None

sensitivity: Any = None

confidence: Any = None

station_confidence: Any = None

depth_confidence: Any = None

metadata: dict[str, Any]