Calibrating matrix-lattice static gain diagnostics
==================================================

.. admonition:: Tutorial goal

   Use a known matrix-lattice all-pass response to validate static gain compensation diagnostics.

.. 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 is a calibration case for the experimental realization scaffold.  It starts
from a known matrix-lattice all-pass response, wraps it in static nonunitary gains, and then
fits static left/right gains back around the lattice response.  The compensated error should
collapse when the only mismatch is static gain.

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

Given a lattice all-pass response ``G(e^{j\omega})`` and a target

.. math::

   H(e^{j\omega}) = L\,G(e^{j\omega})\,R,

the diagnostic solves a least-squares problem for static matrices ``L`` and ``R``.  This
separates static nonunitary gain mismatch from dynamic lattice/all-pass mismatch.

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

Look for near-zero all-pass calibration error and a large improvement after fitting static gains around the gain-wrapped lattice response.

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

.. code-block:: bash

   python examples/experimental_mimo_matrix_lattice_calibration.py

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

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