dspx 0.1.1-alpha.0

package/src/native/core/Policies.h

@@ -0,0 +1,352 @@
+#pragma once
+#include <cmath>
+#include <algorithm>
+#include <numeric>
+
+namespace dsp::core
+{
+    /**
+     * @brief Policy for calculating a running mean (for Moving Average).
+     *
+     * Maintains a running sum and computes the mean on demand.
+     */
+    template <typename T>
+    struct MeanPolicy
+    {
+        T m_sum = 0;
+
+        void onAdd(T val) { m_sum += val; }
+        void onRemove(T val) { m_sum -= val; }
+        void clear() { m_sum = 0; }
+
+        T getResult(size_t count) const
+        {
+            if (count == 0)
+                return 0;
+            return m_sum / static_cast<T>(count);
+        }
+
+        // For state serialization
+        T getState() const { return m_sum; }
+        void setState(T sum) { m_sum = sum; }
+    };
+
+    /**
+     * @brief Policy for calculating RMS (Root Mean Square).
+     *
+     * Maintains a running sum of squares and computes RMS on demand.
+     */
+    template <typename T>
+    struct RmsPolicy
+    {
+        T m_sum_sq = 0;
+
+        void onAdd(T val) { m_sum_sq += (val * val); }
+        void onRemove(T val) { m_sum_sq -= (val * val); }
+        void clear() { m_sum_sq = 0; }
+
+        T getResult(size_t count) const
+        {
+            if (count == 0)
+                return 0;
+            // Clamp to avoid negative values due to floating-point errors
+            T mean_sq = std::max(static_cast<T>(0), m_sum_sq / static_cast<T>(count));
+            return std::sqrt(mean_sq);
+        }
+
+        // For state serialization
+        T getState() const { return m_sum_sq; }
+        void setState(T sumSq) { m_sum_sq = sumSq; }
+    };
+
+    /**
+     * @brief Policy for SlidingWindowFilter that maintains a running sum.
+     * @tparam T The numeric type (e.g., float, double).
+     */
+    template <typename T>
+    struct SumPolicy
+    {
+        double m_sum = 0.0;
+
+        void onAdd(T value)
+        {
+            m_sum += static_cast<double>(value);
+        }
+
+        void onRemove(T value)
+        {
+            m_sum -= static_cast<double>(value);
+        }
+
+        void clear()
+        {
+            m_sum = 0.0;
+        }
+
+        T getResult(size_t count) const
+        {
+            // The result is just the total sum
+            return static_cast<T>(m_sum);
+        }
+
+        // --- State Serialization ---
+        double getState() const
+        {
+            return m_sum;
+        }
+
+        void setState(double state)
+        {
+            m_sum = state;
+        }
+
+        // Optional: State validation (used in adapter)
+        static bool validateState(double state, const std::vector<T> &buffer)
+        {
+            double actualSum = std::accumulate(buffer.begin(), buffer.end(), 0.0);
+            const double tolerance = 0.0001 * std::max(1.0, std::abs(actualSum));
+            return (std::abs(state - actualSum) <= tolerance);
+        }
+    };
+
+    /**
+     * @brief Policy for SlidingWindowFilter that counts 'true' entries.
+     */
+    struct CounterPolicy
+    {
+        size_t m_count = 0;
+
+        void onAdd(bool value)
+        {
+            if (value)
+            {
+                m_count++;
+            }
+        }
+
+        void onRemove(bool value)
+        {
+            if (value)
+            {
+                m_count--;
+            }
+        }
+
+        void clear()
+        {
+            m_count = 0;
+        }
+
+        // Note: The process buffer is float, so we cast the count
+        float getResult(size_t count) const
+        {
+            return static_cast<float>(m_count);
+        }
+
+        // --- State Serialization ---
+        size_t getState() const
+        {
+            return m_count;
+        }
+
+        void setState(size_t state)
+        {
+            m_count = state;
+        }
+
+        // Optional: State validation (used in adapter)
+        static bool validateState(size_t state, const std::vector<bool> &buffer)
+        {
+            size_t actualCount = 0;
+            for (bool val : buffer)
+            {
+                if (val)
+                    actualCount++;
+            }
+            return state == actualCount;
+        }
+    };
+
+    /**
+     * @brief Policy for calculating Mean Absolute Value (MAV).
+     *
+     * Maintains a running sum of absolute values.
+     */
+    template <typename T>
+    struct MeanAbsoluteValuePolicy
+    {
+        T m_sum_abs = 0;
+
+        void onAdd(T val) { m_sum_abs += std::abs(val); }
+        void onRemove(T val) { m_sum_abs -= std::abs(val); }
+        void clear() { m_sum_abs = 0; }
+
+        T getResult(size_t count) const
+        {
+            if (count == 0)
+                return 0;
+            return m_sum_abs / static_cast<T>(count);
+        }
+
+        // For state serialization
+        T getState() const { return m_sum_abs; }
+        void setState(T sumAbs) { m_sum_abs = sumAbs; }
+    };
+
+    /**
+     * @brief Policy for calculating Variance.
+     *
+     * Maintains both sum and sum of squares for variance calculation.
+     * Uses the computational formula: Var(X) = E[X²] - (E[X])²
+     */
+    template <typename T>
+    struct VariancePolicy
+    {
+        T m_sum = 0;
+        T m_sum_sq = 0;
+
+        void onAdd(T val)
+        {
+            m_sum += val;
+            m_sum_sq += (val * val);
+        }
+
+        void onRemove(T val)
+        {
+            m_sum -= val;
+            m_sum_sq -= (val * val);
+        }
+
+        void clear()
+        {
+            m_sum = 0;
+            m_sum_sq = 0;
+        }
+
+        T getResult(size_t count) const
+        {
+            if (count == 0)
+                return 0;
+
+            T mean = m_sum / static_cast<T>(count);
+            T mean_sq = m_sum_sq / static_cast<T>(count);
+
+            // Clamp to avoid negative variance due to floating-point errors
+            return std::max(static_cast<T>(0), mean_sq - (mean * mean));
+        }
+
+        // For state serialization - returns both values as a pair
+        std::pair<T, T> getState() const { return {m_sum, m_sum_sq}; }
+        void setState(T sum, T sumSq)
+        {
+            m_sum = sum;
+            m_sum_sq = sumSq;
+        }
+    };
+
+    /**
+     * @brief Policy for calculating Z-Score normalization.
+     *
+     * Maintains sum and sum of squares to compute mean and stddev,
+     * then normalizes values to Z-scores.
+     */
+    template <typename T>
+    struct ZScorePolicy
+    {
+        T m_sum = 0;
+        T m_sum_sq = 0;
+        T m_epsilon;
+
+        explicit ZScorePolicy(T epsilon = static_cast<T>(1e-8))
+            : m_epsilon(epsilon) {}
+
+        void onAdd(T val)
+        {
+            m_sum += val;
+            m_sum_sq += (val * val);
+        }
+
+        void onRemove(T val)
+        {
+            m_sum -= val;
+            m_sum_sq -= (val * val);
+        }
+
+        void clear()
+        {
+            m_sum = 0;
+            m_sum_sq = 0;
+        }
+
+        // Z-Score needs the current value to normalize
+        T getResult(T currentValue, size_t count) const
+        {
+            if (count == 0)
+                return 0;
+
+            T mean = m_sum / static_cast<T>(count);
+            T mean_sq = m_sum_sq / static_cast<T>(count);
+            T variance = std::max(static_cast<T>(0), mean_sq - (mean * mean));
+            T stddev = std::sqrt(variance);
+
+            // Avoid division by zero
+            if (stddev < m_epsilon)
+            {
+                return 0;
+            }
+
+            return (currentValue - mean) / stddev;
+        }
+
+        // For state serialization
+        std::pair<T, T> getState() const { return {m_sum, m_sum_sq}; }
+        void setState(T sum, T sumSq)
+        {
+            m_sum = sum;
+            m_sum_sq = sumSq;
+        }
+
+        T getEpsilon() const { return m_epsilon; }
+    };
+
+    /**
+     * @brief Policy for FIR filter convolution.
+     *
+     * Performs FIR filtering using dot product with filter coefficients.
+     * The buffer stores recent input samples, and coefficients are the filter taps.
+     * Note: SIMD optimization is handled in the FirFilter implementation.
+     */
+    template <typename T>
+    struct FirConvolutionPolicy
+    {
+        std::vector<T> m_coefficients;
+
+        explicit FirConvolutionPolicy(const std::vector<T> &coefficients)
+            : m_coefficients(coefficients) {}
+
+        void onAdd(T val) {}    // No incremental state to update
+        void onRemove(T val) {} // No incremental state to update
+        void clear() {}         // No state to clear
+
+        // Compute convolution (dot product) with the buffer
+        // Note: This is a simple scalar version; SIMD is applied in FirFilter
+        T getResult(const std::vector<T> &buffer) const
+        {
+            if (buffer.empty() || m_coefficients.empty())
+                return T(0);
+
+            T result = T(0);
+            size_t len = std::min(buffer.size(), m_coefficients.size());
+            for (size_t i = 0; i < len; ++i)
+            {
+                result += buffer[i] * m_coefficients[i];
+            }
+            return result;
+        }
+
+        // For state serialization
+        const std::vector<T> &getCoefficients() const { return m_coefficients; }
+        void setCoefficients(const std::vector<T> &coeffs) { m_coefficients = coeffs; }
+    };
+
+} // namespace dsp::core

