2.21.1.2. pycsamt.inversion.workflow#

High-level inversion workflow entry point.

pycsamt.inversion.workflow is the small orchestration layer that turns an inversion configuration into a backend run. It keeps application code stable: callers build an InversionConfig, pass it to InversionWorkflow, and receive an pycsamt.inversion.results.InversionResult regardless of whether the selected backend is built-in, SimPEG, pyGIMLi, Occam2D, or ModEM.

The workflow object does not implement physics itself. It validates and stores configuration, instantiates the selected backend lazily through the backend registry, and delegates execution to backend.run.

Examples

>>> from pycsamt.inversion.workflow import run_inversion
>>> result = run_inversion(
...     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,
... )

See also

pycsamt.inversion.config.InversionConfig: Configuration object consumed by this module.
pycsamt.inversion.results.InversionResult: Backend-neutral result returned by this module.

Functions

run_inversion([config])

Run an inversion in one call.

Classes

InversionWorkflow([config])

Execute a configured EM inversion backend.

class pycsamt.inversion.workflow.InversionWorkflow(config=None, **kw)[source]

Bases: PyCSAMTObject

Execute a configured EM inversion backend.

InversionWorkflow is the object-oriented entry point for running EM inversions. It owns one normalized pycsamt.inversion.config.InversionConfig and one instantiated backend. Calling run() delegates to that backend and returns a common pycsamt.inversion.results.InversionResult.

Parameters:

config (InversionConfig or dict, optional) – Complete inversion configuration. Dictionaries are converted to pycsamt.inversion.config.InversionConfig. Keyword arguments override matching configuration fields. If omitted, keyword arguments are used to build a default configuration.
**kw – Configuration fields that override values supplied by config. Common keys include method, dimension, backend, data, starting_model, max_iter, regularization, and backend_options.

Returns:

result – Backend-neutral inversion output. It stores the recovered model, mesh, predicted response, RMS/objective values, files, warnings, native backend objects, uncertainty diagnostics, convergence history, and metadata.

Return type:

InversionResult

Notes

The workflow does not mutate caller-provided data. A per-call data override can be supplied to run(), which is convenient for applying the same configuration to multiple soundings or profiles.

Examples

Run from an explicit configuration object:

>>> from pycsamt.inversion.config import InversionConfig
>>> from pycsamt.inversion.workflow import InversionWorkflow
>>> 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 = InversionWorkflow(cfg).run()

Run from a dictionary in one line:

>>> 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,
... })

See also

pycsamt.inversion.config.InversionConfig: Configuration consumed by the workflow.
pycsamt.inversion.backends.get_backend: Backend registry used by InversionConfig.to_backend.
pycsamt.inversion.results.InversionResult: Result returned by run().

References

[workflow-1]

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

[workflow-2]

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

run(data=None)[source]

Run the selected backend.

Parameters:: data (mapping, object, sequence, or path-like, optional) – Optional data override for this call. When omitted, config.data is used. Accepted values are backend-dependent but normally pass through pycsamt.inversion.data.EMData.coerce.
Returns:: Backend-neutral result containing recovered model, RMS/objective diagnostics, files, warnings, uncertainty, history, and native backend objects when available.
Return type:: InversionResult

Examples

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

pycsamt.inversion.workflow.run_inversion(config=None, **kw)[source]

Run an inversion in one call.

This convenience function is equivalent to InversionWorkflow(config, **kw).run(). It is useful in scripts, notebooks, tests, and demos where the workflow object does not need to be reused.

Parameters:

config (InversionConfig or dict, optional) – Complete inversion configuration. Dictionaries are converted to pycsamt.inversion.config.InversionConfig.
**kw – Configuration overrides or full configuration fields when config is omitted.

Returns:

Backend-neutral inversion result.

Return type:

InversionResult

Examples

>>> from pycsamt.inversion.workflow import run_inversion
>>> result = run_inversion(
...     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,
... )