pyFDN.auxiliary package#

Submodules#

pyFDN.auxiliary.acoustics module#

Acoustics and RT related functions.

pyFDN.auxiliary.acoustics.absorption_filters(frequency, target_rt, filterOrder, delays, fs)[source]#

Generate FIR absorption filters for each channel. frequency: [freq_points] target_rt: shape (freq_points, channels) delays: array of length channels

Return type:: ndarray

pyFDN.auxiliary.acoustics.absorption_to_rt(filterCoeffs, delays, nfft, fs)[source]#

Compute reverb time from recursive absorption filter with delay.

Return type:: tuple[ndarray, ndarray]

pyFDN.auxiliary.acoustics.echo_density(ir, n=1024, fs=48000.0, pre_delay=0, mixing_thresh=1.0, hop=500)[source]#

Echo density and mixing time (Abel & Huang 2006).

Computes the transition time between early reflections and stochastic reverberation assuming sound pressure in a reverberant field is Gaussian distributed.

Reference: Abel & Huang (2006), “A simple, robust measure of reverberation echo density”, Proc. 121st AES Convention, San Francisco.

Parameters:

ir (array-like) – Impulse response (1 channel only). Converted to 1D.
n (int, optional) – Window length (must be even). Default 1024.
fs (float, optional) – Sampling rate in Hz. Default 48000.
pre_delay (int, optional) – Onset delay in samples for mixing time. Default 0.
mixing_thresh (float, optional) – Normalized echo density threshold for mixing time (Abel & Huang use 1). Default 1.0.
hop (int, optional) – Hop size in samples for sparse analysis. Default 500.

Return type:

tuple[float, ndarray]

Returns:

t_abel (float) – Mixing time in milliseconds (time at which echo density first exceeds mixing_thresh, relative to pre_delay). 0 if not found.
echo_dens (np.ndarray) – Echo density vector (length = len(ir)), normalized; interpolated from sparse analysis.

pyFDN.auxiliary.acoustics.edc(ir, axis=0)[source]#

Energy decay curve: backward cumulative sum of squared signal along an axis.

EDC(t) = sum(ir[t:]^2), so the curve decreases from total energy to zero. Typically used with impulse responses with shape (n_samples, n_channels).

Parameters:

ir (array-like) – Signal(s). If 1D, EDC of that signal. If 2D (e.g. samples x channels), EDC is computed along the time axis for each channel.
axis (int, optional) – Axis along which time runs (default 0). EDC is computed along this axis.

Returns:

Same shape as ir. Values are non-negative and non-increasing along axis.

Return type:

np.ndarray

pyFDN.auxiliary.acoustics.estimate_initial_level_bands(ir, rt, fs, fc=1000.0, start=-4.0, n=8, filter_order=8)[source]#

Estimate the initial level of the exponential decay per octave band.

Companion to estimate_rt_bands() (same octave filterbank). Models the squared band-filtered impulse response as L^2 * 10^(-6 t / T) and matches the total band energy: E = L^2 * T * fs / (6 ln 10), hence L = sqrt(6 ln(10) E / (T fs)). This replaces the DecayFitNet initial-level estimate used in the MATLAB example_RIR2FDN.

Parameters:

ir (array-like, 1-D) – Impulse response, starting at the onset.
rt (array-like) – RT in seconds per band, as returned by estimate_rt_bands() with the same band parameters.
fs (float) – Sampling rate in Hz.
fc (float) – Octave filterbank parameters, see estimate_rt_bands().
start (float) – Octave filterbank parameters, see estimate_rt_bands().
n (int) – Octave filterbank parameters, see estimate_rt_bands().
filter_order (int) – Octave filterbank parameters, see estimate_rt_bands().

Return type:

tuple[ndarray, ndarray]

Returns:

level ((n_bands,) ndarray) – Initial level (linear amplitude) per band.
f_centre ((n_bands,) ndarray) – Centre frequencies in Hz corresponding to each level.

pyFDN.auxiliary.acoustics.estimate_rt_bands(ir, fs, fc=1000.0, start=-4.0, n=8, filter_order=8, decay_db=30.0)[source]#

Estimate RT in octave bands via Butterworth bandpass filtering.

Filters the impulse response into octave bands using pyroomacoustics.bandpass_filterbank, then estimates RT per band using pyroomacoustics.measure_rt60 (extrapolated from decay_db).

Default bands: 63, 125, 250, 500, 1000, 2000, 4000, 8000 Hz (start=-4, n=8). Bands whose upper edge exceeds fs/2 are dropped.

Parameters:

ir (array-like, 1-D) – Impulse response.
fs (float) – Sampling rate in Hz.
fc (float) – Octave-band reference centre frequency in Hz (default 1000).
start (float) – Octave offset of the lowest band relative to fc (default -4 → 62.5 Hz).
n (int) – Number of octave bands (default 8).
filter_order (int) – Butterworth filter order (default 8).
decay_db (float) – Decay range in dB used for the linear fit. The default 30 dB fit is extrapolated to a 60 dB reverberation time.

Return type:

tuple[ndarray, ndarray]

Returns:

rt ((n_bands,) ndarray) – Estimated RT in seconds per band.
f_centre ((n_bands,) ndarray) – Centre frequencies in Hz corresponding to each RT value.

pyFDN.auxiliary.acoustics.first_order_absorption(rt_dc, rt_ny, delays, fs, crossover_frequency=None)[source]#

Design first-order shelving absorption filters according to specified reverb time.

Each delay line gets a first-order shelving filter whose gain matches the target decay (rt_dc at DC, rt_ny at Nyquist) for its delay length, with the shelf transition at crossover_frequency.

Reference: Jot, J. M., “Proportional parametric equalizers - Application to digital reverberation and environmental audio processing”, AES 2015.

Parameters:

rt_dc (float) – Reverberation time in seconds at DC.
rt_ny (float) – Reverberation time in seconds at Nyquist.
delays (array-like) – Delay lengths in samples, one per channel.
fs (float) – Sampling rate in Hz.
crossover_frequency (float, optional) – Shelf crossover frequency in Hz. Defaults to fs/8, the midpoint of the warped (bilinear) frequency axis. Values above fs/5 are clamped to fs/5 since a too high crossover leads to an unstable filter (fs/4 is the limit).

Returns:

One-section per-channel SOS bank of shape (1, 6, N) (the canonical SOS bank layout); section rows are [b0, b1, b2, a0, a1, a2] (b2 = a2 = 0 for these first-order filters).

Return type:

np.ndarray

pyFDN.auxiliary.acoustics.first_order_shelving_eq(db_dc, db_nyquist, fs, crossover_frequency=None)[source]#

Design first-order shelving EQ filters from gains in dB at DC and Nyquist.

Unlike first_order_absorption() (whose gains are derived from a reverberation time and a delay length), the shelf endpoints are specified directly as decibel gains. Useful as a per-output tone correction (post EQ).

Parameters:

db_dc (array-like) – Gain in dB at DC, scalar or one value per channel.
db_nyquist (array-like) – Gain in dB at Nyquist, scalar or one value per channel. Broadcast against db_dc to a common number of channels.
fs (float) – Sampling rate in Hz.
crossover_frequency (float, optional) – Shelf crossover frequency in Hz. Defaults to fs/8; clamped to fs/5.

Returns:

One-section per-channel SOS bank of shape (1, 6, N) (canonical SOS bank layout); section rows are [b0, b1, b2, a0, a1, a2].

Return type:

np.ndarray

pyFDN.auxiliary.acoustics.one_pole_absorption(rt_dc, rt_ny, delays, fs)[source]#

Design one-pole absorption filters according to specified reverb time.

Returns a one-section per-channel SOS bank of shape (1, 6, N) (the canonical SOS bank layout; section rows are [b0, b1, b2, a0, a1, a2]).

Return type:: ndarray

pyFDN.auxiliary.acoustics.rt_to_gain_per_sample(rt, fs)[source]#

Convert reverb time (seconds) to gain coefficient per sample.

The gain g satisfies g^(rt*fs) = 10^(-3), i.e. about -30 dB after rt seconds.

Return type:: float

pyFDN.auxiliary.acoustics.rt_to_slope(rt, fs)[source]#

Convert reverb time (RT, seconds) to energy decay slope (dB per sample).

Return type:: ndarray

pyFDN.auxiliary.acoustics.slope_to_rt(slope, fs)[source]#

Convert slope (dB/sample) to reverb time in seconds.

Return type:: ndarray

pyFDN.auxiliary.acoustics.sos_gain_per_sample_curves(sos, delays, nfft=512)[source]#

Magnitude response (gain per sample vs angle) for a per-channel SOS bank.

Evaluates \(|H(e^{j\omega})|\) at nfft angles from 0 to \(\pi\) (Nyquist) for each channel’s SOS cascade, then scales by delay length so that the result is gain per sample: for channel j with delay m_j, the curve is \(|H|^{1/m_j}\), so that after m_j samples the effective gain is \(|H|\). Useful for plotting absorption/gain curves (e.g. on a pole plot).

Parameters:

sos ((n_sections, 6, N) array) – Per-channel SOS bank; section rows are [b0, b1, b2, a0, a1, a2]. Same format as one_pole_absorption() / first_order_absorption() return.
delays ((N,) array-like) – Delay lengths in samples, one per channel. Used to scale gain to per-sample.
nfft (int) – Number of frequency points (default 512).

Return type:

tuple[ndarray, ndarray]

Returns:

angles ((nfft,) array) – Angles in rad/sample, 0 to pi.
magnitude ((nfft, N) array) – Gain per sample (linear), i.e. \(|H(e^{j\omega})|^{1/m}\) per channel.

pyFDN.auxiliary.allpass module#

Allpass FDN helpers (Poletti MIMO reverberator, uniallpass test, etc.).

Based on Poletti (1995) and “Allpass Feedback Delay Networks” by Sebastian J. Schlecht.

pyFDN.auxiliary.allpass.is_allpass(A, B, C, D, delays, tol=1e-09)[source]#

Test whether the delay state-space system is allpass.

Checks that the determinant transfer function has numerator = reversed(denominator) (up to sign). See “Allpass Feedback Delay Networks” by Sebastian J. Schlecht.

Parameters:

