Project Structure#

Comprehensive overview of the TorchFX repository structure, including source code organization, module dependencies, and package layout.

Overview#

The TorchFX repository follows a standard Python package structure with clear separation between source code, tests, documentation, and supporting tools. Understanding this structure is essential for contributing to the project and navigating the codebase effectively.

See also

Testing - Testing infrastructure Documentation - Documentation system

Repository Layout#

The repository is organized with the following top-level structure:

        graph TB
    Root["Repository Root"]

    Root --> Src["src/<br/>Source code"]
    Root --> Tests["tests/<br/>Test suite"]
    Root --> Docs["docs/<br/>Sphinx documentation"]
    Root --> Examples["examples/<br/>Usage examples"]
    Root --> Benchmark["benchmark/<br/>Performance tests"]
    Root --> CLI["cli/<br/>Command-line interface"]

    Root --> PyProject["pyproject.toml<br/>Project configuration"]
    Root --> UVLock["uv.lock<br/>Locked dependencies"]
    Root --> PreCommit[".pre-commit-config.yaml<br/>Code quality hooks"]
    Root --> GitHub[".github/<br/>CI/CD workflows"]
    Root --> README["README.md<br/>Project overview"]
    Root --> License["LICENSE<br/>GPLv3"]
    Root --> Changelog["CHANGELOG<br/>Version history"]

    Src --> TorchFX["torchfx/<br/>Main package"]
    Tests --> TestEffects["test_effects.py<br/>Effect tests"]
    Docs --> Source["source/<br/>Documentation source"]
    Examples --> Ex1["series_and_parallel_filters.py"]
    Examples --> Ex2["multi_channel_effect.py"]
    Examples --> Ex3["delay.py"]
    Benchmark --> B1["api_bench.py"]
    Benchmark --> B2["fir_bench.py"]
    Benchmark --> B3["iir_bench.py"]
    CLI --> Main["__main__.py<br/>CLI entry point"]

    GitHub --> CIWorkflow["workflows/ci.yml"]
    GitHub --> DocsWorkflow["workflows/docs.yml"]

Directory Purpose Summary#

Directory

Purpose

Key Contents

src/torchfx/

Main library package

Core modules: wave, effect, filter, typing

tests/

Test suite

Unit and integration tests

docs/

Documentation

Sphinx source files and configuration

examples/

Usage examples

Practical demonstrations of library features

benchmark/

Performance tests

GPU vs CPU performance comparisons

cli/

Command-line interface

CLI implementation (placeholder)

.github/workflows/

CI/CD pipelines

GitHub Actions workflow definitions

Source Package Structure#

The main library is located in src/torchfx/ and organized as a modular Python package. The structure emphasizes clear separation of concerns and explicit public API exports.

Package Layout#

        graph TD
    TorchFX["src/torchfx/"]

    TorchFX --> Init["__init__.py<br/>Public API exports"]
    TorchFX --> Wave["wave.py<br/>Wave class"]
    TorchFX --> Effect["effect.py<br/>FX, Gain, Normalize<br/>Reverb, Delay"]
    TorchFX --> Typing["typing.py<br/>MusicalTime<br/>Type aliases"]
    TorchFX --> FilterDir["filter/<br/>Filter subpackage"]

    FilterDir --> FilterInit["__init__.py<br/>Filter exports"]
    FilterDir --> FilterBase["__base.py<br/>AbstractFilter<br/>ParallelFilterCombination"]
    FilterDir --> FilterIIR["iir.py<br/>IIR implementations"]
    FilterDir --> FilterFIR["fir.py<br/>FIR implementations"]

    Init -.->|exports| Wave
    Init -.->|exports| Effect
    Init -.->|exports| Typing
    Init -.->|exports| FilterInit

    FilterInit -.->|aggregates| FilterBase
    FilterInit -.->|aggregates| FilterIIR
    FilterInit -.->|aggregates| FilterFIR

Module Organization#

The package exposes a clean public API through src/torchfx/__init__.py:

