matten 0.21.2

A family-car multidimensional array (tensor) library for small numerical trials / PoCs.
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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//! Elementwise comfort math on numeric tensors (RFC-038).
//!
//! These are small, familiar `f64` transforms applied to every element. Each
//! preserves shape and follows ordinary `f64` NaN/Inf behavior (for example,
//! `sqrt` of a negative value is `NaN`, `ln(0.0)` is `-inf`). They are numeric-only:
//! on a dynamic tensor the convenience forms panic with an `Unsupported` message,
//! and the `try_*` form returns [`MattenError::Unsupported`]. Call
//! [`Tensor::try_numeric`](crate::Tensor::try_numeric) first to convert.

use crate::{MattenError, Tensor};

impl Tensor {
    /// Builds a new numeric tensor with this tensor's shape from a per-element map.
    ///
    /// Caller must ensure `self` is non-dynamic (the public methods guard first).
    fn map_unchecked(&self, f: impl Fn(f64) -> f64) -> Tensor {
        Tensor {
            data: self.data.iter().map(|&v| f(v)).collect(),
            shape: self.shape.clone(),
            #[cfg(feature = "dynamic")]
            dynamic: None,
        }
    }

    /// Elementwise absolute value. Shape is preserved.
    ///
    /// ```
    /// use matten::Tensor;
    /// let t = Tensor::new(vec![-1.0, 2.0, -3.0, 4.0], &[2, 2]);
    /// assert_eq!(t.abs().as_slice(), &[1.0, 2.0, 3.0, 4.0]);
    /// ```
    #[must_use]
    pub fn abs(&self) -> Tensor {
        #[cfg(feature = "dynamic")]
        self.panic_if_dynamic("abs");
        self.map_unchecked(f64::abs)
    }

    /// Elementwise square root. Shape is preserved; a negative element yields `NaN`.
    ///
    /// ```
    /// use matten::Tensor;
    /// let t = Tensor::from_vec(vec![1.0, 4.0, 9.0]);
    /// assert_eq!(t.sqrt().as_slice(), &[1.0, 2.0, 3.0]);
    /// ```
    #[must_use]
    pub fn sqrt(&self) -> Tensor {
        #[cfg(feature = "dynamic")]
        self.panic_if_dynamic("sqrt");
        self.map_unchecked(f64::sqrt)
    }

    /// Elementwise natural exponential `e^x`. Shape is preserved.
    ///
    /// ```
    /// use matten::Tensor;
    /// let t = Tensor::from_vec(vec![0.0, 1.0]);
    /// let r = t.exp();
    /// assert_eq!(r.as_slice()[0], 1.0);
    /// assert!((r.as_slice()[1] - std::f64::consts::E).abs() < 1e-12);
    /// ```
    #[must_use]
    pub fn exp(&self) -> Tensor {
        #[cfg(feature = "dynamic")]
        self.panic_if_dynamic("exp");
        self.map_unchecked(f64::exp)
    }

    /// Elementwise natural logarithm. Shape is preserved; `ln(0.0)` is `-inf` and a
    /// negative element yields `NaN`.
    ///
    /// ```
    /// use matten::Tensor;
    /// let t = Tensor::from_vec(vec![1.0, std::f64::consts::E]);
    /// let r = t.ln();
    /// assert_eq!(r.as_slice()[0], 0.0);
    /// assert!((r.as_slice()[1] - 1.0).abs() < 1e-12);
    /// ```
    #[must_use]
    pub fn ln(&self) -> Tensor {
        #[cfg(feature = "dynamic")]
        self.panic_if_dynamic("ln");
        self.map_unchecked(f64::ln)
    }

    /// Elementwise clamp into `[min, max]`. Shape is preserved.
    ///
    /// # Panics
    /// Panics if `min > max` (or either bound is `NaN`). Use [`Tensor::try_clip`]
    /// for the non-panicking form.
    ///
    /// ```
    /// use matten::Tensor;
    /// let t = Tensor::from_vec(vec![-5.0, 0.5, 9.0]);
    /// assert_eq!(t.clip(0.0, 1.0).as_slice(), &[0.0, 0.5, 1.0]);
    /// ```
    #[must_use]
    pub fn clip(&self, min: f64, max: f64) -> Tensor {
        #[cfg(feature = "dynamic")]
        self.panic_if_dynamic("clip");
        assert!(
            min <= max,
            "matten invalid argument error in clip: min/max: min must be <= max (got min={min}, max={max})"
        );
        self.map_unchecked(|v| v.clamp(min, max))
    }

    /// Non-panicking [`Tensor::clip`].
    ///
    /// Returns [`MattenError::InvalidArgument`] if `min > max`, or
    /// [`MattenError::Unsupported`] if called on a dynamic tensor.
    ///
    /// ```
    /// use matten::Tensor;
    /// let t = Tensor::from_vec(vec![-5.0, 0.5, 9.0]);
    /// assert_eq!(t.try_clip(0.0, 1.0).unwrap().as_slice(), &[0.0, 0.5, 1.0]);
    /// assert!(t.try_clip(1.0, 0.0).is_err());
    /// ```
    pub fn try_clip(&self, min: f64, max: f64) -> Result<Tensor, MattenError> {
        #[cfg(feature = "dynamic")]
        if self.is_dynamic() {
            return Err(MattenError::Unsupported {
                operation: "clip",
                message: "clip is not supported on dynamic tensors; call try_numeric() first"
                    .to_string(),
            });
        }
        if min.is_nan() || max.is_nan() || min > max {
            return Err(MattenError::InvalidArgument {
                operation: "clip",
                argument: "min/max",
                message: format!("min must be <= max (got min={min}, max={max})"),
            });
        }
        Ok(self.map_unchecked(|v| v.clamp(min, max)))
    }
}