Skip to content

README.md

Latest commit

 

History

History
96 lines (70 loc) · 5.13 KB

README.md

File metadata and controls

96 lines (70 loc) · 5.13 KB
Raw

FFT Debug Tools

Tools for debugging Stockham and other FFT implementations.

Quick Reference

Tool Purpose Command
stockham_reference.js JS reference with stage logging npm run debug:ref -- 16 -v
index_visualizer.js Show read/write patterns npm run debug:index -- 32 verify
wasm_compare.js Compare WASM vs JS vs DFT npm run debug:stockham -- multi
butterfly_tester.js Test butterfly math npm run test:butterfly
permutation_validator.js Validate data flow npm run debug:perm -- 16
accuracy_report.js Numerical error vs f64 reference DFT npm run accuracy
lint-wasm-dead-code.js Find dead code in WASM npm run lint:wasm
generate-dit-codelet.js Generate DIT FFT codelet WAT node tools/generate-dit-codelet.js
generate-irfft-preprocess-codelet.js Generate unrolled IRFFT preprocess WAT (N=64/128) node tools/generate-irfft-preprocess-codelet.js
generate-radix4-32-codelet.js Generate packed dual-16 radix-4 n=32 codelets node tools/generate-radix4-32-codelet.js
fft_r4_split_probe.wat + .harness.mjs Experiment 58 radix-4 split-core probe (correctness + A/B vs pffft SIMD) node tools/fft_r4_split_probe.harness.mjs

Usage

Stage-by-Stage Reference

npm run debug:ref -- 16 -v        # Verbose output showing each stage
npm run debug:ref -- 32           # Quick correctness check

Index Patterns

npm run debug:index -- 16 patterns   # Show read/write indices
npm run debug:index -- 32 verify     # Check stage coordination
npm run debug:index -- 16 trace 0    # Trace input[0] through stages
npm run debug:index -- 16 draw 0     # ASCII diagram of stage 0

WASM Comparison

npm run debug:stockham -- compare 16 impulse   # Single test
npm run debug:stockham -- multi                # Test N=4,8,16,32,64
npm run debug:stockham -- twiddles 32          # Check twiddle factors

Input types: impulse, ramp, alternating, sine, random

Permutation Validation

npm run debug:perm -- 16 validate   # Check all positions written once
npm run debug:perm -- 16 table      # Input->output contribution
npm run debug:perm -- 16 bitrev     # Compare to bit-reversal

Accuracy Report

Measures max-rel and rms-rel error of every module × transform × size (16-4096) against the f64 reference DFT, with seeded inputs. The quality column is max-rel / (eps·√log₂N) — it should stay roughly flat with N, so a jump at one size points at a bad codelet or twiddle path.

npm run accuracy             # per-module error tables
npm run accuracy -- --json   # also write benchmarks/results/accuracy.latest.json

Threshold assertions live in tests/accuracy.test.js (npm run test:accuracy, part of test:all), which calls the same measureAccuracy() function from this tool, so tool and test can never disagree.

WASM Dead Code Linter

Uses Twiggy to detect unreferenced code in WASM binaries.

npm run lint:wasm              # Basic check (warnings for secondary modules)
npm run lint:wasm -- --verbose # Show all modules and dead functions
npm run lint:wasm -- --strict  # Fail on any dead code
npm run lint:wasm -- --fix     # Show fix instructions

Prerequisites: Install Twiggy with cargo install twiggy

Primary modules (fft_real_f32_dual.wasm, fft_combined.wasm) must have zero dead code. Secondary modules show warnings only.

Typical Debug Workflow

  1. Identify failing size: npm run debug:stockham -- multi
  2. Check stage coordination: npm run debug:index -- 32 verify
  3. Trace data flow: npm run debug:ref -- 32 -v
  4. Compare outputs: npm run debug:stockham -- compare 32 impulse
  5. Test butterfly math: npm run test:butterfly

Dead Code Removal Workflow

  1. Run lint: npm run lint:wasm -- --verbose --fix
  2. Find the function: grep -n 'func $function_name' modules/*.wat
  3. Verify not called: grep 'call $function_name' modules/*.wat
  4. Remove and test: Delete the function, npm run build && npm test