pycsamt.ai.inversion.run_config#

End-to-end run configuration for pyCSAMT AI inversion.

RunConfig is a thin container that bundles a ForwardConfig and an InversionConfig into one source-of-truth file. A single file then covers the complete experiment: synthetic dataset generation, network architecture, and training.

Supported file formats: Python (.py), JSON (.json), YAML (.yml).

Quick start#

Generate a default template, edit it, run:

from pycsamt.ai.inversion.run_config import RunConfig

# 1 — write a single annotated file that covers both forward and inversion
RunConfig.write_template("experiment_01.yml")

# 2 — edit experiment_01.yml …

# 3 — load, validate, and run
run = RunConfig.from_file("experiment_01.yml")
run.validate()

from pycsamt.forward.batch import generate_dataset

ds = generate_dataset(**run.to_dataset_kwargs())

inv = run.to_inverter()
inv.fit(ds, **run.to_fit_kwargs())
inv.save(run.checkpoint_path())

Cross-config validation#

RunConfig.validate() checks that the forward and inversion configs are consistent:

  • forward.solver must equal inversion.solver.

  • forward.include_phase must equal inversion.include_phase.

  • When the layer count is fixed (n_layers_min == n_layers_max), forward.n_layers_min must equal inversion.n_layers.

Classes

RunConfig([forward, inversion, name, ...])

Bundle a ForwardConfig and an InversionConfig into one source-of-truth experiment file.
class pycsamt.ai.inversion.run_config.RunConfig(forward=<factory>, inversion=<factory>, name='', description='')[source]

Bases: object

Bundle a ForwardConfig and an InversionConfig into one source-of-truth experiment file.

Parameters:

  • forward (ForwardConfig) – Dataset generation and solver settings.

  • inversion (InversionConfig) – Network architecture and training settings.

  • name (str) – Short experiment identifier written into the file header.

  • description (str) – Optional free-text note describing the experiment.

Notes

validate() checks internal consistency between the two sub-configs:

  • forward.solver == inversion.solver

  • forward.include_phase == inversion.include_phase

  • Fixed layer count (n_layers_min == n_layers_max) must match inversion.n_layers.

Examples

Default run (MT1D, ResNet, 5 layers):

>>> run = RunConfig()
>>> run.forward.solver
'mt1d'
>>> run.inversion.arch
'resnet'

Custom experiment:

>>> run = RunConfig(
...     forward=ForwardConfig(solver="mt1d", n_samples=20_000, seed=1),
...     inversion=InversionConfig(arch="resnet", n_layers=5, epochs=200),
...     name="mt1d_resnet_20k",
... )
>>> run.validate()

Write a template, edit it, reload:

>>> path = RunConfig.write_template("experiment_01.yml")
>>> run = RunConfig.from_file(path)
forward: ForwardConfig
inversion: InversionConfig
name: str = ''
description: str = ''
validate()[source]

Validate both sub-configs and their mutual consistency.

Raises:

ValueError – Descriptive message pointing to the offending parameter or the cross-config inconsistency.

Return type:

None

to_dataset_kwargs()[source]

Return kwargs for generate_dataset().

Delegates to ForwardConfig.to_dataset_kwargs().

Return type:

dict[str, Any]

to_inverter()[source]

Return a configured, untrained EMInverter1D.

Delegates to InversionConfig.to_inverter().

to_fit_kwargs()[source]

Return kwargs for fit().

Delegates to InversionConfig.to_fit_kwargs().

Return type:

dict[str, Any]

checkpoint_path()[source]

Return the checkpoint file path, or None if disabled.

Delegates to InversionConfig.checkpoint_path().

Return type:

Path | None

to_template(path='run_config.py', *, fmt=None)[source]

Write this run configuration to an annotated source-of-truth file.

Parameters:

  • path (path-like, default "run_config.py") – Destination. The suffix selects the format (.py, .json, .yml).

  • fmt ({"py", "json", "yml", "yaml"}, optional) – Explicit format override.

Return type:

pathlib.Path

classmethod write_template(path='run_config.py', *, fmt=None, name='', description='')[source]

Generate a documented source-of-truth run configuration file.

Writes a single file covering both dataset generation and network training with default parameter values and an inline comment for every parameter.

Parameters:

  • path (path-like, default "run_config.py") – Destination.

  • fmt ({"py", "json", "yml", "yaml"}, optional) – Explicit format override.

  • name (str) – Experiment name written into the file header.

  • description (str) – Free-text description written into the file header.

Return type:

pathlib.Path

Examples

>>> from pycsamt.ai.inversion.run_config import RunConfig
>>> path = RunConfig.write_template("experiment_01.yml")
>>> path.suffix
'.yml'
classmethod from_file(path, *, strict=True)[source]

Load a run configuration from a source-of-truth file.

Parameters:

  • path (path-like) – Python, JSON, YML, or YAML file generated by write_template() or following the same structure.

  • strict (bool, default True) – If True, unknown parameter keys raise ValueError. If False, unknown keys are silently ignored.

Return type:

RunConfig

Examples

>>> RunConfig.write_template("run.json")
PosixPath('run.json')
>>> run = RunConfig.from_file("run.json")
>>> run.forward.solver
'mt1d'
>>> run.inversion.arch
'resnet'
classmethod read(path, *, strict=True)

Alias — matches the convention used by ModEmConfig, OccamConfig, ForwardConfig.

Parameters:
Return type:

RunConfig

summary()[source]

Return a human-readable multi-line summary of the full run config.

Return type:

str