pyFDN.train package#

Submodules#

pyFDN.train.build module#

Build a trainable flamo FDN model from a config.

build_fdn() turns a config (delays/N, decay, what is trainable) into a trainable flamo Shell you can render, train, and extract. trainable_from_build() does the same starting from an existing FDNBuild.

class pyFDN.train.build.Trainable(feedback=True, input_gain=True, output_gain=True, direct=False)[source]#

Bases: object

Which FDN parameter groups are trained. Delays are always fixed.

direct: bool = False#
feedback: bool = True#
input_gain: bool = True#
output_gain: bool = True#
pyFDN.train.build.build_fdn(*, delays=None, N=None, rt=2.0, matrix='orthogonal', feedback=None, input_gain=None, output_gain=None, direct=0.0, trainable=None, fs=48000.0, nfft=16384, output='time', device=None, dtype=None, rng=None)[source]#

Build a trainable flamo Shell from a config.

Parameters:

  • delays (np.ndarray, optional) – Explicit integer delay lengths in samples. If omitted, N coprime delays are sampled (pyFDN.sample_delay_lengths()).

  • N (int, optional) – Number of delay lines when delays is omitted.

  • rt (float, (rt_dc, rt_nyquist), or None) – Reverberation time in seconds. None builds a lossless FDN.

  • matrix ({"orthogonal", "random"}) – Feedback-matrix parametrization.

  • feedback (np.ndarray, optional) – Initial (N, N) feedback matrix; defaults to a random SO(N) matrix.

  • input_gain (np.ndarray, optional) – B ((N, n_in)) and C ((n_out, N)); default ones / sqrt(N).

  • output_gain (np.ndarray, optional) – B ((N, n_in)) and C ((n_out, N)); default ones / sqrt(N).

  • direct (float or np.ndarray) – Direct path D; a scalar fills (n_out, n_in).

  • trainable (Trainable, optional) – Trainable parameter groups (default Trainable).

  • fs (see trainable_from_build().)

  • nfft (see trainable_from_build().)

  • output (see trainable_from_build().)

  • device (see trainable_from_build().)

  • dtype (see trainable_from_build().)

  • rng (np.random.Generator, int, or None) – Seed for the sampled delays / default feedback matrix.

Return type:

flamo.processor.system.Shell

pyFDN.train.build.trainable_from_build(build, *, trainable=None, matrix='orthogonal', nfft=16384, output='time', device=None, dtype=None)[source]#

Build a trainable flamo Shell initialized from an FDNBuild.

Parameters:

  • build (FDNBuild) – Initial FDN (A/B/C/D/delays/fs + optional filters/post_eq).

  • trainable (Trainable, optional) – Trainable parameter groups (default Trainable).

  • matrix ({"orthogonal", "random"}) – Feedback-matrix parametrization.

  • nfft (int) – FFT size.

  • output (str) – "time" or "magnitude" output layer (train_fdn sets this to match the mode).

  • device (optional) – Torch device / dtype (default cpu-or-cuda / float32).

  • dtype (optional) – Torch device / dtype (default cpu-or-cuda / float32).

Return type:

flamo.processor.system.Shell

pyFDN.train.build.with_decay(build, rt, *, rt_crossover=None)[source]#

Return a copy of build with homogeneous decay matching rt.

Sets per-delay first-order absorption (pyFDN.first_order_absorption()) for rt (a single value, or (rt_dc, rt_nyquist)). Decay does not change colouration, so this is the natural way to add a tail to a colorless build.

Return type:

FDNBuild

pyFDN.train.engine module#

Train an FDN toward a target.

train_fdn() fits a model from pyFDN.build_fdn() toward a mode (colorless / match_spectrogram / match_mel_spectrogram) in place and returns a TrainLog. Read the result back with pyFDN.extract_build().

class pyFDN.train.engine.TrainLog(train_loss=<factory>, loss_log=<factory>, steps_run=0, stopped_early=False)[source]#

Bases: object

Per-step loss history and stopping info from a training run.

train_loss#

Total loss at each step.

Type:

list of float

loss_log#

Per-criterion loss history, keyed by criterion class name.

Type:

dict of str to list of float

steps_run#

Steps actually run.

Type:

int

stopped_early#

Whether a plateau stopped it before max_steps.

Type:

bool

loss_log: dict[str, list[float]]#
steps_run: int = 0#
stopped_early: bool = False#
train_loss: list[float]#
pyFDN.train.engine.train_fdn(model, mode, *, target=None, criteria=None, sparsity_alpha=0.2, mss_nfft=(256, 512, 1024), max_steps=2000, lr=0.001, optimizer='adam', patience=10, tol=1e-06, device=None, dtype=None, rng=None, log=False, train_dir=None)[source]#

