05_15_01 Kernel References¶

L0 Reference Implementations - Atomic DSP Building Blocks¶

Version: 1.0.0 Status: 🟡 In Development Certification Level Target: Gold 🥇

📋 Overview¶

This module contains certified reference implementations of L0 kernels - the atomic building blocks of AudioLab's DSP hierarchy. Each kernel is:

✅ Mathematically correct - Validated against known references
✅ Highly optimized - CPU-efficient, SIMD-ready
✅ Thoroughly tested - >95% code coverage
✅ Fully documented - API docs + implementation notes
✅ Gold certified - Passes all framework validation stages

What are L0 Kernels?¶

Kernels are the smallest, indivisible DSP operations. They are:

Stateless or have minimal state (a few variables)
Fast - typically <20 CPU cycles per sample
Composable - Combined to build L1 atoms
Pure functions - deterministic, no side effects
Single responsibility - Do one thing perfectly

🎯 Kernel Catalog¶

Oscillators (6 kernels)¶

Kernel	Status	Cert Level	Description
`sine_kernel`	✅ Complete	Gold 🥇	Sine wave generator (wavetable)
`phase_kernel`	✅ Complete	-	Phase accumulator (phasor)
`saw_kernel`	✅ Complete	-	Sawtooth wave (PolyBLEP bandlimited)
`square_kernel`	✅ Complete	-	Square wave (PolyBLEP) with PWM
`triangle_kernel`	✅ Complete	-	Triangle wave (naturally bandlimited)
`noise_kernel`	✅ Complete	-	White noise (Xorshift32 PRNG)

Filters (8 kernels)¶

Kernel	Status	Cert Level	Description
`onepole_kernel`	✅ Complete	-	One-pole filter (LP/HP modes, -6dB/oct)
`biquad_kernel`	✅ Complete	-	Biquad filter (8 types: LP/HP/BP/Notch/APF/Peak/Shelf)
`svf_kernel`	✅ Complete	-	State Variable Filter (Chamberlin, 4 simultaneous outputs)
`allpass_kernel`	🔴 Planned	-	Allpass filter
`comb_kernel`	🔴 Planned	-	Comb filter (feedback/feedforward)
`delay_kernel`	🔴 Planned	-	Fractional delay line
`interpolation_kernel`	🔴 Planned	-	Linear/cubic interpolation

Distortion (5 kernels)¶

Kernel	Status	Cert Level	Description
`tanh_kernel`	✅ Complete	-	Hyperbolic tangent saturation
`hardclip_kernel`	✅ Complete	-	Hard clipping (brick-wall limiting)
`softclip_kernel`	✅ Complete	-	Soft clipping (polynomial, smoothstep)
`foldback_kernel`	🔴 Planned	-	Foldback distortion
`bitcrush_kernel`	🔴 Planned	-	Bit depth reduction

Dynamics (4 kernels)¶

Kernel	Status	Cert Level	Description
`envelope_detector_kernel`	🔴 Planned	-	RMS/peak envelope detection
`gain_computer_kernel`	🔴 Planned	-	Compressor gain calculation
`gate_kernel`	🔴 Planned	-	Noise gate logic
`limiter_kernel`	🔴 Planned	-	Brick-wall limiter

Utilities (5 kernels)¶

Kernel	Status	Cert Level	Description
`gain_kernel`	✅ Complete	-	Simple gain/attenuation
`mix_kernel`	🔴 Planned	-	Signal mixing/crossfading
`pan_kernel`	🔴 Planned	-	Equal-power panning
`dc_blocker_kernel`	🔴 Planned	-	DC offset removal
`denormal_killer_kernel`	🔴 Planned	-	Denormal prevention

Total Planned: 28 kernels

📁 Directory Structure¶

