pyFDN package#

Subpackages#

Submodules#

pyFDN.build module#

Baked feedback-delay-network builds and their JSON representation.

An FDNBuild is a delay state-space (DSS) system – A, B, C, D, and delays – plus the sample rate and three optional baked filter hooks. A build is designed around a DSS system, not the other way around: use the raw DSS arrays (and dss_to_* functions) for pure state-space math, and an FDNBuild (and build_to_* functions) once fs or the filter hooks matter, e.g. for rendering.

class pyFDN.build.FDNBuild(A, B, C, D, delays, fs, post_delay=None, post_matrix=None, post_output=None)[source]#

Bases: object

Complete, renderable parameters of a vanilla FDN.

A, B, C, D, and delays are a delay state-space (DSS) system; fs and the three optional filter hooks turn that system into a complete, renderable build. Every field is a plain NumPy value consumed by pyFDN.process_fdn() and pyFDN.build_to_impz(). A build does not remember how its numbers were designed; that optional information belongs to pyFDN.FDNPreset.

The three optional SOS banks correspond directly to pyFDN’s filter hooks:

  • post_delay has shape (sections, 6, N) and sets the decay inside the loop after the delays.

  • post_matrix has shape (sections, 6, N) and filters the feedback path after the feedback matrix.

  • post_output has shape (sections, 6, outputs) and filters the wet signal outside the recursion.

A: ndarray#
B: ndarray#
C: ndarray#
D: ndarray#
delays: ndarray#
fs: float#
post_delay: ndarray | None = None#
post_matrix: ndarray | None = None#
post_output: ndarray | None = None#
pyFDN.build.fdn_build_from_dict(data, *, fs=None)[source]#

Construct an FDNBuild from its JSON-compatible dictionary.

fs is an optional override retained for loading standalone legacy build files. Preset loading always uses the sample rate stored in the build.

Return type:

FDNBuild

pyFDN.build.fdn_build_to_dict(build, *, metadata=None)[source]#

Convert an FDNBuild to its JSON-compatible format.

Return type:

dict[str, Any]

pyFDN.build.load_fdn_build(path, *, fs=None)[source]#

Load an FDNBuild from its JSON format.

Return type:

FDNBuild

pyFDN.build.save_fdn_build(path, build, *, metadata=None)[source]#

Write an FDNBuild as indented, human-readable JSON.

Return type:

None

pyFDN.preset module#

Readable preset documents for vanilla feedback delay networks.

A preset keeps the exact, renderable FDNBuild separate from optional metadata and JSON-like design notes. The build is authoritative; design records only preserve choices that cannot be inferred reliably from its numbers.

class pyFDN.preset.FDNPreset(build, metadata, design=<factory>)[source]#

Bases: object

A baked vanilla FDN plus metadata and optional design information.

metadata is an open JSON object intended for catalog and attribution information. When used, tags should be a list of strings so callers can filter presets consistently without restricting other metadata fields.

design deliberately uses the same nested dictionaries as the JSON document. Unknown choices are represented by leaving out type or the entire component:

FDNPreset(
    build=build,
    metadata={"name": "small-room", "tags": ["room", "short"]},
    design={
        "delays": {"type": "uniform", "coprime": True},
        "feedback_matrix": {"type": "orthogonal"},
    },
)
build: FDNBuild#
design: dict[str, dict[str, Any]]#
metadata: dict[str, Any]#
pyFDN.preset.available_fdn_presets()[source]#

Return the names accepted by get_fdn_preset().

Return type:

tuple[str, ...]

pyFDN.preset.fdn_preset_from_dict(data)[source]#

Construct an FDNPreset from a parsed JSON dictionary.

Return type:

FDNPreset

pyFDN.preset.fdn_preset_to_dict(preset)[source]#

Convert an FDNPreset to a JSON-compatible dictionary.

Return type:

dict[str, Any]

pyFDN.preset.get_fdn_preset(name)[source]#

Return a packaged FDNPreset document.

Older build-only resources are also accepted. Their metadata is lifted into a preset without guessing design choices that were not saved.

Return type:

FDNPreset

pyFDN.preset.load_fdn_preset(path)[source]#

Load an FDNPreset from a JSON file.

Return type:

FDNPreset

pyFDN.preset.save_fdn_preset(path, preset)[source]#

Write a preset as indented, human-readable JSON.

Return type:

None

pyFDN.process module#

Compact DSS processing and convenience rendering of complete FDN builds.

pyFDN.process.process_dss(input_signal, delays, A, B, C, D, *, post_delay=None, post_matrix=None, post_output=None)[source]#

Process a delay state-space system using block processing.

One-shot form of dss_to_td(...).process_signal(input_signal): a fresh pyFDN.td graph is built for every call. The three optional hooks are runtime objects that implement process_block(block) (or SOS banks). To process an pyFDN.FDNBuild, use pyFDN.process_fdn().

The recursion is

delay -> post_delay -> C on the wet path and delay -> post_delay -> A -> post_matrix -> + B input in the loop. post_output processes the wet signal before the direct D path is added.

Parameters:

  • input_signal (ArrayLike) – Input of shape (num_samples,) or (num_samples, num_inputs).

  • delays (ArrayLike) – Positive delay lengths in samples, shape (N,).

  • A (ArrayLike) – Static feedback matrix (N, N) or FIR polynomial matrix (N, N, order) in the z^-1 convention.

  • B (ArrayLike) – Static input, output, and direct gain matrices.

  • C (ArrayLike) – Static input, output, and direct gain matrices.

  • D (ArrayLike) – Static input, output, and direct gain matrices.

  • post_delay (Any | None) – Optional hooks, see pyFDN.dss_to_td().

  • post_matrix (Any | None) – Optional hooks, see pyFDN.dss_to_td().

  • post_output (Any | None) – Optional hooks, see pyFDN.dss_to_td().

Returns:

Processed signal with singleton dimensions removed.

Return type:

ndarray

pyFDN.process.process_fdn(input_signal, build)[source]#

Process a signal through a fresh time-domain graph built from build.

This is the one-shot convenience form of build_to_td(build).process_signal(input_signal). A fresh graph is built for every call, so delay and filter state cannot leak between independent renders. Use pyFDN.build_to_td() directly to process a stream over multiple calls to pyFDN.td.TimeOperator.process_block() or to reset and reuse the graph.

Parameters:

  • input_signal (ArrayLike) – Input of shape (num_samples,) or (num_samples, num_inputs).

  • build (FDNBuild) – Complete baked FDN configuration.

Returns:

Processed signal with singleton dimensions removed, matching the historical process_fdn output convention.

Return type:

ndarray

pyFDN.references module#

Citation helpers backed by the bibliography distributed with pyFDN.

Return a Markdown citation link for a packaged bibliography entry.

Return type:

str

pyFDN.references.paper_reference(paper_id)[source]#

Return a copy of the bibliography fields for paper_id.

Return type:

dict[str, str]

Module contents#

See API Reference for full documentation of all functions and classes.