pyFDN 0.4.2__tar.gz → 0.6.0__tar.gz

{pyfdn-0.4.2 → pyfdn-0.6.0}/CONTRIBUTING.rst

@@ -141,15 +141,21 @@ The repository separates the installable package, executable examples,
 documentation sources, and tests:
 
 * ``src/pyFDN/`` contains the library. The top-level ``__init__.py`` defines
-  the public API, while ``process.py``, ``build_io.py``, and ``presets.py``
-  provide the main processing and persistence entry points.
+  the public API, while ``process.py``, ``build.py``, and ``preset.py``
+  provide the main build-processing and persistence entry points.
 * ``src/pyFDN/generate/`` contains feedback-matrix and FDN construction
-  algorithms, including the allpass and scattering-delay-network builders.
+  algorithms: ``orthogonal.py``, ``paraunitary.py`` and ``kronecker_matrix.py``
+  for feedback matrices, ``structures.py`` for classic reverberator structures,
+  the galleries, and the allpass and scattering-delay-network builders.
 * ``src/pyFDN/td/`` contains stateful block-processing operators and the
   connectors (``Series``, ``Parallel``, ``Recursion``) that wire them into a
-  time-domain graph. ``process_fdn`` uses ``MatrixFIR`` for polynomial feedback
-  matrices; ``SOSBank`` implements per-delay-line filter cascades used for
-  frequency-dependent absorption.
+  time-domain graph. ``dss_to_td`` assembles an FDN from these
+  operators (``SOSBank`` for per-delay-line filter cascades; a ``MatrixFIR``
+  feedback matrix goes in the ``post_matrix`` hook); ``process_dss`` and
+  ``dss_to_impz`` render the matrix-only system through that graph.
+* ``import pyFDN`` must not import torch or flamo (``tests/test_import.py``):
+  import them inside the functions that need them, or add the module to the
+  lazily loaded names at the end of ``src/pyFDN/__init__.py``.
 * ``src/pyFDN/eq/`` contains every EQ and absorption-filter design, while
   ``src/pyFDN/translate/`` converts between delay state-space, transfer
   function, pole-residue, impulse-response, and FLAMO representations.

pyfdn-0.6.0/HISTORY.rst

