pyFDN 0.4.1__tar.gz → 0.4.2__tar.gz

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

@@ -2,9 +2,44 @@
 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
@@ -15,6 +50,10 @@ History
 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 --
@@ -37,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,
@@ -53,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.1 → pyfdn-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyFDN
-Version: 0.4.1
+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

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

@@ -100,10 +100,11 @@ EQ Design (``pyFDN.eq``)
 
 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.DecayFilter` and :class:`pyFDN.OutputEQ` modules use these
+: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.
+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/
@@ -140,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
@@ -182,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
@@ -246,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
@@ -295,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.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.1 → pyfdn-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyFDN"
-version = "0.4.1"
+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.1"
+current_version = "0.4.2"
 allow_dirty = false
 commit = true
 message = "Bump version: {current_version} → {new_version}"

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

@@ -3,7 +3,7 @@
 from importlib import import_module
 
 __author__ = "Facundo Franchino"
-__version__ = "0.4.1"
+__version__ = "0.4.2"
 
 __all__ = [
     # acoustics
@@ -36,7 +36,7 @@ __all__ = [
     "fir_matrix_module",
     "sos_filter_module",
     "hook_module",
-    "DecayFilter",
+    "AttenuationFilter",
     "OutputEQ",
     "audio_metadata",
     "available_audio",
@@ -45,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",
@@ -148,6 +153,7 @@ __all__ = [
     # training
     "build_fdn",
     "trainable_from_build",
+    "trainable_from_preset",
     "LOSSLESS_ALIAS_DECAY_DB",
     "build_set_decay",
     "Trainable",
@@ -348,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,
@@ -403,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,
@@ -424,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
@@ -436,7 +450,7 @@ from .train import (
     L2,
     LOSSLESS_ALIAS_DECAY_DB,
     AsymmetricFlatMagnitude,
-    DecayFilter,
+    AttenuationFilter,
     Energy,
     FlatMagnitude,
     FlatSpectrogram,
@@ -463,6 +477,7 @@ from .train import (
     params,
     train_fdn,
     trainable_from_build,
+    trainable_from_preset,
 )
 
 # state-space translators

{pyfdn-0.4.1 → 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

{pyfdn-0.4.1 → pyfdn-0.4.2}/src/pyFDN/auxiliary/flamo.py

@@ -645,7 +645,7 @@ def assemble_fdn_core(
         is ``Parallel(brA=fdn_branch, brB=direct)``.
     post_delay : FLAMO module or None
         In-loop filter after the delays (named ``post_delay``). Any module of
-        input/output size N: a :class:`~pyFDN.DecayFilter` or a plain
+        input/output size N: a :class:`~pyFDN.AttenuationFilter` or a plain
         :func:`sos_filter_module` for attenuation, or a whole nested core such as
         a Schroeder allpass. Only an SOS filter here is extractable into an
         :class:`~pyFDN.FDNBuild`.

{pyfdn-0.4.1 → pyfdn-0.4.2}/src/pyFDN/auxiliary/flamo_graph.py

@@ -13,7 +13,7 @@ from typing import TYPE_CHECKING, Any
 import numpy as np
 
 if TYPE_CHECKING:
-    from pyFDN.generate.fdn_matrix_gallery import FDNBuild
+    from pyFDN.build import FDNBuild
 
 
 # Traversal uses type(module).__name__ and getattr; no need to import flamo here.
@@ -421,7 +421,7 @@ def extract_build(model: Any) -> FDNBuild:
     if fs_value is None:
         raise ValueError("FLAMO delay module exposes no sample rate; cannot extract fs")
 
-    from pyFDN.generate.fdn_matrix_gallery import FDNBuild
+    from pyFDN.build import FDNBuild
 
     return FDNBuild(
         A=A,

pyfdn-0.4.1/src/pyFDN/build_io.py → pyfdn-0.4.2/src/pyFDN/build.py

@@ -1,24 +1,48 @@
-"""Readable, versioned serialization for :class:`pyFDN.FDNBuild`."""
+"""Baked feedback-delay-network builds and their JSON representation."""
 
 from __future__ import annotations
 
 import json
-from collections.abc import Mapping
+from dataclasses import dataclass
 from os import PathLike
 from pathlib import Path
 from typing import Any
 
 import numpy as np
 
-from .generate.fdn_matrix_gallery import FDNBuild
-
 FDN_BUILD_FORMAT = "pyfdn-fdn-build"
-#: Current schema version. The three filter hooks are spelled ``post_delay``,
-#: ``post_matrix`` and ``post_output``, the names they carry everywhere else in
-#: pyFDN.
 FDN_BUILD_VERSION = 2
 
 
+@dataclass(frozen=True)
+class FDNBuild:
+    """Complete, renderable parameters of a vanilla FDN.
+
+    Every field is a plain NumPy value consumed by :func:`pyFDN.process_fdn`
+    and :func:`pyFDN.build_to_impz`. A build does not remember how its numbers
+    were designed; that optional information belongs to :class:`pyFDN.FDNPreset`.
+
+    The three optional SOS banks correspond directly to pyFDN's filter hooks:
+
+    * ``post_delay`` has shape ``(sections, 6, N)`` and sets the decay inside
+      the loop after the delays.
+    * ``post_matrix`` has shape ``(sections, 6, N)`` and filters the feedback
+      path after the feedback matrix.
+    * ``post_output`` has shape ``(sections, 6, outputs)`` and filters the wet
+      signal outside the recursion.
+    """
+
+    A: np.ndarray
+    B: np.ndarray
+    C: np.ndarray
+    D: np.ndarray
+    delays: np.ndarray
+    fs: float
+    post_delay: np.ndarray | None = None
+    post_matrix: np.ndarray | None = None
+    post_output: np.ndarray | None = None
+
+
 def _optional_array(value: Any, name: str) -> np.ndarray | None:
     if value is None:
         return None
@@ -29,10 +53,9 @@ def _optional_array(value: Any, name: str) -> np.ndarray | None:
 
 
 def fdn_build_to_dict(
-    build: FDNBuild, *, metadata: Mapping[str, Any] | None = None
+    build: FDNBuild, *, metadata: dict[str, Any] | None = None
 ) -> dict[str, Any]:
-    """Convert an :class:`FDNBuild` to the versioned JSON-compatible format."""
-
+    """Convert an :class:`FDNBuild` to its JSON-compatible format."""
     data: dict[str, Any] = {
         "format": FDN_BUILD_FORMAT,
         "version": FDN_BUILD_VERSION,
@@ -58,21 +81,16 @@ def fdn_build_to_dict(
     }
     if metadata:
         data["metadata"] = dict(metadata)
-    # Validate shape, values, and schema before exposing or writing the data.
     fdn_build_from_dict(data)
     return data
 
 
-def fdn_build_from_dict(
-    data: Mapping[str, Any], *, fs: float | None = None
-) -> FDNBuild:
-    """Construct an :class:`FDNBuild` from its versioned dictionary format.
+def fdn_build_from_dict(data: dict[str, Any], *, fs: float | None = None) -> FDNBuild:
+    """Construct an :class:`FDNBuild` from its JSON-compatible dictionary.
 
-    Args:
-        data: Parsed JSON-compatible build dictionary.
-        fs: Optional sample-rate override in Hz.
+    ``fs`` is an optional override retained for loading standalone legacy build
+    files. Preset loading always uses the sample rate stored in the build.
     """
-
     if data.get("format") != FDN_BUILD_FORMAT:
         raise ValueError(f"Expected format '{FDN_BUILD_FORMAT}'")
     version = data.get("version")
@@ -123,8 +141,6 @@ def fdn_build_from_dict(
     post_delay = _optional_array(data.get("post_delay"), "post_delay")
     post_matrix = _optional_array(data.get("post_matrix"), "post_matrix")
     post_output = _optional_array(data.get("post_output"), "post_output")
-    # The two in-loop hooks run on the delay lines; the output hook on the
-    # output channels.
     for name, hook in (("post_delay", post_delay), ("post_matrix", post_matrix)):
         if hook is not None and (
             hook.ndim != 3 or hook.shape[1] != 6 or hook.shape[2] != num_delays
@@ -154,10 +170,9 @@ def save_fdn_build(
     path: str | PathLike[str],
     build: FDNBuild,
     *,
-    metadata: Mapping[str, Any] | None = None,
+    metadata: dict[str, Any] | None = None,
 ) -> None:
     """Write an :class:`FDNBuild` as indented, human-readable JSON."""
-
     Path(path).write_text(
         json.dumps(
             fdn_build_to_dict(build, metadata=metadata), indent=2, allow_nan=False
@@ -168,9 +183,19 @@ def save_fdn_build(
 
 
 def load_fdn_build(path: str | PathLike[str], *, fs: float | None = None) -> FDNBuild:
-    """Load an :class:`FDNBuild` from the versioned JSON format."""
-
+    """Load an :class:`FDNBuild` from its JSON format."""
     data = json.loads(Path(path).read_text(encoding="utf-8"))
     if not isinstance(data, dict):
         raise ValueError("FDN build JSON must contain an object")
     return fdn_build_from_dict(data, fs=fs)
+
+
+__all__ = [
+    "FDNBuild",
+    "FDN_BUILD_FORMAT",
+    "FDN_BUILD_VERSION",
+    "fdn_build_from_dict",
+    "fdn_build_to_dict",
+    "load_fdn_build",
+    "save_fdn_build",
+]

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

@@ -8,6 +8,7 @@ from .biquads import (
     peaking_biquad,
 )
 from .design import (
+    EQ_DESIGNS,
     EQDesign,
     decay_to_first_order_shelf,
     decay_to_geq,
@@ -29,6 +30,7 @@ __all__ = [
     "BANDWIDTH_R",
     "CENTER_FREQUENCIES",
     "EQDesign",
+    "EQ_DESIGNS",
     "SHELVING_CROSSOVER",
     "decay_to_first_order_shelf",
     "decay_to_geq",

pyfdn-0.4.2/src/pyFDN/eq/_design_record.py

@@ -0,0 +1,25 @@
+"""Small helpers for optional JSON-compatible EQ design records."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+DesignRecord = dict[str, Any]
+
+
+def design_value(value: Any) -> Any:
+    """Detach an array-like design target and convert it to JSON values."""
+    if hasattr(value, "detach"):
+        value = value.detach().cpu().numpy()
+    array = np.asarray(value)
+    return array.item() if array.ndim == 0 else array.tolist()
+
+
+def with_design(value: Any, design: DesignRecord, return_design: bool) -> Any:
+    """Return a coefficient value alone or paired with its design record."""
+    return (value, design) if return_design else value
+
+
+__all__ = ["DesignRecord", "design_value", "with_design"]