Train model for mode in place and return a TrainLog.

Read the trained result back with pyFDN.extract_build().

Parameters:

  • model (flamo Shell) – A trainable model from pyFDN.build_fdn() / trainable_from_build.

  • mode (str) – "colorless", "match_spectrogram" or "match_mel_spectrogram". "colorless" is single-input/single-output only.

  • target (np.ndarray, optional) – Reference impulse response for the matching modes (unused for colorless). Shape (n_samples,) or (n_samples, n_out), or a 3-D (n_samples, n_out, n_in) IR matrix to fit a full MIMO system.

  • criteria (list of (criterion, alpha, requires_model), optional) – Replace the default loss list (primary loss + sparsity) with your own.

  • sparsity_alpha (float) – Weight of the feedback-matrix sparsity penalty (default 0.2; 0 disables).

  • mss_nfft (tuple of int) – STFT window sizes for the spectrogram modes.

  • max_steps (max gradient steps, learning rate, plateau patience.)

  • lr (max gradient steps, learning rate, plateau patience.)

  • patience (max gradient steps, learning rate, plateau patience.)

  • optimizer (str) – "adam" (default) or "lbfgs".

  • tol (float) – Relative-improvement threshold for the plateau early stop.

  • device (optional) – Torch device / dtype (default cpu / float32).

  • dtype (optional) – Torch device / dtype (default cpu / float32).

  • rng (int or None) – Integer seed for torch.manual_seed.

  • log (bool) – If True, log/checkpoint to train_dir.

  • train_dir (str, optional) – Checkpoint directory (used when log=True).

Return type:

TrainLog

pyFDN.train.objectives module#

Map a training mode (and optional target) to the (input, target) tensors, loss criteria, and output domain that pyFDN.train_fdn() uses.

colorless is single-input/single-output (its loss sums the model’s outputs). The matching modes take a time-domain IR target; a 3-D (n_samples, n_out, n_in) target fits a full MIMO system. Every mode also adds a feedback-matrix sparsity penalty (weight sparsity_alpha) that only acts when the feedback matrix is trainable.

pyFDN.train.objectives.build_objective(mode, *, target, criteria, sparsity_alpha, mss_nfft, fs, nfft, n_in, n_out, device, dtype)[source]#

Return (input, target, criteria, output_domain) for a training mode.

Uses the mode’s default criteria (primary loss + sparsity) unless criteria overrides them.

Return type:

tuple[Any, Any, list[tuple[Any, float, bool]], str]

pyFDN.train.objectives.colorless_sparsity_loss()[source]#

Sparsity penalty on the FDN feedback matrix (the colorless penalty of Optimizing Tiny Colorless FDNs, Dal Santo et al.).

Returns an nn.Module with the (y_pred, y_target, model) signature used for requires_model=True criteria.

Return type:

Any

pyFDN.train.objectives.output_domain(mode)[source]#

The model output layer a mode measures in ("time" or "magnitude").

Return type:

str

Module contents#

Training pipeline for FDNs – an explicit three-step API over flamo.

  1. build a trainable flamo model from a config (build_fdn(), or trainable_from_build() from an existing FDNBuild).

  2. train the model toward a mode (train_fdn()) – colorless, match_spectrogram or match_mel_spectrogram, with optional target data.

  3. extract an FDNBuild back out (pyFDN.extract_build()), plus a TrainLog.

class pyFDN.train.TrainLog(train_loss=<factory>, loss_log=<factory>, steps_run=0, stopped_early=False)[source]#

Bases: object

Per-step loss history and stopping info from a training run.

train_loss#

Total loss at each step.

Type:

list of float

loss_log#

Per-criterion loss history, keyed by criterion class name.

Type:

dict of str to list of float

steps_run#

Steps actually run.

Type:

int

stopped_early#

Whether a plateau stopped it before max_steps.

Type:

bool

loss_log: dict[str, list[float]]#
steps_run: int = 0#
stopped_early: bool = False#
train_loss: list[float]#
class pyFDN.train.Trainable(feedback=True, input_gain=True, output_gain=True, direct=False)[source]#

Bases: object

Which FDN parameter groups are trained. Delays are always fixed.

direct: bool = False#
feedback: bool = True#
input_gain: bool = True#
output_gain: bool = True#
pyFDN.train.build_fdn(*, delays=None, N=None, rt=2.0, matrix='orthogonal', feedback=None, input_gain=None, output_gain=None, direct=0.0, trainable=None, fs=48000.0, nfft=16384, output='time', device=None, dtype=None, rng=None)[source]#