@@ -0,0 +1,521 @@
+=======
+History
+=======
+
+0.6.0 (2026-11-08)
+------------------
+
+* ``RecursionState.set_lines`` and ``fill_noise(variance)`` overwrite the delay-line
+  content, e.g. noise for a diffuse-field start. In a ``dss_to_td`` graph the
+  state is at ``graph.ops[0].ops[1].state``.
+* New ``gain_to_two_stage`` / ``decay_to_two_stage`` design the two-stage
+  attenuation filter of Välimäki, Prawda and Schlecht (IEEE SPL, 2024): a
+  first-order shelf sets the gain towards DC and Nyquist, and the ten-band
+  graphic EQ fits the remainder per band. It follows steep high-frequency
+  decays more closely than the graphic EQ alone.
+* ``EQDesign`` gains ``"two_stage"``, so ``AttenuationFilter`` and
+  ``OutputEQ`` can train it.
+* **Breaking: ``FDNBuild`` is replaced by ``DSS``**, a named tuple of exactly
+  ``(delays, A, B, C, D)`` in the argument order of the ``dss_to_*`` functions,
+  so ``pyFDN.dss_to_td(*dss, **filters)`` works. Filters (``post_delay``,
+  ``post_matrix``, ``post_output``) and the sample rate are passed alongside.
+  ``build_to_td`` / ``build_to_impz`` / ``build_to_flamo`` / ``process_fdn``,
+  ``build_set_decay`` and ``plot_fdn_build`` (and ``plot_FDN_build``) are
+  removed. ``dss_to_impz`` and ``process_dss`` take the matrices only; a
+  system with filters renders through its ``td`` graph, and the new
+  ``TimeOperator.impulse_response(ir_len)`` gives
+  ``dss_to_td(*dss, **filters).impulse_response(ir_len)``.
+* **Breaking: a filter (FIR) feedback matrix is a graph operator, not a DSS
+  matrix.** ``dss_to_td`` and ``dss_to_flamo`` take a 2-D ``A`` only; put the
+  FIR matrix on the feedback path with ``A`` the identity:
+  ``post_matrix=td.MatrixFIR(fir)`` or
+  ``post_matrix=pyFDN.fir_matrix_module(fir, nfft)``.
+  ``plot_fdn_parameter``'s ``post_*_sos`` keywords are now ``post_*``.
+  Renamed: ``extract_build`` -> ``flamo_to_dss`` (returns ``(dss, filters)``,
+  now in ``pyFDN.translate`` next to ``dss_to_flamo``),
+  ``trainable_from_build`` -> ``trainable_from_dss(*dss, fs, ...)``,
+  ``fdn_build_gallery`` -> ``fdn_dss_gallery`` (returns ``(dss, filters)``).
+* **Breaking: one save for everything.** ``save_fdn`` / ``load_fdn`` /
+  ``resave_fdn`` write a ``DSS`` as readable JSON (``"format": "pyfdn-dss"``,
+  one matrix row per line) and pickle anything else -- a ``td`` graph, a FLAMO
+  model -- with ``cloudpickle``, plus the pyFDN and Python versions that wrote
+  it; ``pyFDN.save.RENAMED`` maps classes that moved since. The JSON build
+  format (``save_fdn_build`` / ``load_fdn_build`` / ``fdn_build_*_dict``),
+  ``FDNPreset`` with its design records, ``trainable_from_preset`` and the EQ
+  designers' ``return_design`` option are removed. ``get_fdn_preset`` is now
+  ``load_fdn_preset``, pairing with ``load_audio`` and ``load_fdn``, and returns
+  a ``DSS``; the packaged presets are DSS JSON files. New dependency:
+  ``cloudpickle>=3``.
+* **Breaking: one convention per concept.**
+
+  * ``flamo_time_response(model)`` returns ``(nfft, out, in)``, one response
+    per input like ``dss_to_impz``; its ``fs`` and ``identity`` arguments are
+    gone. ``pr_to_impz``'s ``impulse_response_length`` is ``ir_len``.
+  * ``is_paraunitary`` takes an FIR matrix in pyFDN's ``(out, in, taps)``
+    layout; pass an impulse response as ``ir.transpose(1, 2, 0)``.
+  * ``fir_matrix_module`` takes ``alias_decay_db`` like the other module
+    builders, so an FIR feedback matrix works in a model with alias decay.
+  * ``dss_to_flamo``'s ``nfft`` and ``device`` are keyword-only; every FLAMO
+    builder defaults to ``nfft=2**16``.
+  * Gains are ``B, C, D`` everywhere: ``plot_system_matrix``,
+    ``plot_fdn_parameter``, ``allpass_in_fdn``, ``schroeder_reverberator``.
+  * ``pole_boundaries(delays, A, fs, *, post_delay, nfft)``.
+  * Galleries return a matrix and nothing else; ``FEEDBACK_MATRIX_TYPES``,
+    ``FILTER_MATRIX_TYPES`` and ``SYSTEM_TYPES`` list their names. The old
+    fdnToolbox spellings (``"Hadamard"``, ``"nestedAllpass"``, ...) are no
+    longer accepted. ``FDNSystem`` is removed; ``fdn_system_gallery`` returns
+    ``(A, B, C, D)`` like the structure builders.
+  * ``pyFDN`` no longer exports the allpass-completion internals,
+    ``is_almost_zero``, ``ensure_3d``, ``polydiag``, ``negpolyder``, or the
+    ``pyFDN.allpass`` / ``pyFDN.allpass_completion`` aliases; they stay in
+    their modules. Removed as unused: ``flamo_freq_response``,
+    ``flamo_extract_pr_decomposition``, ``matrix_polyder``, ``matrix_sqrt``,
+    ``mulaw_decode``, ``db_to_lin``, ``db_to_sq``.
+  * The system comes before the signal: ``process_dss(*dss, x)``, as in
+    ``dss_to_impz`` and ``flamo_process(model, x)``.
+  * ``TimeVaryingMatrix(N, fs, *, rate, depth, spread=0.0, seed=None)`` names
+    its knobs as ``TimeVaryingKroneckerMatrix`` does (``rate``, ``depth``,
+    ``phase`` attributes) and draws from its own ``seed`` instead of NumPy's
+    global generator.
+  * ``build_fdn`` is ``trainable_fdn``, pairing with ``trainable_from_dss``.
+  * One function per quantity: ``general_char_poly`` uses the FFT route of
+    the former ``general_char_poly_fft`` for a static ``A`` (principal minors
+    remain for a polynomial ``A``), and ``energy_decay_curve`` is removed in
+    favour of ``edc``, which already takes tensors.
+  * Descriptive names for the MATLAB-style ones: ``mgrpdelay`` ->
+    ``matrix_group_delay``, ``ms_to_smp`` -> ``ms_to_samples``, ``adj_poly``
+    -> ``adjugate_polynomial``, ``loop_tf`` -> ``loop_transfer_function``,
+    ``rand_admissible_homogeneous_allpass`` ->
+    ``random_admissible_homogeneous_allpass``.
+  * Option names are matched exactly: ``construct_cascaded_paraunitary_matrix``
+    takes ``"hadamard"`` / ``"random"`` and ``dss_to_pr`` / ``flamo_to_pr``
+    their ``mode`` in lower case only.
+  * ``SDN`` defaults to ``fs=48_000.0`` like the rest of pyFDN, and
+    ``flamo_process`` types ``fs`` as a float.
+  * ``dss_to_ss(delays, A, B, C, D)`` takes the gains like every other
+    ``dss_*`` function (they were optional, lower case and defaulted to ones)
+    and handles several inputs and outputs.
+  * The EQ designers take the sample rate before the shelf frequency, which is
+    the keyword ``crossover``: ``decay_to_first_order_shelf(rt, rt_nyquist,
+    delays, fs, *, crossover=None)``, ``gain_to_first_order_shelf(gain_db,
+    gain_db_nyquist, fs, *, crossover=None)``, and ``crossover=`` for the
+    two-stage designers and ``AttenuationFilter`` (was ``rt_crossover``).
+  * ``AttenuationFilter`` and ``OutputEQ`` default to ``nfft=2**16`` like the
+    model builders they plug into.
+  * Matrix generators take the size as ``N``. ``construct_cascaded_paraunitary_matrix``
+    is ``cascaded_paraunitary_matrix(N, stages, ...)`` and
+    ``construct_paraunitary_from_elementals`` is ``paraunitary_from_elementals``;
+    ``construct_velvet_feedback_matrix`` is removed, since it was
+    ``cascaded_paraunitary_matrix`` with its default Hadamard stages.
+    ``mtf_to_impz`` is ``tf_to_impz``, pairing with ``dss_to_tf``.
+  * ``nfft`` names every FFT size: ``mimo_rir_eigenvalues_per_frequency`` (was
+    ``n_fft``) and ``MatchMelEnergyDecayRelief`` (was ``fft_sizes``). The EAI
+    ``deflation_type`` values are ``"full"``, ``"neighbor"`` and ``"none"``.
+  * ``plot_matrix`` and ``plot_system_matrix`` take ``title``, ``zmin`` and
+    ``zmax`` as keywords.
+  * ``pyFDN`` no longer exports single-caller helpers: ``last_nonzero_indices``,
+    ``downsample_minmax``, ``flamo_model_to_nodes``, ``flamo_nodes_flat``,
+    ``hook_module``, ``skew``, ``poly_degree``, ``polyder_rational``,
+    ``matrix_polyval``, ``shift_matrix``, ``shift_matrix_distribute``,
+    ``random_matrix_shift`` and ``degree_one_lossless`` stay in their modules.
+* ``dss_to_flamo`` takes ``alias_decay_db``, so a lossless FDN renders through
+  it without time aliasing, as through ``trainable_from_dss``.
+* ``DCBlocker`` drops its ``env_tau_s`` / ``gain_tau_s`` arguments and
+  ``PitchShift`` its ``min_delay_samps`` argument; nothing set them, and they
+  are now fixed at 50 ms, 20 ms and 3 samples.
+
+* **Breaking: one convention for randomness.** Every random function takes
+  ``rng=``, a NumPy ``Generator`` or an integer seed, and none draws from
+  NumPy's global generator any more: the matrix and system galleries,
+  ``random_orthogonal`` (now keyword-only), ``tiny_rotation_matrix``,
+  ``anderson_matrix``, ``nearest_sign_agnostic_orthogonal``,
+  ``cascaded_paraunitary_matrix``, ``paraunitary_from_elementals``,
+  ``shift_matrix_distribute``, ``random_matrix_shift``,
+  ``random_admissible_homogeneous_allpass``, ``complete_fdn`` and
+  ``RecursionState.fill_noise``. ``TimeVaryingMatrix`` and
+  ``GranularPitchShift`` take ``rng=`` instead of ``seed=``.
+  ``np.random.seed`` no longer makes them reproducible; pass ``rng=``.
+* **Breaking: the ``is_*`` checks return a plain ``bool``.** ``is_allpass``,
+  ``is_uniallpass``, ``is_paraunitary`` and ``is_bounding_curve`` returned
+  tuples, so ``if pyFDN.is_paraunitary(m):`` was always true. The
+  characteristic polynomial ``is_allpass`` compared is
+  ``general_char_poly(delays, A)``. ``is_uniallpass`` no longer warns when the
+  answer is simply no.
+* **Breaking: ``SDN`` is cleaned up.** It computes everything when it is
+  built (``compute()`` and its 20-key dictionary are gone) and exposes
+  ``delays`` in samples, ``A``, ``B``, ``C``, ``D``, a ``wall_filters`` SOS
+  bank, and the ``input_delays``, ``output_delays`` and ``direct_delay`` of
+  the source, receiver and direct paths. ``wall_filters`` takes an SOS bank
+  with one filter per wall or per delay line. It renders with
+  ``pyFDN.sdn_to_flamo(sdn)`` (default ``nfft=2**16``, the model only) and
+  draws with ``pyFDN.plot_sdn(sdn)``, which replace the ``sdn_to_flamo`` and
+  ``visualize`` methods. The modules ``pyFDN.generate.SDN`` and
+  ``pyFDN.generate.allpass_FDN`` are now ``pyFDN.generate.sdn`` and
+  ``pyFDN.generate.allpass_fdn``.
+* **Breaking: no flags that change the return type.** ``dss_to_flamo``
+  always returns the ``Shell``; ``.get_core()`` gives the FDN without its FFT
+  layers, e.g. for another FDN's hook. ``complete_fdn`` always returns
+  ``(B, C, D, x)``, and its options after ``k`` are keyword-only.
+* **Breaking: no silent sample rates.** ``echo_density(ir, fs, *, window,
+  pre_delay, mixing_threshold, hop)`` and ``probe_sos(sos, fs, *,
+  control_frequencies, nfft)`` take ``fs`` as a required argument, and
+  ``delay_module`` takes delays in samples, like every other pyFDN function.
+
+* **Breaking: pole-residue results are a named tuple.** ``dss_to_pr`` and
+  ``flamo_to_pr`` return ``(pr, info)``: ``pr`` is a ``PoleResidue``
+  ``(residues, poles, direct, is_conjugate_pole_pair)`` that unpacks into
+  ``pr_to_impz(*pr, ir_len)``, and ``info`` is the solver report.
+  ``dss_to_pr`` keeps its static solvers (``"eig"``, ``"roots"``,
+  ``"lindsey_fox"``) and their two options; the Ehrlich-Aberth iteration is
+  ``flamo_to_pr(dss_to_flamo(*dss, fs))``, so ``dss_to_pr`` no longer copies
+  its nine solver and four model options. ``impz_to_res`` returns the residues
+  only.
+* **Breaking: the plots use Matplotlib's vocabulary.** ``vmin``/``vmax``
+  replace ``zmin``/``zmax``, ``plot_spectrogram`` takes ``cmap`` and
+  ``figsize`` instead of ``colorscale`` and a pixel ``height``, and
+  ``plot_matrix_grid`` takes ``figsize``. ``plot_impulse_response_matrix(ir,
+  *, fs=None, ...)`` takes the response first, like
+  ``plot_impulse_response``, and returns the figure alone.
+* **Breaking: the** ``td`` **operators share their parameter names.** Every
+  operator takes its channel count as ``channels`` (``TimeVaryingMatrix``
+  took ``N``); ``fs`` is the second argument wherever a rate in Hz needs it;
+  options are keyword-only, and ``active_channels`` defaults to all channels.
+  ``RingModulator(channels, fs, *, rate, depth)`` names its modulation like
+  the time-varying matrices; ``PitchShift`` and ``GranularPitchShift`` take
+  ``max_delay``, ``window`` and ``grain_length`` in samples (``PitchShift``
+  no longer takes an unused ``fs``); ``DCBlocker`` takes ``pole`` and no
+  ``fs``. ``SDFD`` is ``SignalDependentFractionalDelay`` (``fraction`` for
+  ``d``) and ``ControllableFullWaveRect`` is
+  ``ControllableFullWaveRectifier``.
+* **Breaking: the training losses frame in samples.** ``MatchEchoDensity``
+  takes ``window`` in samples (was ``win_duration`` in seconds),
+  ``MatchMelEnergyDecayRelief`` takes ``window`` and ``hop`` (were
+  ``win_lengths``/``hop_lengths``), and ``MatchSpectrogram`` /
+  ``MatchMelSpectrogram`` take ``overlap`` like the other spectrogram losses
+  instead of ``device``; they follow the response's device.
+* **Breaking:** ``echo_density`` reports the mixing time in seconds, like
+  every other time in pyFDN.
+* **Breaking: the allpass helpers follow the conventions.** ``complete_fdn``
+  and ``complete_general_mimo_svd`` call the number of inputs/outputs
+  ``num_io`` like ``complete_orthogonal`` (was ``k``);
+  ``homogeneous_allpass_fdn`` drops its printing ``verbose`` flag; the
+  completion results are documented as ``B, C, D``.
+* **Breaking:** ``octave_bands``, ``estimate_rt_bands`` and
+  ``estimate_initial_level_bands`` take ``lowest_octave`` and ``num_bands``
+  (were ``start`` and ``n``), keyword-only.
+* ``flamo_delay_feedback_matrix`` and ``swap_flamo_recursion_paths`` moved to
+  ``pyFDN.auxiliary.flamo`` and always return a modified copy (no
+  ``inplace``); ``pole_boundaries`` and ``is_bounding_curve`` moved to
+  ``pyFDN.auxiliary.poles``; ``pyFDN.auxiliary.allpass`` no longer re-exports
+  the allpass structures. The top-level names are unchanged.
+* **Breaking:** ``flamo_time_response`` is ``flamo_to_impz``, pairing with
+  ``dss_to_impz``, ``tf_to_impz`` and ``pr_to_impz``.
+
+* **Breaking:** ``trainable_fdn`` takes its starting matrices as ``A``,
+  ``B``, ``C``, ``D`` (were ``feedback``, ``input_gain``, ``output_gain``,
+  ``direct``), like ``trainable_from_dss``.
+* **Breaking: the EQ designers are named after their designs.**
+  ``decay_to_geq``, ``gain_to_geq``, ``gain_to_bounded_geq`` and
+  ``geq_design_matrix`` are ``decay_to_graphic_eq``, ``gain_to_graphic_eq``,
+  ``gain_to_bounded_graphic_eq`` and ``graphic_eq_design_matrix``. The
+  Nyquist targets are keyword-only, as in ``AttenuationFilter`` and
+  ``OutputEQ``: ``decay_to_first_order_shelf(rt, delays, fs, *, rt_nyquist,
+  crossover=None)``, ``decay_to_one_pole(rt, delays, fs, *, rt_nyquist)``,
+  ``gain_to_first_order_shelf(gain_db, fs, *, gain_db_nyquist,
+  crossover=None)``, ``gain_to_one_pole(gain_db, *, gain_db_nyquist)``.
+  ``OutputEQ`` takes ``channels`` (was ``n_channels``).
+* The biquad builders (``lowshelf_biquad``, ``highshelf_biquad``,
+  ``peaking_biquad``, ``first_order_shelf_biquad``, ``one_pole_biquad``) are
+  no longer exported; they stay in ``pyFDN.eq.biquads`` behind the designers.
+* Every public docstring uses the NumPy style.
+* ``impulse_excitation`` takes ``num_inputs``; the FLAMO module builders,
+  ``flamo_to_impz``, ``flamo_process`` and ``complete_fdn`` are fully typed.
+* **Breaking:** ``plot_flamo_graph`` returns a Figure like every other plot
+  and no longer takes ``ax``.
+* **Breaking:** ``fdn_dss_gallery`` accepts ``io_type="normalized"`` only
+  (the default; ``"normalised"`` is gone).
+* **Breaking:** ``mimo_rir_eigenvalues_per_frequency`` takes ``axis`` like
+  ``edc`` (was ``dim``), ``nearest_sign_agnostic_orthogonal`` takes ``tol``
+  (was ``tolerance``), and ``plot_spectrogram`` takes ``fs`` as a keyword like
+  the other plots.
+
+0.5.0 (2026-09-28)
+------------------
+
+* Fix GPU training (#231): ``model_response`` excites the model on its own
+  device, ``wrap_fdn_shell`` / ``dss_to_flamo`` / ``trainable_from_build``
+  build the FFT layers on the requested device, and ``train_fdn`` now defaults
+  to the model's device instead of the CPU. Requires ``flamo>=0.2.20``, whose
+  canonical module devices let ``device="cpu"`` / ``"cuda"`` mix with
+  ``.to(...)`` (previously ``Shell`` rejected them as different devices).
+* ``import pyFDN`` no longer loads torch or flamo, which makes it about three
+  times faster; the training API and ``flamo_to_pr`` load on first use. Every
+  public name is still exported from ``pyFDN``.
+* ``construct_cascaded_paraunitary_matrix`` (and the ``velvet`` /
+  ``random_dense`` gallery types), ``shift_matrix_distribute`` and
+  ``random_matrix_shift`` are now reproducible with ``np.random.seed``; they
+  used an unseeded generator before. ``random_orthogonal`` takes an optional
+  ``rng``.
+* ``process_dss`` renders through the same graph as ``dss_to_td`` (one
+  time-domain engine), with identical output. ``dss_to_td`` / ``build_to_td``
+  now accept a ``td`` operator or any ``process_block`` object as a hook, and
+  run ``post_delay`` on the delay output in real time.
+* **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)`` and
+  ``dss_to_impz(delays, A, B, C, D, ir_len)``.
+* **Breaking:** ``pole_boundaries`` takes the absorption as an
+  ``(sections, 6, N)`` SOS bank (the ``FDNBuild.post_delay`` format) instead of
+  an object with ``b`` and ``a`` fields, and accepts a 2-D feedback matrix.
+* **Breaking:** ``tiny_rotation_matrix`` and ``rotation_matrix_from_angles``
+  return NumPy arrays (the ``dtype`` argument is gone) and draw from NumPy's
+  random state.
+* ``fdn_system_gallery`` and ``filter_matrix_gallery`` use snake_case type
+  names like ``fdn_matrix_gallery`` (``"nested_allpass"``,
+  ``"allpass_in_fdn"``, ``"velvet"``, ...); the old spellings are still
+  accepted.
+* ``plot_FDN_build`` is now ``plot_fdn_build``; the old name remains an alias.
+* **Breaking:** Plotly is gone; every plot function returns a Matplotlib
+  figure, built without pyplot. ``animate`` returns a Matplotlib
+  ``FuncAnimation`` (show it with ``.to_jshtml()``; the Plotly-only
+  ``transition_ms`` argument is removed), ``SDN.visualize`` draws a
+  Matplotlib 3-D axes, and the Plotly helpers ``downsampled_scatter`` and
+  ``downsample_plotly_trace`` are removed. The example notebooks use
+  Matplotlib throughout, and ``plotly`` is no longer in any extra.
+* ``flamo_to_pr`` no longer prints progress by default (``verbose=False``, like
+  ``dss_to_pr``). ``matrix_sqrt`` keeps float64 precision.
+* ``edc`` accepts torch tensors and shares its Schroeder integral with
+  ``energy_decay_curve`` and the decay losses.
+* Remove the ``pyFDN.auxiliary.coupled_rooms`` module (a hand-wired FLAMO FDN
+  used only by its test; ``example_coupled_rooms`` covers the model) and the
+  unused ``flareverb`` dependency.
+* Internal: ``generate/`` is consolidated into ``orthogonal.py``,
+  ``paraunitary.py`` and ``structures.py``; ``dss_to_flamo`` and
+  ``trainable_from_build`` share one FLAMO core builder; the residue
+  extraction, device default, tensor conversion and seed handling exist once.
+  CI now runs ruff and mypy.
+* Add ``Match``, a composable response loss that extracts a feature from the
+  model response and the reference (waveform, magnitude, phase, mel
+  magnitude, multi-resolution spectrogram, octave-band EDC, cumulative energy),
+  compares them with a distance (squared, absolute, circular, ...) and reduces
+  the result to a scalar. The reference feature is cached across steps.
+  ``FlatMagnitude``, ``FlatSpectrogram``, ``MatchMagnitude``,
+  ``MatchImpulseResponse``, ``MatchEnergyDecay`` and ``MatchCumulativeEnergy``
+  are now built on it, with unchanged values.
+* Add the losses ``SpectralFlatness`` (geometric over arithmetic mean of
+  ``|H|``, gain-invariant), ``MatchPhase`` and ``MatchPhaseSpectrogram``
+  (circular phase distance, whole-response and multi-resolution STFT) and
+  ``MatchMelMagnitude`` (mel-filterbank magnitude).
+* Add the differentiable features ``energy_decay_curve`` (Schroeder EDC) and
+  ``mimo_rir_eigenvalues_per_frequency`` (eigenvalues of a square MIMO
+  transfer matrix per frequency bin).
+* Add the Kronecker feedback matrix of Coppola (DAFx26): ``kronecker_matrix``
+  builds a lossless ``2**M x 2**M`` matrix from ``M`` two-by-two rotation or
+  reflection kernels, one angle each, and ``kronecker_transform`` applies it in
+  ``O(N log2 N)`` with the paper's in-place butterfly instead of a dense
+  product. Every kernel angle addresses one bit of the delay-line index, so a
+  single angle cuts or re-couples the network along one partition -- the
+  outermost across the two stereo halves, the innermost between the even- and
+  odd-indexed lines -- and the matrix stays orthogonal at every setting. All
+  reflection kernels at ``pi/4`` recover the normalised Hadamard matrix, so the
+  usual FDN mixing matrix is one point in the family. Reachable from the
+  gallery as ``fdn_matrix_gallery(N, "kronecker")``, with ``kronecker_angles``
+  for naming the angles to move.
+* Add the ``td.KroneckerMatrix`` and ``td.TimeVaryingKroneckerMatrix``
+  operators. The latter modulates chosen kernel angles by a sine or triangle,
+  which breaks up fixed modal resonances by moving the poles without the
+  chorusing that modulating the delay lengths brings; since only one two-by-two
+  kernel changes per moving angle, per-sample modulation costs no more than the
+  static matrix. Both go straight into the ``post_matrix`` hook of
+  ``process_dss``.
+* Add the ``example_kronecker_matrix`` notebook, which reproduces the
+  configurations from the paper's companion site: the construction and its
+  Hadamard special case, the fast transform, the stereo cross-coupling sweep on
+  the outermost angle with its interchannel-balance and IACC analysis, and
+  matrix modulation on the next angle in, with the pole-frequency histogram
+  that shows why it reduces coloration.
+* **Breaking:** the ten-band graphic EQ's command grid is now the octave
+  centres 31.25 Hz through 16 kHz, with nearest-neighbour hold below 31.25 Hz
+  and above 16 kHz, instead of dummy DC and Nyquist anchors at 1 Hz and
+  ``fs``. The 10-vector of ``gain_to_geq`` / ``decay_to_geq`` /
+  ``AttenuationFilter`` / ``OutputEQ`` targets is ordered on
+  ``pyFDN.eq.COMMAND_FREQUENCIES``. The 11-section cascade itself is
+  unchanged.
+* Fix the first-order shelf bilinear prewarp: ``first_order_shelf_biquad``
+  used ``tan(ω)`` rather than ``tan(ω/2)``, so a requested crossover sat at
+  twice the named frequency. High crossovers are now clamped at ``fs/2.1``
+  (Nyquist-safe for the corrected prewarp) instead of ``fs/5``. The default
+  midpoint is ``fs/4``. ``example_reverberation_enhancement`` uses a
+  challenge gain of 1.6.
+* ``example_train_fdn_to_rir`` now fits on a shorter FFT grid than it measures
+  on. The loss only needs enough of the decay to steer on, while the octave-band
+  estimators need a longer measurement window, so the notebook trains at
+  ``nfft=2**16`` (1.37 s) and switches to ``2**17`` (2.73 s) with FLAMO's new
+  ``Shell.set_nfft`` before rendering. The step cost is linear in ``nfft``, so
+  shorter grid reduces training time. Each training-cell run resets the grid
+  before fitting. Requires ``flamo>=0.2.18``, where ``set_nfft`` was added.
+  The walkthrough now focuses on the implemented workflow and ends with
+  octave-band validation.
+  Keep a CPU/CUDA float32 selector and use first-order shelves for absorption
+  and output EQ. Cite the filter-learning paper with a TODO for publication.
+
+* Type every DSS matrix parameter (``A``/``B``/``C``/``D`` and the ``b``/``c``/``d``
+  gains in ``dss_to_ss``) as ``ArrayLike`` instead of ``ndarray`` across
+  ``dss_to_flamo``, ``dss_to_impz``, ``dss_to_td``, ``dss_to_tf``, ``dss_to_ss``,
+  ``general_char_poly``, and ``loop_tf`` -- matching what these functions
+  already do internally (``np.asarray(...)``) and how ``delays`` was already
+  typed. Also fixes ``dss_to_ss`` silently returning a non-array ``dd`` when
+  ``d`` was passed as a list rather than an ``ndarray``.
+* Add ``dss_to_td``, the raw delay state-space (DSS) counterpart of
+  ``build_to_td`` -- matching the ``dss_to_*``/``build_to_*`` pattern already
+  used by ``dss_to_flamo``/``build_to_flamo`` and ``dss_to_impz``/
+  ``build_to_impz``.
+* **Breaking:** rename the ``m`` parameter to ``delays`` in ``dss_to_ss`` and
+  ``dss_to_flamo``, matching every other DSS-related function.
+* Clarify docs and docstrings on the relationship between a delay state-space
+  (DSS) system and an ``FDNBuild``: a build is a DSS system plus ``fs`` and
+  baked filter hooks.
+* Fix ``dss_to_ss`` raising a dimension-mismatch error for delays at the
+  documented minimum of 3 samples.
+* **Breaking:** ``process_fdn`` now takes an ``FDNBuild`` and assembles a
+  stateful ``td`` graph (new ``build_to_td``) instead of taking raw DSS
+  arguments; the old signature is renamed to ``process_dss``. ``td`` operators
+  rename ``filter(block)``/``process(signal)`` to
+  ``process_block(block)``/``process_signal(signal)``.
+
+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_dss`` 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 --
+  ``FlatMagnitude() + 0.2 * Sparsity(param(model, "feedback"))`` -- and every
+  loss is a function of the impulse response, carried as a ``Response``, so
+  losses own their reference data and one objective can fit two different
+  references. ``pyFDN.train.objectives`` and ``build_objective`` are gone.
+* **Breaking:** collect every EQ design in ``pyFDN.eq`` (formerly
+  ``pyFDN.graphicEQ``) behind one ``EQDesign`` interface, with ``GraphicEQ``,
+  ``FirstOrderShelf`` and ``OnePole`` sharing a single implementation across
+  the numpy and torch backends.
+* **Breaking:** remove ``absorption_filters`` and ``absorption_to_rt``; the FIR
+  absorption path they served has no callers left.
+* **Breaking:** name the three filter hooks ``post_delay``, ``post_matrix`` and
+  ``post_output`` everywhere -- on ``FDNBuild``, in the FLAMO graph, in the
+  plots and in the JSON schema -- and add the slot for the third. The build
+  schema is version 2; version 1 files no longer load.
+* Fix colorless training on a lossless FDN, whose poles sit on the unit circle
+  and leave ``|H|`` unbounded. ``build_fdn`` now defaults ``alias_decay_db``
+  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: ``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,
+  the only part of an FDN that shapes the spectral envelope without touching
+  the decay. Both are passed as the ``post_delay`` and ``post_output`` hooks of
+  ``trainable_from_build``.
+* Add the losses that go with it: ``AsymmetricFlatMagnitude``,
+  ``FlatSpectrogram``, ``MatchEnergyDecay``, ``MatchCumulativeEnergy``,
+  ``MatchMagnitude``, ``MatchSpectrogram``, ``MatchMelSpectrogram``,
+  ``MatchImpulseResponse``, ``Energy``, ``Sparsity``, ``L1`` and ``L2``.
+* Resolve trainable parameters by name: ``param(model, "feedback")`` fails
+  where you write it with the list of available names, and ``params(model)``
+  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``, ``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
+  bake rather than silently dropping it.
+* Add an example notebook that fits every parameter of an FDN, decay included,
+  to a measured concert-hall RIR, and document the loss rationale and
+  measurements in ``docs/training_losses.rst``.
+* Fix stereo orientation in ``labeled_audio``, which decoded a stereo render as
+  thousands of channels.
+* Check packaging metadata in CI and fail the documentation build on notebook
+  cell errors.
+
+0.3.0 (2026-08-17)
+------------------
+
+* **Breaking:** replace the ``pyFDN.dsp`` subpackage with ``pyFDN.td``. The
+  top-level ``FeedbackDelay``, ``FIRMatrixFilter`` and ``SOSFilterBank``
+  exports are gone; use ``pyFDN.td`` operators instead.
+* **Breaking:** ship the packaged colorless-FDN presets as JSON rather than
+  MATLAB ``.mat`` files.
+* Add ``pyFDN.td``, a time-domain block-based processing graph built on NumPy
+  alone (no torch, no FFT), with the ``Series``, ``Parallel`` and
+  ``Recursion`` connectors and stateful ``Gain``, ``Delay``, ``SOSBank``,
+  ``MatrixFIR``, ``MatrixConvolver`` and ``TimeVaryingMatrix`` operators.
+* Add ``load_fdn_build``, ``save_fdn_build``, ``fdn_build_from_dict`` and
+  ``fdn_build_to_dict`` for reading and writing FDN builds as JSON.
+* Add an FDN-to-FAUST example that compiles a pyFDN design with adac, and a
+  reverberation-enhancement example.
+* Improve the example gallery and stop tracking generated documentation in the
+  repository.
+* Test on Python 3.14 in CI and the documentation build.
+
+0.2.0 (2026-08-10)
+------------------
+
+* Package compact audio examples and predefined colorless-FDN coefficients so
+  browser-hosted tutorials work without repository-relative files.
+* Add public APIs for packaged audio, FDN presets, and paper references.
+* Add generated documentation galleries and wheel-content checks.
+* Keep decay-estimation dependencies optional for a smaller core installation.
+
+0.1.0 (2025-07-02)
+------------------
+
+* First release on PyPI.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyFDN
-Version: 0.4.2
+Version: 0.6.0
 Summary: Python library for Feedback Delay Networks
 Author: Sebastian J. Schlecht, Facundo Franchino, Jeremy Bai
 Maintainer: Facundo Franchino, Sebastian J. Schlecht