A (array-like) – Delay state-space matrices.
B (array-like) – Delay state-space matrices.
C (array-like) – Delay state-space matrices.
D (array-like) – Delay state-space matrices.
delays (array-like) – Delay lengths (samples), length N.
tol (float) – Tolerance for coefficient comparison.

Return type:

tuple[bool, ndarray, ndarray]

Returns:

is_a (bool) – True if allpass.
den (ndarray) – Denominator polynomial (z^{-1} ordering).
num (ndarray) – Numerator polynomial (z^{-1} ordering).

pyFDN.auxiliary.allpass.is_paraunitary(ir, tol=1e-09)[source]#

Test whether a MIMO impulse response is paraunitary (lossless).

For real IR matrix H(t), checks that sum_t H(t) H(t)’ = I (output correlation) and sum_t H(t)’ H(t) = I (input correlation).

Parameters:

ir (ndarray, shape (ir_len, n_out, n_in)) – Impulse response [time, output, input].
tol (float) – Tolerance for identity check.

Return type:

tuple[bool, ndarray, float]

Returns:

is_p (bool) – True if paraunitary.
test_matrix (ndarray) – Output correlation matrix (n_out, n_out); should be identity.
max_off_diagonal (float) – Max absolute off-diagonal value in test_matrix.

pyFDN.auxiliary.allpass.is_uniallpass(A, B, C, D, tol=1e-09)[source]#

Test whether the FDN is uniallpass (lossless with a diagonal Lyapunov matrix).

See Michaletzky, G. Factorization of discrete-time all-pass functions; and “Allpass Feedback Delay Networks” by Sebastian J. Schlecht.

Parameters:

A (array-like) – Delay state-space matrices (feedback, input gain, output gain, direct).
B (array-like) – Delay state-space matrices (feedback, input gain, output gain, direct).
C (array-like) – Delay state-space matrices (feedback, input gain, output gain, direct).
D (array-like) – Delay state-space matrices (feedback, input gain, output gain, direct).
tol (float) – Tolerance for zero and diagonal checks.

Return type:

tuple[bool, ndarray]

Returns:

is_a (bool) – True if the system is uniallpass.
P (ndarray) – Solution of discrete Lyapunov A P A’ - P + B B’ = 0; diagonal if uniallpass.

pyFDN.auxiliary.allpass.nested_allpass(g)[source]#

Create Gardner’s nested allpass FDN (SISO).

Iteratively nests a feedforward/back allpass around the previous FDN. From Gardner, W. G. (1992). A real-time multichannel room simulator. J. Acoust. Soc. Am. 92, 1–23. See “Allpass Feedback Delay Networks”, Schlecht.

Parameters:

g (array-like, shape (N,)) – Feedforward/back gains for each nesting stage.

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

Returns:

A (ndarray (N, N)) – Feedback matrix.
B (ndarray (N, 1)) – Input gain (column vector).
C (ndarray (1, N)) – Output gain (row vector).
D (ndarray (1, 1)) – Direct gain (scalar).

pyFDN.auxiliary.allpass.poletti_allpass(g, U)[source]#

Create Poletti’s MIMO unitary reverberator (allpass FDN).

From Poletti, M. (1995). A unitary reverberator for reduced colouration in assisted reverberation systems. INTER-NOISE and NOISE-CON, 5, 1223–1232.

Parameters:

g (float) – Scalar feedback gain (e.g. 0.7).
U (ndarray (N, N)) – Unitary (orthogonal) feedback matrix.

Returns:

A, B, C, D – Delay state-space matrices: A = -g*U, B = (1+g)*I, C = (1-g)*U, D = g*I.

Return type:

ndarray

pyFDN.auxiliary.allpass.series_allpass(g)[source]#

Create Schroeder’s series allpass FDN (SISO).

Iterative series connection of feedforward/back allpass filters (same as seriesAllpass.m). Each stage appends one delay line via seriesFDNinAllpass. From Schroeder & Logan (1961). “Colorless” artificial reverberation. IRE Trans. Audio AU-9, 209–214. See “Allpass Feedback Delay Networks”, Schlecht.

Parameters:

g (array-like, shape (N,)) – Per-section gains (e.g. in (0, 1)).

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

Returns:

A (ndarray (N, N)) – Feedback matrix.
B (ndarray (N, 1)) – Input gain (column vector).
C (ndarray (1, N)) – Output gain (row vector).
D (ndarray (1, 1)) – Direct gain (scalar).

pyFDN.auxiliary.audio module#

Helpers for loading the audio files packaged with pyFDN.

pyFDN.auxiliary.audio.load_audio(name, *, fs=None, package='pyFDN.audio', mono=True)[source]#

Load a packaged audio file as a NumPy array.

Parameters:

name (str) – File name within package (e.g. "synth_dry.wav").
fs (int, optional) – Target sampling rate. If given and different from the file’s rate, the signal is resampled to fs.
package (str) – Importable package holding the audio resource.
mono (bool) – If True, keep only the first channel of multichannel files.

Returns:

(signal, fs) – Samples as float64 and the (possibly resampled) sampling rate.

Return type:

tuple[np.ndarray, int]

pyFDN.auxiliary.coupled_rooms module#

Coupled rooms FDN builder.

Translation of example_coupledRooms.m from fdnToolbox. Original MATLAB code: (c) Sebastian Jiro Schlecht, 2020 Python translation: Facundo Franchino, 2025

pyFDN.auxiliary.coupled_rooms.create_coupled_rooms_fdn()[source]#

Create a coupled rooms FDN matching the MATLAB implementation.

This function builds a 12-delay-line FDN modeling two acoustically coupled rooms with different reverberation characteristics.

Returns:: Impulse response (numpy array, shape [samples, 2]) fs: Sample rate (48000 Hz) feedback_matrix: The 12x12 feedback matrix used delay_lengths: The 12 delay lengths in samples
Return type:: ir

Example

>>> torch.manual_seed(5)
>>> np.random.seed(5)
>>> ir, fs, fb, delays = create_coupled_rooms_fdn()
>>> ir.shape
(96000, 2)

pyFDN.auxiliary.delay module#

Delay related functions.

pyFDN.auxiliary.delay.flamo_delay_feedback_matrix(model, delays, delays_in, delays_out, *, inplace=False)[source]#

Place a delay-matrix-delay chain in a FLAMO FDN feedback path.

The model is expected to have the topology produced by pyFDN.dss_to_flamo(). Its feedforward delay is set to delays and its feedback matrix is wrapped by delays of delays_in and delays_out samples. By default, the operation returns a deep copy.

Return type:: Any

pyFDN.auxiliary.delay.matrix_delay_approximation(matrix)[source]#

Rank-1 approximation of matrix group delay.

Return type:: tuple[ndarray, ndarray]

pyFDN.auxiliary.delay.mgrpdelay(matrix)[source]#

Group delay for each entry of an FIR matrix.

Return type:: tuple[ndarray, ndarray]

pyFDN.auxiliary.delay.ms_to_smp(ms, fs)[source]#

Convert milliseconds to samples.

Return type:: ndarray

pyFDN.auxiliary.delay.swap_flamo_recursion_paths(model, *, inplace=False)[source]#

Swap the feedforward and feedback paths of a FLAMO FDN recursion.

Return type:: Any

pyFDN.auxiliary.flamo module#

Standard wrappers for FLAMO modules that accept numpy arrays and return FLAMO modules.

All functions require flamo to be installed. They take numpy arrays and common options (nfft, device, etc.) and return configured FLAMO dsp modules with values assigned.

pyFDN.auxiliary.flamo.assemble_fdn_core(*, input_gain, feedback, delays, output_gain, direct=None, loop_filter=None, output_filter=None, post_delay_module=None)[source]#

Wire pre-built FLAMO modules into an FDN core (no FFT/iFFT wrapping).

Single source of truth for the FDN signal flow, shared by the render path (pyFDN.dss_to_flamo()) and the training builder (pyFDN.train.trainable_from_build()). All arguments are already-built FLAMO dsp/system modules; this only composes them, so leaf names and topology stay identical across both callers (and match the names pyFDN.extract_build() looks for).

Signal flow:

input_gain -> [recursion: delay -> (loop_filter) -> (post_delay_module); fB = feedback]
           -> output_gain -> (output_filter)

with the direct path direct summed in parallel when provided.

Parameters:

input_gain (FLAMO modules) – Input gain B (named input_gain) and output gain C (named output_gain).
output_gain (FLAMO modules) – Input gain B (named input_gain) and output gain C (named output_gain).
feedback (FLAMO module) – Feedback matrix placed on the recursion feedback branch (fB); a plain Gain/Filter (render) or a parametrized Matrix (training).
delays (FLAMO module) – Delay module on the recursion forward branch (named delay).
direct (FLAMO module or None) – Direct path D. When None the core is the plain feedforward Series (no Parallel wrapper) – this keeps core.feedback_loop reachable for losses such as sparsity_loss. When provided the core is Parallel(brA=fdn_branch, brB=direct).
loop_filter (FLAMO module or None) – Optional in-loop filter after the delays (named filter).
output_filter (FLAMO module or None) – Optional per-output filter after the output gain (named output_filter).
post_delay_module (FLAMO module or None) – Optional module appended after the delay in the recursion.

Returns:

core – The FDN core, ready for wrap_fdn_shell().

Return type:

flamo.processor.system.Series or Parallel

pyFDN.auxiliary.flamo.delay_module(lengths_seconds, nfft, *, Fs, device=None, dtype=None, isint=True, alias_decay_db=0, requires_grad=False)[source]#

Build a FLAMO parallelDelay module from delay lengths in seconds.

Values are assigned directly (no sample conversion); buffer size is derived from Fs.

Parameters:

lengths_seconds (np.ndarray) – 1D array of delay lengths in seconds, one per channel.
nfft (int) – FFT size for the FLAMO module.
Fs (float) – Sampling rate in Hz (used for buffer size max_len = max(lengths_seconds) * Fs).
device (torch device or None) – Device for the module; default is cuda if available else cpu.
dtype (torch.dtype or None) – Optional dtype for module parameters (e.g., torch.float64). If None, uses float32 to preserve previous behavior.
isint (bool) – Whether delays are integer-sample (True) or fractional.
alias_decay_db (float) – FLAMO alias decay in dB.
requires_grad (bool) – Whether the delay parameters are trainable.

