pydynamicestimator.tests.test_avr_algebraic
===========================================

.. py:module:: pydynamicestimator.tests.test_avr_algebraic

.. autoapi-nested-parse::

   Controller-side parity test for the device-private algebraic-equation mechanism.

   The generalized AVR strategy protocol lets an exciter expose its field voltage
   ``Efd`` as *either* a differential state (pure-lag exciter) *or* a device-private
   algebraic variable (direct-feedthrough / lead-lag exciter). This test exercises
   the latter via ``AVRKundur`` -- the Kundur transducer+lead-lag AVR with
   ``Efd`` as the lead's algebraic output -- and validates it two ways:

   1. The recovered ``Efd`` (in ``dae.y``) exactly satisfies its defining equation
      along the trajectory (internal consistency of the private-algebraic solve).
   2. The lead-lag (algebraic ``Efd``) reproduces ``AVRKundur_Filter`` -- the same
      exciter with a parasitic output filter that fakes ``Efd`` into a state -- in
      the ``Tfd -> 0`` singular-perturbation limit. The ``avr_filter`` fixture uses
      a small ``Tfd``, so the two systems must agree to ``O(Tfd)``.

   See docs/algebraic_equations_design.md and CHANGELOG_algebraic_equations.md.



Attributes
----------

.. autoapisummary::

   pydynamicestimator.tests.test_avr_algebraic.FIXTURE_ROOT
   pydynamicestimator.tests.test_avr_algebraic._COMMON


Functions
---------

.. autoapisummary::

   pydynamicestimator.tests.test_avr_algebraic._machine
   pydynamicestimator.tests.test_avr_algebraic.test_avr_leadlag_constraint_holds
   pydynamicestimator.tests.test_avr_algebraic.test_avr_leadlag_matches_filtered_limit
   pydynamicestimator.tests.test_avr_algebraic.test_avr_leadlag_estimation_runs_and_tracks


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

.. py:data:: FIXTURE_ROOT

.. py:data:: _COMMON

.. py:function:: _machine(which='sim')

   The synchronous-machine device from the most recent run.

   ``run`` resets ``system`` (clear_module) on entry, so this must be called
   immediately after a run and before the next one. ``which`` selects the
   simulation or estimation device list.


.. py:function:: test_avr_leadlag_constraint_holds()

   The lead-lag's algebraic field voltage must satisfy its defining equation
   along the whole trajectory: the recovered Efd (in y_full) equals
   Vl*(1 - TA/TB) + (TA/TB)*KA*(Vf_ref - Vtr) evaluated on the states.


.. py:function:: test_avr_leadlag_matches_filtered_limit()

   AVRKundur (Efd algebraic) must reproduce AVRKundur_Filter (Efd a
   state behind a fast parasitic filter) in the Tfd -> 0 limit. The avr_filter
   fixture uses Tfd = 1e-3, so the machine response must agree to O(Tfd).


.. py:function:: test_avr_leadlag_estimation_runs_and_tracks()

   An exciter whose field voltage Efd is a device-private ALGEBRAIC variable
   runs through the full IEKF estimator (qcall noise overlay, init-from-simulation
   seeding of the private, save/restore) and tracks the simulated truth as well as
   the eliminated/state-Efd models. Verifies the controller-side private rides the
   same estimation plumbing as the machine-side SP-DAE privates.