pycsamt.forward.config#

Configuration for pyCSAMT 1-D forward modelling and dataset generation.

The module exposes ForwardConfig, a dataclass that collects every tuneable parameter used by generate_dataset() and the three 1-D forward solvers. Users can:

  1. Call ForwardConfig.write_template() to generate a fully annotated source-of-truth file (Python, JSON, or YAML).

  2. Edit the file to match their survey setup and earth-model priors.

  3. Load the edited file with ForwardConfig.from_file() and pass the resulting object to ForwardConfig.to_dataset_kwargs().

Quick start#

Generate a default template, edit it, run dataset generation:

from pycsamt.forward.config import ForwardConfig

# 1 — write an annotated source-of-truth file
ForwardConfig.write_template("my_forward.py")

# 2 — edit values in my_forward.py …

# 3 — load and run
cfg = ForwardConfig.from_file("my_forward.py")
cfg.validate()

from pycsamt.forward.batch import generate_dataset
ds = generate_dataset(**cfg.to_dataset_kwargs())

Alternatively, construct the config entirely in Python:

cfg = ForwardConfig(
    solver="mt1d",
    n_samples=20_000,
    n_layers_min=3,
    n_layers_max=7,
    noise_level=0.03,
    seed=42,
)
ds = generate_dataset(**cfg.to_dataset_kwargs())

Classes

ForwardConfig([solver, freq_min, freq_max, ...])

Collect settings that define a 1-D forward modelling / dataset run.
class pycsamt.forward.config.ForwardConfig(solver='mt1d', freq_min=0.0001, freq_max=10000.0, n_freqs=30, time_min=1e-06, time_max=0.01, n_times=25, loop_radius=50.0, n_layers_min=3, n_layers_max=7, rho_min=1.0, rho_max=10000.0, depth_max=2000.0, geology=None, n_samples=10000, noise_level=0.05, noise_type='gaussian', include_phase=True, seed=None, n_jobs=1, output_dir='.', output_name='forward_dataset', verbose=True)[source]#

Bases: object

Collect settings that define a 1-D forward modelling / dataset run.

ForwardConfig is the central configuration object for generate_dataset() and the three 1-D solvers. All fields are plain Python scalars so that the dataclass can be serialised to Python, JSON, and YAML without any numpy dependencies.

The recommended workflow is:

  1. Generate a template with write_template().

  2. Edit the values in the generated file.

  3. Load the edited file with from_file().

  4. Optionally call validate() to catch range errors early.

  5. Pass to_dataset_kwargs() to generate_dataset().

Parameters:

  • solver ({'mt1d', 'csamt1d', 'tem1d'}) – Forward solver.

  • freq_min (float) – Frequency grid bounds [Hz] for MT/CSAMT.

  • freq_max (float) – Frequency grid bounds [Hz] for MT/CSAMT.

  • n_freqs (int) – Number of logarithmically spaced frequency points.

  • time_min (float) – Time-gate grid bounds [s] for TEM.

  • time_max (float) – Time-gate grid bounds [s] for TEM.

  • n_times (int) – Number of logarithmically spaced time-gate points.

  • loop_radius (float) – TEM transmitter loop radius [m].

  • n_layers_min (int) – Layer count range (inclusive). Equal values fix the count.

  • n_layers_max (int) – Layer count range (inclusive). Equal values fix the count.

  • rho_min (float) – Resistivity bounds [Ω·m] for the random prior.

  • rho_max (float) – Resistivity bounds [Ω·m] for the random prior.

  • depth_max (float) – Maximum total depth [m] across all layers except the halfspace.

  • geology (str or None) – Geological prior scenario name; overrides rho/depth bounds when set.

  • n_samples (int) – Number of (model, response) pairs to generate.

  • noise_level (float) – Relative noise standard deviation (0 = noise-free).

  • noise_type (str) – Noise model: 'gaussian', 'multiplicative', 'field'.

  • include_phase (bool) – Include impedance phase in the MT/CSAMT feature vector.

  • seed (int or None) – Global random seed for reproducibility.

  • n_jobs (int) – Parallel worker count (-1 = all cores).

  • output_dir (str or None) – Directory for the saved .npz dataset. None skips saving.

  • output_name (str) – Base file name (without extension) for the saved dataset.

  • verbose (bool) – Print progress and summary.