Returns:

FLAMO parallelDelay module with lengths assigned (in seconds).

Return type:

flamo.processor.dsp.parallelDelay

pyFDN.auxiliary.flamo.fir_matrix_module(coeffs, nfft, *, device=None, dtype=None, requires_grad=False)[source]#

Build a FLAMO Filter module from a matrix FIR coefficient array.

Parameters:

coeffs (np.ndarray) – FIR matrix in z^{-1} convention, shape (n_output, n_input, n_taps) (e.g. a paraunitary feedback matrix).
nfft (int) – FFT size for the FLAMO module.
device (torch device or None) – Device for the module; default is cuda if available else cpu.
dtype (torch.dtype or None) – Optional dtype for module parameters (e.g., torch.float64). If None, uses float32.
requires_grad (bool) – Whether the filter parameters are trainable.

Returns:

FLAMO Filter module with coefficients assigned.

Return type:

flamo.processor.dsp.Filter

pyFDN.auxiliary.flamo.flamo_freq_response(model, fs=48000, identity=False)[source]#

Return a FLAMO model’s (complex) frequency response as a NumPy array.

The NumPy-facing counterpart of FLAMO’s model.get_freq_response() and the frequency-domain sibling of flamo_time_response(). It detaches the returned tensor from any autograd graph, transfers it to CPU memory, and preserves its shape and (complex) dtype. Take np.abs(...) for the magnitude response, np.angle(...) for the phase.

get_freq_response evaluates over nfft DFT bins by temporarily swapping the model’s input/output layers to FFT and restoring them before returning, so this is side-effect-free regardless of the model’s current output layer.

Parameters:

model – FLAMO model exposing get_freq_response (e.g. a Shell).
fs (int) – Sampling frequency passed to FLAMO.
identity (bool) – Whether to request FLAMO’s input-free identity response.

Returns:

Complex frequency response with the same shape and numeric dtype as FLAMO’s tensor.

Return type:

np.ndarray

pyFDN.auxiliary.flamo.flamo_process(model, signal, *, fs=None, tail_seconds=0.0, dtype=None)[source]#

Run a 1-D signal through a FLAMO Shell model offline.

Wraps the boilerplate of turning a NumPy signal into the (batch, time, channel) tensor FLAMO expects, running a no-grad forward pass, and converting the result back to NumPy.

The model convolves in the frequency domain over a block of length nfft (read from the model’s input layer), so the signal is truncated or zero-padded to nfft. Because that is a circular convolution, a long reverb tail can wrap around onto the start of the block; pass tail_seconds to reserve that much trailing silence for the tail to decay into (requires fs).

Parameters:

model – FLAMO Shell whose input layer exposes nfft (e.g. the output of pyFDN.dss_to_flamo()).
signal (np.ndarray) – 1-D input signal.
fs (int, optional) – Sampling rate, required only when tail_seconds > 0.
tail_seconds (float) – Trailing silence to reserve so the reverb tail does not wrap around.
dtype (torch.dtype or None) – Tensor dtype for the forward pass; defaults to float32.

Returns:

Squeezed model output on CPU.

Return type:

np.ndarray

pyFDN.auxiliary.flamo.flamo_time_response(model, fs=48000, identity=False)[source]#

Return a FLAMO model’s time response as a NumPy array.

This is the NumPy-facing counterpart of FLAMO’s model.get_time_response(). It detaches the returned tensor from any autograd graph, transfers it to CPU memory, and preserves its dimensions and dtype during conversion.

Parameters:

model – FLAMO model exposing get_time_response.
fs (int) – Sampling frequency passed to FLAMO.
identity (bool) – Whether to request FLAMO’s input-free identity response.

Returns:

Time response with the same shape and numeric dtype as FLAMO’s tensor.

Return type:

np.ndarray

pyFDN.auxiliary.flamo.gain_module(values, nfft, *, device=None, dtype=None, alias_decay_db=0, requires_grad=False)[source]#

Build a FLAMO Gain module from a numpy array.

Parameters:

values (np.ndarray) – Gain matrix, shape (n_output, n_input). Will be cast to float64.
nfft (int) – FFT size for the FLAMO module.
device (torch device or None) – Device for the module; default is cuda if available else cpu.
dtype (torch.dtype or None) – Optional dtype for module parameters (e.g., torch.float64). If None, uses float32.
alias_decay_db (float) – FLAMO alias decay in dB.
requires_grad (bool) – Whether the gain parameters are trainable.

Returns:

FLAMO Gain module with values assigned.

Return type:

flamo.processor.dsp.Gain

pyFDN.auxiliary.flamo.matrix_module(values, nfft, *, matrix_type='orthogonal', device=None, dtype=None, alias_decay_db=0, requires_grad=False)[source]#

Build a FLAMO Matrix initialized to values under a parametrization.

Unlike gain_module() (a plain value container), this preserves the flamo map that constrains the trainable matrix: "orthogonal" keeps it on the SO(N) manifold during optimization, "random" is unconstrained.

Parameters:

values (np.ndarray) – Square (N, N) initial feedback matrix.
nfft (int) – FFT size for the FLAMO module.
matrix_type (str) – "orthogonal" or "random".
device (torch device or None) – Device; default is cuda if available else cpu.
dtype (torch.dtype or None) – Module dtype; defaults to float32.
alias_decay_db (float) – FLAMO alias decay in dB.
requires_grad (bool) – Whether the matrix is trainable.

Returns:

Matrix whose realized value (map(param)) equals values (within the parametrization; an SO(N) projection may apply for orthogonal).

Return type:

flamo.processor.dsp.Matrix

pyFDN.auxiliary.flamo.output_layer(output, nfft, dtype=None)[source]#

Build the FLAMO output layer for an output domain.

"time" -> iFFT (time response); "magnitude" -> |.| of the frequency response. The single source of truth for the output-string -> layer mapping, shared by wrap_fdn_shell() (build time) and the training output-domain swap (pyFDN.train_fdn()) so the two cannot disagree.

Return type:: Any

pyFDN.auxiliary.flamo.sos_filter_module(sos, nfft, *, device=None, dtype=None, requires_grad=False)[source]#

Build a FLAMO parallelSOSFilter from an SOS coefficient array.

Parameters:

sos (np.ndarray) – Shape (n_sections, 6, n_channels). Each section is [b0, b1, b2, a0, a1, a2] (e.g. from SDN wall_filters_sos).
nfft (int) – FFT size for the FLAMO module.
device (torch device or None) – Device for the module; default is cuda if available else cpu.
dtype (torch.dtype or None) – Optional dtype for module parameters (e.g., torch.float64). If None, uses float32 to preserve previous behavior.
requires_grad (bool) – Whether the filter parameters are trainable.

Returns:

FLAMO parallelSOSFilter with coefficients assigned.

Return type:

flamo.processor.dsp.parallelSOSFilter

pyFDN.auxiliary.flamo.wrap_fdn_shell(core, *, nfft, dtype=None, output='time')[source]#

Wrap an FDN core in a FLAMO Shell with an FFT input layer.

Parameters:

core (FLAMO module) – FDN core, e.g. from assemble_fdn_core().
nfft (int) – FFT size.
dtype (torch.dtype or None) – Dtype for the FFT/iFFT layers; defaults to float32.
output (str) –
Output-domain layer:
- "time" – iFFT time response (the render default, matching pyFDN.dss_to_flamo()).
- "magnitude" – |.| of the frequency response, for magnitude-domain losses (e.g. colorless training).

Return type:

flamo.processor.system.Shell

pyFDN.auxiliary.flamo_graph module#

Traverse a FLAMO model and build a node tree or visualize it as a flowchart.

Flow: left-to-right. Series and Parallel are shown as boxes with nested modules. Recursion is shown with forward path (fF) and feedback path (fB) inside a box, with the feedback path drawn so the loop is visible (e.g. fB below fF).

pyFDN.auxiliary.flamo_graph.extract_build(model)[source]#

Extract a complete FDNBuild from a named FLAMO model graph.

The graph must contain leaves named input_gain and output_gain, plus either mixing_matrix or the standard recursion feedback leaf fB. The delay can be named delay or be the graph’s only delay module. Optional attenuation (filters), output-filter (post_eq), and direct-path leaves are included when present. The sample rate is read from the delay module and is required: a graph that does not expose fs is malformed and raises ValueError.

Return type:: FDNBuild

pyFDN.auxiliary.flamo_graph.feedback_matrix_module(model)[source]#

Return the live feedback-matrix module from a FLAMO FDN model.

Works for both a plain Series core and a Parallel core (an FDN summed with a direct path). The module returned is the one on the recursion’s feedback branch; apply module.map(module.param) to read the realized matrix in-graph – e.g. inside a training loss, where the detaching extraction path extract_build() would break gradients.

Return type:: Any

pyFDN.auxiliary.flamo_graph.flamo_model_to_nodes(model, name='root', *, include_shell_io=False)[source]#

Traverse a FLAMO model and build a tree of nodes (nested dicts).

Each node has: - type: “Shell” | “Series” | “Parallel” | “Recursion” | “Leaf” - name: str (from parent’s dict key or assigned) - module: the raw FLAMO module (for Leaf, the actual dsp module) - children: list of child nodes (for Series, Parallel; order preserved) - fF, fB: only for Recursion — nodes for forward and feedback path - input_layer, output_layer: only if include_shell_io and type is Shell

Parameters:

model (FLAMO model (Shell, Series, Parallel, Recursion, or dsp module))
name (str) – Name for the root node.
include_shell_io (bool) – If True, include input_layer and output_layer as children for Shell.

Returns:

node – Root node (nested tree). Use flamo_nodes_flat() to get a list of all nodes.

Return type:

dict

pyFDN.auxiliary.flamo_graph.flamo_nodes_flat(root, path='root')[source]#

Flatten the node tree into a list of nodes, each with a ‘path’ key.

Parameters:

root (dict) – Root node from flamo_model_to_nodes().
path (str) – Path prefix for the root.

Returns:

Each dict has keys from the node plus “path” (e.g. “root/core/feedback_loop/fF”).

Return type:

list of dict

pyFDN.auxiliary.flamo_graph.plot_flamo_graph(model, *, name='flamo', ax=None, scale=0.85, fontsize=9.0)[source]#

