Recommended learning path

lattice-dsp now contains several related pieces: stable scalar lattice filters, adaptive IIR examples, finite-Hankel model reduction, finite-section Nehari/AAK diagnostics, and matrix/MIMO lattice experiments. This page gives a suggested path through the documentation for new users.

Stage 0: orientation and theory map

Start here if the main question is: what niche does this package cover, and which algorithm should I use?

1. Package positioning

   Explains the uncommon combination of stable SISO IIR lattice filters, finite model-reduction diagnostics, MIMO block-Hankel reduction, and matrix-lattice all-pass scaffolds.

2. Choosing an algorithm

   Maps common DSP tasks to the package APIs, diagnostics, validation boundary, and out-of-scope areas.

3. Filtering relationships and signal-processing vocabulary

   Defines equalization, echo cancellation, prediction, adaptivity, recursivity, minimum phase, maximum phase, and the inner/outer viewpoint used by later lattice and model-reduction pages.

4. Choosing the right lattice-dsp algorithm

   Prints the same decision map from executable code and runs tiny API smoke checks.

5. Hardy, Hankel, reachability, and observability

   Introduces the Hardy-space, Hankel, reachability, and observability language used by the model-reduction pages.

Stage 0b: interoperability recipes

Read this page early if you want the package-wide array shape conventions, or if you already have state-space systems, room impulse responses, WAV files, Schur/Pick data, or audio data from another package and want to use lattice-dsp without adding hard dependencies.

1. Interoperability recipes

   Shows dependency-free conventions for scalar streams, online MIMO streams, batched MIMO state-space data, MIMO Markov tensors, MIMO AR coefficients, matrix-lattice reflections, right tangential Schur/Pick data, SciPy and state-space bridges, MATLAB/Octave exchange, Pyroomacoustics-style room.rir data, eSpeak/eSpeak NG WAV generation, standard-library WAV loading, and optional librosa/soundfile user-side loaders.

2. Pyroomacoustics MIMO RIR interoperability recipe

   Converts room.rir[mic][source] into a MIMO Markov tensor and applies the finite block-Hankel reducer.

3. External WAV and eSpeak/eSpeak NG interoperability recipe

   Demonstrates the WAV-to-NumPy boundary without requiring an audio I/O dependency in the package.

Stage 1: scalar stability and lattice coordinates

Start here if the main question is: why use lattice filters at all?

1. Reflection coefficients and denominator coefficients

   Reflection/PARCOR coefficients are the stable coordinate system behind the package. This tutorial shows the round trip between reflection coefficients and denominator polynomials.

2. Reflection coefficients as a stability coordinate system

   Shows reflection coefficients as a static stability coordinate system before the adaptive examples.

3. Why direct-form adaptive IIR updates can become unstable

   Direct-form denominator updates can leave the stable region. Bounded reflection updates keep the denominator in a stability-aware coordinate system.

4. Million-sample IIR throughput for long acoustic-like tails

   Shows the speed motivation for recursive models on million-sample signals: a compact stable IIR can represent a long acoustic-like decay with fixed state instead of a very long FIR tap vector.

5. Large echo-scale recursive model stress

   Extends the long-signal story to echo-scale model sizes: high-order stable recursive filtering is compared with the coefficient-traffic scale of a long FIR echo tap vector.

6. Scalar lattice and lattice-ladder IIR filters

   Read this after the first two examples for the scalar IIR/lattice-ladder formulas.

Stage 2: adaptive recursive filtering

Move here once the scalar lattice coordinates make sense.

1. Stable adaptive IIR system identification

2. Tracking a drifting stable IIR system

3. LMS through the H-infinity lens

4. Adaptive lattice filters: NLMS and RLS

5. LMS as a minimax robust filter

The H∞/minimax LMS tutorial is especially important for motivation: the same simple adaptive recursion can be interpreted through a worst-case energy-gain lens, not only as approximate least-squares optimization.

Stage 3: spectral diagnostics and AR models

These examples give visual intuition for AR/lattice modeling before moving to model reduction.

1. Periodogram versus AR spectral estimates

2. Capon/MVDR spectral estimation

3. Spectral diagnostics comparison and tuning

4. Burg and Levinson-Durbin AR tools

5. Spectral diagnostics: periodogram, AR, Burg, and Capon

6. AR estimation: autocorrelation, Levinson-Durbin, and Burg

Stage 4: finite-Hankel model reduction

This is the first model-reduction layer intended for practical use.

1. Reachability, observability, and Hankel singular values

   Explains why finite Hankel singular values are tied to reachable and observable state directions.

2. Finite Hankel SISO model reduction

3. Finite Hankel reduction amortization benchmark

4. Finite-Hankel and model-reduction API

The finite-Hankel reducer is a finite-section Ho–Kalman-style baseline. It is not advertised as exact AAK/Nehari reduction, but it is useful today and gives a reference point for the finite-section APIs.

