pyFDN 0.4.0__tar.gz → 0.4.2__tar.gz

{pyfdn-0.4.0 → pyfdn-0.4.2}/HISTORY.rst

@@ -2,9 +2,58 @@
 History
 =======
 
+0.4.2 (2026-08-27)
+------------------
+
+* Add the ``example_multislope_rir_to_fdn`` notebook: a measured room-transition
+  response is fitted with two decay slopes per octave band using DecayFitNet
+  from the ``multislope`` package, and each slope is resynthesised by its own
+  FDN. The response it uses ships with the package as the
+  ``meetingroom_to_hallway_290cm`` audio resource, taken from the coupled-rooms
+  transition dataset.
+* Add nonlinear and pitch-shifting time-domain operators for shimmer
+  reverberation -- ``DCBlocker``, ``ControllableFullWaveRect``, ``SDFD``,
+  ``RingModulator``, ``PitchShift`` and ``GranularPitchShift`` -- all usable as
+  ``process_fdn`` hooks, plus the ``example_shimmer_fdn`` notebook that walks
+  through each one inside the feedback loop of the same 8-line FDN.
+* ``is_uniallpass`` no longer solves a singular Lyapunov equation when ``A`` is
+  itself lossless (as in the allpass-in-FDN structure). The spectral radius is
+  checked first and such a system is reported as not uniallpass, instead of the
+  result depending on whether LAPACK chose to warn or raise on the ill-
+  conditioned solve.
+* Fix a device mismatch when a loss built for one run is used in another: every
+  loss that holds a reference impulse response (``MatchCumulativeEnergy``,
+  ``MatchEnergyDecay``, ``MatchMagnitude``, ``MatchImpulseResponse``,
+  ``MatchSpectrogram``, ``MatchMelSpectrogram``) aligned its reference once, on
+  the first response it saw, and then handed that CPU tensor to a later CUDA
+  step -- the way a notebook cell that builds the loss but does not re-run on a
+  runtime switch would hit it. The aligned reference is now keyed on the
+  response's shape, device, dtype and sample rate, and rebuilt when any of them
+  changes. ``MatchSpectrogram`` and ``MatchMelSpectrogram`` also default their
+  ``device`` to the response's rather than to the CPU, so FLAMO builds its
+  filterbanks where the model is.
+
+0.4.1 (2026-08-24)
+------------------
+
+* Let ``fdn_build_gallery`` and the target-to-EQ functions optionally return
+  the design choices used to produce their coefficients, ready to store in an
+  ``FDNPreset``. Build generation now also exposes the delay distribution and
+  coprimality options and lives separately from the matrix galleries.
+* **Breaking:** rename the ``Fs`` parameter to ``fs`` everywhere it is still
+  spelled with a capital -- ``dss_to_flamo``, ``dss_to_pr``, ``delay_module``
+  and ``SDN``. Every other sampling-rate argument in the package was already
+  ``fs``, and the odd one out forced callers to remember which spelling each
+  function wanted. ``SDN`` also renames its ``fs`` attribute and the ``"fs"``
+  key of the dictionary ``SDN.compute()`` returns.
+
 0.4.0 (2026-08-23)
 ------------------
 
+* Add ``FDNPreset`` JSON documents: a baked ``FDNBuild`` plus catalog
+  metadata and a controlled vocabulary for delays, matrices, and the three
+  filter hooks. ``trainable_from_preset`` restores filter targets as meaningful
+  FLAMO parameters only when they reproduce the baked coefficients.
 * **Breaking:** replace ``train_fdn``'s ``mode`` string, and the ``target``,
   ``criteria``, ``sparsity_alpha`` and ``mss_nfft`` arguments that went with
   it, with a composed loss object. An objective is now written out --
@@ -27,7 +76,7 @@ History
   from ``rt`` (``LOSSLESS_ALIAS_DECAY_DB`` when ``rt`` is None) and
   ``trainable_from_build`` threads it into every module, so a magnitude
   objective sees a bounded response.