Draw the FLAMO model signal flow with matplotlib.

Signal flows left to right; only the feedback path of a Recursion flows right to left, drawn below the forward path with a loop back to a sum node at the forward path’s input.

Parameters:

model (FLAMO model (Shell, Series, Parallel, Recursion, or dsp module))
name (str) – Name for the root node.
ax (matplotlib Axes, optional) – Draw into this axes; otherwise a new figure sized to the layout is created.
scale (float) – Inches per layout unit when creating a new figure.
fontsize (float) – Base font size for leaf labels.

Returns:

ax

Return type:

matplotlib Axes

pyFDN.auxiliary.math module#

Matrix polynomial and math operations.

pyFDN.auxiliary.math.adj_poly(polynomial_matrix, var='z^1', tol=-200.0)[source]#

Adjugate of a polynomial matrix via FFT evaluation.

Evaluates the matrix at N * L DFT points, takes the scalar adjugate() at every bin, and transforms back (approach of Henrion, Hromcik & Sebek 2000; translates adjPoly.m).

Parameters:

polynomial_matrix (array) – Polynomial matrix of shape (N, N, L).
var (str) – Coefficient convention along axis 2: "z^1" — descending powers of z, last slice = z^0 (the loop_tf() convention); "z^-1" — ascending powers of z^{-1}, first slice = z^0 (the pyFDN convention used by det_polynomial()).
tol (float) – Noise floor in dB (relative to each entry’s maximum) used to trim the result to its actual degree.

Returns:

adj – Adjugate polynomial matrix (N, N, degree + 1) in the same convention as the input.

Return type:

ndarray

pyFDN.auxiliary.math.adjugate(A)[source]#

Adjugate matrix, valid also for singular and complex matrices.

Uses the SVD identity adj(A) = det(U V^H) V adj(S) U^H (with A = U S V^H), which holds even if A and S are singular.

Translates adjugate.m from fdnToolbox.

Return type:: ndarray

pyFDN.auxiliary.math.det_polynomial(polynomial_matrix)[source]#

Determinant of a polynomial matrix in the z^{-1} convention.

Coefficients are ordered as [z^0, z^{-1}, z^{-2}, …] along axis 2. Uses an FFT-based approach: evaluate at DFT points, compute scalar det at each frequency, then IFFT back.

Parameters:

polynomial_matrix (ndarray) – shape (N, N, L), polynomial matrix entries.

Returns:

1-D array of determinant polynomial coefficients,: ordered [z^0, z^{-1}, …], trimmed to the actual degree.

Return type:

determinant

pyFDN.auxiliary.math.general_char_poly(delays, A)[source]#

Generalized characteristic polynomial (GCP) for delay state-space.

Implements the formula from Schlecht & Habets (2015), Time-varying feedback matrices in feedback delay networks. J. Acoust. Soc. Amer., 138(3), 1389-1398. Matches the reference generalCharPoly.m.

Parameters:

delays (array-like) – Vector of delays in samples (length ND); used with z^{-1} convention.
A (ndarray) – Feedback matrix. If 2D (scalar matrix), GCP is built via submatrix determinants. If 3D of shape (N, N, L), polynomial matrix in z^{-1}.

Returns:

p – Generalized characteristic polynomial coefficients in z^{-1} ordering (index 0 = z^0, index k = z^{-k}).

Return type:

ndarray

pyFDN.auxiliary.math.interpolate_orthogonal(A, B, t)[source]#

Geodesic interpolation between two orthogonal matrices.

C(t) = A @ expm(t * logm(A.T @ B)). C(0)=A, C(1)=B; each C(t) is orthogonal.

Return type:: ndarray

pyFDN.auxiliary.math.is_orthogonal(Q, tol=1e-10)[source]#

Check if Q is orthogonal (Q.T @ Q ≈ I).

Return type:: bool

pyFDN.auxiliary.math.is_unilossless(A, tol=1e-10)[source]#

Test whether A is diagonally similar to an orthogonal matrix.

A is unilossless if there exists a diagonal D such that D^{-1} @ A @ D is orthogonal, i.e. the diagonal scaling is a similarity transform (inv(D) == E).

Translates isDiagonallySimilarToOrthogonal.m from fdnToolbox.

Return type:: bool

pyFDN.auxiliary.math.loop_tf(delays, A)[source]#

Loop transfer function P(z) = diag(z^m) - A as a polynomial matrix.

Coefficients are stored in the z^1 convention along axis 2 (descending powers of z, last slice = z^0). A polynomial feedback matrix (N, N, K) in z^{-1} convention is placed at the low-power end, i.e. the result is diag(z^m) - z^{K-1} A(z) (multiplied through by z^{K-1} to clear negative powers), matching loopTF.m.

Return type:: ndarray

pyFDN.auxiliary.math.matrix_convolution(A, B)[source]#

Matrix polynomial multiplication by convolution.

Return type:: ndarray

pyFDN.auxiliary.math.matrix_polyder(B, A)[source]#

Derivative of rational filter matrices in the z^{-1} convention.

Coefficients are ordered as [z^0, z^{-1}, z^{-2}, …] along axis 0.

Parameters:

B (ndarray) – Numerator coefficients, shape (order, N, M).
A (ndarray) – Denominator coefficients, shape (order, N, M).

Returns:

Numerator of the derivative, shape (order, N, M). P: Denominator of the derivative, shape (order, N, M).

Return type:

Q

pyFDN.auxiliary.math.matrix_polyval(P, z)[source]#

Evaluate a matrix polynomial P at the complex point z.

Return type:: ndarray

pyFDN.auxiliary.math.matrix_sqrt(A)[source]#

Matrix square root via eigenvalue decomposition.

sqrtm(A) = V @ sqrt(D) @ V^(-1) where A = V @ D @ V^(-1).

Parameters:: A (torch.Tensor) – Square matrix (real, will be cast to complex for eig).
Returns:: Real matrix square root of A.
Return type:: torch.Tensor

pyFDN.auxiliary.math.negpolyder(b, a, dont_truncate=False)[source]#

Derivative of rational polynomial with negative exponents.

Parameters:

b (ndarray) – Numerator coefficients
a (ndarray) – Denominator coefficients
dont_truncate (bool) – Leading zeros are not truncated

Returns:

Numerator coefficients of derivative p: Denominator coefficients of derivative

Return type:

q

pyFDN.auxiliary.math.outer_sum_approximation(matrix)[source]#

Rank-1 approximation minimizing ||u + v^T - matrix||_F.

Return type:: tuple[ndarray, ndarray]

pyFDN.auxiliary.math.poly_degree(polynomial, tol=None)[source]#

Return the polynomial degree in the z^{-1} convention.

Coefficients are ordered as [z^0, z^{-1}, z^{-2}, …]; the degree is the index of the last coefficient whose magnitude is above the noise floor.

Return type:: int

pyFDN.auxiliary.math.polyder_rational(b, a)[source]#

Derivative of rational polynomial using quotient rule.

Return type:: tuple[ndarray, ndarray]

pyFDN.auxiliary.math.polydiag(p)[source]#

Construct a diagonal polynomial matrix from an array of polynomials.

Return type:: ndarray

pyFDN.auxiliary.plot module#

Plot utilities (matrix heatmap, system matrix layout, impulse response grid).

pyFDN.auxiliary.plot.animate(plot_fn, frames, *, labels=None, label_prefix='', label_format='', frame_ms=300, transition_ms=0, title=None)[source]#

Animate a sequence of frames built by any per-frame plotting function.

plot_fn(frame) is called for each entry in frames and must return a single-subplot Plotly figure (e.g. plot_matrix(), plot_impulse_response()). The traces of each figure become one animation frame; the first figure supplies the base layout (size, axes, color scale), to which a play/pause button and a slider are added.

This composes with the existing plot_* builders instead of re-deriving their styling. To animate a matrix C of shape (rows, cols, T) over time, with fixed color limits:

import functools

fig = pyFDN.animate(
    functools.partial(pyFDN.plot_matrix, zmin=-1, zmax=1),
    [C[:, :, k] for k in range(C.shape[2])],
    labels=t,
    label_prefix="t = ",
    label_format=".2f",
)
fig.show()

Parameters:

plot_fn (callable) – Maps one frames entry to a Plotly figure. Use functools.partial() or a lambda to fix extra arguments (e.g. color limits) so every frame is built consistently.
frames (sequence) – One argument per frame, passed positionally to plot_fn.
labels (sequence, optional) – Slider label per frame. Defaults to the frame index.
label_prefix (str, optional) – Prefix shown before the current label (e.g. "t = ").
label_format (str, optional) – Format spec applied to each label, e.g. ".2f". Empty uses str.
frame_ms (int, optional) – Per-frame duration in milliseconds during playback. Default 300.
transition_ms (int, optional) – Tween duration between frames in milliseconds. Default 0.
title (str, optional) – Figure title. If None, the first frame’s title is kept.

Returns:

Call .show() to display.

Return type:

go.Figure

pyFDN.auxiliary.plot.downsample_lttb(x, y, *, max_points=10000)[source]#

Downsample a line with Largest-Triangle-Three-Buckets.

LTTB keeps points that preserve the visual shape of the connected line. It is a better default for Plotly mode="lines" than min/max bucketing, because it avoids artificial vertical segments between bucket extrema.

Return type:: tuple[ndarray, ndarray]

pyFDN.auxiliary.plot.downsample_minmax(x, y, *, max_points=10000)[source]#

Downsample a line while preserving local minima and maxima.

This is intended for dense time-domain traces such as impulse responses, where naive stride decimation can miss narrow peaks. The returned samples are sorted by their original order, include the first and last sample, and use at most max_points points for long inputs.

Parameters:

x (array-like or None) – X-values. If None, uses sample indices 0 .. len(y)-1.
y (array-like) – Real-valued y-values.
max_points (int, optional) – Maximum number of samples to return. Must be at least 4.

Returns:

x_ds, y_ds – Downsampled x- and y-values.

Return type:

ndarray

pyFDN.auxiliary.plot.downsample_plotly_trace(trace, *, max_points=10000, method='lttb')[source]#

Return a copy of a Plotly trace with downsampled x and y data.

Traces without y data are returned unchanged. If a trace has no x data, sample indices are generated.

