pycsamt.inversion.backends.modem#

ModEM adapter backend.

This module connects pycsamt.inversion to the ModEM workflow helpers under pycsamt.models.modem. It does not implement the ModEM electromagnetic solver itself. Instead, it prepares or locates ModEM input files, validates the external-run lifecycle, optionally calls the runner when run_external=True, and loads finished results back into a common pycsamt.inversion.results.InversionResult.

Classes

ModEMBackend(config)

Adapt PyCSAMT inversion workflows to ModEM.
class pycsamt.inversion.backends.modem.ModEMBackend(config)[source]#

Bases: BaseInversionBackend

Adapt PyCSAMT inversion workflows to ModEM.

ModEMBackend is the external-run adapter for 2-D and 3-D MT/AMT inversions. It shares the same pycsamt.inversion.workflow.InversionWorkflow interface as the runnable in-process backends, but the numerical inversion is performed by the ModEM ecosystem through pycsamt.models.modem.

The backend handles four lifecycle steps:

  1. normalize ModEM configuration from backend_options;

  2. prepare input files with InputBuilder when a data source is supplied;

  3. validate required runner files and assemble the external command; and

  4. optionally run ModEM and load finished result files.

Parameters:

config (pycsamt.inversion.config.InversionConfig) – Inversion configuration. Important fields are method, dimension, workdir, data, backend_options, run_external, and metadata. The adapter supports MT and AMT in 2-D or 3-D mode.

Variables:

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

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

Notes

backend_options can contain:

config

A ModEmConfig instance or dictionary used to configure file names, binary names, MPI settings, and mode-specific options.

files

Mapping from roles such as "data", "model", "control", and "covariance" to existing or expected file paths. Relative paths are resolved inside workdir.

runner

Runner-only options including use_mpi, n_procs, extra_args, timeout, and load_result.

data_file, model_file, control_file, covariance_file

Convenience aliases for file names when a full files mapping is not supplied.

By default the backend prepares and validates files but does not execute the external binary. Set run_external=True in pycsamt.inversion.config.InversionConfig to allow execution.

Examples

Validate an existing 3-D ModEM run directory without execution:

>>> from pycsamt.inversion.backends.modem import ModEMBackend
>>> from pycsamt.inversion.config import InversionConfig
>>> cfg = InversionConfig(
...     method="mt",
...     dimension="3d",
...     backend="modem",
...     workdir="modem_run",
...     backend_options={
...         "files": {
...             "data": "ModEM_Data.dat",
...             "model": "ModEM_Model.rho",
...             "control": "ModEM_Control.inv",
...             "covariance": "covariance.cov",
...         }
...     },
... )
>>> result = ModEMBackend(cfg).run()
>>> result.status in {"ready", "loaded", "needs_review"}
True

Use the high-level inversion workflow and request execution:

>>> from pycsamt.inversion.workflow import run_inversion
>>> result = run_inversion(
...     method="amt",
...     dimension="2d",
...     backend="modem",
...     workdir="modem_2d",
...     run_external=True,
...     backend_options={
...         "runner": {"use_mpi": False, "timeout": 600},
...         "files": {
...             "data": "ModEM_Data.dat",
...             "model": "ModEM_Model.rho",
...             "control": "ModEM_Control.inv",
...         },
...     },
... )

See also

pycsamt.inversion.workflow.InversionWorkflow

High-level entry point that instantiates this backend.

pycsamt.inversion.backends.occam2d.Occam2DBackend

Similar external-run adapter for Occam2D.

pycsamt.inversion.results.InversionResult

Backend-neutral result returned by run().

References

name = 'modem'#
supports: tuple[tuple[str, str], ...] = (('mt', '2d'), ('mt', '3d'), ('amt', '2d'), ('amt', '3d'))#
run(data=None)[source]#

Prepare, validate, optionally run, and load ModEM outputs.

Parameters:

data (object, mapping, path-like, or sequence, optional) – Input source used by pycsamt.models.modem.InputBuilder when it is available. When omitted, self.config.data is used. If no source is supplied, configured file names are resolved inside the work directory and the backend only validates runner readiness.

Returns:

Backend-neutral result. The files mapping contains prepared or configured ModEM file paths, metadata["command"] records the command that would be executed, and native stores the builder, runner, loaded ModEM result, or another backend-native object.

Return type:

InversionResult

Raises:

Notes

External execution is disabled unless self.config.run_external is True. With the default value, the method prepares or validates the ModEM directory and reports the command that would be executed when the runner files are complete.

The returned status describes the lifecycle stage:

"prepared"

Input files were built or configured, but runner readiness was not fully established.

"ready"

Required files exist and a command string could be assembled.

"executed"

The external runner completed without loading a result object.

"loaded"

A ModEM result object was found and attached to native.

"needs_review"

Preparation, runner execution, or validation raised a recoverable issue. Details are stored in warnings.

Examples

>>> from pycsamt.inversion.backends.modem import ModEMBackend
>>> from pycsamt.inversion.config import InversionConfig
>>> cfg = InversionConfig(
...     method="mt",
...     dimension="3d",
...     backend="modem",
...     workdir="modem_run",
...     backend_options={
...         "files": {
...             "data": "ModEM_Data.dat",
...             "model": "ModEM_Model.rho",
...             "control": "ModEM_Control.inv",
...             "covariance": "covariance.cov",
...         }
...     },
... )
>>> result = ModEMBackend(cfg).run()