geopulse.devices

Nonlinear device models: transformers, rectifiers, cathodic protection.

class geopulse.devices.DeviceModel[source]

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

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.DeviceResponse(time_s, response_current_A, thd, harmonics, top_oil_C=None, hotspot_C=None, metadata=<factory>)[source]

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

Modules

`base`	Abstract base class for nonlinear device models.
`cp_unit`	Cathodic-protection unit response to telluric E-field — STUB (WP3).
`harmonics`	FFT-based harmonic + THD extraction utilities — STUB (WP3).
`rectifier`	Bridge-rectifier model under DC bias — STUB (WP3).
`transformer`	Transformer thermal response — Mate et al. (2021) top-oil + hot-spot model.