Return type:: Any

pyFDN.auxiliary.plot.downsampled_scatter(*args, max_points=10000, method='lttb', **kwargs)[source]#

Create a Plotly go.Scatter trace with downsampled line data.

The call mirrors plotly.graph_objects.Scatter and only adds the max_points and method keywords:

fig.add_trace(pyFDN.downsampled_scatter(x=t, y=ir, max_points=5000))

Return type:: Any

pyFDN.auxiliary.plot.plot_FDN_build(build, *, nfft=512, zmin=None, zmax=None, title=None)[source]#

Plot the parameters stored in an pyFDN.FDNBuild.

This is a convenience wrapper around plot_fdn_parameter(). A multichannel build.post_eq is rendered as one curve per output channel.

Return type:: Any

pyFDN.auxiliary.plot.plot_db_per_sample(sos, delays, *, fs=None, nfft=512, title=None)[source]#

Plot SOS magnitude responses normalized by delay length (dB per sample).

Each curve is the magnitude response of one delay line’s filter cascade divided by its delay length, \(20 \log_{10}|H_i| / m_i\). Filters designed for a homogeneous decay (a common T60 target) collapse onto the same gain-per-sample curve. Curve colors encode the delay length (Viridis, short = dark, long = bright).

Parameters:

sos (array-like) – Per-delay-line SOS bank, same layout as pyFDN.dsp.SOSFilterBank: (n_sections, 6, N).
delays (array-like) – Delay lengths in samples, shape (N,).
fs (float, optional) – Sample rate in Hz. If given, the responses are plotted over a logarithmic frequency axis in Hz; otherwise over rad/sample.
nfft (int, optional) – Number of frequency points. Default 512.
title (str, optional) – Figure title.

Returns:

Call .show() to display.

Return type:

go.Figure

pyFDN.auxiliary.plot.plot_edc(*irs, fs=None, labels=None, db=True, normalize=False, dynamic_range=100.0, title='Energy decay curve', max_points=10000)[source]#

Plot the energy decay curve (EDC) of one or more impulse responses.

The EDC is the backward energy integral (pyFDN.edc()); by default it is shown in dB (pyFDN.sq_to_db()). Dense traces are downsampled with LTTB (downsampled_scatter()) before plotting.

Parameters:

*irs (array-like) – One or more 1-D impulse responses, plotted as overlaid curves.
fs (float, optional) – Sample rate in Hz. If given, the time axis is in seconds; otherwise in samples.
labels (sequence of str, optional) – One legend label per impulse response.
db (bool, optional) – Plot the decay in dB. Default True.
normalize (bool, optional) – Normalize each curve by its initial (total) energy so it starts at 0 dB. Default False.
dynamic_range (float, optional) – When plotting in dB, limit the y-axis to dynamic_range dB below the peak across all curves (default 100, i.e. a floor at peak - 100 dB). This keeps the late decay from blowing out the axis once the tail reaches silence (-inf dB). Use None for auto scaling. Ignored when db is False.
title (str, optional) – Figure title.
max_points (int, optional) – Maximum number of points per trace after downsampling. Default 10000.

Returns:

Call .show() to display.

Return type:

go.Figure

pyFDN.auxiliary.plot.plot_fdn_parameter(delays, A, b, c, d, *, attenuation_sos=None, post_eq_sos=None, fs=None, nfft=512, zmin=None, zmax=None, title=None)[source]#

Plot all FDN parameters in one figure.

Extends plot_system_matrix() with the delay lengths and, optionally, the attenuation filters and the post EQ:

the system matrix blocks A, b, c, d as heatmaps with a shared RdBu color scale;
the delays as a bar plot whose bars are aligned with the columns of the feedback matrix A (one bar per delay line);
the attenuation filters as gain-per-sample curves, as in plot_db_per_sample();
the post EQ as plain magnitude response in dB.

Bar and curve colors are matched per delay line and encode the delay length (Viridis, short = dark, long = bright).

Parameters:

delays (array-like) – Delay lengths in samples, shape (N,).
A (array-like) – Feedback matrix, input gains, output gains, direct gains.
b (array-like) – Feedback matrix, input gains, output gains, direct gains.
c (array-like) – Feedback matrix, input gains, output gains, direct gains.
d (array-like) – Feedback matrix, input gains, output gains, direct gains.
attenuation_sos (array-like, optional) – Per-delay-line SOS attenuation bank, same layout as pyFDN.dsp.SOSFilterBank: (n_sections, 6, N).
post_eq_sos (array-like, optional) – Post EQ as an SOS cascade in scipy format, shape (n_sections, 6) (or (6,) for one section) for a single output, or (n_sections, 6, K) to draw one magnitude curve per output channel.
fs (float, optional) – Sample rate in Hz. If given, the filter responses are plotted over a logarithmic frequency axis in Hz; otherwise over rad/sample.
nfft (int, optional) – Number of frequency points for the filter responses. Default 512.
zmin (float, optional) – Shared color limits for the heatmaps. If both None, uses (-1, 1).
zmax (float, optional) – Shared color limits for the heatmaps. If both None, uses (-1, 1).
title (str, optional) – Figure title.

Returns:

Call .show() to display.

Return type:

go.Figure

pyFDN.auxiliary.plot.plot_impulse_response(*irs, fs=None, labels=None, mulaw=True, mu=255.0, title='Impulse response', max_points=10000)[source]#

Plot one or more impulse responses over time, mu-law compressed by default.

Mu-law companding (pyFDN.mulaw_encode()) keeps the quiet late part of a reverberant decay visible alongside the early reflections. Dense traces are downsampled with LTTB (downsampled_scatter()) before plotting.

Parameters:

*irs (array-like) – One or more 1-D impulse responses, plotted as overlaid lines.
fs (float, optional) – Sample rate in Hz. If given, the time axis is in seconds; otherwise in samples.
labels (sequence of str, optional) – One legend label per impulse response.
mulaw (bool, optional) – Apply mu-law companding to the amplitudes. Default True.
mu (float, optional) – Mu-law compression parameter. Default 255 (G.711).
title (str, optional) – Figure title.
max_points (int, optional) – Maximum number of points per trace after downsampling. Default 10000.

Returns:

Call .show() to display.

Return type:

go.Figure

pyFDN.auxiliary.plot.plot_impulse_response_matrix(t, ir, *, xlabel=None, ylabel=None, title=None, xlim=None, ylim=None, fig=None, **plot_kwargs)[source]#

Plot matrix of impulse responses in a subplot grid (out x in).

Parameters:

t (array-like, optional) – x-values (e.g. time). If None, uses 0 .. size(ir,2)-1.
ir (array-like) – Shape (n_samples, n_out, n_in). Each subplot is ir[:, out, in].
xlabel (str, optional) – Shared axis labels and title.
ylabel (str, optional) – Shared axis labels and title.
title (str, optional) – Shared axis labels and title.
xlim (tuple, optional) – Shared axis limits. If None, computed from data.
ylim (tuple, optional) – Shared axis limits. If None, computed from data.
fig (Figure, optional) – Figure to use.
**plot_kwargs (Any) – Passed to ax.plot().

Return type:

tuple[Figure, ndarray, ndarray]

Returns:

fig (Figure)
plot_axes (ndarray of Axes) – Shape (n_out, n_in).
plot_handles (ndarray of Line2D) – Shape (n_out, n_in).

pyFDN.auxiliary.plot.plot_matrix(A, title=None, zmin=None, zmax=None, *, block_boundaries=None)[source]#

Plot a single matrix as a Plotly heatmap (RdBu, square pixels).

Parameters:

A (array-like) – 2-D matrix to visualise.
title (str, optional) – Figure title (supports HTML/<sup> for subtitles).
zmin (float, optional) – Color limits. Default (-1, 1).
zmax (float, optional) – Color limits. Default (-1, 1).
block_boundaries (sequence of int, optional) – Indices at which to draw dashed dividing lines on both axes, e.g. to separate the sub-blocks of a coupled feedback matrix. A boundary at index k is drawn between rows/columns k-1 and k.

Returns:

Call .show() to display.

Return type:

go.Figure

pyFDN.auxiliary.plot.plot_matrix_grid(matrices, *, titles=None, ncols=2, zmin=None, zmax=None, show_ticks=False, title=None, height=None, width=None)[source]#

Plot several matrices as a grid of Plotly heatmaps sharing one color scale.

Each matrix is rendered like plot_matrix() (RdBu, zero-centered, top-left origin, square cells). Use this to compare several matrices side by side, e.g. a feedback matrix against its nearest orthogonal approximations.

Parameters:

matrices (sequence of array-like) – 2-D matrices to visualise, filled row by row across the grid.
titles (sequence of str, optional) – One subplot title per matrix (supports HTML/<br> for line breaks).
ncols (int, optional) – Number of columns in the grid. Default 2.
zmin (float, optional) – Shared color limits. If both None, uses (-1, 1).
zmax (float, optional) – Shared color limits. If both None, uses (-1, 1).
show_ticks (bool, optional) – If True, label axes with integer row/column indices. Default False.
title (str, optional) – Overall figure title.
height (int, optional) – Figure size in pixels. Defaults scale with the grid shape.
width (int, optional) – Figure size in pixels. Defaults scale with the grid shape.

Returns:

Call .show() to display.

Return type:

go.Figure

pyFDN.auxiliary.plot.plot_spectrogram(ir, fs, *, nperseg=1024, noverlap=None, window='blackman', xlim=(None, None), ylim=(None, None), dynamic_range=80.0, title='Spectrogram', xlabel='Time [s]', ylabel='Frequency [Hz]', height=500, colorscale='Viridis')[source]#

Plot spectrogram of a 1-D signal as a Matplotlib image.

Uses the same default parameters as the Poletti example: Blackman window, 1024-point segments, 75% overlap, log y-axis, dB magnitude.

Parameters:

