pydynamicestimator.tests.test_pss
=================================

.. py:module:: pydynamicestimator.tests.test_pss

.. autoapi-nested-parse::

   Pluggable-PSS test (the inter-strategy coupling case).

   The power system stabilizer is a pluggable strategy whose output 'Vs' is summed
   into the AVR voltage error -- a strategy-to-strategy coupling kept host-mediated
   (`Synchronous.pss_signal` returns the 'Vs' symbol, or 0 when no PSS is present;
   each AVR reads it). 'Vs' is a device-private algebraic (washout + lead-lag has
   direct feedthrough on the speed deviation). This validates:

   1. The PSSKundur output satisfies its defining equation along the trajectory.
   2. The washout blocks DC: 'Vs' is ~0 at steady state and only acts on the
      post-disturbance transient.
   3. The PSS measurably changes the machine dynamics versus no PSS (the
      host-mediated PSS -> AVR -> machine coupling works), and adds exactly its
      three states + one private algebraic.

   (Byte-equivalence of the no-PSS path is covered by the unchanged positional
   baselines in test_recur_sim/test_recur_est/test_run_ideal.)

   See docs/algebraic_equations_design.md and CHANGELOG_algebraic_equations.md.



Attributes
----------

.. autoapisummary::

   pydynamicestimator.tests.test_pss._T_DIST


Functions
---------

.. autoapisummary::

   pydynamicestimator.tests.test_pss.test_pss_constraint_holds
   pydynamicestimator.tests.test_pss.test_pss_washout_and_coupling
   pydynamicestimator.tests.test_pss.test_pss_per_machine_vectorization


Module Contents
---------------

.. py:data:: _T_DIST
   :value: 3.0


.. py:function:: test_pss_constraint_holds()

   The PSS's algebraic output must satisfy its defining equation along the
   whole trajectory: Vs == vl2*(1-T3/T4) + (T3/T4)*y1, with
   y1 = vl1*(1-T1/T2) + (T1/T2)*w and washout output w = K_stab*(omega-1) - vw.
   Note `omega` is the ABSOLUTE per-unit speed, so the PSS input is the deviation
   omega - omega_net (omega_net = 1 p.u.).


.. py:function:: test_pss_washout_and_coupling()

   The PSS adds its three states + one private algebraic; its washout blocks
   DC (Vs ~ 0 at the pre-disturbance steady state, active afterwards); and it
   measurably changes the machine dynamics versus the no-PSS reference.


.. py:function:: test_pss_per_machine_vectorization()

   With multiple machines in one vectorized device group, each PSS must use
   its OWN absolute speed minus the common nominal (omega_i - omega_net) and its
   OWN parameters -- not machine 0's. Two SGs carry PSSKundur with different
   K_stab/Tw/T*; each machine's Vs must satisfy its own defining equation.