rill_fft/
lib.rs

1// rill-fft/src/lib.rs
2//! # Rill FFT
3//!
4//! Fast Fourier Transform and frequency-domain signal processing for the Rill ecosystem.
5//!
6//! ## Modules
7//!
8//! | Module | Key types | Purpose |
9//! |---|---|---|
10//! | `complex_fft` | `ComplexFft<T>` | Radix-2 DIT complex FFT (forward + inverse) |
11//! | `real_fft` | `RealFft<T>` | Real-valued FFT via half-size complex packing |
12//! | `overlap_add` | `OverlapAddConvolver<T, BUF>` | Frequency‑domain convolution (medium IRs) |
13//! | `partitioned_conv` | `PartitionedConvolver<T, BUF>` | Partitioned convolution (long IRs) |
14//! | `spectrum` | `FftSpectrumAnalyzer<T>` | FFT‑based spectrum analyser |
15//! | `effects` | `SpectralGate`, `SpectralDelay` | Frequency‑domain effects |
16//! | `nodes` | `ConvolverNode` | Graph‑node wrappers |
17//!
18//! ## RT safety
19//!
20//! All scratch buffers (twiddle tables, delay lines, overlap buffers) are
21//! pre‑allocated in constructors. `process()` methods perform **zero heap
22//! allocations** — verified by a custom panic‑on‑alloc tests in `tests/rt_safety.rs`.
23//!
24//! ## Performance (f32, x86_64, release profile)
25//!
26//! | Operation | Size | Time | Throughput |
27//! |---|---|---|---|
28//! | `ComplexFft::forward` | 1024 | 6.7 µs | 153 Melem/s |
29//! | `RealFft::forward` | 1024 | 6.2 µs | 165 Melem/s |
30//! | `ComplexFft::forward` | 16384 | 177 µs | 92 Melem/s |
31//! | `OverlapAddConvolver` | IR 2048, BUF 128 | 61 µs/block | ~2100 blocks/s |
32//! | `PartitionedConvolver` | IR 65536, BUF 128 | 104 µs/block | ~9600 blocks/s |
33//! | `DirectConvolver` | 128 taps, BUF 128 | 10 µs/block | 12.7 Melem/s |
34//!
35//! ### f64 precision
36//!
37//! | Operation | Size | Time | Throughput |
38//! |---|---|---|---|
39//! | `ComplexFft::forward` | 1024 | 7.9 µs | 129 Melem/s |
40//! | `ComplexFft::forward` | 4096 | 39.7 µs | 103 Melem/s |
41//! | `ComplexFft::forward` | 8192 | 93.5 µs | 88 Melem/s |
42//!
43//! f64 is ~15–20 % slower than f32, consistent with double‑width memory and cache pressure.
44//! 64‑bit transforms are still well within the real‑time budget for typical block sizes.
45//!
46//! At 44.1 kHz with block size 128 the per‑block budget is ~2.9 ms.
47//! All operations fit comfortably within the real‑time budget.
48//!
49//! ## Examples
50//!
51//! ### Complex FFT
52//!
53//! ```rust,no_run
54//! use rill_fft::complex_fft::ComplexFft;
55//! use num_complex::Complex;
56//!
57//! let fft = ComplexFft::<f32>::new(1024);
58//! let mut data: Vec<Complex<f32>> = (0..1024)
59//!     .map(|i| Complex::new((i as f32 * 0.1).sin(), 0.0))
60//!     .collect();
61//!
62//! fft.forward(&mut data);
63//! // ... manipulate spectrum ...
64//! fft.inverse(&mut data);
65//! ```
66//!
67//! ### Convolution
68//!
69//! ```rust,no_run
70//! use rill_fft::partitioned_conv::PartitionedConvolver;
71//!
72//! // IR length 16384 samples, BUF_SIZE = 128
73//! let mut conv = PartitionedConvolver::<f32, 128>::new(16384);
74//!
75//! // Load impulse response (e.g., from a WAV file)
76//! let ir: Vec<f32> = vec![0.0; 16384];
77//! conv.set_ir(&ir);
78//!
79//! // Process audio blocks in the signal thread
80//! let input = [0.5f32; 128];
81//! let mut output = [0.0f32; 128];
82//! conv.process(&input, &mut output);
83//! ```
84//!
85//! ### Spectral gate
86//!
87//! ```rust,no_run
88//! use rill_fft::effects::spectral_gate::SpectralGate;
89//!
90//! let mut gate = SpectralGate::<f32, 128>::new();
91//! gate.set_threshold(0.01);
92//! gate.set_ratio(0.0);  // hard gate below threshold
93//!
94//! let input = [0.5f32; 128];
95//! let mut output = [0.0f32; 128];
96//! gate.process(&input, &mut output);
97//! ```
98//!
99//! ## Features
100//! - Generic over `T: Transcendental` (f32, f64)
101//! - SIMD acceleration behind `simd` feature flag (via `rill-core/wide`)
102//! - `#![deny(unsafe_code)]` — pure safe Rust
103
104#![warn(missing_docs)]
105#![deny(unsafe_code)]
106
107pub mod complex_fft;
108pub mod effects;
109pub mod overlap_add;
110pub mod partitioned_conv;
111pub mod real_fft;
112pub mod spectrum;
113
114/// Prelude for convenient imports.
115pub mod prelude {
116    pub use crate::complex_fft::ComplexFft;
117    pub use crate::effects::{spectral_delay::SpectralDelay, spectral_gate::SpectralGate};
118    pub use crate::overlap_add::OverlapAddConvolver;
119    pub use crate::partitioned_conv::PartitionedConvolver;
120    pub use crate::real_fft::RealFft;
121    pub use crate::spectrum::FftSpectrumAnalyzer;
122}
123
124/// Register graph nodes and lang builtins for FFT.
125pub mod register;
126
127/// FFT lang builtins (spectral gate, spectral delay, convolver).
128pub mod lang;
rill_fft/lib.rs

rill_fft/
lib.rs
