pydynamicestimator.tests.test_shaft
===================================

.. py:module:: pydynamicestimator.tests.test_shaft

.. autoapi-nested-parse::

   Pluggable rotor-shaft strategy test (multi-mass torsional shaft).

   The rotor mechanics are a pluggable strategy. The default :class:`SingleMass`
   reproduces the classic single rigid-mass swing equation (its byte-equivalence is
   gated by the unchanged positional baselines in
   test_recur_sim/test_recur_est/test_run_ideal). A multi-mass (torsional) shaft
   keeps the generator mass on the canonical ``delta``/``omega`` names -- so the
   electromagnetic model, the network injection, the governor, the PSS and the
   initialisation are untouched -- and adds further rotor masses
   ``delta_<name>``/``omega_<name>``.

   This validates :class:`Shaft4Mass` (HP--IP--LP--GEN) and :class:`Shaft5Mass`
   (HP--IP--LP--GEN--EXC):

   1. Structural: each extra mass adds exactly two differential states and no
      private algebraics; the generator mass stays 'delta'/'omega' as states 0/1.
   2. Steady state: every mass is synchronous (omega_i -> 1 p.u.) and the static
      shaft twist satisfies the torque balance -- each shaft section carries exactly
      the cumulative mechanical power of the turbine masses upstream of it.
   3. The disturbance excites the torsional dynamics (the inter-mass twist
      oscillates), i.e. the elastic shaft is genuinely modelled.

   See docs/algebraic_equations_design.md (shaft strategy).



Attributes
----------

.. autoapisummary::

   pydynamicestimator.tests.test_shaft._T_DIST


Functions
---------

.. autoapisummary::

   pydynamicestimator.tests.test_shaft.test_shaft_structural
   pydynamicestimator.tests.test_shaft.test_shaft_steady_state_torque_balance
   pydynamicestimator.tests.test_shaft.test_shaft_torsional_excitation


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

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


.. py:function:: test_shaft_structural()

   A multi-mass shaft adds exactly two differential states per extra mass and
   no private algebraics; the generator mass stays 'delta'/'omega' as states 0,1.


.. py:function:: test_shaft_steady_state_torque_balance()

   At the pre-disturbance steady state every mass is synchronous and the
   static shaft twist carries the cumulative upstream mechanical power: a shaft
   section between masses a (upstream) and b transmits sum(F_upstream)*pm, so
   K_ab*(delta_a - delta_b) == sum(F_upstream)*pm.


.. py:function:: test_shaft_torsional_excitation()

   The disturbance excites the elastic shaft: the inter-mass twist is flat
   before the disturbance (rigid-body steady state) and oscillates afterwards.