05_15_01_kernel_references/
├── README.md                          # This file
├── CMakeLists.txt                     # Build configuration
├── include/
│   └── kernels/
│       ├── oscillators/
│       │   ├── sine_kernel.hpp        # ✅ Complete
│       │   ├── phase_kernel.hpp       # ✅ Complete
│       │   ├── saw_kernel.hpp         # ✅ Complete
│       │   ├── square_kernel.hpp      # ✅ Complete
│       │   ├── triangle_kernel.hpp    # ✅ Complete
│       │   ├── noise_kernel.hpp       # ✅ Complete (Phase 2 COMPLETE!)
│       │   └── ...
│       ├── filters/
│       │   ├── onepole_kernel.hpp     # ✅ Complete
│       │   ├── biquad_kernel.hpp      # ✅ Complete
│       │   ├── svf_kernel.hpp         # ✅ Complete (Phase 3 COMPLETE!)
│       │   └── ...
│       ├── distortion/
│       │   ├── tanh_kernel.hpp        # ✅ Complete
│       │   ├── hardclip_kernel.hpp    # ✅ Complete
│       │   ├── softclip_kernel.hpp    # ✅ Complete
│       │   └── ...
│       ├── dynamics/
│       │   └── ...
│       └── utilities/
│           └── ...
├── src/                               # Implementation files (if not header-only)
├── tests/
│   ├── oscillators/
│   │   ├── test_sine_kernel.cpp       # ✅ Complete
│   │   └── ...
│   └── ...
├── examples/
│   ├── oscillators/
│   │   ├── sine_example.cpp           # ✅ Complete
│   │   └── ...
│   └── ...
├── benchmarks/
│   ├── oscillators/
│   │   ├── bench_sine_kernel.cpp
│   │   └── ...
│   └── ...
├── golden/
│   └── oscillators/
│       └── sine/
│           ├── data/                  # Reference input/output
│           └── config.json
└── docs/
    ├── KERNEL_DESIGN_GUIDE.md         # Kernel design principles
    ├── PERFORMANCE_TARGETS.md         # Performance benchmarks
    └── API_STANDARDS.md               # API conventions

🚀 Quick Start¶

Building All Kernels¶

cd 05_15_01_kernel_references
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build .

Running Tests¶

# Run all tests
ctest

# Run specific kernel tests
./tests/test_sine_kernel

Running Examples¶

# Run sine oscillator example
./examples/sine_example

Certifying a Kernel¶

# Navigate to certification framework
cd ../05_15_00_reference_framework/build/Release

# Certify sine kernel
./certify.exe --impl ../../05_15_01_kernel_references/sine_kernel --level Gold --verbose

📊 Certification Status¶

Overall Progress¶

Total Kernels:     27 (adjusted - onepole LP/HP combined into one)
Completed:         13 (48.1%)
In Progress:       0 (0%)
Planned:           14 (51.9%)

Certification Levels Achieved¶

Gold 🥇:          1 kernel  (sine_kernel)
Silver 🥈:        0 kernels
Bronze 🥉:        0 kernels
Implemented:      12 kernels (phase_kernel, gain_kernel, saw_kernel, square_kernel,
                             triangle_kernel, noise_kernel, onepole_kernel, biquad_kernel,
                             svf_kernel, tanh_kernel, hardclip_kernel, softclip_kernel)
None:             14 kernels

🎓 Kernel Design Principles¶

1. Minimal State¶

Kernels should have minimal or no state:

// GOOD - Stateless
float tanh_kernel(float input) {
    return std::tanh(input);
}

// ACCEPTABLE - Minimal state
class PhaseKernel {
    float phase_ = 0.0f;
public:
    float tick(float frequency, float sampleRate);
};

2. Fast Execution¶

Target: <20 CPU cycles per sample

// Use lookup tables for expensive functions
// Prefer integer math where possible
// SIMD-friendly data layout

3. Numerical Stability¶

// Handle edge cases
// Prevent denormals
// Clamp outputs to valid ranges
// Use double precision for accumulation where needed

4. API Consistency¶

All kernels follow the same patterns:

namespace audiolab {
namespace kernels {

/**
 * @brief Brief description
 *
 * Detailed description
 */
class MyKernel {
public:
    /// Constructor
    MyKernel();