@@ -22,20 +22,18 @@ License-File: src/pyFDN/resources/licenses/diff-fdn-colorless-MIT.txt
 Requires-Dist: numpy
 Requires-Dist: soundfile
 Requires-Dist: scipy
-Requires-Dist: flamo>=0.2.14
-Requires-Dist: flareverb
+Requires-Dist: flamo>=0.2.20
+Requires-Dist: cloudpickle>=3
 Provides-Extra: examples
 Requires-Dist: marimo; extra == "examples"
 Requires-Dist: adac; extra == "examples"
 Requires-Dist: matplotlib>=3.5.0; extra == "examples"
-Requires-Dist: plotly>=5.0.0; extra == "examples"
 Requires-Dist: multislope>=0.1.1; extra == "examples"
 Requires-Dist: pyroomacoustics; extra == "examples"
 Provides-Extra: test
 Requires-Dist: marimo; extra == "test"
 Requires-Dist: adac; extra == "test"
 Requires-Dist: matplotlib>=3.5.0; extra == "test"
-Requires-Dist: plotly>=5.0.0; extra == "test"
 Requires-Dist: multislope>=0.1.1; extra == "test"
 Requires-Dist: pyroomacoustics; extra == "test"
 Requires-Dist: pytest>=7.0.0; extra == "test"
