geopulse.sources.synthetic

Synthetic B-field waveforms for smoke tests and controlled experiments.

Supports three families:

  • "gaussian_pulse" — B_x(t) = A · exp(-(t - t_0)² / (2σ²)) (WP1 primary).

  • "step" — Heaviside step, jumping from 0 to A at t = t_0.

  • "sinusoid" — single-frequency sinusoid at frequency_Hz.

All waveforms are placed on the bx_T component only (north-south). by_T and bz_T are zero — the plane-wave MT relation then produces a pure Ey response, which makes analytic validation trivial.

Amplitudes are supplied in nanoTesla for scientific convenience but are converted to Tesla at the loader boundary, per the SI-inside-the-core rule.

Classes

SyntheticSource(waveform[, amplitude_nT, ...])

Deterministic synthetic B-field waveforms.
class geopulse.sources.synthetic.SyntheticSource(waveform, amplitude_nT=100.0, *, t0_s=None, sigma_s=300.0, frequency_Hz=0.01, phase_rad=0.0, latitude_deg=45.0, longitude_deg=-75.0, **extra)[source]

Bases: BFieldSource

Deterministic synthetic B-field waveforms.

Parameters:

  • waveform (str) – Waveform family.

  • amplitude_nT (float) – Peak amplitude in nT. Default: 100.

  • t0_s (float | None) – Time of peak (gaussian_pulse) or edge (step), in seconds relative to start_s. Default: half-way through the window.

  • sigma_s (float) – Gaussian half-width (standard deviation), seconds. Default: 300.

  • frequency_Hz (float) – Sinusoid frequency in Hz. Default: 0.01 (100 s period).

  • phase_rad (float) – Sinusoid phase in radians. Default: 0.

  • latitude_deg (float) – Synthetic station coordinates. Default: (45, -75).

  • longitude_deg (float) – Synthetic station coordinates. Default: (45, -75).

  • extra (Any)

Raises:

DataError – If waveform is not one of the supported families.

Examples

>>> src = SyntheticSource("gaussian_pulse", amplitude_nT=500.0)
>>> b = src.load(start_s=0, end_s=3600, dt_s=1.0)
>>> b.bx_T.max() > 4.9e-7   # 500 nT ≈ 5e-7 T
True
load(start_s, end_s, dt_s=1.0, station_id='SYN')[source]

Generate the configured waveform.

Parameters:

  • start_s (float) – Start time (seconds since epoch, or 0 for synthetic).

  • end_s (float) – End time (seconds since epoch). Must satisfy end_s > start_s.

  • dt_s (float) – Sampling interval, seconds. Default: 1.0.

  • station_id (str) – Station identifier stored on the output. Default: "SYN".

Return type:

BFieldTimeSeries

Returns:

BFieldTimeSeries – SI-unit B-field time series with the waveform on bx_T and zeros on by_T, bz_T.

Raises:

DataError – If the time window is invalid.