16.3. Forward Configuration

Forward modelling should be reproducible. A synthetic response, training dataset, or grid experiment is only useful when another user can reconstruct the solver, model prior, sampled axis, station layout, noise model, and random seed.

The forward package provides three configuration dataclasses:

• pycsamt.forward.ForwardConfig for 1-D MT, CSAMT, and TEM dataset generation;

• pycsamt.forward.ForwardConfig2D for 2-D MT finite-difference runs;

• pycsamt.forward.ForwardConfig3D for quasi-3-D MT forward runs.

All three classes follow the same workflow:

1. write an annotated template;

2. edit the template as the project source of truth;

3. load the template back into Python;

4. validate before computation;

5. build arrays, grids, solvers, or dataset keyword arguments from the config;

6. archive the config next to datasets, figures, and interpretation notes.

16.3.1. Configuration Classes

Class	Main purpose	Main helpers
ForwardConfig	1-D MT/CSAMT/TEM synthetic dataset generation.	freq_grid(), time_grid(), to_dataset_kwargs(), write_template(), from_file(), summary().
ForwardConfig2D	2-D MT finite-difference grid and solver setup.	freq_grid(), to_grid(), to_solver_kwargs(), write_template(), from_file(), summary().
ForwardConfig3D	Quasi-3-D MT grid and solver setup.	freq_grid(), to_grid(), to_solver_kwargs(), write_template(), from_file(), summary().

16.3.2. Template Files

Forward configuration files can be written as Python, JSON, YML, or YAML. The file extension selects the format automatically. Templates include parameter comments, which makes them good review artifacts for scientific projects.

>>> from pycsamt.forward import ForwardConfig, ForwardConfig2D, ForwardConfig3D

>>> ForwardConfig.write_template("configs/forward_1d.yml")
>>> ForwardConfig2D.write_template("configs/forward_2d.yml")
>>> ForwardConfig3D.write_template("configs/forward_3d.yml")

Load the edited files with strict validation of keys:

>>> from pycsamt.forward import ForwardConfig

>>> cfg = ForwardConfig.from_file("configs/forward_1d.yml", strict=True)
>>> cfg.validate()
>>> print(cfg.summary())
ForwardConfig
  solver               = 'mt1d'
  freq_min             = 0.0001 Hz
  freq_max             = 1e+04 Hz
  n_freqs              = 30
  n_layers             = 3–7
  rho_min              = 1 Ω·m
  rho_max              = 1e+04 Ω·m
  depth_max            = 2e+03 m
  n_samples            = 10,000
  noise_level          = 0.05  (gaussian)
  seed                 = None
  n_jobs               = 1
  output               = ./forward_dataset.npz

This is an unedited template, so every field is still the class default – edit the values that matter for the experiment before loading it back. strict=True is recommended for production runs because misspelled keys raise an error instead of being ignored. Use strict=False only when loading a file that intentionally contains extra metadata.

16.3.3. 1-D Configuration

ForwardConfig controls the 1-D solver, frequency grid or time gate grid, random layered model prior, noise model, output path, and parallel worker count. The sampled axis is logarithmic: for frequency-domain solvers, \(f_i = 10^{a + i(b-a)/(n_f-1)}\) where \(a=\log_{10}(f_\min)\), \(b=\log_{10}(f_\max)\), and \(i=0,\ldots,n_f-1\). For TEM, the same construction is applied to time gates, \(t_i = 10^{c + i(d-c)/(n_t-1)}\), using \(c=\log_{10}(t_\min)\) and \(d=\log_{10}(t_\max)\). This makes the configuration compact while still recording every sampled point deterministically.

Setting group	Fields
Solver	solver, freq_min, freq_max, n_freqs, time_min, time_max, n_times, loop_radius.
Earth model prior	n_layers_min, n_layers_max, rho_min, rho_max, depth_max, geology.
Dataset	n_samples, noise_level, noise_type, include_phase, seed, n_jobs.
Output	output_dir, output_name, verbose.

The solver controls which sampled axis is active:

solver	Active axis	Main settings
"mt1d"	Frequency	freq_min, freq_max, n_freqs, include_phase.
"csamt1d"	Frequency	freq_min, freq_max, n_freqs, include_phase.
"tem1d"	Time gates	time_min, time_max, n_times, loop_radius.

Generate a 1-D MT training dataset:

>>> from pycsamt.forward import ForwardConfig, generate_dataset

>>> cfg = ForwardConfig(
...     solver="mt1d",
...     freq_min=1e-3,
...     freq_max=1e4,
...     n_freqs=40,
...     n_layers_min=3,
...     n_layers_max=7,
...     rho_min=1.0,
...     rho_max=10_000.0,
...     depth_max=3000.0,
...     n_samples=5000,
...     noise_level=0.05,
...     noise_type="field",
...     include_phase=True,
...     seed=42,
...     n_jobs=1,
...     output_dir="runs/forward",
...     output_name="mt1d_training",
... )

>>> cfg.validate()
>>> print(cfg.summary())
ForwardConfig
  solver               = 'mt1d'
  freq_min             = 0.001 Hz
  freq_max             = 1e+04 Hz
  n_freqs              = 40
  n_layers             = 3–7
  rho_min              = 1 Ω·m
  rho_max              = 1e+04 Ω·m
  depth_max            = 3e+03 m
  n_samples            = 5,000
  noise_level          = 0.05  (field)
  seed                 = 42
  n_jobs               = 1
  output               = runs/forward/mt1d_training.npz
>>> dataset = generate_dataset(**cfg.to_dataset_kwargs())

to_dataset_kwargs() builds the correct frequency or time array and constructs the output path. In this example the resolved frequency grid starts at 0.001 Hz and ends at 10000 Hz, with intermediate samples spaced evenly in \(\log_{10}(f)\). This reduces the risk of the config and the actual dataset generation call drifting apart.

16.3.4. Geological Priors

ForwardConfig.geology can replace broad rho_min/rho_max and depth_max sampling with a named geological prior. This is useful when an AI dataset should represent a known target class instead of arbitrary layered-earth variation.

Common prior names include:

sedimentary
crystalline
geothermal
marine
permafrost

>>> from pycsamt.forward import ForwardConfig, generate_dataset

>>> cfg = ForwardConfig(
...     solver="mt1d",
...     geology="geothermal",
...     n_layers_min=4,
...     n_layers_max=7,
...     n_samples=20_000,
...     noise_type="field",
...     seed=12,
...     output_dir="runs/forward",
...     output_name="geothermal_mt1d",
... )

>>> cfg.validate()
>>> print(cfg.summary())
ForwardConfig
  solver               = 'mt1d'
  freq_min             = 0.0001 Hz
  freq_max             = 1e+04 Hz
  n_freqs              = 30
  n_layers             = 4–7
  geology              = 'geothermal'
  n_samples            = 20,000
  noise_level          = 0.05  (field)
  seed                 = 12
  n_jobs               = 1
  output               = runs/forward/geothermal_mt1d.npz
>>> dataset = generate_dataset(**cfg.to_dataset_kwargs())

When geology is set, the geological prior should be documented in the project notes. A neural network trained on a narrow prior may not generalize outside that geological setting.

16.3.5. TEM Configuration

TEM uses time gates rather than frequency samples. The loop radius \(a\) enters the transmitter geometry, while the configured gates \(t_i\) control where the decay curve is sampled after current shutoff. Because the response changes rapidly at early time and slowly at late time, logarithmic spacing gives useful resolution across several decades without requiring a dense linear grid.

>>> from pycsamt.forward import ForwardConfig, generate_dataset

>>> cfg = ForwardConfig(
...     solver="tem1d",
...     time_min=1e-6,
...     time_max=1e-2,
...     n_times=25,
...     loop_radius=50.0,
...     n_layers_min=3,
...     n_layers_max=6,
...     n_samples=1000,
...     noise_type="gaussian",
...     noise_level=0.03,
...     seed=5,
...     output_dir="runs/forward",
...     output_name="tem1d_training",
... )