ir (array-like, 1-D) – Time-domain signal (e.g. one channel of an impulse response).
fs (float) – Sample rate in Hz (for axis labels and frequency scale).
nperseg (int) – Length of each segment for the STFT. Default 1024.
noverlap (int, optional) – Number of overlapping samples. Default nperseg // 4 * 3 (75% overlap).
window (str or tuple) – Window name or (name, param). Default “blackman”.
xlim (tuple (xmin, xmax)) – Time axis limits in seconds. Use None for auto.
ylim (tuple (ymin, ymax)) – Frequency axis limits in Hz. Use None for auto (ymax defaults to fs/2).
dynamic_range (float, optional) – Color (magnitude) range in dB below the peak of the displayed spectrogram. Default 80. Use None for Plotly’s auto scaling.
title (str, optional) – Figure title.
xlabel (str) – Axis labels.
ylabel (str) – Axis labels.
height (int) – Figure height in pixels.
colorscale (str) – Colormap name (lowercased to a Matplotlib colormap). Default “Viridis”.

Returns:

fig

Return type:

matplotlib.figure.Figure

pyFDN.auxiliary.plot.plot_system_matrix(A, b, c, d, zmin=None, zmax=None, title=None)[source]#

Plot system matrix [A b; c d] as 2x2 Plotly heatmaps, shared RdBu color scale.

Subplot sizes are proportional to block dimensions so that each matrix element (pixel) has the same physical size across all four plots.

Parameters:

A (array-like) – Feedback matrix, input gain, output gain, direct gain.
b (array-like) – Feedback matrix, input gain, output gain, direct gain.
c (array-like) – Feedback matrix, input gain, output gain, direct gain.
d (array-like) – Feedback matrix, input gain, output gain, direct gain.
zmin (float, optional) – Shared color limits. If both None, uses (-1, 1).
zmax (float, optional) – Shared color limits. If both None, uses (-1, 1).
title (str, optional) – Figure title (supports HTML/<sup> for subtitles).

Returns:

Call .show() to display.

Return type:

go.Figure

pyFDN.auxiliary.poles module#

Pole utilities (conjugate pairing, etc.).

pyFDN.auxiliary.poles.reduce_conjugate_pairs(poles, *, tol_real=1e-10, tol_pair=1e-08, verbose=False, strict=False)[source]#

Group poles into real and conjugate pairs using optimal assignment.

For real-coefficient systems, poles are either real or occur in conjugate pairs. This uses the linear sum assignment problem (Hungarian method): cost \(C[i,j] = |poles[j] - conj(poles[i])|\); the minimum-cost permutation pairs each pole with its conjugate (or itself for real poles). Then:

Real: assignment[i] == i and C[i,i] < tol_real (i.e. \(|Im(pole_i)|\) small).
Conjugate pair: assignment[i] == j, assignment[j] == i, C[i,j] < tol_pair.
Unpaired: otherwise (ambiguous or numerical orphans).

Unpaired poles are reported via non_paired AND a UserWarning so callers cannot silently lose poles to imprecise pairing. Set strict=True to raise ValueError instead of warning.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

poles_out (np.ndarray) – One representative per real pole and per conjugate pair (imag >= 0).
is_conjugate (np.ndarray) – Boolean, same length as poles_out: False for real, True for conjugate pair or unpaired.
non_paired (np.ndarray) – Poles that could not be paired.

pyFDN.auxiliary.tiny_rotation_matrix module#

Tiny rotation matrix generator for FDN feedback matrices.

Translation of tinyRotationMatrix.m from fdnToolbox. Original MATLAB code: (c) Sebastian Jiro Schlecht, 2020 Python translation: Facundo Franchino, 2025

pyFDN.auxiliary.tiny_rotation_matrix.rotation_matrix_from_angles(angles, n=None)[source]#

Generate orthogonal matrix with prescribed eigenvalue angles.

Builds a block-diagonal matrix of 2x2 Givens rotations, one block per angle, so the eigenvalues are exp(+-1j * angles). For odd matrix sizes, a single eigenvalue at 1 is appended.

Parameters:

angles (Tensor) – Eigenvalue angles in radians, one per conjugate pair
n (int | None) – Matrix size; either 2 * len(angles) or 2 * len(angles) + 1 (default 2 * len(angles))

Returns:

Orthogonal matrix of shape (n, n)

Return type:

rotation_matrix

Example

>>> angles = torch.tensor([0.1, 0.2], dtype=torch.float64)
>>> R = rotation_matrix_from_angles(angles, n=5)
>>> R.shape
torch.Size([5, 5])
>>> torch.allclose(R @ R.T, torch.eye(5, dtype=R.dtype), atol=1e-12)
True

pyFDN.auxiliary.tiny_rotation_matrix.tiny_rotation_matrix(n, delta, spread=0.1, dtype=None)[source]#

Generate orthogonal matrix with small eigenvalue angles.

Creates a rotation matrix suitable for use in FDN feedback structures, where small eigenvalue angles help control the density of the impulse response. The eigenvalue angles are delta * pi, randomly spread by the spread factor. The matrix is constructed from 2x2 Givens rotations with these angles, pre- and post-multiplied by a random orthogonal matrix so that the result is dense but keeps the prescribed eigenvalues. For odd matrix sizes, one eigenvalue is at 1.

Parameters:

n (int) – Matrix size
delta (float) – Mean normalized eigenvalue angle
spread (float) – Spreading of eigenvalue angle (default 0.1)
dtype (dtype | None) – Floating point dtype of the result (default torch default)

Returns:

Orthogonal matrix of shape (n, n)

Return type:

rotation_matrix

Example

>>> R = tiny_rotation_matrix(6, 12)
>>> R.shape
torch.Size([6, 6])
>>> torch.allclose(R @ R.T, torch.eye(6), atol=1e-5)
True

pyFDN.auxiliary.utils module#

General utility functions.

pyFDN.auxiliary.utils.db_to_lin(db)[source]#

Convert decibel values to linear magnitude.

Return type:: ndarray

pyFDN.auxiliary.utils.db_to_sq(db)[source]#

Convert decibel values to squared magnitude (power).

Return type:: ndarray

pyFDN.auxiliary.utils.ensure_3d(matrix)[source]#

Ensure the matrix has a trailing polynomial dimension.

Return type:: ndarray

pyFDN.auxiliary.utils.hertz_to_rad(hz, fs)[source]#

Convert frequency (Hz) to angular frequency (rad/sample).

Relationship: omega = 2*pi*f/fs. Inverse of rad_to_hertz().

Return type:: ndarray

pyFDN.auxiliary.utils.hertz_to_unit(hz, fs)[source]#

Convert frequency (Hz) to normalised frequency (0-1).

Return type:: ndarray

pyFDN.auxiliary.utils.is_bounding_curve(x_points, y_points, x_curve, y_curve, bound_type)[source]#

Check if all value points are bounded by the curve. :type x_points: Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], complex, bytes, str, _NestedSequence[complex | bytes | str]] :param x_points: x-coordinates of data points (1D array) :type y_points: Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], complex, bytes, str, _NestedSequence[complex | bytes | str]] :param y_points: y-coordinates of data points (1D array) :type x_curve: Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], complex, bytes, str, _NestedSequence[complex | bytes | str]] :param x_curve: x-coordinates of curve points (1D array) :type y_curve: Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], complex, bytes, str, _NestedSequence[complex | bytes | str]] :param y_curve: y-coordinates of curve points (1D array) :type bound_type: str :param bound_type: ‘upper’ or ‘lower’

Returns:: bool, whether all data points are bounded is_bounded: boolean array, whether each data point is bounded
Return type:: all_bounded

pyFDN.auxiliary.utils.last_nonzero_indices(mat)[source]#

Return 1-based indices of the last non-zero element along axis 2.

Return type:: ndarray

pyFDN.auxiliary.utils.lin_to_db(linear)[source]#

Convert linear magnitude to decibels with numerical guard.

Return type:: ndarray

pyFDN.auxiliary.utils.max_corr(signals)[source]#

Pairwise maximum normalized cross-correlation of a MIMO signal matrix.

The (N1, N2, time) input is unfolded column-major into K = N1 * N2 signals (signal k is entry (k % N1, k // N1)); entry (i, j) of the result is the cross-correlation value of largest magnitude between signals i and j over all lags, keeping its sign, normalized so that the autocorrelation at zero lag is 1.

Translates maxCorr.m (Jon Fagerström) from fdnToolbox.

Parameters:: signals (array) – MIMO signal matrix of shape (N1, N2, time), e.g. an adjugate polynomial matrix from pyFDN.adj_poly().
Returns:: max_corr_matrix – Symmetric (K, K) matrix of signed maximum correlations.
Return type:: ndarray

pyFDN.auxiliary.utils.mulaw_decode(y, mu=255.0)[source]#

Mu-law companding (decode): companded to linear amplitude.

Parameters:

y (Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], complex, bytes, str, _NestedSequence[complex | bytes | str]]) – Companded signal.
mu (float) – Compression parameter (default 255, as in G.711).

Return type:

ndarray

Returns:

Linear-amplitude signal.

pyFDN.auxiliary.utils.mulaw_encode(x, mu=255.0)[source]#

Mu-law companding (encode): linear amplitude to companded.

Parameters:

x (Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], complex, bytes, str, _NestedSequence[complex | bytes | str]]) – Input signal. If input is in [-1, 1], the output will be in [-1, 1].
mu (float) – Compression parameter (default 255, as in G.711).

Return type:

ndarray

Returns:

Companded signal.

pyFDN.auxiliary.utils.peak_normalize(x, target_peak=1.0)[source]#

Scale array so the maximum absolute value equals target_peak.

If the array is all zeros, it is returned unchanged.

Parameters:

x (Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], complex, bytes, str, _NestedSequence[complex | bytes | str]]) – Input signal (any shape).
target_peak (float) – Desired peak magnitude (default 1.0).

Return type:

ndarray

Returns:

Scaled array, same shape as input.

pyFDN.auxiliary.utils.pole_boundaries(delays, absorption, feedback_matrix, fs, nfft=4096)[source]#

Find upper and lower pole boundaries for FDN loop. :type delays: Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], complex, bytes, str, _NestedSequence[complex | bytes | str]] :param delays: 1D array of delays in samples (length N) :type absorption: Any :param absorption: object with .b and .a attributes, each shape (N, 1, len) :type feedback_matrix: ndarray :param feedback_matrix: 3D numpy array (N, N, len) :type fs: float :param fs: sampling frequency :type nfft: int :param nfft: number of frequency bins (default: 4096)

Returns:: lower bound of pole magnitude (shape: nfft) MaxCurve: upper bound of pole magnitude (shape: nfft) f: frequency points (Hz, shape: nfft)
Return type:: MinCurve

