ferray_fft/lib.rs
1// ferray-fft: Complete numpy.fft parity with plan caching
2//
3//! FFT operations for the ferray numeric computing library.
4//!
5//! This crate provides the full `numpy.fft` surface:
6//!
7//! - **Complex FFTs**: [`fft`], [`ifft`], [`fft2`], [`ifft2`], [`fftn`], [`ifftn`]
8//! - **Real FFTs**: [`rfft`], [`irfft`], [`rfft2`], [`irfft2`], [`rfftn`], [`irfftn`]
9//! - **Hermitian FFTs**: [`hfft`], [`ihfft`]
10//! - **Frequency utilities**: [`fftfreq`], [`rfftfreq`]
11//! - **Shift utilities**: [`fftshift`], [`ifftshift`]
12//! - **Plan caching**: [`FftPlan`] for efficient repeated transforms
13//! - **Normalization**: [`FftNorm`] enum matching NumPy's `norm` parameter
14//!
15//! ## Precision
16//!
17//! All FFT functions are generic over [`FftFloat`], implemented for both
18//! `f32` and `f64`. The same call works with either precision:
19//!
20//! ```ignore
21//! let spectrum_f64 = ferray_fft::fft(&complex_f64_array, None, None, FftNorm::Backward)?;
22//! let spectrum_f32 = ferray_fft::fft(&complex_f32_array, None, None, FftNorm::Backward)?;
23//! ```
24//!
25//! Plan caches are per-precision — using only f64 means the f32 plan
26//! cache is never constructed.
27//!
28//! ## Real-input convenience
29//!
30//! Real arrays can be transformed with the full complex FFT via
31//! [`fft_real`] / [`ifft_real`] / [`fft_real2`] / [`fft_realn`], which
32//! auto-promote real inputs to complex before calling the standard
33//! complex FFT. For the half-spectrum form use [`rfft`] / [`rfftn`]
34//! instead.
35//!
36//! Internally powered by [`rustfft`](https://crates.io/crates/rustfft)
37//! and [`realfft`](https://crates.io/crates/realfft) with automatic plan
38//! caching for repeated transforms of the same size.
39
40mod axes;
41pub mod complex;
42pub mod float;
43pub mod freq;
44pub mod hermitian;
45mod nd;
46pub mod norm;
47pub mod plan;
48pub mod real;
49pub mod shift;
50
51// Re-export public API at crate root for ergonomic access.
52
53// Normalization
54pub use norm::FftNorm;
55
56// Plan caching
57pub use plan::FftPlan;
58
59// Complex FFTs (REQ-1..REQ-4)
60pub use complex::{fft, fft2, fftn, ifft, ifft2, ifftn};
61
62// Real-input convenience wrappers — auto-promote real arrays to complex.
63// For the Hermitian-folded half-spectrum form use `rfft`/`rfftn` instead.
64pub use complex::{fft_real, fft_real2, fft_realn, ifft_real};
65
66// Real FFTs (REQ-5..REQ-7)
67pub use real::{irfft, irfft2, irfftn, rfft, rfft2, rfftn};
68
69// Hermitian FFTs (REQ-8)
70pub use hermitian::{hfft, ihfft};
71
72// Frequency utilities (REQ-9, REQ-10)
73pub use freq::{fftfreq, rfftfreq};
74
75// Shift utilities (REQ-11)
76pub use shift::{fftshift, ifftshift};