pydynamicestimator.tests.test_algebraic_parity
==============================================

.. py:module:: pydynamicestimator.tests.test_algebraic_parity

.. autoapi-nested-parse::

   Parity test for the device-private algebraic-equation mechanism.

   Runs the stock SynchronousSubtransientSP machine (stator currents inlined as
   explicit expressions) and SynchronousSubtransientSP_DAE (the same currents
   declared as device-private algebraic variables/equations and handed to the DAE
   solver) on the same system, and asserts the differential-state trajectories
   agree to integrator tolerance.

   This validates the full private-algebraic path: declaration, index allocation,
   finit with private unknowns, DAE assembly/solve, and the grid/output slicing.
   See docs/algebraic_equations_design.md and CHANGELOG_algebraic_equations.md.



Attributes
----------

.. autoapisummary::

   pydynamicestimator.tests.test_algebraic_parity.FIXTURE_ROOT
   pydynamicestimator.tests.test_algebraic_parity._COMMON


Functions
---------

.. autoapisummary::

   pydynamicestimator.tests.test_algebraic_parity.test_sp_dae_matches_eliminated_sp
   pydynamicestimator.tests.test_algebraic_parity.test_sp_dae_private_constraints_hold
   pydynamicestimator.tests.test_algebraic_parity.test_sp6_dae_matches_eliminated_sp6
   pydynamicestimator.tests.test_algebraic_parity.test_sp_dae_line_dyn_mixed_dae
   pydynamicestimator.tests.test_algebraic_parity._sorted_eig
   pydynamicestimator.tests.test_algebraic_parity.test_eigenvalue_analysis_line_dyn_mixed
   pydynamicestimator.tests.test_algebraic_parity.test_sp_dae_estimation_runs_and_matches


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

.. py:data:: FIXTURE_ROOT

.. py:data:: _COMMON

.. py:function:: test_sp_dae_matches_eliminated_sp()

   SP_DAE (explicit algebraic stator currents) must reproduce the stock SP
   (eliminated currents) on identical systems, to integrator tolerance.


.. py:function:: test_sp_dae_private_constraints_hold()

   The private stator-current constraints g = -i + <expr> must be satisfied
   along the SP_DAE trajectory: the recovered i_d/i_q (in y_full) equal the
   explicit expression evaluated on the states.


.. py:function:: test_sp6_dae_matches_eliminated_sp6()

   The originally-intended vehicle: the subtransient Sauer-Pai 6th-order
   machine with the 4-equation stator block (i_d, i_q, psi_d, psi_q) declared
   as device-private algebraics instead of eliminated by ca.solve. Must
   reproduce the eliminated SynchronousSubtransientSP6 to integrator tolerance.

   (SP6 was usable only after fixing a spurious 2*pi*f_n factor on its algebraic
   stator equations, which had inflated the init-Jacobian condition number to
   ~1e11; see CHANGELOG_algebraic_equations.md.)


.. py:function:: test_sp_dae_line_dyn_mixed_dae()

   Under line_dyn=True the network (voltages + line currents) is differential
   and the device-private algebraics are the only algebraic block — a mixed DAE.
   SP_DAE must run in this mode and reproduce the eliminated SP (which is a pure
   ODE there). The match is near machine precision because both integrate the
   same differential network states; only the linear private solve differs.


.. py:function:: _sorted_eig(sim)

.. py:function:: test_eigenvalue_analysis_line_dyn_mixed()

   Small-signal eigenvalue analysis for the mixed DAE (line_dyn=True with
   device-private algebraics). The privates are Schur-complemented out, leaving
   an nd = nx + nv + nl differential system. Because the eliminated ground model
   reduces to the same nd-dimensional system, the two spectra must coincide.
   Covers both SP_DAE (2 privates) and SP6_DAE (4 privates).


.. py:function:: test_sp_dae_estimation_runs_and_matches()

   A device with private algebraics runs through the full IEKF estimator and
   tracks the truth as well as the eliminated model. Exact parity is impossible
   (the two extra algebraic variables change the random noise-draw sequence), so
   we assert (a) the DAE estimate is finite, (b) it tracks the simulated truth
   to a sensible accuracy, and (c) it agrees closely with the eliminated-model
   estimate.