pydynamicestimator.devices.governor =================================== .. py:module:: pydynamicestimator.devices.governor Attributes ---------- .. autoapisummary:: pydynamicestimator.devices.governor.GOVERNOR_REGISTRY Classes ------- .. autoapisummary:: pydynamicestimator.devices.governor.Governor pydynamicestimator.devices.governor.TGOV1 pydynamicestimator.devices.governor.Droop 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:`~pydynamicestimator.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_noise() -> Dict[str, float] Relative process-noise weight for each private algebraic. .. 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:: states_noise() -> Dict[str, float] :abstractmethod: Return noise specification for each state. .. py:method:: states_init_error() -> Dict[str, float] :abstractmethod: Return initial error for each state. .. 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: pydynamicestimator.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. Equivalent dynamics to the previously hardcoded ``Synchronous.tgov1`` (which used the absolute ``omega`` and absorbed the constant ``1/Rd`` into the solved ``Pref``) -- the trajectory is identical; the only difference is that ``Pref`` is now the actual mechanical-power setpoint (``psv = pm = Pref`` at steady state) instead of ``pm + 1/Rd``. .. 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:: states_noise() -> Dict[str, float] Return noise specification for each state. .. py:method:: states_init_error() -> Dict[str, float] Return initial error for each state. .. 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: pydynamicestimator.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` -- one verifies that at ``Tsv -> 0`` the valve gives ``psv = Pref - (omega-omega_net)/Rd`` and at ``Tch -> 0`` the chest gives ``pm = psv``. It is the governor-side counterpart of the algebraic-``Efd`` lead-lag exciter: 'pm' rides the device-private-algebraic mechanism and the swing equation reads it through ``Synchronous.var_sym('pm')``, exactly 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_noise() -> Dict[str, float] Relative process-noise weight for each private algebraic. .. 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:: states_noise() -> Dict[str, float] Return noise specification for each state. .. py:method:: states_init_error() -> Dict[str, float] Return initial error for each state. .. 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: pydynamicestimator.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]