dspx 0.2.0-alpha.12 → 0.2.0-alpha.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dspx",
-  "version": "0.2.0-alpha.12",
+  "version": "0.2.0-alpha.14",
   "description": "High-performance DSP library with native C++ acceleration and Redis state persistence",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/native/adapters/ConvolutionStage.h

@@ -5,6 +5,7 @@
 #include "../utils/ConvolutionPolicy.h"
 #include "../utils/SimdOps.h"
 #include "../core/FftEngine.h"
+#include "../core/FirFilterNeon.h"
 #include <vector>
 #include <string>
 #include <memory>
@@ -220,7 +221,9 @@ namespace dsp::adapters
         // De-interleaved buffers for cache-friendly processing
         std::vector<std::vector<float>> m_deinterleaved_buffers;
         std::vector<float> m_temp_output_channel;
-        std::vector<float> m_reversed_window; // Reversed window for SIMD convolution
+
+        // High-performance FIR filters for batch convolution (one per channel)
+        std::vector<std::unique_ptr<core::FirFilterNeon>> m_batch_fir_filters;
 
         // Reusable buffer for moving mode direct convolution (eliminates per-sample allocation)
         mutable std::vector<float> m_moving_temp_buffer;
@@ -390,6 +393,67 @@ namespace dsp::adapters
             size_t samplesPerChannel = numSamples / numChannels;
             size_t kernelSize = m_kernel.size();
 
+#if defined(__ARM_NEON) || defined(__aarch64__)
+            // ARM NEON path: Use FirFilterNeon for optimal performance
+            // This eliminates per-sample gather overhead with O(1) circular buffer
+
+            // Initialize FIR filters for each channel (only once)
+            if (m_batch_fir_filters.size() != static_cast<size_t>(numChannels))
+            {
+                m_batch_fir_filters.clear();
+                for (int ch = 0; ch < numChannels; ++ch)
+                {
+                    m_batch_fir_filters.push_back(
+                        std::make_unique<core::FirFilterNeon>(m_kernel));
+                }
+            }
+
+            // Resize de-interleaved buffers if needed
+            if (m_deinterleaved_buffers.size() != static_cast<size_t>(numChannels))
+            {
+                m_deinterleaved_buffers.resize(numChannels);
+                for (auto &buf : m_deinterleaved_buffers)
+                {
+                    buf.resize(samplesPerChannel);
+                }
+            }
+            else if (!m_deinterleaved_buffers.empty() &&
+                     m_deinterleaved_buffers[0].size() != samplesPerChannel)
+            {
+                for (auto &buf : m_deinterleaved_buffers)
+                {
+                    buf.resize(samplesPerChannel);
+                }
+            }
+
+            // Step 1: De-interleave and process each channel with FirFilterNeon
+            for (int ch = 0; ch < numChannels; ++ch)
+            {
+                auto &fir = m_batch_fir_filters[ch];
+                auto &output = m_deinterleaved_buffers[ch];
+
+                // Reset filter state for batch mode (stateless)
+                fir->reset();
+
+                // Extract channel samples and process in-place
+                for (size_t i = 0; i < samplesPerChannel; ++i)
+                {
+                    float input = buffer[i * numChannels + ch];
+                    output[i] = fir->processSample(input);
+                }
+            }
+
+            // Step 2: Re-interleave output back to buffer
+            for (int ch = 0; ch < numChannels; ++ch)
+            {
+                const auto &output = m_deinterleaved_buffers[ch];
+                for (size_t i = 0; i < samplesPerChannel; ++i)
+                {
+                    buffer[i * numChannels + ch] = output[i];
+                }
+            }
+#else
+            // Non-ARM fallback: Original scalar implementation
             // Resize de-interleaved buffers if channel count changed
             if (m_deinterleaved_buffers.size() != static_cast<size_t>(numChannels))
             {
@@ -414,12 +478,6 @@ namespace dsp::adapters
                 m_temp_output_channel.resize(samplesPerChannel);
             }
 
