circulant_rs/lib.rs
1// @module: crate
2// @status: stable
3// @owner: code_expert
4// @feature: none
5// @depends: [core, error, fft, traits, prelude]
6// @tests: [unit, integration]
7
8//! High-performance block-circulant matrix operations using FFT.
9//!
10//! This library exploits the fact that circulant matrices can be diagonalized
11//! by the DFT matrix, enabling O(N log N) matrix-vector multiplication instead
12//! of the naive O(N²) approach.
13//!
14//! # Overview
15//!
16//! A circulant matrix is a special type of Toeplitz matrix where each row is
17//! a cyclic shift of the previous row. This structure allows for efficient
18//! computation using the Fast Fourier Transform (FFT).
19//!
20//! # Features
21//!
22//! - `std` (default): Enable standard library features
23//! - `physics` (default): Enable quantum physics module (quantum walks, coins, Hamiltonians)
24//! - `parallel` (default): Enable parallel computation with rayon
25//! - `serde` (default): Enable serialization with serde/bincode
26//! - `vision`: Enable image processing with BCCB filters
27//! - `visualize`: Enable visualization with plotters (base feature)
28//! - `visualize-svg`: Enable SVG output for visualization
29//! - `visualize-bitmap`: Enable bitmap output for visualization
30//! - `python`: Enable Python bindings via PyO3
31//!
32//! # Example
33//!
34//! ```
35//! use circulant_rs::prelude::*;
36//! use num_complex::Complex;
37//!
38//! // Create a circulant matrix from a real generator
39//! let c = Circulant::from_real(vec![1.0, 2.0, 3.0, 4.0]).unwrap();
40//!
41//! // Multiply by a vector using FFT (O(N log N))
42//! let x: Vec<Complex<f64>> = vec![
43//! Complex::new(1.0, 0.0),
44//! Complex::new(0.0, 0.0),
45//! Complex::new(1.0, 0.0),
46//! Complex::new(0.0, 0.0),
47//! ];
48//! let result = c.mul_vec(&x).unwrap();
49//! ```
50
51#![cfg_attr(not(feature = "std"), no_std)]
52
53pub mod core;
54pub mod error;
55pub mod fft;
56pub mod traits;
57
58#[cfg(feature = "physics")]
59pub mod physics;
60
61#[cfg(feature = "vision")]
62pub mod vision;
63
64#[cfg(feature = "visualize")]
65pub mod visualize;
66
67#[cfg(feature = "python")]
68mod python;
69
70pub mod prelude;
71
72// Re-export commonly used types at the crate root
73#[allow(deprecated)]
74pub use crate::core::{BlockCirculant, Circulant};
75pub use crate::core::{
76 Circulant1D, Circulant2D, Circulant3D, Circulant4D, CirculantTensor,
77};
78pub use crate::error::{CirculantError, Result};
79pub use crate::fft::{FftBackend, RustFftBackend};
80pub use crate::traits::{BlockOps, CirculantOps, Scalar, TensorOps};