package/src/native/core/RmsFilter.cc

@@ -0,0 +1,18 @@
+/**
+ * @file RmsFilter.cc
+ * @brief Implementation file for RmsFilter (now header-only with policy-based design)
+ *
+ * This file now only contains explicit template instantiations.
+ * The actual implementation is in the header file RmsFilter.h,
+ * which delegates to SlidingWindowFilter<T, RmsPolicy<T>>.
+ */
+
+#include "RmsFilter.h"
+
+// Explicit template instantiation for common types
+namespace dsp::core
+{
+    template class RmsFilter<int>;
+    template class RmsFilter<float>;
+    template class RmsFilter<double>;
+}

package/src/native/core/RmsFilter.h

@@ -0,0 +1,131 @@
+#pragma once
+#include "../utils/SlidingWindowFilter.h"
+#include "Policies.h"
+#include <utility>
+#include <vector>
+#include <stdexcept>
+
+namespace dsp::core
+{
+    using dsp::utils::SlidingWindowFilter;
+    /**
+     * @brief Implements an efficient Root Mean Square (RMS) filter.
+     *
+     * This class is now a thin wrapper around SlidingWindowFilter
+     * using the RmsPolicy for statistical computation.
+     *
+     * @tparam T The numeric type of the samples (e.g., float, double).
+     */
+    template <typename T>
+    class RmsFilter
+    {
+    public:
+        /**
+         * @brief Constructs a new RMS Filter.
+         * @param window_size The number of samples to average over (N).
+         */
+        explicit RmsFilter(size_t window_size)
+            : m_filter(window_size, RmsPolicy<T>{})
+        {
+            if (window_size == 0)
+            {
+                throw std::invalid_argument("Window size must be greater than 0");
+            }
+        }
+
+        /**
+         * @brief Constructs a new time-aware RMS Filter.
+         * @param window_size The buffer capacity in samples.
+         * @param window_duration_ms The time window duration in milliseconds.
+         */
+        explicit RmsFilter(size_t window_size, double window_duration_ms)
+            : m_filter(window_size, window_duration_ms, RmsPolicy<T>{})
+        {
+            if (window_size == 0)
+            {
+                throw std::invalid_argument("Window size must be greater than 0");
+            }
+            if (window_duration_ms <= 0.0)
+            {
+                throw std::invalid_argument("Window duration must be greater than 0");
+            }
+        }
+
+        // Delete copy constructor and copy assignment
+        RmsFilter(const RmsFilter &) = delete;
+        RmsFilter &operator=(const RmsFilter &) = delete;
+
+        // Enable move semantics
+        RmsFilter(RmsFilter &&) noexcept = default;
+        RmsFilter &operator=(RmsFilter &&) noexcept = default;
+
+        /**
+         * @brief Adds a new sample to the filter.
+         * @param newValue The new sample value to add.
+         * @return T The new RMS value.
+         */
+        T addSample(T newValue) { return m_filter.addSample(newValue); }
+
+        /**
+         * @brief Adds a new sample with timestamp (time-aware mode).
+         * @param newValue The new sample value to add.
+         * @param timestamp The timestamp in milliseconds.
+         * @return T The new RMS value.
+         */
+        T addSampleWithTimestamp(T newValue, double timestamp)
+        {
+            return m_filter.addSampleWithTimestamp(newValue, timestamp);
+        }
+
+        /**
+         * @brief Gets the current RMS value.
+         * @return T The RMS of the samples currently in the buffer.
+         */
+        T getRms() const { return m_filter.getPolicy().getResult(m_filter.getCount()); }
+
+        /**
+         * @brief Clears all samples from the filter and resets the sum.
+         */
+        void clear() { m_filter.clear(); }
+
+        /**
+         * @brief Checks if the filter's buffer is full (i.e., has N samples).
+         * @return true if the buffer is full, false otherwise.
+         */
+        bool isFull() const noexcept { return m_filter.isFull(); }
+
+        /**
+         * @brief Checks if the filter is in time-aware mode.
+         * @return true if time-aware, false otherwise.
+         */
+        bool isTimeAware() const noexcept { return m_filter.isTimeAware(); }
+
+        /**
+         * @brief Exports the filter's internal state.
+         *
+         * Delegates to SlidingWindowFilter's generic state management.
+         *
+         * @return A pair containing the buffer contents and running sum of squares.
+         */
+        std::pair<std::vector<T>, T> getState() const
+        {
+            return m_filter.getState();
+        }
+
+        /**
+         * @brief Restores the filter's internal state.
+         *
+         * Delegates to SlidingWindowFilter's generic state management.
+         *
+         * @param bufferData The buffer contents to restore.
+         * @param sumOfSquares The running sum of squares to restore.
+         */
+        void setState(const std::vector<T> &bufferData, T sumOfSquares)
+        {
+            m_filter.setState(bufferData, sumOfSquares);
+        }
+
+    private:
+        SlidingWindowFilter<T, RmsPolicy<T>> m_filter;
+    };
+} // namespace dsp::core

