hermess.devices.governor ======================== .. py:module:: hermess.devices.governor Attributes ---------- .. autoapisummary:: hermess.devices.governor.GOVERNOR_REGISTRY Classes ------- .. autoapisummary:: hermess.devices.governor.Governor hermess.devices.governor.TGOV1 hermess.devices.governor.Droop hermess.devices.governor.GOVCONST Module Contents --------------- .. py:class:: Governor Bases: :py:obj:`abc.ABC` Abstract base class for turbine-governor models (pluggable strategy). Every governor must expose 'pm' -- the mechanical-power coupling variable consumed by the synchronous machine's swing equation. 'pm' may be declared either as a differential ``state`` (when the turbine has lag dynamics, e.g. TGOV1) or as a device-private ``algeb`` (when mechanical power is an instantaneous / algebraic function of the inputs, e.g. a pure-droop or constant-power model). The host resolves 'pm' wherever it lives via ``Synchronous.var_sym`` -- the swing equation is agnostic to the choice. Symmetric to :class:`~hermess.devices.avr.AVR`: the governor 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. It reads the machine's **absolute** per-unit speed via ``host.omega`` (1.0 at synchronism, NOT the deviation) and its setpoint via ``host.Pref``. .. py:method:: states() -> List[str] :abstractmethod: Return ordered list of differential-state names. .. py:method:: algebs() -> List[str] Return ordered list of device-private *algebraic* variable names. Default empty: most governors have turbine lag dynamics whose output 'pm' is a state. A governor whose mechanical power is an instantaneous function of its inputs returns ['pm'] here instead of listing it in :meth:`states`, and writes its defining residual ``0 = -pm + `` into ``dae.g`` in :meth:`fgcall`. .. py:method:: algebs_units() -> Dict[str, str] Units for each private algebraic (mirrors :meth:`units`). .. py:method:: algebs_x0() -> Dict[str, float] Initial guess for each private algebraic (Newton guess in finit). .. py:method:: units() -> List[str] :abstractmethod: Return units for each state, same length as states(). .. py:method:: params() -> Dict[str, float] :abstractmethod: Return dict of parameter names -> default values. .. py:method:: x0() -> Dict[str, float] :abstractmethod: Return default initial guess for each state. .. py:method:: descriptions() -> Dict[str, str] :abstractmethod: Return descriptions for states and params. .. py:method:: setpoints() -> Dict[str, float] :abstractmethod: Return setpoint names -> defaults (e.g., Pref). .. py:method:: fgcall(host, dae: hermess.system.Dae) -> None :abstractmethod: Write the governor's differential equations into ``dae.f`` and, if it declares private algebraics, their defining residuals into ``dae.g``. :param host: The Synchronous machine instance. Access state/algebraic indices via host.psv, host.pm, etc., parameters via host.Rd, host.Tch, ..., the absolute per-unit speed via host.omega and the setpoint via host.Pref. :param dae: The DAE system object. .. py:class:: TGOV1 Bases: :py:obj:`Governor` TGOV1 turbine-governor model as presented in Power System Dynamics and Stability by P.W. Sauer and M.A. Pai, 2006. (page 100) States: psv (steam valve position), pm (mechanical power). 'pm' is the coupling output to the swing equation. This is the framework default. The droop acts on the speed deviation ``omega - omega_net`` (omega_net = 1 p.u.); ``host.omega`` is the ABSOLUTE per-unit speed. ``Pref`` is the mechanical-power setpoint, so ``psv = pm = Pref`` at steady state. .. py:method:: states() -> List[str] Return ordered list of differential-state names. .. py:method:: units() -> List[str] Return units for each state, same length as states(). .. py:method:: params() -> Dict[str, float] Return dict of parameter names -> default values. .. py:method:: x0() -> Dict[str, float] Return default initial guess for each state. .. py:method:: descriptions() -> Dict[str, str] Return descriptions for states and params. .. py:method:: setpoints() -> Dict[str, float] Return setpoint names -> defaults (e.g., Pref). .. py:method:: fgcall(host, dae: hermess.system.Dae) -> None Write the governor's differential equations into ``dae.f`` and, if it declares private algebraics, their defining residuals into ``dae.g``. :param host: The Synchronous machine instance. Access state/algebraic indices via host.psv, host.pm, etc., parameters via host.Rd, host.Tch, ..., the absolute per-unit speed via host.omega and the setpoint via host.Pref. :param dae: The DAE system object. .. py:class:: Droop Bases: :py:obj:`Governor` Pure speed-droop governor with the mechanical power 'pm' declared as a device-private ALGEBRAIC variable. Primary frequency response without turbine lag dynamics: the mechanical power follows the speed deviation instantaneously (omega is the ABSOLUTE per-unit speed; the droop acts on omega - omega_net with omega_net = 1 p.u.), 0 = -pm + Pref - (omega - omega_net) / Rd # pm algebraic (no states) so at steady state pm = Pref. This is the ``Tch, Tsv -> 0`` (quasi-steady-state) limit of :class:`TGOV1`: at ``Tsv -> 0`` the valve gives ``psv = Pref - (omega-omega_net)/Rd`` and at ``Tch -> 0`` the chest gives ``pm = psv``. 'pm' rides the device-private-algebraic mechanism and the swing equation reads it through ``Synchronous.var_sym('pm')``, as for a state-valued 'pm'. .. py:method:: states() -> List[str] Return ordered list of differential-state names. .. py:method:: units() -> List[str] Return units for each state, same length as states(). .. py:method:: algebs() -> List[str] Return ordered list of device-private *algebraic* variable names. Default empty: most governors have turbine lag dynamics whose output 'pm' is a state. A governor whose mechanical power is an instantaneous function of its inputs returns ['pm'] here instead of listing it in :meth:`states`, and writes its defining residual ``0 = -pm + `` into ``dae.g`` in :meth:`fgcall`. .. py:method:: algebs_units() -> Dict[str, str] Units for each private algebraic (mirrors :meth:`units`). .. py:method:: algebs_x0() -> Dict[str, float] Initial guess for each private algebraic (Newton guess in finit). .. py:method:: params() -> Dict[str, float] Return dict of parameter names -> default values. .. py:method:: x0() -> Dict[str, float] Return default initial guess for each state. .. py:method:: descriptions() -> Dict[str, str] Return descriptions for states and params. .. py:method:: setpoints() -> Dict[str, float] Return setpoint names -> defaults (e.g., Pref). .. py:method:: fgcall(host, dae: hermess.system.Dae) -> None Write the governor's differential equations into ``dae.f`` and, if it declares private algebraics, their defining residuals into ``dae.g``. :param host: The Synchronous machine instance. Access state/algebraic indices via host.psv, host.pm, etc., parameters via host.Rd, host.Tch, ..., the absolute per-unit speed via host.omega and the setpoint via host.Pref. :param dae: The DAE system object. .. py:class:: GOVCONST Bases: :py:obj:`Governor` Constant mechanical power (no turbine/governor dynamics). The mechanical power is pinned to the finit-solved setpoint, 0 = -pm + Pref , i.e. the zero-response limit of :class:`Droop` (Rd → ∞). Used by models that deliberately exclude prime-mover dynamics, such as the 14-generator South East Australian benchmark (Gibbard & Vowles 2014), whose small- and large-signal models have no turbine/governor representation. .. py:method:: states() -> List[str] Return ordered list of differential-state names. .. py:method:: units() -> List[str] Return units for each state, same length as states(). .. py:method:: algebs() -> List[str] Return ordered list of device-private *algebraic* variable names. Default empty: most governors have turbine lag dynamics whose output 'pm' is a state. A governor whose mechanical power is an instantaneous function of its inputs returns ['pm'] here instead of listing it in :meth:`states`, and writes its defining residual ``0 = -pm + `` into ``dae.g`` in :meth:`fgcall`. .. py:method:: algebs_units() -> Dict[str, str] Units for each private algebraic (mirrors :meth:`units`). .. py:method:: algebs_x0() -> Dict[str, float] Initial guess for each private algebraic (Newton guess in finit). .. py:method:: params() -> Dict[str, float] Return dict of parameter names -> default values. .. py:method:: x0() -> Dict[str, float] Return default initial guess for each state. .. py:method:: descriptions() -> Dict[str, str] Return descriptions for states and params. .. py:method:: setpoints() -> Dict[str, float] Return setpoint names -> defaults (e.g., Pref). .. py:method:: fgcall(host, dae: hermess.system.Dae) -> None Write the governor's differential equations into ``dae.f`` and, if it declares private algebraics, their defining residuals into ``dae.g``. :param host: The Synchronous machine instance. Access state/algebraic indices via host.psv, host.pm, etc., parameters via host.Rd, host.Tch, ..., the absolute per-unit speed via host.omega and the setpoint via host.Pref. :param dae: The DAE system object. .. py:data:: GOVERNOR_REGISTRY :type: Dict[str, type]