geopulse.sources

B-field data adapters — SuperMAG, INTERMAGNET, MHD, synthetic.

Downstream modules never know which adapter produced the data; they only consume BFieldTimeSeries.

class geopulse.sources.BFieldSource

Bases: ABC

Abstract base class for magnetic-field data sources.

Subclasses must implement load() which returns a BFieldTimeSeries. All unit conversion (nT → T, local time → UTC epoch seconds) happens inside the subclass, never downstream.

Examples

>>> source = SyntheticSource(waveform="gaussian_pulse", amplitude_nT=500)
>>> b = source.load(start_s=0, end_s=3600, dt_s=1.0)
>>> b.bx_T.shape
(3600,)

abstractmethod load(start_s, end_s, dt_s=1.0, station_id='SYN')

Load or generate magnetic-field data for the given time window.

Parameters:

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

• end_s (float) – End time in seconds since epoch.

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

• station_id (str) – Station identifier. Default: "SYN".

Return type:

BFieldTimeSeries

Returns:

BFieldTimeSeries – Validated, SI-unit magnetic-field data.

to_frequency_domain(b_data)

Compute the FFT of the horizontal B-field components.

Concrete helper — NOT abstract — because the FFT is identical regardless of source type.

Parameters:

b_data (BFieldTimeSeries) – Time-domain magnetic-field data.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

• freqs_Hz (numpy.ndarray) – Frequency array in Hz. Shape: (n_freqs,). Positive frequencies only, including DC and Nyquist.

• Bx_f (numpy.ndarray) – FFT of bx_T in Tesla. Shape: (n_freqs,), complex.

• By_f (numpy.ndarray) – FFT of by_T in Tesla. Shape: (n_freqs,), complex.

Notes

Uses scipy.fft.rfft() for real-valued input.

class geopulse.sources.BFieldTimeSeries(time_s, bx_T, by_T, bz_T, station_id, latitude_deg, longitude_deg, sampling_rate_Hz=0.0, metadata=<factory>)

Bases: object

Standardised magnetic-field time-series container.

All values are in SI units (Tesla for field, seconds for time). This is the ONLY object that crosses the source → efield boundary.

Parameters:

• time_s (ndarray)

• bx_T (ndarray)

• by_T (ndarray)

• bz_T (ndarray)

• station_id (str)

• latitude_deg (float)

• longitude_deg (float)

• sampling_rate_Hz (float)

• metadata (dict)

time_s

Time array in seconds since epoch. Shape: (n_times,). Must be monotonically increasing with (approximately) uniform spacing.

Type:

numpy.ndarray

bx_T

North-south magnetic-field component in Tesla. Shape: (n_times,). Geographic north positive.

Type:

numpy.ndarray

by_T

East-west magnetic-field component in Tesla. Shape: (n_times,). Geographic east positive.

Type:

numpy.ndarray

bz_T

Vertical component in Tesla. Downward positive (geophysics convention).

Type:

numpy.ndarray

station_id

Station identifier (e.g. "OTT" for Ottawa).

Type:

str

latitude_deg

Geographic latitude, degrees north.

Type:

float

longitude_deg

Geographic longitude, degrees east.

Type:

float

sampling_rate_Hz

Sampling rate in Hz. Auto-computed from time_s if left at 0.

Type:

float

metadata

Arbitrary metadata (source, processing history, …).

Type:

dict

Notes

Frozen dataclass — immutable after construction. To modify, build a new instance.

time_s: ndarray

bx_T: ndarray

by_T: ndarray

bz_T: ndarray

station_id: str

latitude_deg: float

longitude_deg: float

sampling_rate_Hz: float = 0.0

metadata: dict

Modules

base	Abstract base class for magnetic-field data sources.
intermagnet	INTERMAGNET IAGA-2002 loader.
supermag	SuperMAG CSV / ASCII loader.
swmf_mhd	SWMF / Gamera MHD output adapter — STUB (WP4).
synthetic	Synthetic B-field waveforms for smoke tests and controlled experiments.