-* Train the decay: ``DecayFilter`` parametrizes the in-loop absorption filter
+* Train the decay: ``AttenuationFilter`` parametrizes the in-loop absorption filter
   by reverberation time per band, so the loop stays contractive for every value
   the parameter can take, and takes either one RT curve for the network or one
   per delay line. ``OutputEQ`` trains the output filter outside the recursion,
@@ -43,7 +92,7 @@ History
   enumerates them.
 * Export the FLAMO graph builders (``assemble_fdn_core``, ``wrap_fdn_shell``,
   ``gain_module``, ``delay_module``, ``matrix_module``, ``fir_matrix_module``,
-  ``sos_filter_module``, ``hook_module``, ``DecayFilter``, ``OutputEQ``) from
+  ``sos_filter_module``, ``hook_module``, ``AttenuationFilter``, ``OutputEQ``) from
   the top-level namespace.
 * Make ``build_to_impz`` apply all three hooks, so it no longer rejects builds
   that carry an output EQ, and make ``extract_build`` refuse a hook it cannot

{pyfdn-0.4.0 → pyfdn-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyFDN
-Version: 0.4.0
+Version: 0.4.2
 Summary: Python library for Feedback Delay Networks
 Author: Sebastian J. Schlecht, Facundo Franchino, Jeremy Bai
 Maintainer: Facundo Franchino, Sebastian J. Schlecht
@@ -17,6 +17,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 License-File: src/pyFDN/resources/ATTRIBUTION.md
+License-File: src/pyFDN/resources/licenses/coupled-rooms-CC-BY-4.0.txt
 License-File: src/pyFDN/resources/licenses/diff-fdn-colorless-MIT.txt
 Requires-Dist: numpy
 Requires-Dist: soundfile
@@ -148,17 +149,17 @@ All main functions are accessible directly from the top-level ``pyFDN`` namespac
     feedback = pyFDN.random_orthogonal(len(delays))
 
     # one-pole absorption filters targeting RT of 1.2 s at DC and 0.9 s at Nyquist
-    absorption = pyFDN.one_pole_absorption(1.2, 0.9, delays, fs)
+    absorption = pyFDN.decay_to_one_pole(1.2, 0.9, delays, fs)
 
     # convert delay state-space to standard state-space (A_ss, b, c, d)
     A_ss, b, c, d = pyFDN.dss_to_ss(delays, feedback)
 
 Alternatively, import specific functions directly::
 
-    from pyFDN import random_orthogonal, one_pole_absorption, lin_to_db
+    from pyFDN import decay_to_one_pole, lin_to_db, random_orthogonal
 
     feedback = random_orthogonal(4)
-    absorption = one_pole_absorption(1.2, 0.9, [100, 150, 200, 250], 48_000)
+    absorption = decay_to_one_pole(1.2, 0.9, [100, 150, 200, 250], 48_000)
 
 
 Development

{pyfdn-0.4.0 → pyfdn-0.4.2}/README.rst

@@ -78,17 +78,17 @@ All main functions are accessible directly from the top-level ``pyFDN`` namespac
     feedback = pyFDN.random_orthogonal(len(delays))
 
     # one-pole absorption filters targeting RT of 1.2 s at DC and 0.9 s at Nyquist
-    absorption = pyFDN.one_pole_absorption(1.2, 0.9, delays, fs)
+    absorption = pyFDN.decay_to_one_pole(1.2, 0.9, delays, fs)
 
     # convert delay state-space to standard state-space (A_ss, b, c, d)
     A_ss, b, c, d = pyFDN.dss_to_ss(delays, feedback)
 
 Alternatively, import specific functions directly::
 
-    from pyFDN import random_orthogonal, one_pole_absorption, lin_to_db
+    from pyFDN import decay_to_one_pole, lin_to_db, random_orthogonal
 
     feedback = random_orthogonal(4)
-    absorption = one_pole_absorption(1.2, 0.9, [100, 150, 200, 250], 48_000)
+    absorption = decay_to_one_pole(1.2, 0.9, [100, 150, 200, 250], 48_000)
 
 
 Development
@@ -112,4 +112,4 @@ Helpful links
 * `List of papers on Feedback Delay Networks <https://github.com/gdalsanto/delay-network-reverbs>`_ .
 * `Multislope Estimation library <https://github.com/artificial-audio/multislope>`_ .
 * `FLAMO (An Open-Source Library for Frequency-Domain Differentiable Audio Processing) <https://github.com/gdalsanto/flamo>`_ .
-* `ADAC (Automatic Differentiable Audio Compilation) library <https://github.com/cucuwritescode/adac>`_ .
+* `ADAC (Automatic Differentiable Audio Compilation) library <https://github.com/cucuwritescode/adac>`_ .

{pyfdn-0.4.0 → pyfdn-0.4.2}/docs/api_reference.rst

@@ -95,34 +95,36 @@ Acoustics & Absorption
    pyFDN.slope_amplitude_to_level
    pyFDN.slope_to_rt
 
-EQ & Absorption Design (``pyFDN.eq``)
---------------------------------------
+EQ Design (``pyFDN.eq``)
+-------------------------
 
-Three designs of the same two filters -- an FDN's in-loop absorption and its
-output EQ -- behind one interface. A design carries its own target and maps it
-to biquad sections in numpy or in torch from a single implementation, which is
-what a trainable :class:`pyFDN.DecayFilter` or :class:`pyFDN.OutputEQ` runs
-inside a training loop.
+Explicit functions map either decay targets or gain targets onto a named
+filter design. The same functions run in NumPy or Torch; the trainable
+:class:`pyFDN.AttenuationFilter` and :class:`pyFDN.OutputEQ` modules use these
+mappings inside a training loop. ``EQDesign`` is the literal choice of
+``"graphic_eq"``, ``"first_order_shelf"``, or ``"one_pole"`` used by those
+modules. The target-to-EQ functions accept ``return_design=True`` when their
+JSON-compatible design record is also needed for an ``FDNPreset``.
 
 .. autosummary::
    :toctree: generated/
    :nosignatures:
 
    pyFDN.EQDesign
-   pyFDN.GraphicEQ
-   pyFDN.FirstOrderShelf
-   pyFDN.OnePole
-   pyFDN.design_geq
-   pyFDN.geq_sos
+   pyFDN.decay_to_geq
+   pyFDN.decay_to_first_order_shelf
+   pyFDN.decay_to_one_pole
+   pyFDN.gain_to_geq
+   pyFDN.gain_to_bounded_geq
+   pyFDN.gain_to_first_order_shelf
+   pyFDN.gain_to_one_pole
    pyFDN.geq_design_matrix
-   pyFDN.graphic_eq
-   pyFDN.absorption_geq
-   pyFDN.first_order_absorption
-   pyFDN.first_order_shelving_eq
-   pyFDN.one_pole_absorption
+   pyFDN.lowshelf_biquad
+   pyFDN.highshelf_biquad
+   pyFDN.peaking_biquad
+   pyFDN.first_order_shelf_biquad
+   pyFDN.one_pole_biquad
    pyFDN.probe_sos
-   pyFDN.shelving_filter
-   pyFDN.bandpass_filter
 
 Time-Domain Graph (``pyFDN.td``)
 --------------------------------
@@ -139,6 +141,12 @@ rendered with ``.process(signal)``. See :mod:`pyFDN.td`.
    pyFDN.td.Gain
    pyFDN.td.Delay
    pyFDN.td.AbsoluteValue
+   pyFDN.td.DCBlocker
+   pyFDN.td.ControllableFullWaveRect
+   pyFDN.td.SDFD
+   pyFDN.td.RingModulator
+   pyFDN.td.PitchShift
+   pyFDN.td.GranularPitchShift
    pyFDN.td.SOSBank
    pyFDN.td.MatrixFIR
    pyFDN.td.MatrixConvolver
@@ -181,7 +189,7 @@ An FDN as FLAMO modules, assembled from numpy values. The three filter hooks --
    pyFDN.fir_matrix_module
    pyFDN.sos_filter_module
    pyFDN.hook_module
-   pyFDN.DecayFilter
+   pyFDN.AttenuationFilter
    pyFDN.OutputEQ
 
 Polynomial & Matrix Maths
@@ -245,6 +253,11 @@ Build Files, Packaged Examples & References
    pyFDN.audio_metadata
    pyFDN.load_audio
    pyFDN.available_fdn_presets
+   pyFDN.get_fdn_preset
+   pyFDN.FDNPreset
+   pyFDN.fdn_preset_to_dict
+   pyFDN.fdn_preset_from_dict
+   pyFDN.save_fdn_preset
    pyFDN.load_fdn_preset
    pyFDN.fdn_build_to_dict
    pyFDN.fdn_build_from_dict
@@ -294,6 +307,7 @@ Training
 
    pyFDN.build_fdn
    pyFDN.trainable_from_build
+   pyFDN.trainable_from_preset
    pyFDN.build_set_decay
    pyFDN.Trainable
    pyFDN.train_fdn

{pyfdn-0.4.0 → pyfdn-0.4.2}/docs/example_gallery.py

@@ -15,11 +15,14 @@ OUTPUT_FILE = DOCS_DIR / "examples_gallery.rst"
 
 CATEGORY_ORDER = (
     "Getting Started",
-    "Absorption & Filters",
-    "Translation Examples",
-    "Allpass FDN Examples",
+    "Feedback Matrices",
+    "Absorption & Decay",
+    "Analysis & Verification",
+    "Optimization",
+    "Allpass FDNs",
     "Special FDNs",
-    "FDN Design & Analysis",
+    "Representations",
+    "Export & Deployment",
 )
 
 

pyfdn-0.4.2/docs/usage.rst

@@ -0,0 +1,102 @@
+=====
+Usage
+=====
+
+All main functions are accessible directly from ``pyFDN``::
+
+    import pyFDN
+
+    feedback = pyFDN.random_orthogonal(4)
+    attenuation = pyFDN.decay_to_first_order_shelf(
+        1.2, 0.9, None, [100, 150, 200, 250], 48_000
+    )
+    gain_db = pyFDN.lin_to_db([0.5, 1.0, 2.0])
+
+Or import specific functions::
+
+    from pyFDN import random_orthogonal, decay_to_first_order_shelf, dss_to_ss
+
+    feedback = random_orthogonal(4)
+
+Packaged tutorial resources
+---------------------------
+
+The small resources used by the browser tutorials are available through the
+public API, independent of the current working directory::
+
+    dry, fs = pyFDN.load_audio("synth_dry")
+
+    preset = pyFDN.get_fdn_preset("colorless_N8_d1")
+    reverberator = pyFDN.build_set_decay(preset.build, 1.5)
+
+    citation = pyFDN.paper_link("Allpass_Feedback_Delay_Networks")
+
+Use ``pyFDN.available_audio()`` and ``pyFDN.available_fdn_presets()`` to list
+the bundled choices. Attribution and license information for audio is returned
+by ``pyFDN.audio_metadata(name)``.
+
+FDN builds can also be exchanged as readable, versioned JSON files::
+
+    pyFDN.save_fdn_build("reverberator.json", reverberator)
+    restored = pyFDN.load_fdn_build("reverberator.json")
+
+Preset documents
+----------------
+
+An ``FDNPreset`` keeps a baked ``FDNBuild`` together with catalog metadata and
+the design choices that cannot be recovered reliably from its numbers. Unknown
+design choices are left out rather than guessed. Generators and EQ design
+functions return only their numerical result by default; opt into their design
+record when preparing a preset::
+
+    build, design = pyFDN.fdn_build_gallery(
+        N=8,
+        fs=48_000,
+        delay_distribution="geometric",
+        coprime=True,
+        rt=1.2,
+        rt_nyquist=0.8,
+        return_design=True,
+    )
+
+A separately designed filter can return the same kind of record. The caller
+only has to say which FDN hook receives it::
+
+    import dataclasses
+
+    post_matrix, post_matrix_design = pyFDN.gain_to_one_pole(
+        gain_db=[0.0] * 8,
+        gain_db_nyquist=[-3.0] * 8,
+        return_design=True,
+    )
+    build = dataclasses.replace(build, post_matrix=post_matrix)
+    design["post_matrix"] = post_matrix_design
+
+Once all numerical and design parts are assembled, freeze that particular
+realization as the preset::
+
+    preset = pyFDN.FDNPreset(
+        build=build,
+        metadata={
+            "name": "small-room",
+            "description": "A short, neutral room",
+            "authors": ["A. Author"],
+            "license": "CC0-1.0",
+            "tags": ["room", "short"],
+        },
+        design=design,
+    )
+    pyFDN.save_fdn_preset("small-room.json", preset)
+    restored = pyFDN.load_fdn_preset("small-room.json")
+
+Metadata is an open dictionary because it is descriptive rather than part of
+the sound. By convention, ``tags`` is a list of strings, so selecting presets
+does not require a metadata class::
+
+    requested = {"room", "short"}
+    matches = requested <= set(restored.metadata.get("tags", []))
+
+The numerical build, including its sample rate, is authoritative. Filter design
+records may additionally carry RT or gain targets. In that case
+``pyFDN.trainable_from_preset`` restores the meaningful FLAMO parameters and
+checks that they reproduce the baked SOS coefficients before building a model.

{pyfdn-0.4.0 → pyfdn-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyFDN"
-version = "0.4.0"
+version = "0.4.2"
 description = "Python library for Feedback Delay Networks"
 readme = "README.rst"
 authors = [
@@ -113,7 +113,7 @@ include = ["pyFDN*"]
 # triggers on. Usage: bump-my-version bump {major|minor|patch}
 
 [tool.bumpversion]
-current_version = "0.4.0"
+current_version = "0.4.2"
 allow_dirty = false
 commit = true
 message = "Bump version: {current_version} → {new_version}"

{pyfdn-0.4.0 → pyfdn-0.4.2}/src/pyFDN/__init__.py

@@ -3,7 +3,7 @@
 from importlib import import_module
 
 __author__ = "Facundo Franchino"
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 __all__ = [
     # acoustics
@@ -11,11 +11,8 @@ __all__ = [
     "estimate_initial_level_bands",
     "estimate_rt_bands",
     "edc",
-    "first_order_absorption",
-    "first_order_shelving_eq",
     "octave_band_filterbank",
     "octave_bands",
-    "one_pole_absorption",
     "rt_to_gain_per_sample",
     "rt_to_slope",
     "slope_amplitude_to_level",
@@ -39,7 +36,7 @@ __all__ = [
     "fir_matrix_module",
     "sos_filter_module",
     "hook_module",
-    "DecayFilter",
+    "AttenuationFilter",
     "OutputEQ",
     "audio_metadata",
     "available_audio",
@@ -48,7 +45,12 @@ __all__ = [
     "paper_link",
     "paper_reference",
     "available_fdn_presets",
+    "get_fdn_preset",
     "load_fdn_preset",
+    "FDNPreset",
+    "fdn_preset_from_dict",
+    "fdn_preset_to_dict",
+    "save_fdn_preset",
     "fdn_build_from_dict",
     "fdn_build_to_dict",
     "load_fdn_build",
@@ -80,18 +82,21 @@ __all__ = [
     "shift_matrix_distribute",
     "tiny_rotation_matrix",
     # eq
-    "absorption_geq",
-    "bandpass_filter",
     "EQDesign",
-    "FirstOrderShelf",
-    "GraphicEQ",
-    "OnePole",
-    "design_geq",
+    "decay_to_first_order_shelf",
+    "decay_to_geq",
+    "decay_to_one_pole",
+    "first_order_shelf_biquad",
+    "gain_to_bounded_geq",
+    "gain_to_first_order_shelf",
+    "gain_to_geq",
+    "gain_to_one_pole",
     "geq_design_matrix",
-    "geq_sos",
-    "graphic_eq",
+    "highshelf_biquad",
+    "lowshelf_biquad",
+    "one_pole_biquad",
+    "peaking_biquad",
     "probe_sos",
-    "shelving_filter",
     # polynomial and matrix maths
     "adj_poly",
     "adjugate",
@@ -148,6 +153,7 @@ __all__ = [
     # training
     "build_fdn",
     "trainable_from_build",
+    "trainable_from_preset",
     "LOSSLESS_ALIAS_DECAY_DB",
     "build_set_decay",
     "Trainable",
@@ -263,8 +269,6 @@ from .auxiliary.delay import (
     swap_flamo_recursion_paths,
 )
 from .auxiliary.flamo import (
-    DecayFilter,
-    OutputEQ,
     assemble_fdn_core,
     delay_module,
     fir_matrix_module,
@@ -350,7 +354,8 @@ from .auxiliary.utils import (
     skew,
     sq_to_db,
 )
-from .build_io import (
+from .build import (
+    FDNBuild,
     fdn_build_from_dict,
     fdn_build_to_dict,
     load_fdn_build,
@@ -358,20 +363,20 @@ from .build_io import (
 )
 from .eq import (
     EQDesign,
-    FirstOrderShelf,
-    GraphicEQ,
-    OnePole,
-    absorption_geq,
-    bandpass_filter,
-    design_geq,
-    first_order_absorption,
-    first_order_shelving_eq,
+    decay_to_first_order_shelf,
+    decay_to_geq,
+    decay_to_one_pole,
+    first_order_shelf_biquad,
+    gain_to_bounded_geq,
+    gain_to_first_order_shelf,
+    gain_to_geq,
+    gain_to_one_pole,
     geq_design_matrix,
-    geq_sos,
-    graphic_eq,
-    one_pole_absorption,
+    highshelf_biquad,
+    lowshelf_biquad,
+    one_pole_biquad,
+    peaking_biquad,
     probe_sos,
-    shelving_filter,
 )
 from .generate.allpass_FDN import allpass_completion
 from .generate.allpass_FDN.allpass_completion import (
@@ -405,10 +410,9 @@ from .generate.construct_paraunitary_from_elementals import (
 )
 from .generate.construct_velvet_feedback_matrix import construct_velvet_feedback_matrix
 from .generate.degree_one_lossless import degree_one_lossless
+from .generate.fdn_build_gallery import fdn_build_gallery
 from .generate.fdn_matrix_gallery import (
-    FDNBuild,
     FDNSystem,
-    fdn_build_gallery,
     fdn_matrix_gallery,
     fdn_system_gallery,
     filter_matrix_gallery,
@@ -426,7 +430,15 @@ from .generate.schroeder_reverberator import schroeder_reverberator
 from .generate.SDN import SDN
 from .generate.shift_matrix import shift_matrix
 from .generate.shift_matrix_distribute import shift_matrix_distribute
-from .presets import available_fdn_presets, load_fdn_preset
+from .preset import (
+    FDNPreset,
+    available_fdn_presets,
+    fdn_preset_from_dict,
+    fdn_preset_to_dict,
+    get_fdn_preset,
+    load_fdn_preset,
+    save_fdn_preset,
+)
 
 # fdn processing
 from .process import process_fdn
@@ -438,6 +450,7 @@ from .train import (
     L2,
     LOSSLESS_ALIAS_DECAY_DB,
     AsymmetricFlatMagnitude,
+    AttenuationFilter,
     Energy,
     FlatMagnitude,
     FlatSpectrogram,
@@ -448,6 +461,7 @@ from .train import (
     MatchMagnitude,
     MatchMelSpectrogram,
     MatchSpectrogram,
+    OutputEQ,
     ParameterLoss,
     ParamRef,
     Response,
@@ -463,6 +477,7 @@ from .train import (
     params,
     train_fdn,
     trainable_from_build,
+    trainable_from_preset,
 )
 
 # state-space translators

{pyfdn-0.4.0 → pyfdn-0.4.2}/src/pyFDN/auxiliary/acoustics.py

@@ -9,14 +9,6 @@ from numpy.typing import ArrayLike
 from scipy.signal import sosfreqz
 from scipy.special import erfc
 
-# The filter designs live in pyFDN.eq, and are re-exported here because this
-# module's rt_to_slope is what turns a reverberation time into the dB target
-# they take. They import it inside a function, not at module level, so the two
-# modules do not cycle.
-from pyFDN.eq.first_order import first_order_absorption as first_order_absorption
-from pyFDN.eq.first_order import first_order_shelving_eq as first_order_shelving_eq
-from pyFDN.eq.one_pole import one_pole_absorption as one_pole_absorption
-
 
 def rt_to_slope(rt: ArrayLike, fs: float) -> np.ndarray:
     """Convert reverb time (RT, seconds) to energy decay slope (dB per sample)."""
@@ -457,7 +449,8 @@ def sos_gain_per_sample_curves(
     ----------
     sos : (n_sections, 6, N) array
         Per-channel SOS bank; section rows are ``[b0, b1, b2, a0, a1, a2]``. Same
-        format as :func:`one_pole_absorption` / :func:`first_order_absorption`
+        format as :func:`pyFDN.decay_to_one_pole` /
+        :func:`pyFDN.decay_to_first_order_shelf`
         return.
     delays : (N,) array-like
         Delay lengths in samples, one per channel. Used to scale gain to per-sample.

{pyfdn-0.4.0 → pyfdn-0.4.2}/src/pyFDN/auxiliary/allpass.py

@@ -15,6 +15,10 @@ from scipy.linalg import solve_discrete_lyapunov
 from pyFDN.auxiliary.math import general_char_poly
 from pyFDN.generate.is_almost_zero import is_almost_zero
 
+# How far inside the unit circle the eigenvalues of A must sit for the discrete
+# Lyapunov equation solved by is_uniallpass to be well posed.
+_STABILITY_TOL = 1e-9
+
 
 def poletti_allpass(
     g: float, U: np.ndarray
@@ -72,11 +76,33 @@ def is_uniallpass(
         True if the system is uniallpass.
     P : ndarray
         Solution of discrete Lyapunov A P A' - P + B B' = 0; diagonal if uniallpass.
+        All-NaN when A is not strictly stable, see the note below.
+
+    Notes
+    -----
+    The Lyapunov equation only has a (unique, finite) solution when A is
+    strictly stable.  If A itself is lossless -- as in the allpass-in-FDN
+    structure, where the feedback matrix has all its eigenvalues on the unit
+    circle -- no such P exists, and the linear system scipy solves is exactly
+    singular.  Rather than let that surface as an ill-conditioned solve (which
+    raises or returns garbage depending on the LAPACK build), the spectral
+    radius is checked up front and the system reported as not uniallpass.
     """
     A = np.asarray(A, dtype=float)
     B = np.asarray(B, dtype=float)
     C = np.asarray(C, dtype=float)
     D = np.asarray(D, dtype=float)
+    # P exists only for a strictly stable A; on the unit circle the Lyapunov
+    # operator P -> A P A' - P is singular (eigenvalue pairs with λi·λj = 1).
+    spectral_radius = float(np.max(np.abs(np.linalg.eigvals(A)))) if A.size else 0.0
+    if spectral_radius >= 1.0 - _STABILITY_TOL:
+        warnings.warn(
+            f"A has spectral radius {spectral_radius:.6g} >= 1; the discrete "
+            "Lyapunov equation has no finite solution, so the system is not "
+            "uniallpass.",
+            stacklevel=2,
+        )
+        return False, np.full_like(A, np.nan)
     # P = dlyap(A, B @ B')
     P = solve_discrete_lyapunov(A, B @ B.T)
     # Check P is diagonal