API Reference

All functions and classes are accessible from the top-level pyFDN namespace:

import pyFDN
feedback = pyFDN.random_orthogonal(4)

The reference is organised by functional area, mirroring the package’s module structure. It covers the headline public API; a small number of low-level helpers are exported for advanced/composability use but intentionally omitted here (see tests/test_api_reference.py).

---

Matrix Generators

pyFDN.random_orthogonal	Generate a random orthogonal matrix distributed according to the Haar measure.
pyFDN.random_matrix_shift	Randomly shift polynomial matrices in time.
pyFDN.shift_matrix	Shift a polynomial matrix in time-domain by shift samples.
pyFDN.shift_matrix_distribute	Randomly distribute time shifts for a polynomial matrix.
pyFDN.householder_matrix	Create a Householder reflection matrix from a vector.
pyFDN.anderson_matrix	Build an N×N block-circulant orthogonal matrix.
pyFDN.complete_orthogonal	Solve the orthogonal completion problem for feedback matrix A.
pyFDN.nearest_orthogonal	Return the nearest orthogonal matrix to A in the Frobenius norm.
pyFDN.nearest_sign_agnostic_orthogonal	Find the orthogonal matrix U minimising ‖A − |U|‖_F.
pyFDN.degree_one_lossless	Build the degree-one lossless polynomial matrix V(z) = (I - vv^T) + z^{-1} vv^T.
pyFDN.schroeder_reverberator	Create combs and allpass filters as a single FDN.
pyFDN.allpass_in_fdn	Create an allpass structure embedded in an FDN of size [2N, 2N].
pyFDN.construct_cascaded_paraunitary_matrix	Construct a paraunitary matrix and its reverse response.
pyFDN.construct_paraunitary_from_elementals	Construct a random paraunitary matrix as a cascade of elemental factors.
pyFDN.construct_velvet_feedback_matrix	Wrapper for construct_cascaded_paraunitary_matrix using Hadamard stages.
pyFDN.tiny_rotation_matrix	Generate orthogonal matrix with small eigenvalue angles.
pyFDN.rotation_matrix_from_angles	Generate orthogonal matrix with prescribed eigenvalue angles.
pyFDN.fdn_matrix_gallery	Return a feedback matrix of the requested type, or list all type names.
pyFDN.fdn_system_gallery	Return a full FDN system (A, B, C, D) of the requested type, or list all type names.
pyFDN.filter_matrix_gallery	Return an FIR (filter) feedback matrix of the requested type, or list all type names.
pyFDN.fdn_build_gallery	Build a complete FDN and optionally return its non-inferable design.
pyFDN.sample_delay_lengths	Generate N delay-line lengths in samples.
pyFDN.FDNSystem	Full FDN system matrices returned by fdn_system_gallery().
pyFDN.FDNBuild	Complete, renderable parameters of a vanilla FDN.

Allpass FDN

pyFDN.homogeneous_allpass_fdn	Generate allpass FDN with homogeneous decay: V = [A,b;c,d] uniallpass, A = U @ G.
pyFDN.rand_admissible_homogeneous_allpass	Generate a random admissible diagonal matrix P for homogeneous uniallpass FDN.
pyFDN.complete_fdn	Compute a completion (B,C,D) for given A.
pyFDN.complete_full_mimo_halmos	Full MIMO (k=N) Halmos/Julia dilation.
pyFDN.complete_general_mimo_svd	General MIMO completion via defect subspace (CS/SVD-based).
pyFDN.nested_allpass	Create Gardner's nested allpass FDN (SISO).
pyFDN.poletti_allpass	Create Poletti's MIMO unitary reverberator (allpass FDN).
pyFDN.series_allpass	Create Schroeder's series allpass FDN (SISO).
pyFDN.is_allpass	Test whether the delay state-space system is allpass.
pyFDN.is_uniallpass	Test whether the FDN is uniallpass (lossless with a diagonal Lyapunov matrix).
pyFDN.is_paraunitary	Test whether a MIMO impulse response is paraunitary (lossless).

Scattering Delay Network

pyFDN.SDN

Minimal SDN: from room and source/receiver, compute only network parameters (delay lengths, routing, scattering matrices, wall filters) for use in an FDN.

Acoustics & Absorption

