[SebastianJiroSchlecht]

Summary

Implements the toolbox audit. It removes duplicated implementations, dead fallback code and one-function modules, fixes an RNG reproducibility bug, makes import pyFDN light, makes the delay state-space API consistent, and replaces Plotly with Matplotlib throughout.

As agreed, these two things are unchanged:

• Every non-Plotly top-level export stays. One name is added (plot_fdn_build). The two Plotly-only helpers downsampled_scatter and downsample_plotly_trace are removed.
• The nonlinear td operators stay in the library.

Changes

Bug fixes

• construct_cascaded_paraunitary_matrix (and the velvet/random_dense gallery types), shift_matrix_distribute and random_matrix_shift ignored np.random.seed, because they drew from an unseeded default_rng(); the tests had been patching around this. They now use NumPy's global state like the rest of generate/. A regression test is added.
• rt_to_gain_per_sample docstring: the level after RT seconds is −60 dB, not −30 dB.
• matrix_sqrt always returned float32. It now keeps the input's dtype.

Import time and dead code

• import pyFDN no longer loads torch or flamo: about 2.9 s → 0.9 s. The training API and flamo_to_pr load on first attribute access. tests/test_import.py guards this.
• flamo and scipy are required dependencies, so these are removed:
  • about a dozen "is flamo installed?" checks
  • the placeholder AttenuationFilter/OutputEQ classes
  • the scipy-less sqrtm fallback
• Removed auxiliary/coupled_rooms.py, a hand-wired FLAMO FDN used only by its own test; example_coupled_rooms covers the model.
• Removed the unused flareverb dependency, the dead docs/references.py, the setup.py shim and stale mypy overrides.

Merged duplicates (outputs checked against the old code)

• One time-domain engine. process_dss now renders through dss_to_td. dss_to_td runs post_delay directly on the delay output, so results are bit-identical to the old process_dss for LTI, time-varying and nonlinear hooks (checked for SOS, PitchShift, RingModulator and time-varying Kronecker hooks). dss_to_impz and build_to_impz share one impulse loop.
• One FLAMO builder. dss_to_flamo and trainable_from_build share one fdn_core().
• Energy decay curve. edc and energy_decay_curve share one Schroeder integral that works on NumPy arrays and torch tensors. The loss octave edges are derived from octave_bands() (same values).
• Residues. The residue formula and multipole handling exist once, used by both dss_to_pr and flamo_to_pr.
• Small helpers now written once: the random-orthogonal draw (was 3 copies), seed handling (3), default device (5), tensor-to-NumPy conversion (4), the losses' channels check (5), the RT-to-dB formula, and the filter target validation.

Consistency

• Breaking: delay state-space arguments are (delays, A, B, C, D) everywhere:

  • dss_to_flamo(delays, A, B, C, D, fs, ...)
  • is_allpass(delays, A, B, C, D)
  • dss_to_impz(delays, A, B, C, D, ir_len)

  All call sites in src/, tests/ and examples/ were rewritten mechanically with an AST script.

• Breaking: pole_boundaries takes the absorption as an (sections, 6, N) SOS bank (the FDNBuild.post_delay format) instead of a .b/.a object. Output is identical to the old version.

• Breaking: tiny_rotation_matrix and rotation_matrix_from_angles now return NumPy arrays; every caller already converted the torch result.

• Gallery names: all three galleries use snake_case type names ("nested_allpass", "velvet", …). The old fdnToolbox spellings are still accepted.

• Renames and defaults: plot_fdn_build is the new name (plot_FDN_build stays as an alias), and flamo_to_pr no longer prints progress by default.

Plotting: Matplotlib only

• Breaking: every plot function now returns a Matplotlib figure, built without pyplot so figures don't accumulate. Arguments and look are unchanged: zero-centred RdBu heatmaps, proportional block sizes, delay bars aligned with the columns of A, and curves coloured by delay length.
• Breaking: animate returns a Matplotlib FuncAnimation; in a notebook, show it with mo.Html(anim.to_jshtml()). The Plotly-only transition_ms argument is removed.
• SDN.visualize draws a Matplotlib 3-D axes.
• Breaking: downsampled_scatter and downsample_plotly_trace are removed.
• plotly is removed from every extra, and all example notebooks use Matplotlib. Ruff allows a bare fig as a cell's last expression in examples/, because that is how marimo displays a figure.

Less verbosity and structure

• In generate/, fifteen one-function modules become orthogonal.py, paraunitary.py and structures.py. The allpass structure builders move there and are still re-exported from pyFDN.allpass.
• fdn_build_gallery loses its two @overload copies of its signature.
• Duplicated rationale in the training docstrings is trimmed.

CI: a new lint job runs ruff check, ruff format --check and mypy, and mypy is clean. The four unformatted test files are now formatted. Optional imports (marimo, mpl_toolkits) are in mypy's ignore-missing-imports list, because the lint job doesn't install the examples extra.

Testing

• pytest passes locally: 523 passed, including all example notebooks (test_marimo_examples_run.py)
• marimo export html of several notebooks (animation, SDN, gallery, echo density) runs with no cell errors
• New tests: import stays light and every export resolves; seeded reproducibility of the paraunitary constructors; NumPy tiny rotation matrix; gallery name aliases; plot_FDN_build alias; plot and SDN tests now check the Matplotlib figures
• Coverage not measured separately

Checklist

• ruff check, ruff format --check and python -m mypy all clean
• Docstrings updated for the changed public API
• HISTORY.rst (Unreleased) and CONTRIBUTING.rst updated
• sdist and wheel build; check-wheel.py and twine check pass

🤖 Generated with Claude Code

https://claude.ai/code/session_01CNoCYhy16up9ifdTYpfUFX