NeuralAmpModeler-rs 0.1.0

NeuralAmpModeler-rs is a high-performance, real-time neural inference DSP library written in pure Rust. It provides the core engine for loading, building, and executing Neural Amp Modeler (NAM) models — WaveNet (A1/A2), LSTM, ConvNet, and Linear — as well as impulse response (.wav) cabinet convolution. Designed for embedding in audio hosts, offline renderers, analysis tools, and embedded DSP pipelines, it guarantees zero heap allocations, zero locks, and zero blocking I/O on the real-time audio processing thread.

NeuralAmpModeler-rs is an independent public library for the wider audio and Rust communities. No particular application, audio backend, plugin format, or downstream consumer owns its architecture. Public APIs and policies are expected to remain host-agnostic and generally reusable; integration-specific behavior belongs in downstream crates.

❤️‍🔥 NeuralAmpModeler-rs is in beta stage. Feedbacks, bug reports, suggestions, and testing are very welcome (and needed 😉)!

⚡ Key Strengths

• Pure Rust & Zero-Allocation RT Safety: Engineered from the ground up for absolute real-time determinism: zero heap allocations, zero locks, zero blocking I/O on the hot path. Lock-free SPSC channels handle all control-plane communication.
• Extremely Fast SIMD Inference: Hand-crafted AVX2 (x86-64-v3) baseline vectorization and optional AVX-512 kernels are protected by statistical performance gates and real-time deadline tests.
• Uncompromising Audio Parity: Validated against three independent test oracles (canonical C++ NAMCore f32, double-precision f64 reference oracle, and cross-ISA parity). In the 2026-08-02 quality run, BossWN Standard measured 2.31e-14 ESR against NAMCore and BossLSTM 1x16 measured 8.50e-12; paired f64-oracle ESR was 9.05e-15 and 8.90e-13, respectively.
• Const-Generic Optimization: Static WaveNet and LSTM variants leverage Rust const generics so kernel sizes and channel counts are known at compile time, enabling aggressive LLVM compiler optimization such as SIMD, instruction reordering, and loop unrolling.
• Flexible Host Integration: Exposes a clean, host-agnostic API for model loading, inference, resampling, gating, and cab simulation. Designed to be embedded as an rlib dependency in any Rust audio application.

🧠 Supported Architectures

🚀 Quick Start — Installation & Usage

Add to Your Cargo.toml

[dependencies]
NeuralAmpModeler-rs = "0.1.0"

For off-RT testing utilities and audio signal generators:

[dev-dependencies]
NeuralAmpModeler-rs = { version = "0.1.0", features = ["testing"] }

Feature Flags

Minimal Example

use std::path::Path;
use neural_amp_modeler_rs::loader::{load_and_build_model, LoadOptions};
use neural_amp_modeler_rs::SystemSnapshot;

// Capture system capabilities (SIMD feature set, CPU topology)
let sys = SystemSnapshot::capture();

// Load a .nam or .namb model file
let model_pair = load_and_build_model(
    Path::new("path/to/model.nam"),
    &sys,
    false, // mono
    LoadOptions::default(),
).expect("Failed to load model");

// Process audio in blocks
let mut input = vec![0.0_f32; 64];
let mut output = vec![0.0_f32; 64];
if let Some(ref mut model) = model_pair.model_l {
    model.process(&input, &mut output);
}

Rustdoc Module Map

Full API documentation: cargo doc --open

🏆 Quality & Performance

• Numerical Fidelity: The quality contract tracks NAMCore parity, independent f64-oracle error, SNR, and MR-STFT instead of relying on a single metric.
• Measured CPU Headroom: On the logged AMD Ryzen 7 5700U run, WaveNet Standard CH16 processed a 64-sample block in 37.5 us (2.8% of the 1.33 ms deadline), while LSTM 1x16 used 7.4 us (0.6%).
• Stress Coverage: Soak, concurrency, heap-audit, deadline, and model-checking suites exercise long-running and real-time invariants; skipped coverage and failed audit phases must be reviewed separately from passing checks.
• SIMD Acceleration: AVX2 baseline (x86-64-v3), AVX-512 multiversioning with BF16/VNNI on supported hardware (Intel Sapphire Rapids+, AMD Zen 4+). FastMath activations (tanh, sigmoid) via Padé/minimax polynomial approximations.

📚 Documentation

The following engineering documents are maintained in the source repository. The public Rust API is documented on docs.rs.

• docs/architecture.md — Architecture: engine pipeline, SIMD microarchitecture, mixed precision, NAMB format
• docs/audio_fidelity_map.md — DSP decision quality trade-off map
• docs/fastmath-approximations.md — Activation approximation benchmarks and math details
• docs/namb-spec.md — Binary .namb container spec and CRC32 layout
• docs/testing.md — Test suite layout, execution phases, and verification rules
• docs/perceptual_validation.md — Perceptual measurement framework (ESR, MR-STFT, ASR, LUFS)
• docs/cpp_parity_map.md — Parity audit against NeuralAmpModelerCore
• docs/benchmarks.md — Criterion benchmark methodology and regression gates
• docs/research-references.md — Scientific literature and DSP reference bibliography
• docs/functional-tests.md — Engine functional test checklist
• docs/postmortem-libm-symbol-interposition.md — libm symbol interposition resolution analysis
• docs/quality-contract.txt — Quality contract: benchmark and audio fidelity regression baseline gates
• tests/fixtures/README.md — Golden vector formats and stress signal generation

🧪 Tests & Quality Assurance

Over 1,000 automated unit and integration checks, plus long-running audit phases, are backed by three independent verification oracles:

Automated Test Scripts

These maintainer commands require a source repository checkout; they are not runtime requirements for downstream users.

# Formatting, SPDX checks, and Clippy lints
utils/lints.sh

# Fast test suite (unit, integration, measurement oracles)
utils/tests-quick.sh

# Quality Dashboard (benchmarks & audio fidelity contract check)
utils/quality-dashboard.sh --check docs/quality-contract.txt

# Model diagnostic check (validates .nam file metadata)
python3 utils/check-model.py path/to/model.nam

🤝 Contributing & Feedback

• Test Models: Try your favorite .nam models and IR files — share your experience.
• Report Issues: Submit detailed bug reports or feature suggestions on GitHub.
• Code & Docs: Pull requests for optimizations, bug fixes, or documentation enhancements are welcome.

🙏 Credits & Acknowledgments

• Steven Atkinson — Creator of Neural Amp Modeler (NAM) for pioneering deep learning amplifier modeling and sharing the ecosystem with the community.
• Mike Oliphant — Author of NeuralAudio, whose codebase provided invaluable insight into WaveNet inference in the early stages.

⚖️ License & AI Transparency

AI Transparency Note

The architecture, core engineering decisions, mathematical verification framework, and project orchestration are the intellectual work of the maintainer. The implementation was accelerated through pair programming with Artificial Intelligence (Vibe Coding) using models like Gemini, Claude, and DeepSeek within Google Antigravity IDE and Kilo Code.

License

This project is licensed under the Apache License, Version 2.0. See LICENSE.txt for details.