@@ -62,7 +60,6 @@ Requires-Dist: sphinx-marimo; extra == "docs"
 Requires-Dist: nbsphinx>=0.9.0; extra == "docs"
 Requires-Dist: ipykernel>=6.0.0; extra == "docs"
 Requires-Dist: pandoc>=2.0; extra == "docs"
-Requires-Dist: plotly>=5.0.0; extra == "docs"
 Requires-Dist: matplotlib>=3.5.0; extra == "docs"
 Requires-Dist: multislope>=0.1.1; extra == "docs"
 Requires-Dist: pyroomacoustics; extra == "docs"
@@ -78,8 +75,8 @@ pyFDN
    :align: center
    :width: 300px
 
-.. image:: https://img.shields.io/badge/python-3.10%20%7C%203.11-blue
-        :target: https://www.python.org/downloads/
+.. image:: https://img.shields.io/pypi/pyversions/pyfdn.svg
+        :target: https://pypi.org/project/pyfdn/
         :alt: Python versions
 
 .. image:: https://img.shields.io/badge/license-MIT-blue.svg
@@ -114,7 +111,7 @@ Highlights
 
 * Matrix polynomial helpers for evaluating, differentiating, and convolving FIR/IIR blocks.
 * Loop analysis utilities including pole boundary estimation and curve bounding checks.