torchfx/
├── __init__.py          # Public API gateway
├── wave.py              # Wave data container
├── effect.py            # Effects and FX base class
├── typing.py            # Custom type definitions
└── filter/              # Filter subpackage
    ├── __init__.py      # Filter module exports
    ├── __base.py        # Abstract base classes
    ├── iir.py           # IIR filter implementations
    └── fir.py           # FIR filter implementations

Core Modules#

wave.py - Audio Data Container#

The wave.py module contains the Wave class, which is the primary data structure for audio in TorchFX.

Key responsibilities:

  • Audio tensor data storage (ys: torch.Tensor)

  • Sample rate management (fs: int)

  • Device management methods (CPU/GPU)

  • File I/O functionality

  • Pipe operator support for chaining effects

Example usage:

from torchfx import Wave

# Load audio file
wave = Wave.from_file("audio.wav")

# Access properties
print(wave.fs)  # Sample rate
print(wave.ys.shape)  # Tensor shape

# Move to GPU
wave.to("cuda")

See also

Wave - Digital Audio Representation - Complete Wave documentation

effect.py - Effects and Base Class#

The effect.py module contains the FX abstract base class and built-in effect implementations.

Classes:

  • FX - Abstract base class inheriting from torch.nn.Module

  • Gain - Amplitude adjustment effect

  • Normalize - Audio normalization with multiple strategies

  • Reverb - Reverberation effect

  • Delay - BPM-synchronized delay effect

All effects support the pipe operator (|) for chaining.

Example usage:

from torchfx import Wave
from torchfx.effect import Gain, Normalize

wave = Wave.from_file("audio.wav")

# Chain effects using pipe operator
processed = wave | Gain(gain=2.0) | Normalize(peak=0.9)

See also

Creating Custom Effects - Creating custom effects Effects Design - Effect design patterns

typing.py - Type System#

The typing.py module defines custom types for audio DSP operations.

Key types:

  • MusicalTime - Type for BPM-synchronized timing

  • Type aliases for audio parameters (e.g., Decibel, Second)

  • Annotations for improved type safety

Example usage:

from torchfx.typing import MusicalTime

# Parse musical time notation
quarter_note = MusicalTime.from_string("1/4")
dotted_eighth = MusicalTime.from_string("1/8d")

# Convert to seconds
duration = quarter_note.duration_seconds(bpm=120, beats_per_bar=4)
print(f"Duration: {duration} seconds")  # 0.5 seconds

See also

Type System - Musical Time and Audio Units - Complete type system documentation

filter/ - Filter Subpackage#

The filter subpackage is organized into three main files:

__base.py - Abstract Interfaces#

Contains abstract base classes for all filters:

  • AbstractFilter - Base class for all filters

  • ParallelFilterCombination - Combines multiple filters in parallel (supports + operator)

iir.py - IIR Filter Implementations#

Contains specific IIR filter types:

  • Butterworth filters: HiButterworth, LoButterworth, BandButterworth, BandStopButterworth

  • Chebyshev filters: HiChebyshev1, LoChebyshev1, HiChebyshev2, LoChebyshev2

  • Shelving filters: LoShelving, HiShelving

  • Peaking filters: PeakingEQ

  • Notch filters: NotchFilter

  • AllPass filters: AllPassFilter

  • Linkwitz-Riley crossover filters: LinkwitzRiley

fir.py - FIR Filter Implementations#

Contains FIR filter classes:

  • FIR - Basic FIR filter with coefficient input

  • DesignableFIR - FIR filter with automatic coefficient design

See also

Filters Design - Filter design guide Series and Parallel Filter Combinations - Combining filters

Module Dependencies#

