Crate circulant_rs 

High-performance block-circulant matrix operations using FFT.

This library exploits the fact that circulant matrices can be diagonalized by the DFT matrix, enabling O(N log N) matrix-vector multiplication instead of the naive O(N²) approach.

Overview

A circulant matrix is a special type of Toeplitz matrix where each row is a cyclic shift of the previous row. This structure allows for efficient computation using the Fast Fourier Transform (FFT).

Features

• std (default): Enable standard library features
• physics (default): Enable quantum physics module (quantum walks, coins, Hamiltonians)
• parallel (default): Enable parallel computation with rayon
• serde (default): Enable serialization with serde/bincode
• vision: Enable image processing with BCCB filters
• visualize: Enable visualization with plotters (base feature)
• visualize-svg: Enable SVG output for visualization
• visualize-bitmap: Enable bitmap output for visualization
• python: Enable Python bindings via PyO3

Example

use circulant_rs::prelude::*;
use num_complex::Complex;

// Create a circulant matrix from a real generator
let c = Circulant::from_real(vec![1.0, 2.0, 3.0, 4.0]).unwrap();

// Multiply by a vector using FFT (O(N log N))
let x: Vec<Complex<f64>> = vec![
    Complex::new(1.0, 0.0),
    Complex::new(0.0, 0.0),
    Complex::new(1.0, 0.0),
    Complex::new(0.0, 0.0),
];
let result = c.mul_vec(&x).unwrap();

Re-exports

pub use crate::core::BlockCirculant;Deprecated

pub use crate::core::Circulant;Deprecated

pub use crate::core::Circulant1D;

pub use crate::core::Circulant2D;

pub use crate::core::Circulant3D;

pub use crate::core::Circulant4D;

pub use crate::core::CirculantTensor;

pub use crate::error::CirculantError;

pub use crate::error::Result;

pub use crate::fft::FftBackend;

pub use crate::fft::RustFftBackend;

pub use crate::traits::BlockOps;

pub use crate::traits::CirculantOps;

pub use crate::traits::Scalar;

pub use crate::traits::TensorOps;

Modules

core

Core circulant matrix and tensor types.

error

Error types for circulant-rs operations.

fft

FFT backend implementations.

physics

Quantum physics module for quantum walks and simulations.

prelude

Convenient re-exports for common usage.

traits

Trait definitions for circulant-rs.

vision

Image processing with block-circulant matrices.

visualize

Visualization utilities for quantum states and matrices.