Examples

Default MT1D configuration:

>>> cfg = ForwardConfig()
>>> cfg.solver
'mt1d'

Fixed 5-layer configuration with geology prior:

>>> cfg = ForwardConfig(
...     solver="mt1d",
...     n_layers_min=5,
...     n_layers_max=5,
...     geology="sedimentary",
...     n_samples=10_000,
...     seed=0,
... )

Generate a template file and round-trip:

>>> path = ForwardConfig.write_template("forward_config.py")
>>> cfg = ForwardConfig.from_file(path)
>>> cfg.solver
'mt1d'
solver: str = 'mt1d'#
freq_min: float = 0.0001#
freq_max: float = 10000.0#
n_freqs: int = 30#
time_min: float = 1e-06#
time_max: float = 0.01#
n_times: int = 25#
loop_radius: float = 50.0#
n_layers_min: int = 3#
n_layers_max: int = 7#
rho_min: float = 1.0#
rho_max: float = 10000.0#
depth_max: float = 2000.0#
geology: str | None = None#
n_samples: int = 10000#
noise_level: float = 0.05#
noise_type: str = 'gaussian'#
include_phase: bool = True#
seed: int | None = None#
n_jobs: int = 1#
output_dir: str | None = '.'#
output_name: str = 'forward_dataset'#
verbose: bool = True#
validate()[source]#

Check parameter ranges and raise ValueError on errors.

Call before a long dataset generation run to catch obvious mistakes (e.g. freq_min >= freq_max) before any compute is spent.

Raises:

ValueError – Descriptive message pointing to the offending parameter.

Return type:

None

freq_grid()[source]#

Return the logarithmically spaced frequency array [Hz].

This is the array that would be passed as freqs to the MT/CSAMT solvers and to generate_dataset().

Return type:

numpy.ndarray, shape (n_freqs,)

time_grid()[source]#

Return the logarithmically spaced time-gate array [s].

This is the array that would be passed as times to the TEM solver and to generate_dataset().

Return type:

numpy.ndarray, shape (n_times,)

to_dataset_kwargs()[source]#

Assemble keyword arguments for generate_dataset().

The returned dict is ready to be unpacked directly:

from pycsamt.forward.batch import generate_dataset
ds = generate_dataset(**cfg.to_dataset_kwargs())
Returns:

All keyword arguments for generate_dataset, with numpy arrays built from the stored scalar parameters.

Return type:

dict

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

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

Parameters:

  • path (path-like, default "forward_config.py") – Destination file. Suffixes .py, .json, .yml, and .yaml select the output format automatically.

  • fmt ({"py", "json", "yml", "yaml"}, optional) – Explicit format override. When omitted, the suffix of path is used. Paths without a suffix default to Python.

Returns:

Path of the generated file.

Return type:

pathlib.Path

classmethod write_template(path='forward_config.py', *, fmt=None)[source]#

Generate a documented source-of-truth configuration file.

Creates a file with default parameter values and an inline comment for every parameter explaining its role. Edit the generated file, then load it with from_file().

Parameters:

  • path (path-like, default "forward_config.py") – Destination file. The suffix determines the output format (.py, .json, .yml).

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

Returns:

Path of the generated file.

Return type:

pathlib.Path

Examples

>>> from pycsamt.forward.config import ForwardConfig
>>> path = ForwardConfig.write_template("my_forward.yml")
>>> path.suffix
'.yml'
classmethod from_file(path, *, strict=True)[source]#

Load a 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 keys raise ValueError. If False, unknown keys are silently ignored.

Returns:

Configuration populated from the file values.

Return type:

ForwardConfig

Examples

>>> ForwardConfig.write_template("forward_config.json")
PosixPath('forward_config.json')
>>> cfg = ForwardConfig.from_file("forward_config.json")
>>> cfg.solver
'mt1d'
classmethod read(path, *, strict=True)#

Alias — matches the convention used by ModEmConfig and OccamConfig.

Parameters:
Return type:

ForwardConfig

summary()[source]#

Return a human-readable multi-line summary of the configuration.

Return type:

str