SciRS2 Signal

[]

Production-ready signal processing module for the SciRS2 scientific computing library (v0.1.0-rc.4). Following the SciRS2 POLICY, this module provides core signal processing tools including filtering, convolution, spectral analysis, and wavelet transforms with ecosystem consistency through scirs2-core abstractions.

🚨 Current Status: SIMD Optimization Disabling (Active Development)

Notice: This module is currently undergoing SIMD optimization disabling to achieve full compilation.

• Current State: ~1000 compilation errors due to missing SIMD implementations
• Active Fix: Implementing scalar fallbacks for all SIMD functions
• Estimated Completion: 5-7 hours
• Performance Impact: Temporary 2-5x slowdown for compute-intensive operations
• Future: SIMD optimizations will be re-enabled once implementations are complete

For Developers: See TODO.md and PROGRESS.md for detailed status and TODO.md for current tasks.

Core Features (Production-Ready)

• Signal Generation: Essential waveform generation functions
• Digital Filtering: Comprehensive IIR and FIR filter design and application
• Convolution & Correlation: Efficient signal convolution and correlation operations
• Spectral Analysis: Fundamental frequency domain analysis (FFT, PSD, spectrograms)
• Wavelet Transforms: Core wavelet analysis (DWT, CWT) with multiple families
• Peak Detection: Robust algorithms for finding and analyzing peaks
• Signal Measurements: Standard signal quality metrics (RMS, SNR, THD)
• Basic Resampling: Up/down sampling and rate conversion

Installation

Add the following to your Cargo.toml:

[dependencies]
scirs2-signal = "0.1.0-rc.4"
scirs2-core = "0.1.0-rc.4"
ndarray = "0.16.1"

Note: This is Release Candidate 4 (rc.4). The API is stable and production-ready with minimal changes expected before 1.0.

Basic usage examples:

use scirs2_signal::{waveforms, filter, convolve, spectral, peak};
use scirs2_core::error::CoreResult;
use ndarray::{Array1, array};
use std::f64::consts::PI;

// Signal generation
fn waveform_example() -> CoreResult<()> {
    // Create time array
    let t = Array1::linspace(0.0, 1.0, 1000); // 1000 points from 0 to 1 second
    let freq = 5.0; // 5 Hz
    
    // Generate basic waveforms
    let sine = t.mapv(|x| (2.0 * PI * freq * x).sin());
    let square = waveforms::square(&t, freq, 0.0, 1.0, 0.5)?;
    let chirp = waveforms::chirp(&t, 1.0, 1.0, 10.0)?;
    
    println!("Generated sine, square, and chirp signals");
    
    Ok(())
}

// Filtering example
fn filter_example() -> CoreResult<()> {
    // Create a noisy signal
    let t = Array1::linspace(0.0, 1.0, 1000);
    let signal = t.mapv(|x| (2.0 * PI * 5.0 * x).sin()); // 5 Hz sine wave
    
    // Add some noise (simplified)
    let noisy_signal = signal.mapv(|x| x + 0.1 * rand::random::<f64>());
    
    // Design a low-pass Butterworth filter
    let fs = 1000.0; // Sample rate: 1000 Hz
    let cutoff = 10.0; // Cutoff frequency: 10 Hz
    let order = 4; // Filter order
    let (b, a) = filter::butter(order, &[cutoff / (fs / 2.0)], "lowpass", None, None)?;
    
    // Apply the filter (zero-phase)
    let filtered = filter::filtfilt(&b, &a, &noisy_signal)?;
    
    println!("Applied Butterworth low-pass filter");
    
    Ok(())
}

// Convolution example
fn convolution_example() -> CoreResult<()> {
    // Create a signal
    let signal = array![1.0, 2.0, 3.0, 4.0, 5.0];
    
    // Create a kernel
    let kernel = array![0.1, 0.2, 0.4, 0.2, 0.1];
    
    // Perform convolution
    let result = convolve::convolve(&signal, &kernel, "same")?;
    
    println!("Convolution result: {:?}", result);
    
    Ok(())
}