Stage 5: finite Nehari/AAK diagnostics and SISO IIR reduction

Read this sequence in order. Each page adds one finite-dimensional layer.

1. Nehari and AAK intuition from a finite SISO Hankel matrix

2. Finite Nehari/AAK rank-sweep benchmark

3. Finite Nehari tail to rational model

4. AAK Schmidt-pair diagnostics for SISO Hankel approximation

5. Selecting a finite SISO AAK/Nehari rational candidate

6. Exact rational-tail validation for finite Nehari candidates

7. Finite-section SISO AAK/Nehari certificate

8. Finite-section AAK/Nehari reduction on a non-exact tail

9. Finite-section AAK/Nehari reduction of a stable IIR filter

10. Finite-section AAK/Nehari IIR reduction benchmark

This sequence is the current SISO AAK/Nehari path. It is best understood as a finite-section workflow: rank selection, Schmidt-pair certification, rational candidate fitting, exact-tail validation, and then application to stable IIR filters.

Stage 6: matrix/MIMO intuition and baselines

The matrix/MIMO material should be read after the scalar path. The key bridge is that a diagonal MIMO lattice is just independent SISO filters side by side.

1. Diagonal MIMO equals independent SISO

2. Online coupled MIMO prediction versus independent SISO

3. Matrix lattice all-pass response

4. Coupled MIMO matrix-lattice filtering

5. Paraunitary filter-bank behavior

6. Multichannel AR with block Levinson-Durbin

7. Causal online MIMO lattice prediction

8. Finite block-Hankel MIMO model reduction

9. Coupled MIMO finite-Hankel model reduction

10. MIMO long-signal state-space stress

    Stress the compiled MIMO runtime on long batched multichannel signals after finite block-Hankel reduction. This is the clearest scale demonstration for the package’s MIMO niche.

11. MIMO block-Hankel to matrix-lattice bridge diagnostics

12. Experimental MIMO state-space to matrix-lattice realization

13. Calibrating matrix-lattice static gain diagnostics

14. Matrix-lattice all-pass runtime benchmark

15. Matrix lattice all-pass filters

16. Multichannel AR and block Levinson

The MIMO block-Hankel reducer returns state-space matrices A, B, C, D from Markov parameters. This is the reference MIMO baseline for the current release scope. The bridge tutorial shows how reduced MIMO Markov data can seed a stable matrix-lattice all-pass scaffold. The experimental realization tutorial wraps this into a gain-search helper that fits the reduced model’s unitary polar factor. The calibration tutorial then fits static left/right gains around a known lattice response so readers can distinguish all-pass scaffold error from static nonunitary gain mismatch. The workflow remains an all-pass and static-gain diagnostic scaffold rather than a full dynamic realization of arbitrary nonunitary MIMO gain responses.

Status after this path

After completing the path, the package scope is:

Layer	Role	Status
Scalar lattice/IIR filtering	stable recursive filtering coordinates	implemented
Finite-Hankel SISO reduction	practical finite-section model-reduction baseline	implemented
Finite-section SISO AAK/Nehari workflow	rank selection, certificate, rational candidate, IIR reduction	implemented as finite-section baseline
MIMO diagonal sanity check	shows diagonal MIMO equals independent SISO filters	implemented
MIMO block-Hankel reduction	state-space baseline from Markov matrices	implemented
Compiled MIMO state-space runtime	batched coupled MIMO state-space simulation for reduced/full model comparisons	implemented
Matrix-lattice runtime and bridge diagnostics	all-pass runtime benchmark, coupled filter example, block-Hankel-to-lattice scaffold, and static gain calibration	implemented as diagnostics
Full infinite-dimensional SISO AAK/Nehari solver	exact scalar solver beyond finite sections	outside current scope
Matrix AAK/Nehari solver	MIMO/operator-theoretic solver	outside current scope
Full MIMO state-space to matrix-lattice realization solver	constructive dynamic realization of general reduced MIMO models in matrix-lattice coordinates	outside current scope

MIMO reduction extension

After the diagonal MIMO sanity check, read Coupled MIMO finite-Hankel model reduction and then the coupled MIMO benchmark. This shows the finite block-Hankel baseline on a dense state-space system and keeps it separate from matrix AAK/Nehari solvers, which are outside the current scope. The benchmark uses the compiled mimo_state_space_process_batch helper when available, which separates the runtime question from the reduction/certification question.

Theory motivation

Readers who want the mathematical motivation behind the stable-IIR and model-reduction examples should also read Interpolation, Schur stability, and why lattice coordinates help. It explains why Pick matrices can be ill-conditioned, why Schur/reflection coordinates are useful stability coordinates, how inner/outer factors relate to all-pass and spectral-factor ideas, and why Kronecker finite-rank structure motivates Hankel model reduction.