>>> cfg.validate()
>>> print(cfg.summary())
ForwardConfig
  solver               = 'tem1d'
  time_min             = 1e-06 s
  time_max             = 0.01 s
  n_times              = 25
  loop_radius          = 50.0 m
  n_layers             = 3–6
  rho_min              = 1 Ω·m
  rho_max              = 1e+04 Ω·m
  depth_max            = 2e+03 m
  n_samples            = 1,000
  noise_level          = 0.03  (gaussian)
  seed                 = 5
  n_jobs               = 1
  output               = runs/forward/tem1d_training.npz
>>> dataset = generate_dataset(**cfg.to_dataset_kwargs())

TEM generation can be slower than MT1D because the current implementation uses numerical integration for the step-off response. Start with a small n_samples value, inspect the response, then scale up.

16.3.6. 2-D Configuration

ForwardConfig2D creates a pycsamt.forward.Grid2D and solver keyword arguments for pycsamt.forward.MT2DForward. The finite-difference grid stores resistivity as a cell model \(\rho(x,z)\). For the rectangular anomaly case, the background resistivity \(\rho_b\) is used everywhere except inside the configured box, where \(\rho(x,z)=\rho_a\) for \(x_\mathrm{lo}\le x\le x_\mathrm{hi}\) and \(z_\mathrm{lo}\le z\le z_\mathrm{hi}\). Padding extends the numerical domain beyond the core survey area so boundary conditions are less visible in the predicted response.

Setting group	Fields
Solver	freq_min, freq_max, n_freqs.
Grid	nx, nz, x_max, z_max, n_pad, pad_factor.
Earth model	bg_rho, model_type, anomaly_rho, anomaly_x_lo, anomaly_x_hi, anomaly_z_lo, anomaly_z_hi.
Stations	n_stations, station_x_max.
Output	verbose.

The supported model_type values are:

model_type	Meaning
"halfspace"	Uniform background resistivity.
"anomaly"	Rectangular anomaly inside a background.
"random"	Random 2-D grid model generated by Grid2D.random.

Example 2-D anomaly run:

>>> from pycsamt.forward import ForwardConfig2D, MT2DForward

>>> cfg = ForwardConfig2D(
...     freq_min=1e-2,
...     freq_max=1e3,
...     n_freqs=25,
...     nx=50,
...     nz=35,
...     x_max=10_000.0,
...     z_max=6000.0,
...     n_pad=8,
...     pad_factor=1.3,
...     bg_rho=300.0,
...     model_type="anomaly",
...     anomaly_rho=10.0,
...     anomaly_x_lo=2500.0,
...     anomaly_x_hi=6500.0,
...     anomaly_z_lo=400.0,
...     anomaly_z_hi=1800.0,
...     n_stations=16,
...     verbose=False,
... )

>>> cfg.validate()
>>> print(cfg.summary())
ForwardConfig2D
  model_type             = 'anomaly'
  bg_rho                 = 300.0 Ω·m
  freq range             = 0.01–1e+03 Hz  (25 pts)
  grid (nx × nz)         = 50 × 35  (core, +8 pad)
  x_max                  = 10000 m
  z_max                  = 6000 m
  n_stations             = 16
  anomaly                = 10.0 Ω·m  x=[2500.0,6500.0]  z=[400.0,1800.0]

>>> grid = cfg.to_grid()
>>> solver = MT2DForward(grid=grid, **cfg.to_solver_kwargs())
>>> response = solver.run()
>>> features = response.to_feature_array(mode="both")
>>> features.shape
(16, 100)

Sixteen stations times the twenty-five sampled frequencies times both modes’ apparent resistivity and phase gives the hundred columns above – the same to_feature_array pattern used throughout Forward Modelling Concepts, now driven entirely by the config rather than by hand-built keyword arguments. Set verbose=True on ForwardConfig2D during long exploratory runs; it streams a per-frequency progress line to stdout, which is useful interactively but not worth capturing in a static transcript.

to_grid() accepts a seed argument for random models:

>>> cfg = ForwardConfig2D(model_type="random")
>>> cfg.validate()
>>> grid = cfg.to_grid(seed=42)
>>> grid.resistivity.shape
(38, 56)

