geopulse.devices.base

Abstract base class for nonlinear device models.

A DeviceModel takes a GIC time series (from the solver) and computes the device response: transformer magnetisation current, harmonic content, hot-spot temperature proxy, or cathodic-protection shift.

Classes

DeviceModel()	Abstract base class for nonlinear device models.
DeviceResponse(time_s, response_current_A, ...)	Container for a device response to GIC injection.

class geopulse.devices.base.DeviceModel

Bases: ABC

Abstract base class for nonlinear device models.

Subclasses:

• TransformerModel — saturation curve → half-cycle → THD.

• RectifierModel — bridge rectifier under DC bias.

• CathodicProtectionModel — PSP shift under telluric E-field.

abstractmethod inject_gic(time_s, gic_A, ac_voltage_V=0.0, ac_frequency_Hz=50.0)

Inject a GIC time series into the device and compute the response.

Parameters:

• time_s (ndarray) – Time array in seconds. Shape (n_times,).

• gic_A (ndarray) – GIC current in Amperes. Shape (n_times,).

• ac_voltage_V (float) – Nominal AC voltage (transformers only). Default: 0.0.

• ac_frequency_Hz (float) – AC system frequency in Hz. Default: 50.0.

Return type:

DeviceResponse

Returns:

DeviceResponse – Full response including harmonics and THD.

class geopulse.devices.base.DeviceResponse(time_s, response_current_A, thd, harmonics, top_oil_C=None, hotspot_C=None, metadata=<factory>)

Bases: object

Container for a device response to GIC injection.

Parameters:

• time_s (ndarray)

• response_current_A (ndarray)

• thd (float)

• harmonics (ndarray)

• top_oil_C (ndarray | None)

• hotspot_C (ndarray | None)

• metadata (dict)

time_s

Time array in seconds. Shape (n_times,).

Type:

numpy.ndarray

response_current_A

Device response current (e.g. magnetisation current). Shape (n_times,). Units: Amperes.

Type:

numpy.ndarray

thd

Total harmonic distortion (0 to 1, or NaN if not applicable).

Type:

float

harmonics

Harmonic amplitudes. Shape (n_harmonics,). Index 0 = fundamental.

Type:

numpy.ndarray

top_oil_C

Top-oil temperature time series in °C. Shape (n_times,). Set by TransformerModel; None for devices without a thermal model.

Type:

numpy.ndarray or None

hotspot_C

Winding hot-spot temperature time series in °C. Shape (n_times,). Set by TransformerModel.

Type:

numpy.ndarray or None

metadata

Additional device-specific outputs.

Type:

dict

time_s: ndarray

response_current_A: ndarray

thd: float

harmonics: ndarray

top_oil_C: ndarray | None = None

hotspot_C: ndarray | None = None

metadata: dict