Build a trainable flamo Shell from a config.

Parameters:

  • delays (np.ndarray, optional) – Explicit integer delay lengths in samples. If omitted, N coprime delays are sampled (pyFDN.sample_delay_lengths()).

  • N (int, optional) – Number of delay lines when delays is omitted.

  • rt (float, (rt_dc, rt_nyquist), or None) – Reverberation time in seconds. None builds a lossless FDN.

  • matrix ({"orthogonal", "random"}) – Feedback-matrix parametrization.

  • feedback (np.ndarray, optional) – Initial (N, N) feedback matrix; defaults to a random SO(N) matrix.

  • input_gain (np.ndarray, optional) – B ((N, n_in)) and C ((n_out, N)); default ones / sqrt(N).

  • output_gain (np.ndarray, optional) – B ((N, n_in)) and C ((n_out, N)); default ones / sqrt(N).

  • direct (float or np.ndarray) – Direct path D; a scalar fills (n_out, n_in).

  • trainable (Trainable, optional) – Trainable parameter groups (default Trainable).

  • fs (see trainable_from_build().)

  • nfft (see trainable_from_build().)

  • output (see trainable_from_build().)

  • device (see trainable_from_build().)

  • dtype (see trainable_from_build().)

  • rng (np.random.Generator, int, or None) – Seed for the sampled delays / default feedback matrix.

Return type:

flamo.processor.system.Shell

pyFDN.train.train_fdn(model, mode, *, target=None, criteria=None, sparsity_alpha=0.2, mss_nfft=(256, 512, 1024), max_steps=2000, lr=0.001, optimizer='adam', patience=10, tol=1e-06, device=None, dtype=None, rng=None, log=False, train_dir=None)[source]#

Train model for mode in place and return a TrainLog.

Read the trained result back with pyFDN.extract_build().

Parameters:

  • model (flamo Shell) – A trainable model from pyFDN.build_fdn() / trainable_from_build.

  • mode (str) – "colorless", "match_spectrogram" or "match_mel_spectrogram". "colorless" is single-input/single-output only.

  • target (np.ndarray, optional) – Reference impulse response for the matching modes (unused for colorless). Shape (n_samples,) or (n_samples, n_out), or a 3-D (n_samples, n_out, n_in) IR matrix to fit a full MIMO system.

  • criteria (list of (criterion, alpha, requires_model), optional) – Replace the default loss list (primary loss + sparsity) with your own.

  • sparsity_alpha (float) – Weight of the feedback-matrix sparsity penalty (default 0.2; 0 disables).

  • mss_nfft (tuple of int) – STFT window sizes for the spectrogram modes.

  • max_steps (max gradient steps, learning rate, plateau patience.)

  • lr (max gradient steps, learning rate, plateau patience.)

  • patience (max gradient steps, learning rate, plateau patience.)

  • optimizer (str) – "adam" (default) or "lbfgs".

  • tol (float) – Relative-improvement threshold for the plateau early stop.

  • device (optional) – Torch device / dtype (default cpu / float32).

  • dtype (optional) – Torch device / dtype (default cpu / float32).

  • rng (int or None) – Integer seed for torch.manual_seed.

  • log (bool) – If True, log/checkpoint to train_dir.

  • train_dir (str, optional) – Checkpoint directory (used when log=True).

Return type:

TrainLog

pyFDN.train.trainable_from_build(build, *, trainable=None, matrix='orthogonal', nfft=16384, output='time', device=None, dtype=None)[source]#

Build a trainable flamo Shell initialized from an FDNBuild.

Parameters:

  • build (FDNBuild) – Initial FDN (A/B/C/D/delays/fs + optional filters/post_eq).

  • trainable (Trainable, optional) – Trainable parameter groups (default Trainable).

  • matrix ({"orthogonal", "random"}) – Feedback-matrix parametrization.

  • nfft (int) – FFT size.

  • output (str) – "time" or "magnitude" output layer (train_fdn sets this to match the mode).

  • device (optional) – Torch device / dtype (default cpu-or-cuda / float32).

  • dtype (optional) – Torch device / dtype (default cpu-or-cuda / float32).

Return type:

flamo.processor.system.Shell

pyFDN.train.with_decay(build, rt, *, rt_crossover=None)[source]#

Return a copy of build with homogeneous decay matching rt.

Sets per-delay first-order absorption (pyFDN.first_order_absorption()) for rt (a single value, or (rt_dc, rt_nyquist)). Decay does not change colouration, so this is the natural way to add a tail to a colorless build.

Return type:

FDNBuild