geopulse.sources.base

Abstract base class for magnetic-field data sources.

Every source adapter (SuperMAG, INTERMAGNET, synthetic, MHD) implements this interface. Downstream modules (efield, network) never know or care which source produced the B-field data — they only see BFieldTimeSeries.

Design principle: load raw data → convert to SI (Tesla) at the boundary → return a standardised container.

Classes

`BFieldSource`()	Abstract base class for magnetic-field data sources.
`BFieldTimeSeries`(time_s, bx_T, by_T, bz_T, ...)	Standardised magnetic-field time-series container.

class geopulse.sources.base.BFieldSource[source]

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')[source]

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)[source]

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.base.BFieldTimeSeries(time_s, bx_T, by_T, bz_T, station_id, latitude_deg, longitude_deg, sampling_rate_Hz=0.0, metadata=<factory>)[source]