// Spectral analysis example
fn spectral_example() -> CoreResult<()> {
    // Create a signal with multiple frequency components
    let fs = 1000.0; // Sample rate: 1000 Hz
    let t = Array1::linspace(0.0, 1.0, 1000);
    
    // Create signal with 5 Hz and 20 Hz components
    let signal = t.mapv(|x| {
        (2.0 * PI * 5.0 * x).sin() + 0.5 * (2.0 * PI * 20.0 * x).sin()
    });
    
    // Compute the power spectral density using Welch's method
    let (f, psd) = spectral::welch(&signal, None, None, None, None, Some(fs))?;
    
    // Find peaks in the PSD
    let peaks = peak::find_peaks(&psd, None, None, None, None)?;
    
    println!("Found {} peaks in the power spectrum", peaks.len());
    for (i, &idx) in peaks.iter().enumerate() {
        if idx < f.len() && idx < psd.len() {
            println!("Peak {}: frequency = {:.1} Hz, power = {:.2}", 
                     i+1, f[idx], psd[idx]);
        }
    }
    
    Ok(())
}

// Resampling example (basic)
fn resampling_example() -> CoreResult<()> {
    // Create a signal
    let t = Array1::linspace(0.0, 1.0, 1000);
    let signal = t.mapv(|x| (2.0 * std::f64::consts::PI * 5.0 * x).sin());
    
    // Basic resampling (Note: Advanced resampling in future releases)
    // let resampled = resample::resample(&signal, 1000, 2000)?;
    
    println!("Original signal: {} points", signal.len());
    
    Ok(())
}

Components

Waveforms

Functions for generating signal waveforms:

use scirs2_signal::waveforms::{
    time_array,             // Create a time array
    sine,                   // Sine wave
    cosine,                 // Cosine wave
    square,                 // Square wave
    sawtooth,               // Sawtooth wave
    triangle,               // Triangle wave
    chirp,                  // Frequency sweep (chirp)
    sweep_poly,             // Polynomial frequency sweep
    noise,                  // Noise generator
    impulse,                // Impulse signal
    step,                   // Step signal
    gaussian,               // Gaussian pulse
    gabor,                  // Gabor wavelet
};

Digital Filtering

Comprehensive filtering capabilities:

use scirs2_signal::filter::{
    // IIR Filter Design
    butter,                 // Butterworth filter design
    cheby1,                 // Chebyshev Type I filter design
    cheby2,                 // Chebyshev Type II filter design
    ellip,                  // Elliptic filter design
    bessel,                 // Bessel filter design
    
    // FIR Filter Design
    firwin,                 // Window-based FIR design
    remez,                  // Parks-McClellan optimal FIR design
    
    // Filter Application
    lfilter,                // Apply filter to data
    filtfilt,               // Zero-phase filtering
    
    // Specialized Filters
    notch_filter,           // Notch filter design
    comb_filter,            // Comb filter design
    allpass_filter,         // Allpass filter design
    
    // Filter Analysis
    analyze_filter,         // Analyze filter properties
    check_filter_stability, // Check filter stability
};
use scirs2_signal::savgol::savgol_filter; // Savitzky-Golay filter

Convolution

Functions for signal convolution:

use scirs2_signal::convolve::{
    convolve,               // 1D convolution
    convolve2d,             // 2D convolution
    fftconvolve,            // FFT-based convolution
    correlate,              // 1D correlation
    correlate2d,            // 2D correlation
};

Spectral Analysis

Fundamental frequency domain analysis:

use scirs2_signal::spectral::{
    periodogram,            // Periodogram power spectral density estimate
    welch,                  // Welch's method for PSD estimation
    spectrogram,            // Time-frequency representation
};
use scirs2_signal::stft::ShortTimeFft; // Short-time Fourier transform class

// Note: For direct FFT operations, use scirs2-fft crate
use scirs2_fft::fft::{
    fft,                    // Fast Fourier Transform
    ifft,                   // Inverse FFT
    rfft,                   // Real FFT
    irfft,                  // Inverse real FFT
};