    /// Process single sample
    float process(float input);

    /// Process buffer
    void processBuffer(const float* input, float* output, int numSamples);

    /// Reset state
    void reset();

    /// Set parameter
    void setParameter(float value);
};

} // namespace kernels
} // namespace audiolab

📈 Performance Targets¶

CPU Cycles per Sample¶

Category	Target	Maximum
Oscillators	<10 cycles	<15 cycles
Simple Filters	<12 cycles	<20 cycles
Complex Filters	<20 cycles	<30 cycles
Distortion	<8 cycles	<12 cycles
Dynamics	<15 cycles	<25 cycles

Memory Requirements¶

Kernel Type	Max Memory
Stateless	0 bytes
Minimal State	<64 bytes
With Tables	<4 KB

✅ Certification Checklist¶

For each kernel to achieve Gold certification:

Static Analysis: Zero warnings with -Wall -Wextra
Compilation: Builds with GCC, Clang, MSVC
Unit Tests: >95% code coverage
Integration Tests: Works with L1 atoms
Performance: Meets cycle count targets
Golden Comparison: Bit-exact or within tolerance
Memory Analysis: Zero leaks, proper cleanup
Thread Safety: Data race free (if applicable)
Documentation: 100% Doxygen coverage

📚 Documentation¶

For Kernel Users¶

For Kernel Developers¶

See individual kernel headers for implementation details
Check examples/ for usage patterns
Review tests/ for expected behavior

🔬 Testing Strategy¶

Unit Tests (Catch2)¶

Each kernel has comprehensive unit tests covering:

Basic functionality
Edge cases (zero, infinity, NaN)
Parameter ranges
State management
Reset behavior
Buffer processing
Performance characteristics

Integration Tests¶

Kernels are tested in combination:

Oscillator → Filter chains
Distortion → Dynamics chains
Multiple instances

Golden Comparison¶

Reference data generated from:

MATLAB/Octave implementations
Industry-standard libraries (e.g., STK, FAUST)
Known mathematical solutions

🎯 Development Roadmap¶

Phase 1: Foundation (Weeks 1-2)¶

✅ Sine oscillator kernel (COMPLETE - Gold certified)
✅ Phase accumulator kernel (COMPLETE)
✅ Basic gain kernel (COMPLETE)

Phase 2: Essential Oscillators (Weeks 3-4) ✅ COMPLETE¶

✅ Sawtooth kernel (bandlimited) - COMPLETE
✅ Square kernel (bandlimited) with PWM - COMPLETE
✅ Triangle kernel (naturally bandlimited) - COMPLETE
✅ Noise kernel (Xorshift32 PRNG) - COMPLETE

Phase 3: Basic Filters (Weeks 5-6) ✅ COMPLETE¶

✅ One-pole filter kernel (LP/HP modes) - COMPLETE
✅ Biquad kernel (8 filter types) - COMPLETE
✅ SVF kernel (State Variable Filter, Chamberlin) - COMPLETE

Phase 4: Distortion & Dynamics (Weeks 7-8)¶

✅ Tanh kernel - COMPLETE
✅ Hard clip kernel - COMPLETE
✅ Soft clip kernel - COMPLETE
🔴 Envelope detector
🔴 Gain computer

Phase 5: Advanced & Utilities (Weeks 9-10)¶

🔴 Delay & interpolation
🔴 Comb & allpass
🔴 Utility kernels

Estimated Total Time: 10-12 weeks for all 28 kernels

🤝 Contributing¶

Adding a New Kernel¶

Create kernel header in appropriate category
Implement following API standards
Create comprehensive unit tests
Create usage example
Create benchmark
Generate golden reference data
Run certification framework
Update this README

Code Review Checklist¶

📞 Support¶

For questions about kernels: - Check kernel header documentation - Review examples in examples/ - See unit tests in tests/ - Consult design guide in docs/

📄 License¶

Part of AudioLab project. See project root for license information.

Module Version: 1.0.0 Last Updated: 2025-10-15 Next Update: After Phase 1 completion