pyFDN.sos_gain_per_sample_curves	Magnitude response (gain per sample vs angle) for a per-channel SOS bank.
pyFDN.echo_density	Echo density and mixing time (Abel & Huang 2006).
pyFDN.edc	Energy decay curve: backward cumulative sum of squared signal along an axis.
pyFDN.estimate_initial_level_bands	Estimate the initial level of the exponential decay per octave band.
pyFDN.estimate_rt_bands	Estimate RT in octave bands via Butterworth bandpass filtering.
pyFDN.octave_bands	Octave band edges and centre frequencies.
pyFDN.octave_band_filterbank	Butterworth bandpass filters (SOS) for the given band edges.
pyFDN.rt_to_gain_per_sample	Convert reverb time (seconds) to gain coefficient per sample.
pyFDN.rt_to_slope	Convert reverb time (RT, seconds) to energy decay slope (dB per sample).
pyFDN.slope_amplitude_to_level	Initial amplitude of an exponential decay from its energy (EDC amplitude).
pyFDN.slope_to_rt	Convert slope (dB/sample) to reverb time in seconds.

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 pyFDN.AttenuationFilter and 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.

pyFDN.EQDesign
pyFDN.decay_to_geq	Design attenuation GEQs from ten reverberation times in seconds.
pyFDN.decay_to_first_order_shelf	Design first-order attenuation shelves from endpoint RTs in seconds.
pyFDN.decay_to_one_pole	Design one-pole attenuation filters from endpoint RTs in seconds.
pyFDN.gain_to_geq	Design a ten-band graphic EQ from amplitudes in dB.
pyFDN.gain_to_bounded_geq	Design a graphic EQ with bounded internal section gains.
pyFDN.gain_to_first_order_shelf	Design a first-order shelf from its endpoint amplitudes in dB.
pyFDN.gain_to_one_pole	Design a one-pole filter from its endpoint amplitudes in dB.
pyFDN.geq_design_matrix	Return the constant map from ten band targets to eleven command gains.
pyFDN.lowshelf_biquad	Return (b, a) for a second-order low-shelf section.
pyFDN.highshelf_biquad	Return (b, a) for a second-order high-shelf section.
pyFDN.peaking_biquad	Return (b, a) for a peaking section.
pyFDN.first_order_shelf_biquad	Return a normalized one-section SOS from two linear amplitudes.
pyFDN.one_pole_biquad	Return a normalized one-pole section from two linear amplitudes.
pyFDN.probe_sos	Evaluate the magnitude response of each biquad at control frequencies.

Time-Domain Graph (pyFDN.td)

Stateful block-processing operators, wired into a graph by the connectors and rendered with .process(signal). See pyFDN.td.

pyFDN.td.TimeOperator	Abstract class.
pyFDN.td.Identity	Stateless pass-through.
pyFDN.td.Gain	Stateless static gain matrix y = x @ M.T with M of shape (out, in).
pyFDN.td.Delay	Stateful per-channel integer feed-forward delay line, y[n, c] = x[n - m_c, c].
pyFDN.td.AbsoluteValue	Stateless memoryless nonlinearity y[n, c] = |x[n, c]|.
pyFDN.td.DCBlocker	Stateful per-channel first-order DC blocker with optional slow energy compensation, y[n, c] = x[n, c] - x[n-1, c] + R * y[n-1, c].
pyFDN.td.ControllableFullWaveRect	Stateful, controllable, memoryless nonlinearity, y[n, c] = g_cfwr * ((1 - alpha) * x[n, c] + alpha * abs(x[n, c])), applied to active_channels only; the rest pass through unchanged.
pyFDN.td.SDFD	Stateful, controllable Signal-Dependent Fractional Delay, y[n, c] = (1 - d) n[n-1, c] + d n[n, c] + d p[n-2, c] + (1 - d) p[n-1, c], applied to active_channels only; the rest pass through unchanged.
pyFDN.td.RingModulator	Stateful, controllable ring modulator, y[n, c] = mod_amp * x[n, c] * sin(2 * pi * mod_freq * n / fs), applied to active_channels only; the rest pass through unchanged.
pyFDN.td.PitchShift	Stateful, controllable dual-read-head pitch shifter.
pyFDN.td.GranularPitchShift	Stateful, controllable granular pitch shifter.
pyFDN.td.SOSBank	Stateful per-channel SOS filter cascade (e.g. in-loop absorption).
pyFDN.td.MatrixFIR	Stateful matrix of FIR filters (e.g. a paraunitary scattering feedback matrix).
pyFDN.td.MatrixConvolver	Stateful matrix of FIR filters via streaming overlap-save FFT convolution.
pyFDN.td.TimeVaryingMatrix	Stateful sinusoidally modulated orthogonal mixing matrix (time-varying feedback).
pyFDN.td.RecursionState	Vectorised bank of block-addressable delay lines.
pyFDN.td.Series	Chain operators left to right.
pyFDN.td.Parallel	Feed the same input to every branch and combine the outputs (optional).
pyFDN.td.Recursion	Closed feedback loop, y[n] = fF(x[n] + fB(y[n - block_size])).

