Updating documentation

Author: michaelciraci

Cargo.toml

@@ -1,13 +1,15 @@
 [package]
 name = "monarch-butterfly"
-version = "0.3.0"
+version = "0.3.1"
 edition = "2021"
 description = "Proc-Macro unrolled FFTs"
 license = "MIT"
 documentation = "https://docs.rs/monarch-butterfly"
 homepage = "https://github.com/michaelciraci/Monarch-Butterfly"
 repository = "https://github.com/michaelciraci/Monarch-Butterfly"
 rust-version = "1.63"
+keywords = ["fft", "dft", "discrete", "fourier", "transform"]
+categories = ["algorithms", "science"]
 
 [dependencies]
 monarch-derive = "=0.3.0"

README.md

@@ -5,7 +5,10 @@
 
 # Monarch Butterfly
 
-Experimental FFT library where all FFTs are proc-macro generated const-evaluation functions. The use case is if you know the FFT size at compile time. However, knowing the FFT size at compile time gives immense gains.
+Experimental FFT library where all FFTs are proc-macro generated const-evaluation functions. 
+The one requirement is you must know the size of the FFT at compile-time. Knowing the FFT size at
+compile time gives immense gains, as the compiler is able unroll the call stack and optimize for
+SIMD throughput through function calls.
 
 This library implements FFTs for both `f32` and `f64` sizes `1-200`. The FFTs are auto-generated so this limit could be increased above 200 at the expense of compile time.
 
@@ -21,8 +24,16 @@ This library implements FFTs for both `f32` and `f64` sizes `1-200`. The FFTs ar
 - FFT size must be known at compile time
 - By default, only FFTs up to size 200 are generated
 
+## Comparison
+
+RustFFT and FFTW FFT sizes can be decided at runtime, so comparing against a library whose FFT sizes need to be known at compile time is comparing apples and oranges. With that in mind, knowing the FFT size at compile time does give immense gains.
+
 ![log](assets/log_comparison.png)
 
+## Usage
+
+The top level functions are `fft` and `ifft`.
+
 ```
 use monarch_butterfly::*;
 use num_complex::Complex;
@@ -31,8 +42,7 @@ let input: Vec<_> = (0..8).map(|i| Complex::new(i as f32, 0.0)).collect();
 let output = fft::<8, _, _>(input);
 ```
 
-This library will use all SIMD features your CPU has available including AVX512,
-assuming you compile with those features (`RUSTFLAGS="-C target-cpu=native" cargo build`).
+This library will use all SIMD features your CPU has, assuming `rustc` can compile to those SIMD features.
 
 The larger the FFT sizes, the larger speed boost this library will give you.
 

src/lib.rs

@@ -5,9 +5,13 @@
 //!
 //! # Monarch Butterfly
 //!
-//! Experimental FFT library where all FFTs are proc-macro generated const-evaluation functions. //! The use case is if you know the FFT size at compile time. However, knowing the FFT size at //! compile time gives immense gains.
+//! Experimental FFT library where all FFTs are proc-macro generated const-evaluation functions. 
+//! The one requirement is you must know the size of the FFT at compile-time. Knowing the FFT size at
+//! compile time gives immense gains, as the compiler is able unroll the call stack and optimize for
+//! SIMD throughput through function calls.
 //!
-//! This library implements FFTs for both `f32` and `f64` sizes `1-200`. The FFTs are //! auto-generated so this limit could be increased above 200 at the expense of compile time.
+//! This library implements FFTs for both `f32` and `f64` sizes `1-200`. The FFTs are 
+//! auto-generated so this limit could be increased above 200 at the expense of compile time.
 //!
 //! ## Features
 //!
@@ -21,17 +25,17 @@
 //! - FFT size must be known at compile time
 //! - By default, only FFTs up to size 200 are generated
 //!
-//!
+//! ## Usage
+//! 
+//! The top level functions are [`fft`] and [`ifft`].
+//! 
 //! ```
 //! use monarch_butterfly::*;
 //! use num_complex::Complex;
 //!
 //! let input: Vec<_> = (0..8).map(|i| Complex::new(i as f32, 0.0)).collect();
 //! let output = fft::<8, _, _>(input);
 //! ```
-//!
-//! The top level functions are [`fft`] and [`ifft`].
-//!
 //! This library will use all SIMD features your CPU has available including AVX512,
 //! assuming you compile with those features (`RUSTFLAGS="-C target-cpu=native" cargo build`).
 //!
@@ -40,7 +44,7 @@
 //! As an example of AVX512 instructions, here is an example on just an FFT
 //! of size 128: <https://godbolt.org/z/Y58eh1x5a>(`Ctrl+F` for "zmm" instructions)
 //!
-//! The FFTs before unrolling are heavily inspired from [`RustFFT``](<https://github.com/ejmahler/RustFFT>).
+//! The FFTs before unrolling are heavily inspired from [`RustFFT`](<https://github.com/ejmahler/RustFFT>).
 //! Credit is given to Elliott Mahler as the RustFFT original author.
 
 #![allow(clippy::excessive_precision)]