-* Acoustic absorption design tools that translate RT targets into one-pole loop filters.
+* Acoustic absorption design tools that translate RT targets into one-pole and first-order shelf loop filters.
 * Echo density (Abel & Huang 2006) for analysing reverberation and mixing time.
 * Random orthogonal matrix generation to prototype energy-preserving feedback networks.
 
@@ -149,17 +146,24 @@ 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.decay_to_one_pole(1.2, 0.9, delays, fs)
+    absorption = pyFDN.decay_to_one_pole(1.2, delays, fs, rt_nyquist=0.9)
 
-    # convert delay state-space to standard state-space (A_ss, b, c, d)
-    A_ss, b, c, d = pyFDN.dss_to_ss(delays, feedback)
+    # convert delay state-space to standard state-space
+    B, C, D = np.ones((4, 1)) / 2, np.ones((1, 4)) / 2, np.zeros((1, 1))
+    A_ss, B_ss, C_ss, D_ss = pyFDN.dss_to_ss(delays, feedback, B, C, D)
 
 Alternatively, import specific functions directly::
 
     from pyFDN import decay_to_one_pole, lin_to_db, random_orthogonal
 
     feedback = random_orthogonal(4)
-    absorption = decay_to_one_pole(1.2, 0.9, [100, 150, 200, 250], 48_000)
+    absorption = decay_to_one_pole(1.2, [100, 150, 200, 250], 48_000, rt_nyquist=0.9)
+
+
+Citing pyFDN
+------------
+
+If you use pyFDN in research, please cite Sebastian J. Schlecht, Facundo Franchino, and Jeremy B. Bai (2026), *pyFDN: A Python Toolbox for Feedback Delay Network Design, Analysis, and Optimization*, `arXiv:2610.27217 <https://arxiv.org/abs/2610.27217>`_ (technical report; not peer reviewed). BibTeX is available in the `documentation <https://artificial-audio.github.io/pyFDN/#citing-pyfdn>`_.
 
 
 Development