solvr 0.2.0

Advanced computing library for real-world problem solving - optimization, differential equations, interpolation, statistics, and more
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! Local extrema detection algorithm traits.
//!
//! Provides algorithms for finding local minima and maxima in signals.
use crate::DType;

use numr::error::Result;
use numr::runtime::Runtime;
use numr::tensor::Tensor;

/// Mode for handling boundaries when finding extrema.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ExtremumMode {
    /// Wrap around at boundaries (periodic signal).
    Wrap,
    /// Clip comparisons at boundaries (no wraparound).
    #[default]
    Clip,
}

/// Result from extrema detection.
#[derive(Debug, Clone)]
pub struct ExtremaResult<R: Runtime<DType = DType>> {
    /// Indices of detected extrema.
    pub indices: Vec<usize>,
    /// Values at extrema locations.
    pub values: Tensor<R>,
}

/// Local extrema detection algorithms.
///
/// All backends implementing extrema detection MUST implement this trait
/// using the EXACT SAME ALGORITHMS to ensure numerical parity.
pub trait ExtremaAlgorithms<R: Runtime<DType = DType>> {
    /// Find local minima in a 1D signal.
    ///
    /// A point is a local minimum if it's smaller than all points within
    /// `order` samples on either side.
    ///
    /// # Arguments
    ///
    /// * `x` - Input signal (1D tensor)
    /// * `order` - Number of samples to compare on each side (default: 1)
    /// * `mode` - How to handle boundaries (Wrap or Clip)
    ///
    /// # Returns
    ///
    /// [`ExtremaResult`] containing indices and values of local minima.
    ///
    /// # Example
    ///
    /// For order=1, a point x`[i]` is a local minimum if:
    /// - x`[i]` < x`[i-1]` AND x`[i]` < x`[i+1]`
    ///
    /// For order=2, a point x`[i]` is a local minimum if:
    /// - x`[i]` < x`[i-2]` AND x`[i]` < x`[i-1]` AND x`[i]` < x`[i+1]` AND x`[i]` < x`[i+2]`
    fn argrelmin(
        &self,
        x: &Tensor<R>,
        order: usize,
        mode: ExtremumMode,
    ) -> Result<ExtremaResult<R>>;

    /// Find local maxima in a 1D signal.
    ///
    /// A point is a local maximum if it's larger than all points within
    /// `order` samples on either side.
    ///
    /// # Arguments
    ///
    /// * `x` - Input signal (1D tensor)
    /// * `order` - Number of samples to compare on each side (default: 1)
    /// * `mode` - How to handle boundaries (Wrap or Clip)
    ///
    /// # Returns
    ///
    /// [`ExtremaResult`] containing indices and values of local maxima.
    fn argrelmax(
        &self,
        x: &Tensor<R>,
        order: usize,
        mode: ExtremumMode,
    ) -> Result<ExtremaResult<R>>;

    /// Find both local minima and maxima in a 1D signal.
    ///
    /// Convenience function that calls both `argrelmin` and `argrelmax`.
    ///
    /// # Arguments
    ///
    /// * `x` - Input signal (1D tensor)
    /// * `order` - Number of samples to compare on each side (default: 1)
    /// * `mode` - How to handle boundaries (Wrap or Clip)
    ///
    /// # Returns
    ///
    /// Tuple of (minima, maxima) as [`ExtremaResult`]s.
    fn argrelextrema(
        &self,
        x: &Tensor<R>,
        order: usize,
        mode: ExtremumMode,
    ) -> Result<(ExtremaResult<R>, ExtremaResult<R>)> {
        let minima = self.argrelmin(x, order, mode)?;
        let maxima = self.argrelmax(x, order, mode)?;
        Ok((minima, maxima))
    }
}