Peak Detection

Functions for finding peaks in signals:

use scirs2_signal::peak::{
    find_peaks,             // Find peaks in data
    find_peaks_cwt,         // Find peaks using continuous wavelet transform
    peak_prominences,       // Calculate peak prominences
    peak_widths,            // Calculate peak widths
};

Resampling

Basic resampling operations:

use scirs2_signal::resample::{
    resample,               // Resample signal to new sampling rate
    // Note: Advanced resampling features are planned for future releases
};

Signal Measurements

Standard signal quality metrics:

use scirs2_signal::measurements::{
    rms,                    // Root mean square
    snr,                    // Signal-to-noise ratio
    thd,                    // Total harmonic distortion
    peak_to_peak,           // Peak-to-peak measurement
    peak_to_rms,            // Peak-to-RMS ratio
};

Wavelet Transforms

Core wavelet analysis with proven algorithms:

use scirs2_signal::{
    dwt::{Wavelet, dwt_decompose, dwt_reconstruct, wavedec, waverec},
    wavelets::{cwt, morlet, ricker},
    denoise::{denoise_wavelet, ThresholdMethod, ThresholdSelect},
};

// Supported wavelet families (stable)
let wavelets = [
    Wavelet::Haar,          // Haar wavelet
    Wavelet::DB(4),         // Daubechies wavelet (4 vanishing moments)
    Wavelet::Sym(4),        // Symlet wavelet (4 vanishing moments)
    Wavelet::Coif(3),       // Coiflet wavelet (3 vanishing moments)
    Wavelet::Meyer,         // Meyer wavelet
];

// Discrete Wavelet Transform (DWT)
let signal = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0];
let (approx, detail) = dwt_decompose(&signal, Wavelet::DB(4), None)?;
let reconstructed = dwt_reconstruct(&approx, &detail, Wavelet::DB(4))?;

// Multi-level decomposition
let coeffs = wavedec(&signal, Wavelet::DB(4), 3)?; // 3 levels
let reconstructed = waverec(&coeffs, Wavelet::DB(4))?;

// Continuous Wavelet Transform (CWT)
let scales = vec![1.0, 2.0, 4.0, 8.0, 16.0];
let cwt_result = cwt(&signal, morlet, &scales)?;

// Wavelet denoising
let denoised = denoise_wavelet(
    &noisy_signal,
    Wavelet::DB(4),
    3,                      // Decomposition levels
    ThresholdMethod::Soft,  // Soft thresholding
    ThresholdSelect::Universal, // Universal threshold
    None,
)?;

Integration with Other SciRS2 Modules

Seamless integration with the SciRS2 ecosystem:

use scirs2_signal::spectral;
use scirs2_fft::fft;
use scirs2_core::error::CoreResult;
use ndarray::Array1;

// Combined usage with scirs2-fft
let data: Array1<f64> = array![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0];

// Direct FFT computation
let fft_result = fft::fft(&data)?;

// Power spectral density estimation
let (freq, psd) = spectral::welch(&data, None, None, None, None, Some(1000.0))?;

// Filter design and application
let (b, a) = filter::butter(4, &[0.1], "lowpass", None, None)?;
let filtered = filter::filtfilt(&b, &a, &data)?;

Development Status

Current Release: 0.1.0-rc.4

Production-Ready Features ✅

• Digital filtering (IIR/FIR design and application)
• Basic spectral analysis (periodogram, Welch's method, STFT)
• Core wavelet transforms (DWT, CWT)
• Signal convolution and correlation
• Peak detection and signal measurements
• Waveform generation and basic resampling

Experimental Features ⚠️

• Advanced time-frequency analysis
• 2D wavelet transforms
• Advanced denoising and restoration
• Real-time processing capabilities

Note: Experimental features may have API changes or require additional validation.

Contributing

See the CONTRIBUTING.md file for contribution guidelines.

License

This project is dual-licensed under:

• MIT License
• Apache License Version 2.0

You can choose to use either license. See the LICENSE file for details.