@emnudge/wat-fft 0.1.0 → 0.4.0

package/README.md

@@ -6,17 +6,18 @@ A high-performance FFT implementation in WebAssembly Text format that **signific
 
 ### Complex FFT
 
-Benchmarked against [fft.js](https://github.com/indutny/fft.js) (fastest pure-JS FFT):
-
-| Size   | wat-fft (f64)       | fft.js          | Speedup  |
-| ------ | ------------------- | --------------- | -------- |
-| N=64   | **3,830,000 ops/s** | 2,794,000 ops/s | **1.4x** |
-| N=128  | **1,586,000 ops/s** | 1,105,000 ops/s | **1.4x** |
-| N=256  | **973,000 ops/s**   | 559,000 ops/s   | **1.7x** |
-| N=512  | **344,000 ops/s**   | 223,000 ops/s   | **1.5x** |
-| N=1024 | **191,000 ops/s**   | 113,000 ops/s   | **1.7x** |
-| N=2048 | **74,500 ops/s**    | 47,200 ops/s    | **1.6x** |
-| N=4096 | **44,400 ops/s**    | 23,400 ops/s    | **1.9x** |
+Benchmarked against [pffft-wasm](https://www.npmjs.com/package/@echogarden/pffft-wasm) (PFFFT with SIMD):
+
+| Size   | wat-fft (f32)        | pffft-wasm (f32) | Speedup  |
+| ------ | -------------------- | ---------------- | -------- |
+| N=16   | **16,700,000 ops/s** | 13,900,000 ops/s | **+20%** |
+| N=64   | **6,040,000 ops/s**  | 4,440,000 ops/s  | **+36%** |
+| N=128  | **3,040,000 ops/s**  | 1,950,000 ops/s  | **+56%** |
+| N=256  | **1,640,000 ops/s**  | 980,000 ops/s    | **+67%** |
+| N=512  | **736,000 ops/s**    | 404,000 ops/s    | **+82%** |
+| N=1024 | **365,000 ops/s**    | 201,000 ops/s    | **+81%** |
+| N=2048 | **163,000 ops/s**    | 84,000 ops/s     | **+94%** |
+| N=4096 | **81,000 ops/s**     | 41,000 ops/s     | **+95%** |
 
 ```mermaid
 ---
@@ -26,35 +27,36 @@ config:
         height: 400
     themeVariables:
         xyChart:
-            plotColorPalette: "#4ade80, #60a5fa, #a855f7, #f87171"
+            plotColorPalette: "#4ade80, #60a5fa, #f59e0b, #a855f7, #f87171"
 ---
 xychart-beta
     title "Complex FFT Performance (Million ops/s)"
-    x-axis [N=64, N=128, N=256, N=512, N=1024, N=2048, N=4096]
-    y-axis "Million ops/s" 0 --> 5
-    line [3.83, 1.59, 0.97, 0.34, 0.19, 0.074, 0.044]
-    line [4.60, 2.40, 1.17, 0.54, 0.27, 0.124, 0.062]
-    line [2.79, 1.11, 0.56, 0.22, 0.11, 0.047, 0.023]
-    line [1.90, 0.80, 0.45, 0.18, 0.10, 0.041, 0.022]
+    x-axis [N=16, N=64, N=128, N=256, N=512, N=1024, N=2048, N=4096]
+    y-axis "Million ops/s" 0 --> 18
+    line [17.57, 3.83, 1.74, 0.96, 0.37, 0.19, 0.080, 0.044]
+    line [16.68, 6.04, 3.04, 1.64, 0.74, 0.36, 0.163, 0.081]
+    line [13.88, 4.44, 1.95, 0.98, 0.40, 0.20, 0.084, 0.041]
+    line [11.50, 2.80, 1.07, 0.56, 0.22, 0.11, 0.047, 0.023]
+    line [6.05, 1.86, 0.80, 0.44, 0.18, 0.10, 0.041, 0.022]
 ```
 
-> 🟢 **wat-fft f64** · 🔵 **wat-fft f32** · 🟣 **fft.js** · 🔴 **kissfft-js**
+> 🟢 **wat-fft f64** · 🔵 **wat-fft f32** · 🟠 **pffft-wasm** · 🟣 **fft.js** · 🔴 **kissfft-js**
 
-**Choose f64** (`fft_combined.wasm`) for double precision - **1.4-1.9x faster** than fft.js at all sizes. **Choose f32** (`fft_stockham_f32_dual.wasm`) for maximum speed with single precision - up to **2.6x faster** than fft.js.
+**wat-fft f32 beats pffft-wasm by 20-95%** across all sizes. It's also **2-3x faster** than fft.js (the fastest pure JS). **Choose f64** (`fft_combined.wasm`) for double precision. **Choose f32** (`fft_stockham_f32_dual.wasm`) for maximum single-precision speed.
 
 ### Real FFT
 
-Benchmarked against [fftw-js](https://www.npmjs.com/package/fftw-js) (Emscripten port of FFTW):
+Benchmarked against [pffft-wasm](https://www.npmjs.com/package/@echogarden/pffft-wasm) and [fftw-js](https://www.npmjs.com/package/fftw-js):
 
-| Size   | wat-fft (f32)       | fftw-js (f32)   | Comparison |
-| ------ | ------------------- | --------------- | ---------- |
-| N=64   | **6,700,000 ops/s** | 6,620,000 ops/s | **+1%**    |
-| N=128  | **4,290,000 ops/s** | 4,100,000 ops/s | **+5%**    |
-| N=256  | **2,170,000 ops/s** | 1,430,000 ops/s | **+51%**   |
-| N=512  | **1,130,000 ops/s** | 870,000 ops/s   | **+31%**   |
-| N=1024 | **525,000 ops/s**   | 444,000 ops/s   | **+18%**   |
-| N=2048 | **264,000 ops/s**   | 225,000 ops/s   | **+18%**   |
-| N=4096 | **116,000 ops/s**   | 105,000 ops/s   | **+11%**   |
+| Size   | wat-fft (f32)       | pffft-wasm (f32)    | fftw-js (f32)   | vs best     |
+| ------ | ------------------- | ------------------- | --------------- | ----------- |
+| N=64   | 6,640,000 ops/s     | **6,970,000 ops/s** | 6,660,000 ops/s | -5% (pffft) |
+| N=128  | **4,510,000 ops/s** | 3,490,000 ops/s     | 4,290,000 ops/s | **+5%**     |
+| N=256  | **2,280,000 ops/s** | 1,920,000 ops/s     | 1,440,000 ops/s | **+19%**    |
+| N=512  | **1,110,000 ops/s** | 830,000 ops/s       | 850,000 ops/s   | **+31%**    |
+| N=1024 | **531,000 ops/s**   | 419,000 ops/s       | 458,000 ops/s   | **+16%**    |
+| N=2048 | **274,000 ops/s**   | 179,000 ops/s       | 222,000 ops/s   | **+23%**    |
+| N=4096 | **126,000 ops/s**   | 89,000 ops/s        | 106,000 ops/s   | **+19%**    |
 
 ```mermaid
 ---
@@ -64,21 +66,22 @@ config:
         height: 400
     themeVariables:
         xyChart:
-            plotColorPalette: "#4ade80, #60a5fa, #f87171, #a855f7"
+            plotColorPalette: "#4ade80, #60a5fa, #f87171, #f59e0b, #a855f7"
 ---
 xychart-beta
     title "Real FFT Performance (Million ops/s)"
     x-axis [N=64, N=128, N=256, N=512, N=1024, N=2048, N=4096]
     y-axis "Million ops/s" 0 --> 8
-    line [4.80, 2.99, 1.28, 0.76, 0.27, 0.16, 0.062]
-    line [6.70, 4.29, 2.17, 1.13, 0.525, 0.264, 0.116]
-    line [6.62, 4.10, 1.43, 0.87, 0.444, 0.225, 0.105]
-    line [2.93, 1.74, 0.75, 0.42, 0.17, 0.094, 0.039]
+    line [4.70, 2.95, 1.28, 0.76, 0.29, 0.16, 0.063]
+    line [6.64, 4.51, 2.28, 1.11, 0.53, 0.27, 0.126]
+    line [6.66, 4.29, 1.44, 0.85, 0.46, 0.22, 0.106]
+    line [6.97, 3.49, 1.92, 0.83, 0.42, 0.18, 0.089]
+    line [2.93, 1.79, 0.76, 0.42, 0.17, 0.094, 0.039]
 ```
 
-> 🟢 **wat-fft f64** · 🔵 **wat-fft f32** · 🔴 **fftw-js** · 🟣 **kissfft-js**
+> 🟢 **wat-fft f64** · 🔵 **wat-fft f32** · 🔴 **fftw-js** · 🟠 **pffft-wasm** · 🟣 **kissfft-js**
 
-**wat-fft f32 beats fftw-js at all sizes** (+1% to +51%). **Choose f64** (`fft_real_combined.wasm`) for double precision. **Choose f32** (`fft_real_f32_dual.wasm`) for maximum single-precision speed.
+**wat-fft f32 beats all competitors at N≥128** (+5% to +31%). At N=64, pffft-wasm has a slight edge. **Choose f64** (`fft_real_combined.wasm`) for double precision. **Choose f32** (`fft_real_f32_dual.wasm`) for maximum single-precision speed.
 
 ## Quick Start
 
@@ -110,9 +113,9 @@ cargo install wasm-tools
 ```javascript
 import fs from "fs";
 
-// Load the WASM module (Stockham is recommended for best performance)
+// Load the WASM module
 // No JavaScript imports needed - trig functions are computed inline
-const wasmBuffer = fs.readFileSync("dist/combined_stockham.wasm");
+const wasmBuffer = fs.readFileSync("dist/fft_combined.wasm");
 const wasmModule = await WebAssembly.compile(wasmBuffer);
 const instance = await WebAssembly.instantiate(wasmModule);
 const fft = instance.exports;
@@ -127,22 +130,29 @@ for (let i = 0; i < N; i++) {
 
 // Compute FFT
 fft.precompute_twiddles(N);
-fft.fft_stockham(N);
+fft.fft(N);
 
 // Results are in-place in data[]
 console.log("DC component:", data[0], data[1]);
+
+// Compute inverse FFT (roundtrip back to original)
+fft.ifft(N);
+console.log("Recovered signal:", data[0], data[1]);
 ```
 
 ## Implementations
 
 **Recommended modules:**
 
-| Module                       | Use Case               | Precision |
-| ---------------------------- | ---------------------- | --------- |
-| `fft_combined.wasm`          | Complex FFT (any size) | f64       |
-| `fft_real_combined.wasm`     | Real FFT (any size)    | f64       |
-| `fft_stockham_f32_dual.wasm` | Complex FFT (fastest)  | f32       |
-| `fft_real_f32_dual.wasm`     | Real FFT (fastest)     | f32       |
+| Module                       | Use Case                   | Precision | Inverse      |
+| ---------------------------- | -------------------------- | --------- | ------------ |
+| `fft_combined.wasm`          | Complex FFT (any size)     | f64       | `ifft`       |
+| `fft_real_combined.wasm`     | Real FFT (any size)        | f64       | -            |
+| `fft_stockham_f32_dual.wasm` | Complex FFT (interleaved)  | f32       | `ifft`       |
+| `fft_split_native_f32.wasm`  | Complex FFT (split format) | f32       | `ifft_split` |
+| `fft_real_f32_dual.wasm`     | Real FFT (fastest)         | f32       | `irfft`      |
+
+**Split-format** (`fft_split_native_f32.wasm`) stores real and imaginary parts in separate arrays, enabling 4 complex numbers per SIMD operation. Performance is similar to interleaved format - use when your data is already in split format to avoid conversion overhead.
 
 See [docs/IMPLEMENTATIONS.md](docs/IMPLEMENTATIONS.md) for detailed documentation of all modules, usage examples, and numerical accuracy information.
 
@@ -166,7 +176,6 @@ npm run bench:rfft    # Run real FFT benchmarks
 npm run bench:rfft32  # Run f32 real FFT benchmarks
 npm run test:fft      # Run comprehensive FFT tests
 npm run test:rfft     # Run real FFT tests
-npm run test:permutation  # Test permutation algorithms
 ```
 
 ## Development Tools
@@ -207,11 +216,11 @@ The comprehensive FFT test suite (`tests/fft.test.js`) tests all implementations
 npm run test:fft
 ```
 
-### Test a single implementation (useful for debugging)
+### Test a specific size and pattern
 
 ```bash
-node tests/fft.test.js --impl stockham 64 random
-node tests/fft.test.js --impl fast 256 impulse
+node tests/fft.test.js 64 random
+node tests/fft.test.js 256 impulse
 ```
 
 ### Input patterns
@@ -223,7 +232,7 @@ node tests/fft.test.js --impl fast 256 impulse
 
 ### Test sizes
 
-Powers of 2: 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096
+Powers of 2: 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192
 
 ## License
 

package/package.json

@@ -1,48 +1,50 @@
 {
   "name": "@emnudge/wat-fft",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "High-performance FFT in WebAssembly",
-  "license": "ISC",
-  "author": "EmNudge",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/emnudge/wat-fft"
-  },
   "keywords": [
+    "audio",
+    "dsp",
     "fft",
-    "rfft",
     "fourier",
+    "rfft",
+    "signal-processing",
     "transform",
     "wasm",
-    "webassembly",
-    "dsp",
-    "signal-processing",
-    "audio"
+    "webassembly"
   ],
-  "type": "module",
-  "exports": {
-    ".": {
-      "import": "./index.js"
-    }
+  "license": "ISC",
+  "author": "EmNudge",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EmNudge/wat-fft.git"
   },
   "files": [
     "index.js",
     "dist/*.wasm"
   ],
-  "engines": {
-    "node": ">=18"
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./index.js"
+    }
   },
   "scripts": {
-    "test": "npm run test:swap && npm run test:reverse_bits && npm run test:fft",
-    "test:all": "npm run test && npm run test:rfft && npm run test:property && npm run test:boundary && npm run test:correctness && npm run test:output-order",
+    "test": "npm run test:fft && npm run test:combined && npm run test:ifft",
+    "test:all": "npm run test && npm run test:rfft && npm run test:boundary && npm run test:correctness && npm run test:output-order && npm run test:f32 && npm run test:twiddles && npm run test:golden && npm run test:perbin && npm run test:split && npm run test:thirdparty && npm run test:bench-correctness",
+    "test:split": "node --test tests/fft_split_native.test.js",
+    "test:thirdparty": "node --test tests/third-party-correctness.test.js",
+    "test:bench-correctness": "node --test tests/benchmark-correctness.test.js",
+    "test:ifft": "node tests/ifft.test.js",
+    "test:twiddles": "node tests/twiddle_validation.test.js",
+    "test:property": "node --test tests/property_based.test.js",
+    "test:golden": "node --test tests/golden_reference.test.js",
+    "test:perbin": "node --test tests/per_bin_validation.test.js",
     "test:output-order": "node --test tests/output-order.test.js",
-    "test:swap": "node tests/swap.test.js",
-    "test:reverse_bits": "node tests/reverse_bits.test.js",
-    "test:permutation": "node tests/permutation.test.js",
     "test:fft": "node tests/fft.test.js",
+    "test:combined": "node tests/combined.test.js",
     "test:rfft": "node --test tests/rfft.test.js",
     "test:f32": "node tests/fft_f32_dual.test.js",
-    "test:property": "node tests/fft.property.test.js",
     "test:boundary": "node --test tests/boundary.test.js",
     "test:butterfly": "node tools/butterfly_tester.js",
     "test:correctness": "node --test tests/correctness/*.test.js",
@@ -52,20 +54,28 @@
     "test:correctness:shift": "node --test tests/correctness/fft.shift.test.js",
     "test:correctness:reference": "node --test tests/correctness/fft.reference.test.js",
     "test:correctness:known": "node --test tests/correctness/fft.known-values.test.js",
-    "debug:stockham": "node tools/wasm_compare.js",
+    "debug:compare": "node tools/wasm_compare.js",
     "debug:index": "node tools/index_visualizer.js",
     "debug:perm": "node tools/permutation_validator.js",
     "debug:ref": "node tools/stockham_reference.js",
+    "debug:split": "node tests/debug_split.js",
     "build": "node build.js",
     "bench": "node benchmarks/fft.bench.js",
     "bench:rfft": "node benchmarks/rfft.bench.js",
     "bench:f32": "node benchmarks/fft_f32_dual.bench.js",
     "bench:rfft32": "node benchmarks/rfft_f32_dual.bench.js",
+    "bench:browser": "vitest bench --run",
+    "bench:browser:ci": "vitest bench --run --outputJson=benchmark-results.json",
+    "bench:check": "node scripts/check-benchmarks.js",
     "lint": "oxlint .",
+    "lint:all": "npm run lint && npm run lint:wasm",
+    "lint:wasm": "node tools/lint-wasm-dead-code.js",
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check ."
   },
   "devDependencies": {
+    "@echogarden/pffft-wasm": "^0.4.2",
+    "@vitest/browser": "^3.0.0",
     "fast-check": "^4.5.3",
     "fft-js": "^0.0.12",
     "fft.js": "^4.0.4",
@@ -73,6 +83,13 @@
     "kissfft-js": "^0.1.8",
     "kissfft-wasm": "^2.0.1",
     "oxfmt": "^0.26.0",
-    "oxlint": "^1.41.0"
+    "oxlint": "^1.41.0",
+    "playwright": "^1.50.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "webfft": "^1.0.3"
+  },
+  "engines": {
+    "node": ">=18"
   }
 }