pyFDN.auxiliary.utils.rad_to_hertz(rad, fs)[source]#

Convert angular frequency (rad/sample) to frequency (Hz).

Relationship: omega = 2*pi*f/fs, so f = omega * fs / (2*pi).

Return type:: ndarray

pyFDN.auxiliary.utils.skew(X)[source]#

Return skew-symmetric matrix from upper triangle (Matlab skew convention).

Y = triu(X, 1) - triu(X, 1).T so that Y is skew-symmetric. Equivalent to skew.m: Y = X - X’ with X = triu(X, 1).

Return type:: ndarray

pyFDN.auxiliary.utils.sq_to_db(squared)[source]#

Convert squared magnitude (power) to decibels with numerical guard.

Return type:: ndarray

Module contents#

Auxiliary modules (utils, acoustics, allpass, flamo wrappers, etc.).

pyFDN.auxiliary.assemble_fdn_core(*, input_gain, feedback, delays, output_gain, direct=None, loop_filter=None, output_filter=None, post_delay_module=None)[source]#

Wire pre-built FLAMO modules into an FDN core (no FFT/iFFT wrapping).

Single source of truth for the FDN signal flow, shared by the render path (pyFDN.dss_to_flamo()) and the training builder (pyFDN.train.trainable_from_build()). All arguments are already-built FLAMO dsp/system modules; this only composes them, so leaf names and topology stay identical across both callers (and match the names pyFDN.extract_build() looks for).

Signal flow:

input_gain -> [recursion: delay -> (loop_filter) -> (post_delay_module); fB = feedback]
           -> output_gain -> (output_filter)

with the direct path direct summed in parallel when provided.

Parameters:

input_gain (FLAMO modules) – Input gain B (named input_gain) and output gain C (named output_gain).
output_gain (FLAMO modules) – Input gain B (named input_gain) and output gain C (named output_gain).
feedback (FLAMO module) – Feedback matrix placed on the recursion feedback branch (fB); a plain Gain/Filter (render) or a parametrized Matrix (training).
delays (FLAMO module) – Delay module on the recursion forward branch (named delay).
direct (FLAMO module or None) – Direct path D. When None the core is the plain feedforward Series (no Parallel wrapper) – this keeps core.feedback_loop reachable for losses such as sparsity_loss. When provided the core is Parallel(brA=fdn_branch, brB=direct).
loop_filter (FLAMO module or None) – Optional in-loop filter after the delays (named filter).
output_filter (FLAMO module or None) – Optional per-output filter after the output gain (named output_filter).
post_delay_module (FLAMO module or None) – Optional module appended after the delay in the recursion.

Returns:

core – The FDN core, ready for wrap_fdn_shell().

Return type:

flamo.processor.system.Series or Parallel

pyFDN.auxiliary.delay_module(lengths_seconds, nfft, *, Fs, device=None, dtype=None, isint=True, alias_decay_db=0, requires_grad=False)[source]#

Build a FLAMO parallelDelay module from delay lengths in seconds.

Values are assigned directly (no sample conversion); buffer size is derived from Fs.

Parameters:

lengths_seconds (np.ndarray) – 1D array of delay lengths in seconds, one per channel.
nfft (int) – FFT size for the FLAMO module.
Fs (float) – Sampling rate in Hz (used for buffer size max_len = max(lengths_seconds) * Fs).
device (torch device or None) – Device for the module; default is cuda if available else cpu.
dtype (torch.dtype or None) – Optional dtype for module parameters (e.g., torch.float64). If None, uses float32 to preserve previous behavior.
isint (bool) – Whether delays are integer-sample (True) or fractional.
alias_decay_db (float) – FLAMO alias decay in dB.
requires_grad (bool) – Whether the delay parameters are trainable.

Returns:

FLAMO parallelDelay module with lengths assigned (in seconds).

Return type:

flamo.processor.dsp.parallelDelay

pyFDN.auxiliary.extract_build(model)[source]#

Extract a complete FDNBuild from a named FLAMO model graph.

The graph must contain leaves named input_gain and output_gain, plus either mixing_matrix or the standard recursion feedback leaf fB. The delay can be named delay or be the graph’s only delay module. Optional attenuation (filters), output-filter (post_eq), and direct-path leaves are included when present. The sample rate is read from the delay module and is required: a graph that does not expose fs is malformed and raises ValueError.

Return type:: FDNBuild

pyFDN.auxiliary.fir_matrix_module(coeffs, nfft, *, device=None, dtype=None, requires_grad=False)[source]#

Build a FLAMO Filter module from a matrix FIR coefficient array.

Parameters:

coeffs (np.ndarray) – FIR matrix in z^{-1} convention, shape (n_output, n_input, n_taps) (e.g. a paraunitary feedback matrix).
nfft (int) – FFT size for the FLAMO module.
device (torch device or None) – Device for the module; default is cuda if available else cpu.
dtype (torch.dtype or None) – Optional dtype for module parameters (e.g., torch.float64). If None, uses float32.
requires_grad (bool) – Whether the filter parameters are trainable.

Returns:

FLAMO Filter module with coefficients assigned.

Return type:

flamo.processor.dsp.Filter

pyFDN.auxiliary.flamo_freq_response(model, fs=48000, identity=False)[source]#

Return a FLAMO model’s (complex) frequency response as a NumPy array.

The NumPy-facing counterpart of FLAMO’s model.get_freq_response() and the frequency-domain sibling of flamo_time_response(). It detaches the returned tensor from any autograd graph, transfers it to CPU memory, and preserves its shape and (complex) dtype. Take np.abs(...) for the magnitude response, np.angle(...) for the phase.

get_freq_response evaluates over nfft DFT bins by temporarily swapping the model’s input/output layers to FFT and restoring them before returning, so this is side-effect-free regardless of the model’s current output layer.

Parameters:

model – FLAMO model exposing get_freq_response (e.g. a Shell).
fs (int) – Sampling frequency passed to FLAMO.
identity (bool) – Whether to request FLAMO’s input-free identity response.

Returns:

Complex frequency response with the same shape and numeric dtype as FLAMO’s tensor.

Return type:

np.ndarray

pyFDN.auxiliary.flamo_model_to_nodes(model, name='root', *, include_shell_io=False)[source]#

Traverse a FLAMO model and build a tree of nodes (nested dicts).

Each node has: - type: “Shell” | “Series” | “Parallel” | “Recursion” | “Leaf” - name: str (from parent’s dict key or assigned) - module: the raw FLAMO module (for Leaf, the actual dsp module) - children: list of child nodes (for Series, Parallel; order preserved) - fF, fB: only for Recursion — nodes for forward and feedback path - input_layer, output_layer: only if include_shell_io and type is Shell

Parameters:

model (FLAMO model (Shell, Series, Parallel, Recursion, or dsp module))
name (str) – Name for the root node.
include_shell_io (bool) – If True, include input_layer and output_layer as children for Shell.

Returns:

node – Root node (nested tree). Use flamo_nodes_flat() to get a list of all nodes.

Return type:

dict

pyFDN.auxiliary.flamo_nodes_flat(root, path='root')[source]#

Flatten the node tree into a list of nodes, each with a ‘path’ key.

Parameters:

root (dict) – Root node from flamo_model_to_nodes().
path (str) – Path prefix for the root.

Returns:

Each dict has keys from the node plus “path” (e.g. “root/core/feedback_loop/fF”).

Return type:

list of dict

pyFDN.auxiliary.flamo_process(model, signal, *, fs=None, tail_seconds=0.0, dtype=None)[source]#

Run a 1-D signal through a FLAMO Shell model offline.

Wraps the boilerplate of turning a NumPy signal into the (batch, time, channel) tensor FLAMO expects, running a no-grad forward pass, and converting the result back to NumPy.

The model convolves in the frequency domain over a block of length nfft (read from the model’s input layer), so the signal is truncated or zero-padded to nfft. Because that is a circular convolution, a long reverb tail can wrap around onto the start of the block; pass tail_seconds to reserve that much trailing silence for the tail to decay into (requires fs).

Parameters:

model – FLAMO Shell whose input layer exposes nfft (e.g. the output of pyFDN.dss_to_flamo()).
signal (np.ndarray) – 1-D input signal.
fs (int, optional) – Sampling rate, required only when tail_seconds > 0.
tail_seconds (float) – Trailing silence to reserve so the reverb tail does not wrap around.
dtype (torch.dtype or None) – Tensor dtype for the forward pass; defaults to float32.

Returns:

Squeezed model output on CPU.

Return type:

np.ndarray

pyFDN.auxiliary.flamo_time_response(model, fs=48000, identity=False)[source]#

Return a FLAMO model’s time response as a NumPy array.

This is the NumPy-facing counterpart of FLAMO’s model.get_time_response(). It detaches the returned tensor from any autograd graph, transfers it to CPU memory, and preserves its dimensions and dtype during conversion.

Parameters:

model – FLAMO model exposing get_time_response.
fs (int) – Sampling frequency passed to FLAMO.
identity (bool) – Whether to request FLAMO’s input-free identity response.

Returns:

Time response with the same shape and numeric dtype as FLAMO’s tensor.

Return type:

np.ndarray

pyFDN.auxiliary.gain_module(values, nfft, *, device=None, dtype=None, alias_decay_db=0, requires_grad=False)[source]#

Build a FLAMO Gain module from a numpy array.

Parameters:

values (np.ndarray) – Gain matrix, shape (n_output, n_input). Will be cast to float64.
nfft (int) – FFT size for the FLAMO module.
device (torch device or None) – Device for the module; default is cuda if available else cpu.
dtype (torch.dtype or None) – Optional dtype for module parameters (e.g., torch.float64). If None, uses float32.
alias_decay_db (float) – FLAMO alias decay in dB.
requires_grad (bool) – Whether the gain parameters are trainable.

Returns:

FLAMO Gain module with values assigned.

Return type:

flamo.processor.dsp.Gain

pyFDN.auxiliary.is_allpass(A, B, C, D, delays, tol=1e-09)[source]#

Test whether the delay state-space system is allpass.

Checks that the determinant transfer function has numerator = reversed(denominator) (up to sign). See “Allpass Feedback Delay Networks” by Sebastian J. Schlecht.