The following diagram illustrates dependency relationships between modules and external packages:

        graph TB
    subgraph "Public API (torchfx.*)"
        Wave["Wave<br/>(from wave)"]
        FX["FX<br/>(from effect)"]
        EffectModule["effect module<br/>(Gain, Normalize, Reverb, Delay)"]
        FilterModule["filter module<br/>(AbstractFilter, IIR, FIR, Parallel)"]
        TypingModule["typing module<br/>(MusicalTime, type aliases)"]
    end

    subgraph "Internal Modules"
        WaveImpl["wave.py<br/>Wave class implementation"]
        EffectImpl["effect.py<br/>FX + effect implementations"]
        TypingImpl["typing.py<br/>Type definitions"]

        subgraph "filter/ subpackage"
            FilterBase["__base.py<br/>AbstractFilter<br/>ParallelFilterCombination"]
            FilterIIR["iir.py<br/>Butterworth, Chebyshev<br/>Shelving, Peaking, etc."]
            FilterFIR["fir.py<br/>FIR, DesignableFIR"]
        end
    end

    subgraph "External Dependencies"
        PyTorch["torch<br/>torch.nn.Module<br/>Tensor operations"]
        TorchAudio["torchaudio<br/>Audio I/O<br/>Transforms"]
        SciPy["scipy.signal<br/>Filter coefficient design"]
        NumPy["numpy<br/>Array operations"]
    end

    Wave -.->|implemented in| WaveImpl
    FX -.->|implemented in| EffectImpl
    EffectModule -.->|implemented in| EffectImpl
    FilterModule -.->|aggregates| FilterBase
    FilterModule -.->|aggregates| FilterIIR
    FilterModule -.->|aggregates| FilterFIR
    TypingModule -.->|implemented in| TypingImpl

    WaveImpl -->|depends on| PyTorch
    WaveImpl -->|depends on| TorchAudio
    EffectImpl -->|depends on| PyTorch
    EffectImpl -->|depends on| TorchAudio
    EffectImpl -->|uses| TypingImpl
    FilterBase -->|extends| PyTorch
    FilterIIR -->|extends| FilterBase
    FilterIIR -->|uses| SciPy
    FilterFIR -->|extends| FilterBase
    FilterFIR -->|uses| SciPy

Public API Exports#

The public API is explicitly controlled through __all__ declarations in __init__.py:

Export

Source Module

Description

Wave

torchfx.wave

Audio data container class

FX

torchfx.effect

Abstract base class for all effects/filters

effect

torchfx.effect

Module containing effect implementations

filter

torchfx.filter

Subpackage containing filter implementations

typing

torchfx.typing

Module with custom type definitions

Import Patterns#

Import Hierarchy#

        graph LR
    User["User Code"]

    subgraph "Top-Level Imports"
        TopWave["from torchfx import Wave"]
        TopFX["from torchfx import FX"]
        TopEffect["import torchfx.effect"]
        TopFilter["import torchfx.filter"]
        TopTyping["import torchfx.typing"]
    end

    subgraph "Submodule Imports"
        EffectClasses["from torchfx.effect import Gain, Normalize, Reverb, Delay"]
        FilterClasses["from torchfx.filter import Butterworth, Chebyshev, FIR"]
        TypeDefs["from torchfx.typing import MusicalTime"]
    end

    User --> TopWave
    User --> TopFX
    User --> TopEffect
    User --> TopFilter
    User --> TopTyping

    User --> EffectClasses
    User --> FilterClasses
    User --> TypeDefs

    TopEffect -.->|contains| EffectClasses
    TopFilter -.->|contains| FilterClasses
    TopTyping -.->|contains| TypeDefs

Supporting Infrastructure#

Examples Directory#

The examples/ directory contains practical demonstrations of library features:

File

Purpose

series_and_parallel_filters.py

Demonstrates filter chaining (|) and parallel combination (+)

multi_channel_effect.py

Shows custom multi-channel effect implementation

delay.py

Demonstrates BPM-synchronized delay with musical timing

Running examples:

python examples/series_and_parallel_filters.py
python examples/multi_channel_effect.py
python examples/delay.py

Tests Directory#

The tests/ directory contains the test suite with unit and integration tests. Test configuration is specified in pyproject.toml:

  • Test discovery in tests/ directory

  • Python path includes src/ for imports

  • Coverage reporting targets src/torchfx

