pycsamt.inversion.backends.occam2d#

Occam2D adapter backend.

This module connects pycsamt.inversion to the Occam2D workflow helpers under pycsamt.models.occam2d. It prepares Occam2D input directories, validates runner files, optionally executes the external binary when run_external=True, and loads finished Occam2D results into the common pycsamt.inversion.results.InversionResult container.

Classes

Occam2DBackend(config)

Adapt PyCSAMT inversion workflows to Occam2D.
class pycsamt.inversion.backends.occam2d.Occam2DBackend(config)[source]#

Bases: BaseInversionBackend

Adapt PyCSAMT inversion workflows to Occam2D.

Occam2DBackend is the external-run adapter for smooth 2-D EM inversion with Occam2D-style workflows. It uses pycsamt.models.occam2d to prepare input files, assemble runner commands, optionally launch the external executable, and load completed model sections. The actual inversion physics are provided by Occam2D, while PyCSAMT keeps a consistent configuration and result interface.

The adapter supports MT, AMT, CSAMT, and EMAP in 2-D mode. Its main purpose is to make external Occam2D projects reproducible from pycsamt.inversion.config.InversionConfig and to return a common pycsamt.inversion.results.InversionResult.

Parameters:

config (pycsamt.inversion.config.InversionConfig) – Inversion configuration. Important fields are method, dimension, workdir, data, backend_options, run_external, error_floor, phase_error, and metadata.

Variables:

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

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

Notes

backend_options can contain:

config

An OccamConfig instance or dictionary used to configure file names and binary settings.

files

Mapping from roles "data", "mesh", "model", and "startup" to existing or expected paths. Relative paths are resolved inside workdir.

runner

Runner-only options such as binary_path, startup_file, max_iter, target_misfit, and auto_compile.

binary_path

Convenience runner executable path when not supplied inside runner.

When a data source is supplied, InputBuilder receives the source and the configured error floors. Without a data source, the adapter treats backend_options["files"] as an existing Occam2D project and only validates whether it is ready to run or load.

Examples

Validate an existing Occam2D directory without executing the binary:

>>> from pycsamt.inversion.backends.occam2d import Occam2DBackend
>>> from pycsamt.inversion.config import InversionConfig
>>> cfg = InversionConfig(
...     method="mt",
...     dimension="2d",
...     backend="occam2d",
...     workdir="occam_run",
...     backend_options={
...         "files": {
...             "data": "OccamData.dat",
...             "mesh": "OccamMesh",
...             "model": "OccamModel",
...             "startup": "Startup",
...         }
...     },
... )
>>> result = Occam2DBackend(cfg).run()
>>> result.status in {"ready", "loaded", "needs_review"}
True

Run through the high-level workflow and allow external execution:

>>> from pycsamt.inversion.workflow import run_inversion
>>> result = run_inversion(
...     method="csamt",
...     dimension="2d",
...     backend="occam2d",
...     workdir="occam_csamt",
...     run_external=True,
...     backend_options={
...         "runner": {
...             "binary_path": "Occam2D",
...             "startup_file": "Startup",
...             "target_misfit": 1.0,
...         },
...         "files": {
...             "data": "OccamData.dat",
...             "mesh": "OccamMesh",
...             "model": "OccamModel",
...             "startup": "Startup",
...         },
...     },
... )

See also

pycsamt.inversion.workflow.InversionWorkflow

High-level entry point that instantiates this backend.

pycsamt.inversion.backends.modem.ModEMBackend

Similar external-run adapter for ModEM.

pycsamt.inversion.results.InversionResult

Backend-neutral result returned by run().

References

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

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

Parameters:

data (object, mapping, path-like, or sequence, optional) – Input source used by pycsamt.models.occam2d.InputBuilder. When omitted, self.config.data is used. If no source is supplied, configured file names are resolved inside workdir and the backend validates whether the runner can be launched.

Returns:

Backend-neutral result. The files mapping contains data, mesh, model, and startup file paths when known. metadata stores the command, startup file, binary name, external execution flag, exit code, and whether a runner was executed.

Return type:

InversionResult

Raises:

Notes

External execution is disabled unless self.config.run_external is True. With the default value, this method prepares or validates the directory and reports the command that would be used when all required files exist.

Status values follow the adapter lifecycle:

"prepared"

Files were prepared or configured, but the runner is not ready.

"ready"

Required files exist and an Occam2D command was assembled.

"executed"

The external runner returned exit code 0.

"loaded"

A finished Occam2D result with rho_2d was loaded.

"needs_review"

Preparation, runner execution, or result loading needs user review.

Examples

>>> from pycsamt.inversion.backends.occam2d import Occam2DBackend
>>> from pycsamt.inversion.config import InversionConfig
>>> cfg = InversionConfig(
...     method="mt",
...     dimension="2d",
...     backend="occam2d",
...     workdir="occam_run",
...     backend_options={
...         "files": {
...             "data": "OccamData.dat",
...             "mesh": "OccamMesh",
...             "model": "OccamModel",
...             "startup": "Startup",
...         }
...     },
... )
>>> result = Occam2DBackend(cfg).run()