Tangential Schur Pick and J-inner diagnostics

Tutorial goal

Check definite right-tangential Schur data with a Pick matrix and verify elementary Potapov J-inner factors.

Note

New to the terminology? See the lattice DSP concept map and the causality/data-use guide for how online, offline, block, and MIMO examples should be read.

Context

Tangential interpolation asks a matrix-valued Schur function to match only selected input directions rather than every column of the transfer matrix. This tutorial uses data generated from a known constant contraction so the Pick certificate, interpolation residual, and J-inner diagnostics can all be checked without hiding a difficult synthesis problem inside the example.

Key idea and equations

The right tangential data are

\[S(z_i)u_i = v_i, \qquad \lVert S\rVert_\infty \le 1.\]

The RKHS/de Branges–Rovnyak kernel for a Schur function is

\[K_S(z,w)=\frac{I-S(z)^HS(w)}{1-\overline z w}.\]

Testing this kernel on tangential directions gives the finite Pick Gram matrix

\[P_{ij}=u_i^H K_S(z_i,z_j)u_j =\frac{u_i^H u_j-v_i^H v_j}{1-\overline{z_i}z_j}.\]

Feasibility in the definite problem requires \(P\succeq0\). For each strict rank-one datum, the graph vector \(\xi_i=[v_i;u_i]\) has negative J-norm for

\[\begin{split}J=\begin{bmatrix}I_{out}&0\\0&-I_{in}\end{bmatrix}.\end{split}\]

The scalar Blaschke factor and its Potapov–Blaschke lift are

\[b_a(z)=\frac{z-a}{1-\overline a z}, \qquad \Theta_i(z)=I+(b_{z_i}(z)-1)P_{\xi_i}.\]

The projection \(P_{\xi_i}\) is J-orthogonal. The resulting \(\Theta_i\) is J-inner on the unit circle and annihilates \(\xi_i\) at \(z_i\).

Causality and data use

This is finite interpolation-data analysis, not streaming filtering. It is an offline Pick/J-inner diagnostic that explains the matrix-lattice background.

What this example verifies

This verifies the finite definite tangential-Schur baseline. The Pick matrix should be positive semidefinite, the known constant contraction should interpolate the data to roundoff, elementary Potapov factors should annihilate their graph vectors, and the factor product should be J-inner on the unit circle.

How to read the result

The Pick eigenvalues should be nonnegative, the constant solution residual should be near roundoff, and the J-inner residual should be near numerical precision.

Run command

python examples/tangential_schur_pick_jinner.py

Source code

"""Tangential Schur Pick, RKHS, and Potapov--Blaschke diagnostics.

This example is intentionally small but mathematically explicit.  It checks
finite right-tangential Schur data, the Pick/RKHS Gram matrix, a known constant
Schur solution, and elementary Potapov--Blaschke J-inner factors.

The factors here are interpolation-side J-inner objects.  They are related to
lossless/all-pass matrix-lattice systems, but this example is not the full
recursive tangential-Schur manifold algorithm used in the
Hanzon--Olivi--Peeters/Marmorat literature.
"""

from __future__ import annotations

import os
from pathlib import Path

import numpy as np

import lattice_dsp as ld


def _artifact_dir() -> Path:
    path = Path(os.environ.get("LATTICE_DSP_ARTIFACT_DIR", "reports/example-artifacts"))
    path.mkdir(parents=True, exist_ok=True)
    return path


def _save_figures(pick_eigs: np.ndarray, omega: np.ndarray, residuals: np.ndarray) -> None:
    try:
        import matplotlib.pyplot as plt
    except ImportError:  # pragma: no cover - optional plotting dependency
        print("matplotlib is not installed; skipped figures")
        return

    out_dir = _artifact_dir()

    fig, ax = plt.subplots(figsize=(6.8, 3.8))
    ax.plot(np.arange(1, pick_eigs.size + 1), pick_eigs, marker="o")
    ax.axhline(0.0, linestyle="--", linewidth=1.0)
    ax.set_xlabel("eigenvalue index")
    ax.set_ylabel("Pick eigenvalue")
    ax.set_title("Definite tangential Pick matrix is positive semidefinite")
    fig.tight_layout()
    fig.savefig(out_dir / "tangential_pick_eigenvalues.png", dpi=160)
    plt.close(fig)

    fig, ax = plt.subplots(figsize=(6.8, 3.8))
    ax.semilogy(omega, np.maximum(residuals, 1e-18))
    ax.set_xlabel("rad/sample")
    ax.set_ylabel(r"$\|\Theta^*J\Theta-J\|_2$")
    ax.set_title("Potapov product is J-inner on the unit circle")
    fig.tight_layout()
    fig.savefig(out_dir / "potapov_j_inner_residual.png", dpi=160)
    plt.close(fig)


rng = np.random.default_rng(52)
output_dim = 2
input_dim = 2
points = np.array([0.0, 0.22 - 0.10j, -0.30 + 0.08j, 0.15j])
raw = rng.normal(size=(output_dim, input_dim)) + 1j * rng.normal(size=(output_dim, input_dim))
known_schur = 0.45 * raw / np.linalg.svd(raw, compute_uv=False)[0]
directions = rng.normal(size=(points.size, input_dim)) + 1j * rng.normal(
    size=(points.size, input_dim)
)
values = np.einsum("oi,ni->no", known_schur, directions)

data = ld.RightTangentialSchurData(points, directions, values)
pick = ld.right_tangential_pick_matrix(data)
pick_eigs = ld.pick_matrix_eigenvalues(pick)
constant_solution = ld.constant_schur_solution(data)
residual = ld.max_tangential_residual(data, constant_solution)
product = ld.potapov_product_from_rank_one_data(data)
omega = np.linspace(0.0, 2.0 * np.pi, 256, endpoint=False)
theta = product.evaluate(np.exp(1j * omega))
j_residual = ld.j_unitarity_residual(theta, product.j)

print("points:", data.n_points)
print("input dimension:", data.input_dim)
print("output dimension:", data.output_dim)
print("total tangential conditions:", data.total_conditions)
print("known Schur spectral norm:", f"{np.linalg.svd(known_schur, compute_uv=False)[0]:.6f}")
print("Pick min eigenvalue:", f"{pick_eigs[0]:.6e}")
print("Pick condition number:", f"{np.linalg.cond(pick):.6e}")
print("definite Pick test says feasible:", ld.is_tangential_schur_solvable(data))
print("constant-solution interpolation residual:", f"{residual:.3e}")
print("Potapov product J-inner max residual:", f"{np.max(j_residual):.3e}")
print("first factor annihilation residual:", f"{product.factors[0].annihilation_residual():.3e}")
print("scope: finite definite Pick/RKHS/J-inner diagnostics")
print("not implemented here: full recursive tangential-Schur manifold parametrization")

_save_figures(pick_eigs, omega, j_residual)