See also

Testing - Complete testing documentation

Documentation Directory#

The docs/ directory contains Sphinx documentation:

docs/
├── source/
│   ├── api.rst          # API reference
│   ├── conf.py          # Sphinx configuration
│   ├── guides/          # User and developer guides
│   └── ...              # Other documentation pages
├── Makefile             # Build automation (Unix)
└── make.bat             # Build automation (Windows)

Documentation is automatically built and deployed to GitHub Pages via .github/workflows/docs.yml.

See also

Documentation - Documentation build system

Benchmark Directory#

The benchmark/ directory contains performance measurement scripts:

File

Purpose

api_bench.py

Compares different API patterns (FilterChain, Sequential, pipe operator)

fir_bench.py

Measures FIR filter performance (GPU vs CPU vs SciPy)

iir_bench.py

Measures IIR filter performance (GPU vs CPU vs SciPy)

draw3.py

Visualizes benchmark results as PNG images

See also

Benchmarking - Benchmarking guide

CLI Directory#

The cli/ directory contains the command-line interface:

cli/
└── __main__.py          # CLI entry point

The CLI is configured as a project script in pyproject.toml:

[project.scripts]
torchfx = "cli.__main__:main"

Currently serves as a placeholder for future CLI functionality.

Configuration Files#

pyproject.toml - Central Configuration Hub#

The pyproject.toml file serves as the central configuration for the entire project, containing:

Project Metadata#

  • Name, version, description

  • License (GPLv3) and authors

  • Python version requirement (>=3.10)

  • Dependencies and classifiers

  • Project URLs (repository, documentation, changelog)

Tool Configurations#

Tool

Purpose

Section

uv

Package manager with PyTorch source configuration

[tool.uv]

mypy

Type checking with strict mode

[tool.mypy]

ruff

Fast Python linter and formatter

[tool.ruff]

black

Code formatting

[tool.black]

coverage

Test coverage measurement

[tool.coverage]

pytest

Testing framework

[tool.pytest]

docformatter

Docstring formatting

[tool.docformatter]

Build System#

Uses hatchling as the build backend:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Dependency Groups#

[dependency-groups]
cli = ["typer"]
dev = ["black", "mypy", "pytest", "ruff", ...]
docs = ["sphinx", "sphinx-immaterial", ...]

uv.lock - Dependency Lock File#

The uv.lock file provides:

  • Complete dependency resolution with exact versions

  • Reproducible builds across environments

  • Platform-specific dependency tracking

Generated and managed by the uv package manager.

.pre-commit-config.yaml - Code Quality Hooks#

Configures pre-commit hooks that run before each commit:

  • Type checking with mypy

  • Linting with ruff

  • Formatting with black

  • Docstring formatting with docformatter

Installation:

pre-commit install

.github/workflows/ - CI/CD Configuration#

Contains GitHub Actions workflow definitions:

Workflow

Purpose

File

CI

Runs tests, linting, and type checking in parallel across Python 3.10-3.13

ci.yml

Docs

Builds Sphinx documentation and deploys to GitHub Pages

docs.yml

Package Distribution#

The project is configured for distribution as a Python package:

Build Artifacts#

Installation Methods#

The package can be installed via:

# From PyPI
pip install torchfx

# From source (development)
pip install -e .

# With extras (CLI support)
pip install torchfx[cli]

Best Practices#

Module Organization#

  • Single Responsibility: Each module has a clear, focused purpose

  • Explicit Exports: Public API is controlled via __all__ declarations

  • Shallow Hierarchy: Avoid deeply nested package structures

  • Clear Dependencies: Minimize coupling between modules

Code Structure#

  • Type Hints: Use type hints for all public functions and methods

  • Docstrings: Document all public APIs with NumPy-style docstrings

  • Testing: Write tests for all new functionality

  • Linting: Follow ruff and black formatting standards

See also

Style Guide - Complete style guide