Skip to main content

mnn_runtime/
tensor.rs

1//! Owned tensor data and metadata.
2
3use crate::{Error, Result};
4
5/// Model tensor metadata at load time. Nonpositive dimensions are unresolved.
6/// Use returned `Tensor` shapes for the actual dimensions of a particular run.
7#[derive(Debug, Clone, PartialEq, Eq)]
8pub struct TensorInfo {
9    name: String,
10    shape: Vec<i32>,
11    channel_last: bool,
12}
13
14impl TensorInfo {
15    pub(crate) fn checked(name: String, shape: Vec<i32>, channel_last: bool) -> Result<Self> {
16        let info = Self {
17            name,
18            shape,
19            channel_last,
20        };
21        if !info.is_dynamic() {
22            let shape = info.concrete_shape()?;
23            checked_elements(info.name(), &shape)?;
24        }
25        Ok(info)
26    }
27
28    #[cfg(test)]
29    pub(crate) fn new(name: String, shape: Vec<i32>) -> Self {
30        Self::checked(name, shape, false).expect("test tensor shape")
31    }
32
33    /// Whether dimensions/values use channel-last order (NHWC for rank four).
34    #[must_use]
35    pub fn is_channel_last(&self) -> bool {
36        self.channel_last
37    }
38
39    /// Tensor name from the MNN graph.
40    #[must_use]
41    pub fn name(&self) -> &str {
42        &self.name
43    }
44
45    /// Signed graph dimensions. Nonpositive dimensions require concrete inputs.
46    /// An output awaiting its first resize is represented by `[-1]`.
47    #[must_use]
48    pub fn shape(&self) -> &[i32] {
49        &self.shape
50    }
51
52    /// Whether one or more dimensions are unresolved.
53    #[must_use]
54    pub fn is_dynamic(&self) -> bool {
55        self.shape.iter().any(|&d| d <= 0)
56    }
57
58    /// Concrete dimensions, when known.
59    ///
60    /// # Errors
61    /// Returns `UnresolvedShape` if dimensions still depend on the input.
62    pub fn concrete_shape(&self) -> Result<Vec<usize>> {
63        self.shape
64            .iter()
65            .map(|&d| {
66                usize::try_from(d)
67                    .ok()
68                    .filter(|&d| d > 0)
69                    .ok_or_else(|| Error::UnresolvedShape {
70                        name: self.name.clone(),
71                    })
72            })
73            .collect()
74    }
75
76    /// Number of f32 elements, or `None` until all dimensions are known.
77    #[must_use]
78    pub fn element_count(&self) -> Option<usize> {
79        self.concrete_shape()
80            .ok()
81            .and_then(|shape| checked_elements(&self.name, &shape).ok())
82    }
83}
84
85// MNN uses signed int sizes. Reserve headroom for packed channels (NC4HW4).
86fn checked_elements(name: &str, shape: &[usize]) -> Result<usize> {
87    if shape.len() > 8 || shape.contains(&0) {
88        return Err(Error::InvalidShape {
89            name: name.to_owned(),
90            shape: shape.to_vec(),
91        });
92    }
93    shape
94        .iter()
95        .try_fold(1_usize, |n, &d| n.checked_mul(d))
96        .filter(|&n| n <= i32::MAX as usize / std::mem::size_of::<f32>() / 4)
97        .ok_or_else(|| Error::ShapeOverflow {
98            name: name.to_owned(),
99        })
100}
101
102/// Owned `f32` tensor passed to or returned from a model.
103#[derive(Debug, Clone, PartialEq)]
104pub struct Tensor {
105    name: String,
106    shape: Vec<usize>,
107    data: Vec<f32>,
108}
109
110impl Tensor {
111    /// Build a named tensor and validate its element count.
112    ///
113    /// # Errors
114    ///
115    /// Returns an error for zero dimensions, rank above eight, shapes exceeding
116    /// native allocation limits, or data length differing from the element count.
117    pub fn new(
118        name: impl Into<String>,
119        shape: impl Into<Vec<usize>>,
120        data: impl Into<Vec<f32>>,
121    ) -> Result<Self> {
122        let name = name.into();
123        let shape = shape.into();
124        let data = data.into();
125        let expected = checked_elements(&name, &shape)?;
126        if expected != data.len() {
127            return Err(Error::DataLengthMismatch {
128                name,
129                expected,
130                actual: data.len(),
131            });
132        }
133        Ok(Self { name, shape, data })
134    }
135
136    pub(crate) fn resize_output(&mut self, shape: Vec<usize>) -> Result<()> {
137        let count = checked_elements(&self.name, &shape)?;
138        self.data.resize(count, 0.0);
139        self.shape = shape;
140        Ok(())
141    }
142
143    /// Tensor name.
144    #[must_use]
145    pub fn name(&self) -> &str {
146        &self.name
147    }
148
149    /// Tensor dimensions.
150    #[must_use]
151    pub fn shape(&self) -> &[usize] {
152        &self.shape
153    }
154
155    /// Contiguous tensor values.
156    #[must_use]
157    pub fn data(&self) -> &[f32] {
158        &self.data
159    }
160
161    /// Mutate values while preserving the validated length and shape.
162    pub fn data_mut(&mut self) -> &mut [f32] {
163        &mut self.data
164    }
165
166    /// Consume the tensor and return its contiguous values.
167    #[must_use]
168    pub fn into_data(self) -> Vec<f32> {
169        self.data
170    }
171}
172
173#[cfg(test)]
174mod tests {
175    use super::*;
176
177    #[test]
178    fn validates_data_length() {
179        let error = Tensor::new("image", [1, 3, 2, 2].to_vec(), vec![0.0; 11])
180            .expect_err("eleven values cannot fill a twelve-element tensor");
181        assert!(matches!(error, Error::DataLengthMismatch { .. }));
182    }
183}