Parameters:

A (array-like) – Delay state-space matrices.
B (array-like) – Delay state-space matrices.
C (array-like) – Delay state-space matrices.
D (array-like) – Delay state-space matrices.
delays (array-like) – Delay lengths (samples), length N.
tol (float) – Tolerance for coefficient comparison.

Return type:

tuple[bool, ndarray, ndarray]

Returns:

is_a (bool) – True if allpass.
den (ndarray) – Denominator polynomial (z^{-1} ordering).
num (ndarray) – Numerator polynomial (z^{-1} ordering).

pyFDN.auxiliary.is_paraunitary(ir, tol=1e-09)[source]#

Test whether a MIMO impulse response is paraunitary (lossless).

For real IR matrix H(t), checks that sum_t H(t) H(t)’ = I (output correlation) and sum_t H(t)’ H(t) = I (input correlation).

Parameters:

ir (ndarray, shape (ir_len, n_out, n_in)) – Impulse response [time, output, input].
tol (float) – Tolerance for identity check.

Return type:

tuple[bool, ndarray, float]

Returns:

is_p (bool) – True if paraunitary.
test_matrix (ndarray) – Output correlation matrix (n_out, n_out); should be identity.
max_off_diagonal (float) – Max absolute off-diagonal value in test_matrix.

pyFDN.auxiliary.is_uniallpass(A, B, C, D, tol=1e-09)[source]#

Test whether the FDN is uniallpass (lossless with a diagonal Lyapunov matrix).

See Michaletzky, G. Factorization of discrete-time all-pass functions; and “Allpass Feedback Delay Networks” by Sebastian J. Schlecht.

Parameters:

A (array-like) – Delay state-space matrices (feedback, input gain, output gain, direct).
B (array-like) – Delay state-space matrices (feedback, input gain, output gain, direct).
C (array-like) – Delay state-space matrices (feedback, input gain, output gain, direct).
D (array-like) – Delay state-space matrices (feedback, input gain, output gain, direct).
tol (float) – Tolerance for zero and diagonal checks.

Return type:

tuple[bool, ndarray]

Returns:

is_a (bool) – True if the system is uniallpass.
P (ndarray) – Solution of discrete Lyapunov A P A’ - P + B B’ = 0; diagonal if uniallpass.

pyFDN.auxiliary.load_audio(name, *, fs=None, package='pyFDN.audio', mono=True)[source]#

Load a packaged audio file as a NumPy array.

Parameters:

name (str) – File name within package (e.g. "synth_dry.wav").
fs (int, optional) – Target sampling rate. If given and different from the file’s rate, the signal is resampled to fs.
package (str) – Importable package holding the audio resource.
mono (bool) – If True, keep only the first channel of multichannel files.

Returns:

(signal, fs) – Samples as float64 and the (possibly resampled) sampling rate.

Return type:

tuple[np.ndarray, int]

pyFDN.auxiliary.matrix_module(values, nfft, *, matrix_type='orthogonal', device=None, dtype=None, alias_decay_db=0, requires_grad=False)[source]#

Build a FLAMO Matrix initialized to values under a parametrization.

Unlike gain_module() (a plain value container), this preserves the flamo map that constrains the trainable matrix: "orthogonal" keeps it on the SO(N) manifold during optimization, "random" is unconstrained.

Parameters:

values (np.ndarray) – Square (N, N) initial feedback matrix.
nfft (int) – FFT size for the FLAMO module.
matrix_type (str) – "orthogonal" or "random".
device (torch device or None) – Device; default is cuda if available else cpu.
dtype (torch.dtype or None) – Module dtype; defaults to float32.
alias_decay_db (float) – FLAMO alias decay in dB.
requires_grad (bool) – Whether the matrix is trainable.

Returns:

Matrix whose realized value (map(param)) equals values (within the parametrization; an SO(N) projection may apply for orthogonal).

Return type:

flamo.processor.dsp.Matrix

pyFDN.auxiliary.nested_allpass(g)[source]#

Create Gardner’s nested allpass FDN (SISO).

Iteratively nests a feedforward/back allpass around the previous FDN. From Gardner, W. G. (1992). A real-time multichannel room simulator. J. Acoust. Soc. Am. 92, 1–23. See “Allpass Feedback Delay Networks”, Schlecht.

Parameters:

g (array-like, shape (N,)) – Feedforward/back gains for each nesting stage.

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

Returns:

A (ndarray (N, N)) – Feedback matrix.
B (ndarray (N, 1)) – Input gain (column vector).
C (ndarray (1, N)) – Output gain (row vector).
D (ndarray (1, 1)) – Direct gain (scalar).

pyFDN.auxiliary.output_layer(output, nfft, dtype=None)[source]#

Build the FLAMO output layer for an output domain.

"time" -> iFFT (time response); "magnitude" -> |.| of the frequency response. The single source of truth for the output-string -> layer mapping, shared by wrap_fdn_shell() (build time) and the training output-domain swap (pyFDN.train_fdn()) so the two cannot disagree.

Return type:: Any

pyFDN.auxiliary.plot_flamo_graph(model, *, name='flamo', ax=None, scale=0.85, fontsize=9.0)[source]#

Draw the FLAMO model signal flow with matplotlib.

Signal flows left to right; only the feedback path of a Recursion flows right to left, drawn below the forward path with a loop back to a sum node at the forward path’s input.

Parameters:

model (FLAMO model (Shell, Series, Parallel, Recursion, or dsp module))
name (str) – Name for the root node.
ax (matplotlib Axes, optional) – Draw into this axes; otherwise a new figure sized to the layout is created.
scale (float) – Inches per layout unit when creating a new figure.
fontsize (float) – Base font size for leaf labels.

Returns:

ax

Return type:

matplotlib Axes

pyFDN.auxiliary.poletti_allpass(g, U)[source]#

Create Poletti’s MIMO unitary reverberator (allpass FDN).

From Poletti, M. (1995). A unitary reverberator for reduced colouration in assisted reverberation systems. INTER-NOISE and NOISE-CON, 5, 1223–1232.

Parameters:

g (float) – Scalar feedback gain (e.g. 0.7).
U (ndarray (N, N)) – Unitary (orthogonal) feedback matrix.

Returns:

A, B, C, D – Delay state-space matrices: A = -g*U, B = (1+g)*I, C = (1-g)*U, D = g*I.

Return type:

ndarray

pyFDN.auxiliary.reduce_conjugate_pairs(poles, *, tol_real=1e-10, tol_pair=1e-08, verbose=False, strict=False)[source]#

Group poles into real and conjugate pairs using optimal assignment.

For real-coefficient systems, poles are either real or occur in conjugate pairs. This uses the linear sum assignment problem (Hungarian method): cost \(C[i,j] = |poles[j] - conj(poles[i])|\); the minimum-cost permutation pairs each pole with its conjugate (or itself for real poles). Then:

Real: assignment[i] == i and C[i,i] < tol_real (i.e. \(|Im(pole_i)|\) small).
Conjugate pair: assignment[i] == j, assignment[j] == i, C[i,j] < tol_pair.
Unpaired: otherwise (ambiguous or numerical orphans).

Unpaired poles are reported via non_paired AND a UserWarning so callers cannot silently lose poles to imprecise pairing. Set strict=True to raise ValueError instead of warning.

Return type:

tuple[ndarray, ndarray, ndarray]

Returns:

poles_out (np.ndarray) – One representative per real pole and per conjugate pair (imag >= 0).
is_conjugate (np.ndarray) – Boolean, same length as poles_out: False for real, True for conjugate pair or unpaired.
non_paired (np.ndarray) – Poles that could not be paired.

pyFDN.auxiliary.series_allpass(g)[source]#

Create Schroeder’s series allpass FDN (SISO).

Iterative series connection of feedforward/back allpass filters (same as seriesAllpass.m). Each stage appends one delay line via seriesFDNinAllpass. From Schroeder & Logan (1961). “Colorless” artificial reverberation. IRE Trans. Audio AU-9, 209–214. See “Allpass Feedback Delay Networks”, Schlecht.

Parameters:

g (array-like, shape (N,)) – Per-section gains (e.g. in (0, 1)).

Return type:

tuple[ndarray, ndarray, ndarray, ndarray]

Returns:

A (ndarray (N, N)) – Feedback matrix.
B (ndarray (N, 1)) – Input gain (column vector).
C (ndarray (1, N)) – Output gain (row vector).
D (ndarray (1, 1)) – Direct gain (scalar).

pyFDN.auxiliary.skew(X)[source]#

Return skew-symmetric matrix from upper triangle (Matlab skew convention).

Y = triu(X, 1) - triu(X, 1).T so that Y is skew-symmetric. Equivalent to skew.m: Y = X - X’ with X = triu(X, 1).

Return type:: ndarray

pyFDN.auxiliary.sos_filter_module(sos, nfft, *, device=None, dtype=None, requires_grad=False)[source]#

Build a FLAMO parallelSOSFilter from an SOS coefficient array.

Parameters:

sos (np.ndarray) – Shape (n_sections, 6, n_channels). Each section is [b0, b1, b2, a0, a1, a2] (e.g. from SDN wall_filters_sos).
nfft (int) – FFT size for the FLAMO module.
device (torch device or None) – Device for the module; default is cuda if available else cpu.
dtype (torch.dtype or None) – Optional dtype for module parameters (e.g., torch.float64). If None, uses float32 to preserve previous behavior.
requires_grad (bool) – Whether the filter parameters are trainable.

Returns:

FLAMO parallelSOSFilter with coefficients assigned.

Return type:

flamo.processor.dsp.parallelSOSFilter

pyFDN.auxiliary.wrap_fdn_shell(core, *, nfft, dtype=None, output='time')[source]#

Wrap an FDN core in a FLAMO Shell with an FFT input layer.

Parameters:

core (FLAMO module) – FDN core, e.g. from assemble_fdn_core().
nfft (int) – FFT size.
dtype (torch.dtype or None) – Dtype for the FFT/iFFT layers; defaults to float32.
output (str) –
Output-domain layer:
- "time" – iFFT time response (the render default, matching pyFDN.dss_to_flamo()).
- "magnitude" – |.| of the frequency response, for magnitude-domain losses (e.g. colorless training).

Return type:

flamo.processor.system.Shell