NeuralAmpModeler-rs 0.1.0

// SPDX-License-Identifier: Apache-2.0
// Copyright (c) 2026 Fábio Henrique de Lima Silva (fhl.bsb@gmail.com) All rights reserved.
#![warn(missing_docs)]

//! # Neural Amp Modeler (NAM-rs) — DSP Core Library
//!
//! **NeuralAmpModeler-rs** is the pure DSP kernel for high-performance,
//! real-time inference of [Neural Amp Modeler (NAM)](https://www.neuralampmodeler.com/)
//! neural network models (WaveNet A1 and A2, LSTM, ConvNet, Linear) and
//! impulse response (.wav) convolutions.
//!
//! This is an independent public library for the wider audio and Rust
//! communities. Its APIs and policies are host-agnostic: no particular
//! application, audio backend, plugin format, or downstream consumer owns
//! its architecture. Integration-specific behavior belongs in downstream
//! crates.
//!
//! The library provides:
//! - **SIMD-Accelerated Inference Kernels**: Native `x86-64-v3` (AVX2 + FMA)
//!   and `AVX-512` math routines.
//! - **Flexible Model Loader**: Parser and builder for `.nam` (JSON) and
//!   `.namb` (binary profile) files.
//! - **Lock-Free DSP Engine**: Zero heap allocations on the audio
//!   processing hot-path.
//!
//! ---
//!
//! ## 🛠 Feature Flags & Recommended Dependency Setup
//!
//! > ⚠️ **Important for Library Integrators:**
//! > By default no feature flags are enabled. Enable only what you need.
//!
//! ### `Cargo.toml` Configuration Examples
//!
//! **Pure Core DSP & Model Inference:**
//! ```toml
//! [dependencies]
//! NeuralAmpModeler-rs = "0.1.0"
//! ```
//!
//! **Adding Off-RT Testing & Audio Signal Generators:**
//! ```toml
//! [dependencies]
//! NeuralAmpModeler-rs = { version = "0.1.0", features = ["testing"] }
//! ```
//!
//! ### Feature Flags Summary Table
//!
//! | Feature Flag | Default | Description                                                        |
//! |:------------ |:-------:|:------------------------------------------------------------------ |
//! | `stereo`     | No      | Enables multi-channel / stereo dual-model loader support.          |
//! | `testing`    | No      | Exposes off-RT test utilities, audio signal generators, and        |
//! |              |         | perceptual metrics (`testing` module).                             |
//! | `heap-audit` | No      | Enables heap-allocation auditing infrastructure.                   |
//! | `long_bench` | No      | Enables long-form inference benchmarks.                            |
//! | `pgo`        | No      | Build with PGO (Profile-Guided Optimization) support.              |
//!
//! ---
//!
//! ## 🚀 Quick Start — Loading & Building a Model
//!
//! The [`loader::load_and_build_model`] function reads `.nam` (JSON) or
//! `.namb` (binary) files and constructs optimized [`models::StaticModel`]
//! instances ready for real-time execution.
//!
//! ```no_run
//! 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 model file (.nam or .namb)
//! let model_pair = load_and_build_model(
//!     Path::new("path/to/model.nam"),
//!     &sys,
//!     false, // mono execution (set true for stereo)
//!     LoadOptions::default(),
//! )
//! .expect("Failed to load model");
//!
//! println!("Loaded {} model", model_pair.architecture);
//! assert!(model_pair.model_l.is_some());
//! assert!(model_pair.model_r.is_none()); // Mono load: right channel is None
//! assert!(model_pair.sample_rate > 0);
//! ```
//!
//! ---
//!
//! ## ⚡ FastMath & SIMD Vector Activations
//!
//! High-performance scalar activation functions are available directly in
//! [`math::activations`]:
//!
//! ```rust
//! use neural_amp_modeler_rs::math::activations::{tanh, sigmoid};
//!
//! // Padé [5,4] rational approximant, clamped to [-1.0, 1.0]
//! let t = tanh(1.0);
//! assert!((t - 0.761594).abs() < 1e-3);
//! assert!(tanh(10.0) <= 1.0);
//! assert!(tanh(-10.0) >= -1.0);
//!
//! // Degree-17 minimax polynomial, clamped to [0.0, 1.0]
//! let s = sigmoid(0.0);
//! assert!((s - 0.5).abs() < 1e-2);
//! assert!(sigmoid(10.0) > 0.999);
//! assert!(sigmoid(-10.0) < 0.001);
//! ```
//!
//! For slice-based processing that automatically selects vectorized SIMD
//! kernels (AVX2/AVX-512), use `tanh_slice` and `sigmoid_slice` from
//! [`math::activations`].
//!
//! ---
//!
//! ## 🗺 Crate Module Map
//!
//! | Module     | Purpose                                            | Key Entry Points & Types                               |
//! |:---------- |:-------------------------------------------------- |:------------------------------------------------------ |
//! | [`loader`] | Model deserialization & construction (`.nam`,      | [`loader::load_and_build_model`],                      |
//! |            | `.namb`)                                           | [`loader::LoadOptions`]                                |
//! | [`math`]   | Mathematical primitives, SIMD kernels, &           | [`math::activations`]                                  |
//! |            | activations                                        |                                                        |
//! | [`models`] | Neural network architectures & static topologies   | [`models::StaticModel`], WaveNet, LSTM, ConvNet        |
//! | [`dsp`]    | Digital signal processing engine & oversampling    | [`dsp::gate::GateParams`],                             |
//! |            |                                                    | [`dsp::oversample::OversampleEngine`]                  |
//! | [`common`] | Diagnostics, atomic bitmasks, & SPSC queues        | [`common::RtStatusFlags`],                             |
//! |            |                                                    | [`common::alloc_audit`]                                |
//! | `testing`  | Off-RT test utilities & perceptual metrics         | Audio validation and f64 Oracles                       |
//! |            | (requires `testing`)                               |                                                        |
//!
//! ---
//!
//! ## 🛡 Real-Time Safety & Performance Guarantees
//!
//! NeuralAmpModeler-rs is engineered for **absolute real-time safety** on
//! the audio processing thread (`SCHED_FIFO`). The following guarantees
//! are enforced at the architecture level:
//!
//! ### 1. Zero Heap Allocations on Hot-Path
//! Heap objects (`Box`, `Vec`, `Arc`, `String`) are **never** allocated or
//! dropped on the real-time audio thread. All dynamic resources are
//! allocated off-RT and swapped via lock-free SPSC channels
//! ([`common::spsc`]). Compile-time allocation auditing is available via
//! [`common::alloc_audit`].
//!
//! ### 2. Zero Blocking I/O
//! No `println!`, `eprintln!`, `format!`, file I/O, or blocking
//! synchronization primitives are permitted on the RT thread. State
//! transitions are signaled atomically via [`common::RtStatusFlags`].
//!
//! ### 3. Denormal Protection (FTZ + DAZ)
//! Subnormal (denormal) floating-point numbers cause severe performance
//! degradation (up to 100× slowdown). NeuralAmpModeler-rs configures
//! **Flush-To-Zero (FTZ)** and **Denormals-Are-Zero (DAZ)** at
//! initialization and periodically reasserts them on the hot path
//! ([`math::common::set_daz_ftz`]).
//!
//! ### 4. Panic-Free Hot Path
//! Stack unwinding (panics) breaks hard real-time determinism. Processing
//! hot paths avoid `unwrap()`/`expect()` in favor of explicit fallback
//! bounds checks.
//!
//! ### 5. Lock-Free Cache-Isolated Concurrency
//! Shared structures RT ↔ Main use `#[repr(align(128))]` to eliminate
//! false sharing on CPU cache lines. Inter-thread SPSC buffers use
//! `Acquire`/`Release` atomic ordering.
//!
//! ---
//!
//! ## 📜 License
//!
//! Licensed under the **Apache License, Version 2.0**.
//! Official repository: <https://github.com/fabiohl/NeuralAmpModeler-rs>