The requested nx=40, nz=30 core is padded on every side that is not the free surface, so the stored array is larger than the core grid: eight padding cells on each side of nx (40 + 2*8 = 56) and eight beneath nz (30 + 8 = 38), with no padding added above z=0.

16.3.7. 2-D Grid Tuning

2-D forward runs are sensitive to grid design.

Parameter	Practical guidance
x_max	Should include all stations and enough side room that boundaries do not dominate the response.
z_max	Should extend below the expected maximum investigation depth.
nx and nz	Increase when anomalies are small or response gradients are sharp.
n_pad	Add side and bottom padding to reduce boundary artifacts.
pad_factor	Values around 1.2 to 1.5 are typical; 1.3 is a stable starting point.
n_stations	Should resolve the lateral scale of the target.

16.3.8. 3-D Configuration

ForwardConfig3D builds a pycsamt.forward.Grid3D and keyword arguments for pycsamt.forward.MT3DForward. The model is written as \(\rho(x,y,z)\), with station samples arranged over the horizontal \(x\) and \(y\) axes. In the documented quasi-3-D path, each requested frequency still follows the same log grid as the 2-D case, while the solver uses a practical approximation to produce survey-scale synthetic responses over a 3-D resistivity volume.

Setting group	Fields
Solver	freq_min, freq_max, n_freqs, method.
Grid	nx, ny, nz, x_max, y_max, z_max, n_pad, pad_factor.
Earth model	bg_rho, model_type, anomaly bounds, n_layers, lateral_variation, corr_length.
Stations	nx_stations, ny_stations.
Output	verbose.

The supported model_type values are:

model_type	Meaning
"halfspace"	Uniform 3-D background.
"block_anomaly"	Rectangular 3-D anomaly inside a background.
"random_layered"	Random horizontal layers with optional Gaussian-random-field lateral variation.

Example quasi-3-D block anomaly:

>>> from pycsamt.forward import ForwardConfig3D, MT3DForward

>>> cfg = ForwardConfig3D(
...     freq_min=1e-2,
...     freq_max=1e3,
...     n_freqs=15,
...     method="quasi3d",
...     nx=24,
...     ny=24,
...     nz=18,
...     x_max=9000.0,
...     y_max=9000.0,
...     z_max=5000.0,
...     n_pad=8,
...     bg_rho=500.0,
...     model_type="block_anomaly",
...     anomaly_rho=20.0,
...     anomaly_x_lo=2500.0,
...     anomaly_x_hi=6500.0,
...     anomaly_y_lo=2500.0,
...     anomaly_y_hi=6500.0,
...     anomaly_z_lo=500.0,
...     anomaly_z_hi=2000.0,
...     nx_stations=6,
...     ny_stations=6,
...     verbose=False,
... )

>>> cfg.validate()
>>> print(cfg.summary())
ForwardConfig3D
  method                   = 'quasi3d'
  model_type               = 'block_anomaly'  (bg=500.0 Ω·m)
  freq range               = 0.01–1e+03 Hz  (15 pts)
  grid (nx×ny×nz)          = 24×24×18  (core, +8 pad)
  extents (x,y,z)          = 9000 m × 9000 m × 5000 m
  stations                 = 6×6 = 36 total
  anomaly                  = 20.0 Ω·m  x=[2500.0,6500.0]  y=[2500.0,6500.0]  z=[500.0,2000.0]

>>> grid = cfg.to_grid()
>>> response = MT3DForward(grid=grid, **cfg.to_solver_kwargs()).run()
>>> x = response.to_feature_array(components="xy_yx")
>>> x.shape
(36, 60)

Thirty-six stations on the 6x6 layout, times the fifteen sampled frequencies, times the xy/yx components’ apparent resistivity and phase, gives the sixty columns above – config-driven quasi-3-D behaves exactly like the hand-built pycsamt.forward.Grid3D example in Forward Modelling Concepts, which is the point of routing both through the same to_feature_array convention.

Random layered 3-D model:

>>> cfg = ForwardConfig3D(
...     model_type="random_layered",
...     n_layers=5,
...     lateral_variation=True,
...     corr_length=2500.0,
...     nx_stations=7,
...     ny_stations=7,
... )