Delay Utilities

pyFDN.matrix_delay_approximation	Rank-1 approximation of matrix group delay.
pyFDN.mgrpdelay	Group delay for each entry of an FIR matrix.
pyFDN.ms_to_smp	Convert milliseconds to samples.
pyFDN.flamo_time_response	Return a FLAMO model's time response as a NumPy array.
pyFDN.flamo_freq_response	Return a FLAMO model's (complex) frequency response as a NumPy array.

Building a FLAMO Graph

An FDN as FLAMO modules, assembled from numpy values. The three filter hooks – post_delay inside the loop, post_matrix on the feedback path, post_output on the wet signal – are the same three pyFDN.process_fdn() takes, in the same positions and under the same names.

pyFDN.assemble_fdn_core	Wire pre-built FLAMO modules into an FDN core (no FFT/iFFT wrapping).
pyFDN.wrap_fdn_shell	Wrap an FDN core in a FLAMO Shell that returns the impulse response.
pyFDN.gain_module	Build a FLAMO Gain module from a numpy array.
pyFDN.delay_module	Build a FLAMO parallelDelay module from delay lengths in seconds.
pyFDN.matrix_module	Build a FLAMO Matrix initialized to values under a parametrization.
pyFDN.fir_matrix_module	Build a FLAMO Filter module from a matrix FIR coefficient array.
pyFDN.sos_filter_module	Build a FLAMO parallelSOSFilter from an SOS coefficient array.
pyFDN.hook_module	One FLAMO module for a filter hook, from an SOS bank, a module, or several.
pyFDN.AttenuationFilter	Parallel in-loop SOS bank parametrized by reverberation time.
pyFDN.OutputEQ	Parallel SOS bank parametrized by gain in dB.

Polynomial & Matrix Maths

pyFDN.adj_poly	Adjugate of a polynomial matrix via FFT evaluation.
pyFDN.adjugate	Adjugate matrix, valid also for singular and complex matrices.
pyFDN.det_polynomial	Determinant of a polynomial matrix in the z^{-1} convention.
pyFDN.general_char_poly	Generalized characteristic polynomial (GCP) for delay state-space.
pyFDN.interpolate_orthogonal	Geodesic interpolation between two orthogonal matrices.
pyFDN.is_orthogonal	Check if Q is orthogonal (Q.T @ Q ≈ I).
pyFDN.is_unilossless	Test whether A is diagonally similar to an orthogonal matrix.
pyFDN.loop_tf	Loop transfer function P(z) = diag(z^m) - A as a polynomial matrix.
pyFDN.matrix_convolution	Matrix polynomial multiplication by convolution.
pyFDN.matrix_polyder	Derivative of rational filter matrices in the z^{-1} convention.
pyFDN.matrix_polyval	Evaluate a matrix polynomial P at the complex point z.
pyFDN.matrix_sqrt	Matrix square root via eigenvalue decomposition.
pyFDN.negpolyder	Derivative of rational polynomial with negative exponents.
pyFDN.outer_sum_approximation	Rank-1 approximation minimizing ||u + v^T - matrix||_F.
pyFDN.poly_degree	Return the polynomial degree in the z^{-1} convention.
pyFDN.polyder_rational	Derivative of rational polynomial using quotient rule.
pyFDN.polydiag	Construct a diagonal polynomial matrix from an array of polynomials.

General Utilities

