Experimental MIMO state-space to matrix-lattice realization
===========================================================

.. admonition:: Tutorial goal

   Fit a stable matrix-lattice all-pass scaffold to the polar factor of a reduced MIMO state-space response.

.. note::

   New to the terminology? See the :doc:`lattice DSP concept map <../../algorithms/concept_map>` and the :doc:`causality/data-use guide <../../theory/causality_and_data_use>` for how online, offline, block, and MIMO examples should be read.

Context
-------

This tutorial promotes the previous bridge diagnostic into a small experimental solver-style
API.  A stable MIMO state-space model is first reduced with the finite block-Hankel baseline.
The experimental matrix-lattice helper then builds Markov-initialized all-pass scaffolds,
searches over reflection gains, and returns the lattice with the smallest error against the
reduced model's unitary polar factor.

The result is a useful matrix-lattice realization scaffold and initialization diagnostic.
Optional static gain compensation reports how much of the remaining mismatch can be explained
by constant left/right gains around the all-pass lattice.  It is still not a full matrix
AAK/Nehari solver and it does not realize arbitrary dynamic gain responses exactly.

Key idea and equations
----------------------

For a square MIMO response ``H(e^{j\omega})``, the target is its polar factor

.. math::

   U_p(e^{j\omega}) = U(e^{j\omega})V(e^{j\omega})^H,
   \qquad H=U\Sigma V^H.

Candidate matrix-lattice all-pass responses ``G_\alpha`` are built from Markov directions
and reflection gain ``\alpha``.  Static gain diagnostics then fit

.. math::

   H(e^{j\omega}) \approx L\,G_\alpha(e^{j\omega})\,R.

How to read the result
----------------------

Look for a stable lattice, unitarity error near numerical precision, selected gain, polar-factor fit error, and static-gain compensated error.  Treat this as an experimental all-pass realization scaffold.

Run command
-----------

.. code-block:: bash

   python examples/experimental_mimo_matrix_lattice_realization.py

Source code
-----------

.. literalinclude:: ../../../examples/experimental_mimo_matrix_lattice_realization.py
   :language: python
   :linenos: