hermess.devices.avr

Attributes

AVR_REGISTRY

Classes

AVR	Abstract base class for Automatic Voltage Regulator models.
IEEEDC1A	IEEEDC1A exciter and AVR model as presented in Power System Dynamics
AVRKundur_Filter	AVR model used in Kundur's book (Power System Stability and Control, 1994)
AVRKundur	Kundur 2-area AVR as a transducer + lead-lag, with the field voltage
AVRKundur_NoTGR	AVRKundur with the transient gain reduction (the lead-lag
AVRKundur_ODE	AVR model used in Kundur's book (Power System Stability and Control, 1994)
SEXST	AVR model used in Kundur's book (Power System Stability and Control, 1994)
AVRST1A	IEEE Std 421.5 ST1A static exciter (small-signal form, no limits).
AVRAC1A	IEEE Std 421.5 AC1A exciter (small-signal form, no limits/saturation).

Module Contents

class hermess.devices.avr.AVR

Bases: abc.ABC

Abstract base class for Automatic Voltage Regulator models.

Every AVR must expose ‘Efd’ – the field-voltage coupling variable consumed by the electromagnetic equations of the synchronous machine. ‘Efd’ may be declared either as a differential state (when the exciter is a pure lag, e.g. IEEEDC1A) or as a device-private algeb (when the exciter has a direct-feedthrough block such as a lead-lag, so its output is algebraic; see AVRKundur). The host resolves ‘Efd’ wherever it lives via Synchronous.var_sym – the machine equations are agnostic to the choice.

The AVR does NOT own state arrays or DAE indices. It declares what states, private algebraics, parameters, noise values, etc. it needs, and the host Synchronous machine registers them on itself.

abstract states() → List[str]

Return ordered list of differential-state names.

Return type:

List[str]

algebs() → List[str]

Return ordered list of device-private algebraic variable names.

Default empty: most AVRs are pure-lag exciters whose output ‘Efd’ is a state. An exciter with a direct-feedthrough (lead-lag) block returns [‘Efd’] here instead of listing it in states(), and writes its defining residual 0 = -Efd + <expr> into dae.g in fgcall(). These ride the device-private-algebraic mechanism (_algebs_int).

Return type:

List[str]

algebs_units() → Dict[str, str]

Units for each private algebraic (mirrors units()).

Return type:

Dict[str, str]

algebs_x0() → Dict[str, float]

Initial guess for each private algebraic (Newton guess in finit).

Return type:

Dict[str, float]

abstract units() → List[str]

Return units for each state, same length as states().

Return type:

List[str]

abstract params() → Dict[str, float]

Return dict of parameter names -> default values.

Return type:

Dict[str, float]

abstract x0() → Dict[str, float]

Return default initial guess for each state.

Return type:

Dict[str, float]

abstract descriptions() → Dict[str, str]

Return descriptions for states and params.

Return type:

Dict[str, str]

abstract setpoints() → Dict[str, float]

Return setpoint names -> defaults (e.g., Vf_ref).

Return type:

Dict[str, float]

abstract fgcall(host, dae: hermess.system.Dae) → None

Write the AVR’s differential equations into dae.f and, if the AVR declares private algebraics, their defining residuals into dae.g.

Parameters:

• host – The Synchronous machine instance. Access state/algebraic indices via host.Efd, host.Rf, etc. and parameters via host.KA, etc.

• dae (hermess.system.Dae) – The DAE system object.

Return type:

None

class hermess.devices.avr.IEEEDC1A

Bases: AVR

IEEEDC1A exciter and AVR model as presented in Power System Dynamics and Stability by P.W. Sauer and M.A. Pai, 2006. (page 100)

States: Efd, Rf, Vr (3 states)

states() → List[str]

Return ordered list of differential-state names.

Return type:

List[str]

units() → List[str]

Return units for each state, same length as states().

Return type:

List[str]

params() → Dict[str, float]

Return dict of parameter names -> default values.

Return type:

Dict[str, float]

x0() → Dict[str, float]

Return default initial guess for each state.

Return type:

Dict[str, float]

descriptions() → Dict[str, str]

Return descriptions for states and params.

Return type:

Dict[str, str]

setpoints() → Dict[str, float]

Return setpoint names -> defaults (e.g., Vf_ref).

Return type:

Dict[str, float]

fgcall(host, dae: hermess.system.Dae) → None

Write the AVR’s differential equations into dae.f and, if the AVR declares private algebraics, their defining residuals into dae.g.

Parameters:

• host – The Synchronous machine instance. Access state/algebraic indices via host.Efd, host.Rf, etc. and parameters via host.KA, etc.

• dae (hermess.system.Dae) – The DAE system object.

Return type:

None

class hermess.devices.avr.AVRKundur_Filter

Bases: AVR

AVR model used in Kundur’s book (Power System Stability and Control, 1994) for the 2-area system. A filter is added to the AVR output to prevent unrealistic fast dynamics and improve numerical stability.

states() → List[str]

Return ordered list of differential-state names.

Return type:

List[str]

units() → List[str]

Return units for each state, same length as states().

Return type:

List[str]

params() → Dict[str, float]

Return dict of parameter names -> default values.

Return type:

Dict[str, float]

x0() → Dict[str, float]

Return default initial guess for each state.

Return type:

Dict[str, float]

descriptions() → Dict[str, str]

Return descriptions for states and params.

Return type:

Dict[str, str]

setpoints() → Dict[str, float]

Return setpoint names -> defaults (e.g., Vf_ref).

Return type:

Dict[str, float]

fgcall(host, dae: hermess.system.Dae) → None

Write the AVR’s differential equations into dae.f and, if the AVR declares private algebraics, their defining residuals into dae.g.

Parameters:

• host – The Synchronous machine instance. Access state/algebraic indices via host.Efd, host.Rf, etc. and parameters via host.KA, etc.

• dae (hermess.system.Dae) – The DAE system object.

Return type:

None

class hermess.devices.avr.AVRKundur

Bases: AVR

Kundur 2-area AVR as a transducer + lead-lag, with the field voltage ‘Efd’ declared as a device-private ALGEBRAIC variable.

The lead-lag

Efd = KA * (1 + s*TA) / (1 + s*TB) * (Vf_ref - Vtr)

is proper but not strictly proper, so its output has a direct feedthrough and is genuinely algebraic. It is realized as one lag-pole state Vl plus the algebraic output:

Vtr_dot = (1/TR) (-Vtr + |V|) # transducer Vl_dot = (1/TB) (-Vl + KA (Vf_ref - Vtr)) # lag pole state 0 = -Efd + Vl (1 - TA/TB) + (TA/TB) KA (Vf_ref - Vtr) # Efd algebraic

The third line is the lead feedthrough D = TA/TB; Vl(1-TA/TB) + (TA/TB)KA(Vf_ref-Vtr) = KA(1+sTA)/(1+sTB)(Vf_ref-Vtr).

‘Efd’ is exposed via algebs() (not states()) and rides the device-private-algebraic mechanism; the host reads it through Synchronous.var_sym('Efd').

states() → List[str]

Return ordered list of differential-state names.

Return type:

List[str]

units() → List[str]

Return units for each state, same length as states().

Return type:

List[str]

algebs() → List[str]

Return ordered list of device-private algebraic variable names.

Default empty: most AVRs are pure-lag exciters whose output ‘Efd’ is a state. An exciter with a direct-feedthrough (lead-lag) block returns [‘Efd’] here instead of listing it in states(), and writes its defining residual 0 = -Efd + <expr> into dae.g in fgcall(). These ride the device-private-algebraic mechanism (_algebs_int).

Return type:

List[str]

algebs_units() → Dict[str, str]

Units for each private algebraic (mirrors units()).

Return type:

Dict[str, str]

algebs_x0() → Dict[str, float]

Initial guess for each private algebraic (Newton guess in finit).

Return type:

Dict[str, float]

params() → Dict[str, float]

Return dict of parameter names -> default values.

Return type:

Dict[str, float]

x0() → Dict[str, float]

Return default initial guess for each state.

Return type:

Dict[str, float]

descriptions() → Dict[str, str]

Return descriptions for states and params.

Return type:

Dict[str, str]

setpoints() → Dict[str, float]

Return setpoint names -> defaults (e.g., Vf_ref).

Return type:

Dict[str, float]

fgcall(host, dae: hermess.system.Dae) → None

Write the AVR’s differential equations into dae.f and, if the AVR declares private algebraics, their defining residuals into dae.g.

Parameters:

• host – The Synchronous machine instance. Access state/algebraic indices via host.Efd, host.Rf, etc. and parameters via host.KA, etc.

• dae (hermess.system.Dae) – The DAE system object.

Return type:

None

class hermess.devices.avr.AVRKundur_NoTGR

Bases: AVR

AVRKundur with the transient gain reduction (the lead-lag (1+sTA)/(1+sTB)) removed: a plain high-gain static exciter with only a terminal-voltage transducer.

Efd = KA * (Vf_ref - Vtr), Vtr = Vt / (1 + s*TR)

States: Vtr (transducer). Efd is the algebraic output KA*(Vf_ref - Vtr), an instantaneous gain on the transduced error, so it is declared as a private algebraic (read by the machine via Synchronous.var_sym('Efd')). Parameters: KA, TR.

With a high KA and no TGR this exciter reduces the damping of the electromechanical modes, the classic setting in which a power system stabilizer (PSS) is needed to restore damping. The PSS signal enters at the summing junction via host.pss_signal(dae) (0 when no PSS is attached).

states() → List[str]

Return ordered list of differential-state names.

Return type:

List[str]

units() → List[str]

Return units for each state, same length as states().

Return type:

List[str]

algebs() → List[str]

Return ordered list of device-private algebraic variable names.

Default empty: most AVRs are pure-lag exciters whose output ‘Efd’ is a state. An exciter with a direct-feedthrough (lead-lag) block returns [‘Efd’] here instead of listing it in states(), and writes its defining residual 0 = -Efd + <expr> into dae.g in fgcall(). These ride the device-private-algebraic mechanism (_algebs_int).

Return type:

List[str]

algebs_units() → Dict[str, str]

Units for each private algebraic (mirrors units()).

Return type:

Dict[str, str]

algebs_x0() → Dict[str, float]

Initial guess for each private algebraic (Newton guess in finit).

Return type:

Dict[str, float]

params() → Dict[str, float]

Return dict of parameter names -> default values.

Return type:

Dict[str, float]

x0() → Dict[str, float]

Return default initial guess for each state.

Return type:

Dict[str, float]

descriptions() → Dict[str, str]

Return descriptions for states and params.

Return type:

Dict[str, str]

setpoints() → Dict[str, float]

Return setpoint names -> defaults (e.g., Vf_ref).

Return type:

Dict[str, float]

fgcall(host, dae: hermess.system.Dae) → None

Write the AVR’s differential equations into dae.f and, if the AVR declares private algebraics, their defining residuals into dae.g.

Parameters:

• host – The Synchronous machine instance. Access state/algebraic indices via host.Efd, host.Rf, etc. and parameters via host.KA, etc.

• dae (hermess.system.Dae) – The DAE system object.

Return type:

None

class hermess.devices.avr.AVRKundur_ODE

Bases: AVR

AVR model used in Kundur’s book (Power System Stability and Control, 1994) for the 2-area system example with transient gain reduction.

All-ODE realization of the transducer + lead-lag controller: loop transfer function KA (1+sTA)/(1+sTB) on the error e = Vf_ref - Vtr with DC gain KA, realizing the lead as a derivative of the measurement. States are Efd, Vtr (Efd is a differential state via the TB lag). The setpoint-derivative term KA*TA*dVf_ref/dt is omitted; it is zero for a constant Vf_ref.

states() → List[str]

Return ordered list of differential-state names.

Return type:

List[str]

units() → List[str]

Return units for each state, same length as states().

Return type:

List[str]

params() → Dict[str, float]

Return dict of parameter names -> default values.

Return type:

Dict[str, float]

x0() → Dict[str, float]

Return default initial guess for each state.

Return type:

Dict[str, float]

descriptions() → Dict[str, str]

Return descriptions for states and params.

Return type:

Dict[str, str]

setpoints() → Dict[str, float]

Return setpoint names -> defaults (e.g., Vf_ref).

Return type:

Dict[str, float]

fgcall(host, dae: hermess.system.Dae) → None

Write the AVR’s differential equations into dae.f and, if the AVR declares private algebraics, their defining residuals into dae.g.

Parameters:

• host – The Synchronous machine instance. Access state/algebraic indices via host.Efd, host.Rf, etc. and parameters via host.KA, etc.

• dae (hermess.system.Dae) – The DAE system object.

Return type:

None

class hermess.devices.avr.SEXST

Bases: AVR

AVR model used in Kundur’s book (Power System Stability and Control, 1994) for the 2-area system example with transient gain reduction.

states() → List[str]

Return ordered list of differential-state names.

Return type:

List[str]

units() → List[str]

Return units for each state, same length as states().

Return type:

List[str]

params() → Dict[str, float]

Return dict of parameter names -> default values.

Return type:

Dict[str, float]

x0() → Dict[str, float]

Return default initial guess for each state.

Return type:

Dict[str, float]

descriptions() → Dict[str, str]

Return descriptions for states and params.

Return type:

Dict[str, str]

setpoints() → Dict[str, float]

Return setpoint names -> defaults (e.g., Vf_ref).

Return type:

Dict[str, float]

fgcall(host, dae: hermess.system.Dae) → None

Write the AVR’s differential equations into dae.f and, if the AVR declares private algebraics, their defining residuals into dae.g.

Parameters:

• host – The Synchronous machine instance. Access state/algebraic indices via host.Efd, host.Rf, etc. and parameters via host.KA, etc.

• dae (hermess.system.Dae) – The DAE system object.

Return type:

None

class hermess.devices.avr.AVRST1A

Bases: AVR

IEEE Std 421.5 ST1A static exciter (small-signal form, no limits).

As used by the 14-generator South East Australian benchmark (Gibbard & Vowles 2014, Fig. 20 / Tables 16 and 26):

Vc = Vt / (1 + s·Tr) (transducer) y1 = (1 + s·TC)/(1 + s·TB) · (Vf_ref − Vc + Vs) y2 = (1 + s·TC1)/(1 + s·TB1) · y1 (second lead-lag) Efd = KA/(1 + s·TA) · y2

Lead-lags are realized as a lag state plus direct feedthrough, so TB and TB1 must be > 0; a unity block is obtained exactly with TC == TB (and the SEA build uses a tiny equal pair when the data gives 0/0). Tr = 0 in the data is approximated by a small transducer lag (1e-4 s, a parasitic pole at 10⁴ rad/s, far above the rotor-mode range).

states() → List[str]

Return ordered list of differential-state names.

Return type:

List[str]

units() → List[str]

Return units for each state, same length as states().

Return type:

List[str]

params() → Dict[str, float]

Return dict of parameter names -> default values.

Return type:

Dict[str, float]

x0() → Dict[str, float]

Return default initial guess for each state.

Return type:

Dict[str, float]

descriptions() → Dict[str, str]

Return descriptions for states and params.

Return type:

Dict[str, str]

setpoints() → Dict[str, float]

Return setpoint names -> defaults (e.g., Vf_ref).

Return type:

Dict[str, float]

fgcall(host, dae: hermess.system.Dae) → None

Write the AVR’s differential equations into dae.f and, if the AVR declares private algebraics, their defining residuals into dae.g.

Parameters:

• host – The Synchronous machine instance. Access state/algebraic indices via host.Efd, host.Rf, etc. and parameters via host.KA, etc.

• dae (hermess.system.Dae) – The DAE system object.

Return type:

None

class hermess.devices.avr.AVRAC1A

Bases: AVR

IEEE Std 421.5 AC1A exciter (small-signal form, no limits/saturation).

As used by the 14-generator South East Australian benchmark (Gibbard & Vowles 2014, Fig. 21 / Tables 16 and 27); exciter saturation, armature reaction and rectifier regulation are neglected (KC = KD = 0), and the lead-lag is unity (TB = TC = 0 in the data):

Vf = s·KF/(1 + s·TF) · Efd (rate feedback) Vr = KA/(1 + s·TA) · (Vf_ref − Vt + Vs − Vf) TE · dEfd/dt = Vr − KE·Efd (rotating exciter)

The data has Tr = 0, so the terminal voltage is used unfiltered.

states() → List[str]

Return ordered list of differential-state names.

Return type:

List[str]

units() → List[str]

Return units for each state, same length as states().

Return type:

List[str]

params() → Dict[str, float]

Return dict of parameter names -> default values.

Return type:

Dict[str, float]

x0() → Dict[str, float]

Return default initial guess for each state.

Return type:

Dict[str, float]

descriptions() → Dict[str, str]

Return descriptions for states and params.

Return type:

Dict[str, str]

setpoints() → Dict[str, float]

Return setpoint names -> defaults (e.g., Vf_ref).

Return type:

Dict[str, float]

fgcall(host, dae: hermess.system.Dae) → None

Write the AVR’s differential equations into dae.f and, if the AVR declares private algebraics, their defining residuals into dae.g.

Parameters:

• host – The Synchronous machine instance. Access state/algebraic indices via host.Efd, host.Rf, etc. and parameters via host.KA, etc.

• dae (hermess.system.Dae) – The DAE system object.

Return type:

None

hermess.devices.avr.AVR_REGISTRY: Dict[str, type]