pyFDN.db_to_lin	Convert decibel values to linear magnitude.
pyFDN.db_to_sq	Convert decibel values to squared magnitude (power).
pyFDN.lin_to_db	Convert linear magnitude to decibels with numerical guard.
pyFDN.sq_to_db	Convert squared magnitude (power) to decibels with numerical guard.
pyFDN.ensure_3d	Ensure the matrix has a trailing polynomial dimension.
pyFDN.fade_out	Apply a linear fade-out over the last fade_samples samples.
pyFDN.hertz_to_unit	Convert frequency (Hz) to normalised frequency (0-1).
pyFDN.hertz_to_rad	Convert frequency (Hz) to angular frequency (rad/sample).
pyFDN.rad_to_hertz	Convert angular frequency (rad/sample) to frequency (Hz).
pyFDN.is_bounding_curve	Check if all value points are bounded by the curve.
pyFDN.last_nonzero_indices	Return 1-based indices of the last non-zero element along axis 2.
pyFDN.max_corr	Pairwise maximum normalized cross-correlation of a MIMO signal matrix.
pyFDN.mulaw_decode	Mu-law companding (decode): companded to linear amplitude.
pyFDN.mulaw_encode	Mu-law companding (encode): linear amplitude to companded.
pyFDN.peak_normalize	Scale array so the maximum absolute value equals target_peak.
pyFDN.pole_boundaries	Find upper and lower pole boundaries for FDN loop.
pyFDN.skew	Return skew-symmetric matrix from upper triangle.

Build Files, Packaged Examples & References

pyFDN.available_audio	Return the names accepted by load_audio().
pyFDN.audio_metadata	Return attribution and license metadata for a packaged audio sample.
pyFDN.load_audio	Load an audio sample distributed with pyFDN.
pyFDN.available_fdn_presets	Return the names accepted by get_fdn_preset().
pyFDN.get_fdn_preset	Return a packaged FDNPreset document.
pyFDN.FDNPreset	A baked vanilla FDN plus metadata and optional design information.
pyFDN.fdn_preset_to_dict	Convert an FDNPreset to a JSON-compatible dictionary.
pyFDN.fdn_preset_from_dict	Construct an FDNPreset from a parsed JSON dictionary.
pyFDN.save_fdn_preset	Write a preset as indented, human-readable JSON.
pyFDN.load_fdn_preset	Load an FDNPreset from a JSON file.
pyFDN.fdn_build_to_dict	Convert an FDNBuild to its JSON-compatible format.
pyFDN.fdn_build_from_dict	Construct an FDNBuild from its JSON-compatible dictionary.
pyFDN.save_fdn_build	Write an FDNBuild as indented, human-readable JSON.
pyFDN.load_fdn_build	Load an FDNBuild from its JSON format.
pyFDN.paper_reference	Return a copy of the bibliography fields for paper_id.
pyFDN.paper_link	Return a Markdown citation link for a packaged bibliography entry.

State-Space Translators

pyFDN.dss_to_ss	Convert delay state-space (DSS) FDN to standard state-space.
pyFDN.dss_to_impz	Compute MIMO impulse response from delay state-space (DSS) representation.
pyFDN.build_to_impz	Render an FDNBuild to a time-domain impulse response.
pyFDN.dss_to_tf	From delay state-space to transfer function matrix (numerator and denominator).
pyFDN.dss_to_pr	Modal decomposition of an FDN from raw DSS matrices.
pyFDN.dss_to_flamo	Build a FLAMO model from delay state-space (A, B, C, D, m).
pyFDN.build_to_flamo	Build a FLAMO model from a complete FDNBuild config.
pyFDN.flamo_to_pr	Poles/residues from a FLAMO transfer H(z) = C(z)P(z)^{-1}B(z) + D(z).
pyFDN.flamo_decompose_for_pr	Decompose a FLAMO model into the subgraphs needed for poles/residues.
pyFDN.flamo_extract_pr_decomposition	Extract the H(z)=C P(z)^{-1}B+D probes from a FLAMO model.
pyFDN.FlamoDecompositionForPR	Decomposition of a FLAMO model into small subgraphs for poles/residues.
pyFDN.impz_to_res	Estimate residues from impulse response and known poles via least squares.
pyFDN.mtf_to_impz	Compute MIMO impulse response from matrix transfer function (numerator/denominator).
pyFDN.pr_to_impz	Synthesize impulse response from poles and residues.

FDN Processing

pyFDN.process_fdn	Simulate the feedback delay network using block processing.
pyFDN.flamo_process	Run a 1-D signal through a FLAMO Shell model offline.

Training