-            // Resize reversed window buffer for SIMD (only allocate once)
-            if (m_reversed_window.size() != kernelSize)
-            {
-                m_reversed_window.resize(kernelSize);
-            }
-
             // Step 1: De-interleave input data for cache-friendly processing
             for (int ch = 0; ch < numChannels; ++ch)
             {
@@ -438,43 +496,16 @@ namespace dsp::adapters
                 float *output = m_temp_output_channel.data();
 
                 // Standard convolution: y[n] = sum(h[k] * x[n-k])
-                // For small K: simple loop (compiler auto-vectorizes)
-                // For large K: use explicit SIMD with window collection
                 for (size_t n = 0; n < samplesPerChannel; ++n)
                 {
                     float sum = 0.0f;
 
-                    if (kernelSize <= 16)
+                    // Simple scalar loop (compiler may auto-vectorize)
+                    for (size_t k = 0; k < kernelSize; ++k)
                     {
-                        // Small kernels: tight loop, compiler auto-vectorizes
-                        for (size_t k = 0; k < kernelSize; ++k)
-                        {
-                            if (n >= k)
-                            {
-                                sum += kernelPtr[k] * channelInput[n - k];
-                            }
-                        }
-                    }
-                    else
-                    {
-                        // Large kernels: collect window and use SIMD dot product
-                        // This avoids the performance cliff from backward indexing
-                        if (n >= kernelSize - 1)
-                        {
-                            // Full window available - collect in forward order for SIMD
-                            for (size_t k = 0; k < kernelSize; ++k)
-                            {
-                                m_reversed_window[k] = channelInput[n - k];
-                            }
-                            sum = simd::dot_product(kernelPtr, m_reversed_window.data(), kernelSize);
-                        }
-                        else
+                        if (n >= k)
                         {
-                            // Partial window at the start
-                            for (size_t k = 0; k <= n; ++k)
-                            {
-                                sum += kernelPtr[k] * channelInput[n - k];
-                            }
+                            sum += kernelPtr[k] * channelInput[n - k];
                         }
                     }
 
@@ -487,6 +518,7 @@ namespace dsp::adapters
                     buffer[i * numChannels + ch] = output[i];
                 }
             }
+#endif
         }
 
         /**

package/src/native/core/FirFilterNeon.h

@@ -2,19 +2,24 @@
 
 /**
  * @file FirFilterNeon.h
- * @brief ARM NEON-optimized FIR filter with transposed direct-form II structure
+ * @brief ARM NEON-optimized FIR filter with guard-zone circular buffer
  *
- * This implementation eliminates circular buffer overhead by using a transposed
- * (direct-form II) structure where the delay line is updated once per output sample
- * with simple shifts, allowing pure NEON vectorization without gather operations.
+ * This implementation keeps O(1) state updates while enabling fully contiguous
+ * NEON vectorization using a "guard zone" (mirrored buffer) technique.
  *
- * Expected performance gain vs circular buffer: 3-6x for 16-128 tap filters on ARM.
+ * Key insight: Allocate buffer of size N + GUARD (where GUARD >= max SIMD width).
+ * When writing sample at index i, also write it at i+N. This ensures that any
+ * NEON load starting from 'head' can read contiguously without wrap-around logic.
+ *
+ * Performance: O(1) state update + fully vectorized O(N) convolution.
+ * Expected gain vs naive circular buffer: 3-6x for 16-128 tap filters on ARM.
  */
 
 #include <vector>
 #include <cstddef>
 #include <cstring>
 #include <stdexcept>
+#include <algorithm>
 
 #if defined(__ARM_NEON) || defined(__aarch64__)
 #include <arm_neon.h>