package/src/native/core/SscFilter.cc

@@ -0,0 +1,16 @@
+/**
+ * @file SscFilter.cc
+ * @brief Implementation file for SscFilter (now header-only with policy-based design)
+ * This file now only contains explicit template instantiations.
+ * The actual implementation is in the header file SscFilter.h,
+ * which delegates to SlidingWindowFilter<T, CounterPolicy>.
+ */
+
+#include "SscFilter.h"
+
+// Explicit template instantiation for common types
+namespace dsp::core
+{
+    template class SscFilter<float>;
+    template class SscFilter<double>;
+} // namespace dsp::core

package/src/native/core/SscFilter.h

@@ -0,0 +1,137 @@
+#pragma once
+
+#include "../utils/SlidingWindowFilter.h"
+#include "Policies.h"
+#include <cmath>   // For std::abs
+#include <utility> // For std::pair
+#include <vector>
+
+namespace dsp::core
+{
+    template <typename T>
+    class SscFilter
+    {
+    public:
+        /**
+         * @brief Constructs a new Ssc Filter.
+         * @param window_size The number of samples to consider in the sliding window.
+         * @param threshold The amplitude change threshold to detect.
+         */
+        explicit SscFilter(size_t window_size, T threshold)
+            : m_filter(window_size),
+              m_threshold(threshold),
+              m_sample_minus_1(0.0),
+              m_sample_minus_2(0.0),
+              m_init_count(0) {}
+
+        // Delete copy constructor and copy assignment
+        SscFilter(const SscFilter &) = delete;
+        SscFilter &operator=(const SscFilter &) = delete;
+
+        // Enable move semantics
+        SscFilter(SscFilter &&) noexcept = default;
+        SscFilter &operator=(SscFilter &&) noexcept = default;
+
+        /**
+         * @brief Adds a new sample to the filter.
+         * @param sample_n The new sample value to add.
+         * @return T The updated SSC count over the window.
+         */
+        T addSample(T sample_n) // sample_n is x_{i+1}
+        {
+            bool did_change = false;
+
+            if (m_init_count >= 2)
+            {
+                // We have x_{i-1} (m_sample_minus_2), x_i (m_sample_minus_1), and x_{i+1} (sample_n)
+                T diff1 = m_sample_minus_1 - m_sample_minus_2; // (x_i - x_{i-1})
+                T diff2 = m_sample_minus_1 - sample_n;         // (x_i - x_{i+1})
+
+                did_change = (diff1 * diff2) > m_threshold;
+            }
+            else
+            {
+                if (m_init_count == 0)
+                    m_sample_minus_2 = sample_n; // First sample
+                if (m_init_count == 1)
+                    m_sample_minus_1 = sample_n; // Second sample
+                m_init_count++;
+            }
+
+            // Update state for the *next* iteration
+            m_sample_minus_2 = m_sample_minus_1;
+            m_sample_minus_1 = sample_n;
+
+            // Add the boolean to the window, get the count back
+            // Cast count (size_t) to T (float/double)
+            return static_cast<T>(m_filter.addSample(did_change));
+        }
+
+        /**
+         * @brief Clears all samples from the filter and resets state.
+         */
+        void clear()
+        {
+            m_filter.clear();
+            m_sample_minus_1 = 0.0;
+            m_sample_minus_2 = 0.0;
+            m_init_count = 0;
+        }
+
+        // --- State Management ---
+        using SscState = std::pair<std::vector<bool>, size_t>;
+
+        struct SscFilterState
+        {
+            T sample_minus_1;
+            T sample_minus_2;
+            int init_count;
+        };
+
+        /**
+         * @brief Exports the complete filter state (buffer + previous samples).
+         * @return A pair containing the buffer contents, running count, and previous samples.
+         */
+
+        auto getState() const -> std::pair<SscState, SscFilterState>
+        {
+            // Returns: { {buffer_of_bools, running_count}, {s_m1, s_m2, init_count} }
+            return {
+                m_filter.getState(),
+                {m_sample_minus_1, m_sample_minus_2, m_init_count}};
+        }
+
+        /**
+         * @brief Restores the complete filter state (buffer + previous samples).
+         * @param buffer The buffer contents to restore.
+         * @param count The count of 'true' entries in the buffer.
+         * @param filterState The previous samples and init count to restore.
+         * @return void
+         */
+
+        void setState(const std::vector<bool> &buffer, size_t count, const SscFilterState &filterState)
+        {
+            m_filter.setState(buffer, count);
+            m_sample_minus_1 = filterState.sample_minus_1;
+            m_sample_minus_2 = filterState.sample_minus_2;
+            m_init_count = filterState.init_count;
+        }
+
+        /**
+         * @brief Gets const access to the internal SlidingWindowFilter.
+         * @return const SlidingWindowFilter<bool, CounterPolicy>& Reference to the internal filter
+         */
+        const dsp::utils::SlidingWindowFilter<bool, CounterPolicy> &getInternalFilter() const
+        {
+            return m_filter;
+        }
+
+    private:
+        dsp::utils::SlidingWindowFilter<bool, CounterPolicy> m_filter;
+        T m_threshold;
+        T m_sample_minus_1; // x_i
+        T m_sample_minus_2; // x_{i-1}
+        int m_init_count;   // Needs 2 samples to be fully initialized
+    };
+
+} // namespace dsp::core

package/src/native/core/WampFilter.cc

@@ -0,0 +1,16 @@
+/**
+ * @file WampFilter.cc
+ * @brief Implementation file for WampFilter (now header-only with policy-based design)
+ * This file now only contains explicit template instantiations.
+ * The actual implementation is in the header file WampFilter.h,
+ * which delegates to SlidingWindowFilter<T, CounterPolicy>.
+ */
+
+#include "WampFilter.h"
+
+// Explicit template instantiation for common types
+namespace dsp::core
+{
+    template class WampFilter<float>;
+    template class WampFilter<double>;
+}