pyFDN.build_fdn	Build a trainable flamo Shell from a config.
pyFDN.trainable_from_build	Build a trainable flamo Shell initialized from an FDNBuild.
pyFDN.trainable_from_preset	Build a FLAMO model while recovering designed filter parameters.
pyFDN.build_set_decay	Return a copy of build with homogeneous decay matching rt.
pyFDN.Trainable	Which of the FDN's gain groups are trained.
pyFDN.train_fdn	Train model on loss in place and return a TrainLog.
pyFDN.TrainLog	Per-step loss history and stopping info from a training run.
pyFDN.LOSSLESS_ALIAS_DECAY_DB	Convert a string or number to a floating-point number, if possible.

Training Objectives

An objective is a weighted sum of losses, composed with + and *. Losses on the impulse response read a pyFDN.Response; losses on a model parameter take a pyFDN.ParamRef from pyFDN.param().

pyFDN.Response	The impulse response of an FDN, as a loss sees it.
pyFDN.model_response	Run model on an impulse and wrap the result in a Response.
pyFDN.param	Reference the parameter called name in model.
pyFDN.params	Every parameter of model, in graph order.
pyFDN.ParamRef	A reference to one parameter of one model.
pyFDN.Loss	Base class for training losses.
pyFDN.FlatMagnitude	Mean squared error of \(|H|\) against a flat target -- colorless.
pyFDN.AsymmetricFlatMagnitude	Flatness that punishes peaks far harder than dips -- colorless.
pyFDN.FlatSpectrogram	Flatness measured on multi-resolution smoothed spectra -- colorless.
pyFDN.MatchMagnitude	Mean squared error of \(|H|\) against a reference impulse response.
pyFDN.MatchSpectrogram	Multi-resolution STFT distance to a reference impulse response.
pyFDN.MatchMelSpectrogram	Mel-scaled multi-resolution STFT distance (FLAMO's mel_mss_loss).
pyFDN.MatchImpulseResponse	Mean squared error against a reference impulse response, sample by sample.
pyFDN.MatchEnergyDecay	RMS dB error of the octave-band energy decay curves against a reference.
pyFDN.MatchCumulativeEnergy	Doubly-cumulated energy against a reference -- decay and colour, no bands.
pyFDN.Energy	Squared deviation of the response's total energy from target.
pyFDN.Sparsity	Density penalty on a square mixing matrix, after Optimizing Tiny Colorless FDNs (Dal Santo et al.).
pyFDN.L1	Mean absolute value of a parameter -- pushes it toward sparse.
pyFDN.L2	Mean squared value of a parameter -- plain weight decay.

Plotting

pyFDN.plot_matrix	Plot a single matrix as a Plotly heatmap (RdBu, square pixels).
pyFDN.plot_matrix_grid	Plot several matrices as a grid of Plotly heatmaps sharing one color scale.
pyFDN.plot_system_matrix	Plot system matrix [A b; c d] as 2x2 Plotly heatmaps, shared RdBu color scale.
pyFDN.plot_fdn_parameter	Plot all FDN parameters in one figure.
pyFDN.plot_FDN_build	Plot the parameters stored in an pyFDN.FDNBuild.
pyFDN.plot_db_per_sample	Plot SOS magnitude responses normalized by delay length (dB per sample).
pyFDN.plot_impulse_response	Plot one or more impulse responses over time, mu-law compressed by default.
pyFDN.plot_impulse_response_matrix	Plot matrix of impulse responses in a subplot grid (out x in).
pyFDN.plot_edc	Plot the energy decay curve (EDC) of one or more impulse responses.
pyFDN.plot_spectrogram	Plot spectrogram of a 1-D signal as a Matplotlib image.
pyFDN.animate	Animate a sequence of frames built by any per-frame plotting function.
pyFDN.downsampled_scatter	Create a Plotly go.Scatter trace with downsampled line data.
pyFDN.downsample_minmax	Downsample a line while preserving local minima and maxima.
pyFDN.downsample_plotly_trace	Return a copy of a Plotly trace with downsampled x and y data.

Notebook Display

pyFDN.labeled_audio

Stack a text label above an audio player (a marimo element).

FLAMO Graph

pyFDN.plot_flamo_graph	Draw the FLAMO model signal flow with matplotlib.
pyFDN.flamo_model_to_nodes	Traverse a FLAMO model and build a tree of nodes (nested dicts).
pyFDN.flamo_nodes_flat	Flatten the node tree into a list of nodes, each with a 'path' key.
pyFDN.extract_build	Extract a complete FDNBuild from a named FLAMO model graph.