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 from a delay range, a reverberation time, and an EQ.
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 FDN parameters returned by fdn_build_gallery().

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.absorption_filters	Generate FIR absorption filters for each channel.
pyFDN.first_order_absorption	Design first-order shelving absorption filters according to specified reverb time.
pyFDN.first_order_shelving_eq	Design first-order shelving EQ filters from gains in dB at DC and Nyquist.
pyFDN.one_pole_absorption	Design one-pole absorption filters according to specified reverb time.
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.absorption_to_rt	Compute reverb time from recursive absorption filter with delay.
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.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_to_rt	Convert slope (dB/sample) to reverb time in seconds.

Graphic EQ

pyFDN.design_geq	Design a 10-band graphic EQ matching a target magnitude response.
pyFDN.graphic_eq	Build a graphic EQ as a bank of independent biquad sections.
pyFDN.absorption_geq	Design per-delay GEQ absorption filters matching target reverberation times.
pyFDN.probe_sos	Evaluate the magnitude response of each biquad at control frequencies.
pyFDN.shelving_filter	Design a shelving biquad filter.
pyFDN.bandpass_filter	Design a peaking bandpass biquad filter.

DSP Components

pyFDN.FeedbackDelay	Vectorised block delay lines for the FDN.
pyFDN.FIRMatrixFilter	Apply a matrix of FIR filters to a multichannel signal, block by block.
pyFDN.SOSFilterBank	Apply one SOS filter cascade per channel, block by block.

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.

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.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.load_audio	Load a packaged audio file as a NumPy array.
pyFDN.pole_boundaries	Find upper and lower pole boundaries for FDN loop.
pyFDN.skew	Return skew-symmetric matrix from upper triangle (Matlab skew convention).

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.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.with_decay	Return a copy of build with homogeneous decay matching rt.
pyFDN.Trainable	Which FDN parameter groups are trained.
pyFDN.train_fdn	Train model for mode in place and return a TrainLog.
pyFDN.TrainLog	Per-step loss history and stopping info from a training run.

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.

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.