#[cfg(not(target_arch = "x86_64"))]
compile_error!("NeuralAmpModeler-rs requires x86_64 architecture");

#[cfg(not(any(doc, all(target_feature = "avx2", target_feature = "fma"))))]
compile_error!(
    "NeuralAmpModeler-rs requires x86-64-v3 (AVX2 + FMA). \
     Compile with RUSTFLAGS=\"-Ctarget-cpu=x86-64-v3\""
);

pub mod common;
pub use common::*;

pub mod dsp;
pub mod loader;
pub mod math;
pub mod models;

#[cfg(any(test, feature = "testing"))]
pub mod testing;

// Backward compatibility with older GLIBC versions (e.g. for Flatpak/Bitwig).
// Redirects math symbols to the stable GLIBC_2.2.5 version.
// Since external dependencies use these symbols, we declare global wrappers
// that intercept calls and jump (jmp) via PLT to the compatible versions.
#[cfg(all(target_os = "linux", target_env = "gnu"))]
core::arch::global_asm!(
    ".global log10f",
    ".hidden log10f",
    ".type log10f, @function",
    "log10f:",
    "    jmp log10f_compat@PLT",
    ".symver log10f_compat, log10f@GLIBC_2.2.5",
    ".global atan2f",
    ".hidden atan2f",
    ".type atan2f, @function",
    "atan2f:",
    "    jmp atan2f_compat@PLT",
    ".symver atan2f_compat, atan2f@GLIBC_2.2.5",
    ".global acosf",
    ".hidden acosf",
    ".type acosf, @function",
    "acosf:",
    "    jmp acosf_compat@PLT",
    ".symver acosf_compat, acosf@GLIBC_2.2.5",
    ".global cbrt",
    ".hidden cbrt",
    ".global cbrtf",
    ".hidden cbrtf",
    ".global fma",
    ".hidden fma",
    ".global fmod",
    ".hidden fmod"
);