>>> cfg.validate()
>>> grid = cfg.to_grid(seed=42)
>>> grid.resistivity.shape
(23, 36, 36)

The default 20x20x15 core grid picks up the same eight-cell padding convention as the 2-D case, on every side except the free surface: nx = ny = 20 + 2*8 = 36 and nz = 15 + 8 = 23. pycsamt.forward.Grid3D stores resistivity as (nz, ny, nx), which is why the padded shape reads (23, 36, 36) rather than (36, 36, 23).

16.3.9. 3-D Configuration Notes

ForwardConfig3D.method currently validates to "quasi3d". The underlying solver code contains experimental hooks for fuller 3-D methods, but the documented configuration path is quasi-3-D. Treat quasi-3-D outputs as survey-scale synthetic responses, not as final production 3-D inversion results.

For production 3-D modelling or inversion, continue to:

• ModEM

• MARE2DEM

16.3.10. Validation

Call validate() before any expensive run. Validation catches basic range errors such as negative frequencies, invalid model types, impossible anomaly bounds, and invalid station counts.

>>> from pycsamt.forward import ForwardConfig2D

>>> cfg = ForwardConfig2D(freq_min=100.0, freq_max=10.0)

>>> try:
...     cfg.validate()
... except ValueError as exc:
...     print(f"Configuration problem: {exc}")
Configuration problem: freq_min must be > 0 and freq_max > freq_min.

Validation does not prove that the model is geologically meaningful. It only checks that the parameters are internally acceptable for the builder and solver.

16.3.11. Summaries And Provenance

Each config object provides summary() and repr output that can be saved in logs or reports.

>>> from pathlib import Path
>>> from pycsamt.forward import ForwardConfig2D

>>> cfg = ForwardConfig2D(model_type="anomaly")
>>> cfg.validate()

>>> run_dir = Path("runs/forward/2d_anomaly")
>>> run_dir.mkdir(parents=True, exist_ok=True)
>>> (run_dir / "summary.txt").write_text(cfg.summary(), encoding="utf-8")
363
>>> cfg.to_template(run_dir / "forward_config_2d.yml")

summary() contains the Ω·m resistivity unit, so pass encoding="utf-8" explicitly – on Windows, pathlib.Path otherwise defaults to the console code page and raises UnicodeEncodeError on that character.

16.3.12. What To Record

For reproducibility, record:

• config file path and format;

• solver type and dimensionality;

• frequency grid or time-gate grid;

• model prior or grid constructor;

• resistivity bounds, anomaly bounds, or geology prior;

• station layout;

• noise type and noise level;

• random seed;

• output dataset or figure paths;

• pyCSAMT version or commit;

• any manual edits made after grid creation.

16.3.13. Recommended Run Layout

runs/
  forward/
    mt1d_training/
      forward_config.yml
      summary.txt
      mt1d_training.npz
      sample_responses.png
    profile_2d_anomaly/
      forward_config_2d.yml
      summary.txt
      model.png
      pseudosection_te.png
    survey_quasi3d/
      forward_config_3d.yml
      summary.txt
      response_maps/

16.3.14. Common Mistakes

The generated dataset cannot be reproduced.

Record seed, configuration file, pyCSAMT version, and output path. Avoid manually changing keyword arguments outside the config.

The run validates but the response is not useful.

Validation only checks parameter ranges. Review frequency range, grid extents, anomaly size, station spacing, and plots.

TEM generation is unexpectedly slow.

Start with fewer samples or fewer time gates. TEM1D currently uses numerical integration for the step-off response.

The 2-D model has boundary artifacts.

Increase x_max, z_max, n_pad, or adjust pad_factor.

The 3-D response is treated as a production inversion result.

ForwardConfig3D documents quasi-3-D synthetic modelling. Use ModEM or MARE2DEM for production external-engine workflows.

16.3.15. Next Steps

• Solvers And Grids explains how configs create models and solvers.

• Synthetic Datasets And Noise explains dataset generation and train/validation splits.

• Forward Plotting shows how to inspect configured runs.

• From Forward Modelling To Inversion explains synthetic recovery workflows.