@@ -23,40 +28,50 @@
 namespace dsp::core
 {
     /**
-     * @brief High-performance NEON-optimized FIR filter (ARM only)
+     * @brief High-performance NEON-optimized FIR filter using guard-zone circular buffer
      *
-     * Uses transposed direct-form structure:
-     * - Delay line stored in linear buffer (NO circular indexing)
-     * - Coefficients reversed once during construction
-     * - Inner loop is pure NEON FMA: acc = vmlaq_f32(acc, coeff, delay)
-     * - Per-sample update is simple memmove/NEON shift
+     * Architecture:
+     * - Circular buffer with power-of-2 size for bitmask wrapping (O(1) update)
+     * - Guard zone (mirrored tail) to make SIMD reads always contiguous
+     * - Coefficients stored in forward order (newest sample = h[0])
+     * - NEON kernel reads forward from 'head' with no modulo in inner loop
      *
-     * This architecture allows the CPU to:
-     * 1. Stream memory linearly (no gather/scatter)
-     * 2. Use full NEON FMA pipeline (1 cycle per 4 MACs)
-     * 3. Prefetch ahead automatically (predictable access pattern)
+     * This gives best of both worlds:
+     * 1. O(1) state updates (increment head, write sample + guard)
+     * 2. Fully contiguous NEON loads (no gather/scatter)
+     * 3. No memmove/shift overhead (eliminated algorithmic regression)
      */
     class FirFilterNeon
     {
     public:
         explicit FirFilterNeon(const std::vector<float> &coefficients)
-            : m_numTaps(coefficients.size())
+            : m_numTaps(coefficients.size()),
+              m_head(0)
         {
             if (coefficients.empty())
             {
                 throw std::invalid_argument("FIR coefficients cannot be empty");
             }
 
-            // Store coefficients in REVERSE order for direct convolution
-            // (eliminates index arithmetic in inner loop)
-            m_coefficients.resize(m_numTaps);
-            for (size_t i = 0; i < m_numTaps; ++i)
+            // Round up to next power of 2 for bitmask wrapping
+            m_bufferSize = 1;
+            while (m_bufferSize < m_numTaps)
             {
-                m_coefficients[i] = coefficients[m_numTaps - 1 - i];
+                m_bufferSize <<= 1;
             }
-
-            // Allocate delay line (zero-initialized)
-            m_delayLine.resize(m_numTaps, 0.0f);
+            m_headMask = m_bufferSize - 1;
+
+            // Reverse coefficients to match memory access pattern:
+            // readStart points to oldest sample, we read forward (oldest→newest)
+            // So h[0] should multiply oldest sample = original h[numTaps-1]
+            // This way: h_rev[0]*x[oldest] + ... + h_rev[N-1]*x[newest]
+            //         = h[N-1]*x[oldest] + ... + h[0]*x[newest] ✓
+            m_coefficients.resize(coefficients.size());
+            std::reverse_copy(coefficients.begin(), coefficients.end(), m_coefficients.begin());
+
+            // Allocate state buffer + guard zone
+            // Guard zone mirrors the entire circular buffer for contiguous wraparound reads
+            m_state.resize(m_bufferSize * 2, 0.0f);
         }
 
         /**
@@ -87,119 +102,136 @@ namespace dsp::core
         }
 
         /**
-         * @brief Reset filter state (clear delay line)
+         * @brief Reset filter state (clear circular buffer and guard zone)
          */
         void reset()
         {
-            std::fill(m_delayLine.begin(), m_delayLine.end(), 0.0f);
+            std::fill(m_state.begin(), m_state.end(), 0.0f);
+            m_head = 0;
         }
 
         size_t getNumTaps() const { return m_numTaps; }
+        size_t getBufferSize() const { return m_bufferSize; }
 
     private:
-        size_t m_numTaps;
-        std::vector<float> m_coefficients; // Reversed for direct convolution
-        std::vector<float> m_delayLine;    // Linear buffer (NO circular indexing!)
+        size_t m_numTaps;                  // Number of filter taps
+        size_t m_bufferSize;               // Power-of-2 buffer size (>= m_numTaps)
+        size_t m_head;                     // Current write position
+        size_t m_headMask;                 // Bitmask for wrapping (bufferSize - 1)
+        std::vector<float> m_coefficients; // Filter coefficients (forward order)
+        std::vector<float> m_state;        // Circular buffer + guard zone
 
 #if defined(__ARM_NEON) || defined(__aarch64__)
         /**
-         * @brief NEON-optimized sample processing
+         * @brief NEON-optimized sample processing with guard-zone circular buffer
          *
-         * Transposed Direct-Form II FIR:
-         * 1. Compute output: y[n] = sum(c[i] * d[i]) using NEON FMA
-         * 2. Update delay line: shift left, insert new sample at end
+         * Algorithm:
+         * 1. Write input to state[head] and state[head + bufferSize] (guard mirror)
+         * 2. Read N contiguous floats starting from state[head] using NEON
+         * 3. Compute dot product with coefficients (fully vectorized)
+         * 4. Advance head with bitmask wrapping (O(1))
          *
-         * This is THE key optimization: delay line is contiguous, so NEON
-         * can stream loads/stores without address computation.
+         * Key: The guard zone ensures that reads from 'head' are ALWAYS contiguous,
+         * even when they logically "wrap around" the circular buffer boundary.
          */
         float processSampleNeon(float input)
         {
-            const size_t simd_width = 4;
-            const size_t simd_count = m_numTaps / simd_width;
-            const size_t simd_end = simd_count * simd_width;
+            // Advance head FIRST (points to oldest sample position)
+            m_head = (m_head + 1) & m_headMask;
+
+            // Write input to current position AND guard zone (O(1) mirroring)
+            m_state[m_head] = input;
+            // Always mirror to guard zone - this is critical for wraparound reads!
+            m_state[m_head + m_bufferSize] = input;
+
+            // NEON convolution: read samples from oldest to newest
+            // Coefficients are stored in REVERSE order, so:
+            // h_rev[0]*x[oldest] + h_rev[1]*x[older] + ... + h_rev[N-1]*x[newest]
+            // = h[N-1]*x[oldest] + ... + h[0]*x[newest] = correct FIR formula ✓
+            // The guard zone ensures contiguous reads even across the wrap boundary
+            // Calculate start position: if m_head >= (numTaps-1), read from [m_head - numTaps + 1]
+            // Otherwise, read from guard zone: [m_head + bufferSize - numTaps + 1]
+            size_t readStart;
+            if (m_head >= m_numTaps - 1)
+            {
+                readStart = m_head - m_numTaps + 1;
+            }
+            else
+            {
+                // Wrap using guard zone (no modulo needed!)
+                readStart = m_head + m_bufferSize - m_numTaps + 1;
+            }
+            const float *x = &m_state[readStart];
+            const float *h = m_coefficients.data();
+
+            constexpr size_t simd_width = 4;
+            const size_t simd_end = (m_numTaps / simd_width) * simd_width;
 
             float32x4_t acc = vdupq_n_f32(0.0f);
 
-            // Vectorized MAC: acc += coeff[i] * delay[i]
+            // Vectorized MAC loop (no modulo, no branches!)
             for (size_t i = 0; i < simd_end; i += simd_width)
             {
-                float32x4_t c = vld1q_f32(&m_coefficients[i]);
-                float32x4_t d = vld1q_f32(&m_delayLine[i]);
+                float32x4_t c = vld1q_f32(h + i);
+                float32x4_t d = vld1q_f32(x + i);
                 acc = vmlaq_f32(acc, c, d); // Fused multiply-add
             }
 
-            // Horizontal reduction (sum 4 lanes)
+            // Horizontal reduction
+#if defined(__aarch64__) && defined(__ARM_FEATURE_FP16_VECTOR_ARITHMETIC)
+            // ARMv8.1-a and later: use vaddvq_f32
+            float output = vaddvq_f32(acc);
+#else
+            // ARMv8.0 fallback: manual pairwise addition
             float32x2_t sum_lo = vget_low_f32(acc);
             float32x2_t sum_hi = vget_high_f32(acc);
             float32x2_t sum_pair = vadd_f32(sum_lo, sum_hi);
             float32x2_t sum_final = vpadd_f32(sum_pair, sum_pair);
             float output = vget_lane_f32(sum_final, 0);
+#endif
 
-            // Handle remainder (scalar)
+            // Scalar tail (remaining 0-3 taps)
             for (size_t i = simd_end; i < m_numTaps; ++i)
             {
-                output += m_coefficients[i] * m_delayLine[i];
-            }
-
-            // Update delay line: shift left by 1, insert new sample at end
-            // For small taps (<= 64), NEON shift is faster than memmove
-            if (m_numTaps <= 64)
-            {
-                neonShiftLeft(m_delayLine.data(), m_numTaps, input);
-            }
-            else
-            {
-                std::memmove(m_delayLine.data(), m_delayLine.data() + 1, (m_numTaps - 1) * sizeof(float));
-                m_delayLine[m_numTaps - 1] = input;
+                output += h[i] * x[i];
             }
 
             return output;
         }
+#endif
 
         /**
-         * @brief NEON-accelerated delay line shift
-         * Shifts entire array left by 1 element using vectorized loads/stores
+         * @brief Scalar fallback for non-ARM platforms
          */
-        static void neonShiftLeft(float *data, size_t size, float newValue)
+        float processSampleScalar(float input)
         {
-            const size_t simd_width = 4;
-            const size_t simd_count = (size - 1) / simd_width;
-            const size_t simd_end = simd_count * simd_width;
+            // Advance head FIRST
+            m_head = (m_head + 1) & m_headMask;
 
-            // Vectorized shift: data[i] = data[i+1]
-            for (size_t i = 0; i < simd_end; i += simd_width)
+            // Write to circular buffer + guard
+            m_state[m_head] = input;
+            // Always mirror to guard zone
+            m_state[m_head + m_bufferSize] = input;
+
+            // Compute output (read backward from newest to oldest)
+            float output = 0.0f;
+            size_t readStart;
+            if (m_head >= m_numTaps - 1)
             {
-                float32x4_t vals = vld1q_f32(&data[i + 1]);
-                vst1q_f32(&data[i], vals);
+                readStart = m_head - m_numTaps + 1;
             }
-
-            // Scalar remainder
-            for (size_t i = simd_end; i < size - 1; ++i)
+            else
             {
-                data[i] = data[i + 1];
+                readStart = m_head + m_bufferSize - m_numTaps + 1;
             }
+            const float *x = &m_state[readStart];
+            const float *h = m_coefficients.data();
 
-            data[size - 1] = newValue;
-        }
-#endif
-
-        /**
-         * @brief Scalar fallback for non-ARM platforms
-         */
-        float processSampleScalar(float input)
-        {
-            float output = 0.0f;
-
-            // Compute output
             for (size_t i = 0; i < m_numTaps; ++i)
             {
-                output += m_coefficients[i] * m_delayLine[i];
+                output += h[i] * x[i];
             }
 
-            // Update delay line
-            std::memmove(m_delayLine.data(), m_delayLine.data() + 1, (m_numTaps - 1) * sizeof(float));
-            m_delayLine[m_numTaps - 1] = input;
-
             return output;
         }
     };

package/src/native/core/MovingAverageFilter.h

@@ -70,6 +70,27 @@ namespace dsp::core
          */
         T addSample(T newValue) { return m_filter.addSample(newValue); }
 
+        /**
+         * @brief Process array of samples in batch (optimized for throughput).
+         *
+         * This is significantly faster than calling addSample() in a loop
+         * for small-to-medium input sizes, as it:
+         * 1. Avoids per-call overhead (JS→Native boundary crossing)
+         * 2. Enables better CPU cache utilization
+         * 3. Allows compiler to vectorize the loop
+         *
+         * @param input Input array of samples
+         * @param output Output array (same size as input)
+         * @param length Number of samples to process
+         */
+        void processArray(const T *input, T *output, size_t length)
+        {
+            for (size_t i = 0; i < length; ++i)
+            {
+                output[i] = addSample(input[i]);
+            }
+        }
+
         /**
          * @brief Adds a new sample with timestamp (time-aware mode only).
          * @param newValue The new sample value to add.