Struct Tensor 

pub struct Tensor { /* private fields */ }

A dense, row-major, owned multidimensional array of f64.

Fields are private. The storage layout is never exposed across the public API. A scalar is shape [] with one element.

Examples

use matten::Tensor;

// 2×2 matrix
let m = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
assert!(m.is_matrix());

// Fill constructors
let z = Tensor::zeros(&[3]);
assert_eq!(z.as_slice(), &[0.0, 0.0, 0.0]);

// Range constructor
let r = Tensor::arange(0.0, 5.0, 1.0);
assert_eq!(r.len(), 5);

Implementations

impl Tensor

pub fn linspace(start: f64, end: f64, count: usize) -> Tensor

Creates a 1-D tensor of count evenly spaced values from start to end (inclusive of both endpoints when count >= 2).

count == 1 returns [start]. Element values follow ordinary f64 behavior, so non-finite bounds propagate.

Panics

Panics if count == 0 (a zero-sized dimension) or the result exceeds the allocation limit. Use Tensor::try_linspace for the non-panicking form.

use matten::Tensor;
assert_eq!(Tensor::linspace(0.0, 1.0, 5).as_slice(), &[0.0, 0.25, 0.5, 0.75, 1.0]);
assert_eq!(Tensor::linspace(2.0, 9.0, 1).as_slice(), &[2.0]);

Examples found in repository

examples/40_trapezoidal_integration.rs (line 39)

fn main() {
    // Evenly spaced sample grid on [0, 1].
    let x = Tensor::linspace(0.0, 1.0, 11);
    let xs = x.as_slice();
    let h = xs[1] - xs[0];

    // f(x) = x^2, evaluated with elementwise multiplication.
    let f = &x * &x;
    let fs = f.as_slice();
    let n = fs.len();

    // Composite trapezoidal rule: h * (Σ f - (f_first + f_last)/2).
    let estimate = h * (f.sum() - (fs[0] + fs[n - 1]) / 2.0);
    let exact = 1.0 / 3.0; // ∫_0^1 x^2 dx = 1/3
    let err = (estimate - exact).abs();

    println!("trapezoidal estimate: {estimate:.6}");
    println!("exact integral (1/3): {exact:.6}");
    println!("abs error:            {err:.6}");

    assert!(err < 0.01);
    println!("Trapezoidal integration: OK");
}

examples/39_finite_difference_derivative.rs (line 45)

fn main() {
    // Evenly spaced sample grid on [0, 2].
    let x = Tensor::linspace(0.0, 2.0, 9);
    let xs = x.as_slice();
    let h = xs[1] - xs[0];

    // f(x) = x^3, evaluated with elementwise Tensor multiplication.
    let x2 = &x * &x;
    let f = &x2 * &x;
    let fs = f.as_slice();

    println!("h = {h}");
    println!("   x    f'approx   f'exact");
    let mut max_err = 0.0f64;
    for i in 1..xs.len() - 1 {
        let approx = (fs[i + 1] - fs[i - 1]) / (2.0 * h);
        let exact = 3.0 * xs[i] * xs[i]; // d/dx x^3 = 3x^2
        let err = (approx - exact).abs();
        max_err = max_err.max(err);
        println!("{:4.2}     {:6.4}    {:6.4}", xs[i], approx, exact);
        // Central difference of x^3 has error exactly h^2.
        assert!((approx - (exact + h * h)).abs() < 1e-9);
    }
    println!("max abs error = {max_err:.4} (= h^2 = {:.4})", h * h);
    assert!((max_err - h * h).abs() < 1e-9);
    println!("Finite-difference derivative: OK");
}

pub fn try_linspace( start: f64, end: f64, count: usize, ) -> Result<Tensor, MattenError>

Non-panicking Tensor::linspace.

Errors

Returns MattenError::Shape if count == 0, or MattenError::Allocation if the result exceeds the element limit.

use matten::Tensor;
assert!(Tensor::try_linspace(0.0, 1.0, 0).is_err());

pub fn eye(n: usize) -> Tensor

Creates an n × n identity matrix (1.0 on the diagonal, 0.0 elsewhere).

Panics

Panics if n == 0 (a zero-sized dimension) or the result exceeds the allocation limit. Use Tensor::try_eye for the non-panicking form.

use matten::Tensor;
let i = Tensor::eye(3);
assert_eq!(i.shape(), &[3, 3]);
assert_eq!(i.as_slice(), &[1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]);

pub fn try_eye(n: usize) -> Result<Tensor, MattenError>

Non-panicking Tensor::eye.

Errors

Returns MattenError::Shape if n == 0, or MattenError::Allocation if the result exceeds the element limit.

use matten::Tensor;
assert!(Tensor::try_eye(0).is_err());

impl Tensor

pub fn try_zeros(shape: &[usize]) -> Result<Tensor, MattenError>

Creates a zero tensor, returning an error instead of panicking.

Uses the default MattenLimits. For a custom budget use try_zeros_with_limits.

Errors

Returns MattenError for invalid shape, overflow, or exceeding the default element budget.

Examples

use matten::Tensor;

let t = Tensor::try_zeros(&[3, 4]).unwrap();
assert_eq!(t.shape(), &[3, 4]);
assert_eq!(t.as_slice(), &[0.0f64; 12]);

Examples found in repository

examples/13_resource_limits.rs (line 22)

fn main() {
    // ── Default limits ────────────────────────────────────────────────────
    let limits = MattenLimits::default();
    println!("Default max_dimensions: {}", limits.max_dimensions);
    println!(
        "Default max_elements:   {} (~{} MiB f64)",
        limits.max_elements,
        limits.max_elements * 8 / 1_048_576
    );

    // ── Boundary-safe constructors ────────────────────────────────────────
    let t = Tensor::try_zeros(&[100, 100]).unwrap();
    assert_eq!(t.shape(), &[100, 100]);
    assert_eq!(t.len(), 10_000);
    println!("try_zeros([100, 100]): OK, {} elements", t.len());

    let t = Tensor::try_ones(&[50, 20]).unwrap();
    assert_eq!(t.as_slice().iter().sum::<f64>(), 1000.0);
    println!("try_ones([50, 20]):    OK, sum = {}", t.sum());

    let t = Tensor::try_full(&[10, 10], -1.0).unwrap();
    assert_eq!(t.as_slice()[0], -1.0);
    println!("try_full([10, 10], -1.0): OK");

    // ── Custom limits ─────────────────────────────────────────────────────
    let tight = MattenLimits {
        max_elements: 10,
        ..MattenLimits::default()
    };
    let err = Tensor::try_zeros_with_limits(&[100], &tight).unwrap_err();
    assert!(matches!(err, MattenError::Allocation { .. }));
    println!("Custom limit (max=10): correctly rejected [100]");

    // ── Panicking variants respect limits too ─────────────────────────────
    // These delegate to try_zeros/try_ones/try_full internally:
    let _t = Tensor::zeros(&[10, 10]); // fine — 100 elements
    println!("zeros([10, 10]):        OK (panicking form, within limit)");

    println!("done.");
}

pub fn try_zeros_with_limits( shape: &[usize], limits: &MattenLimits, ) -> Result<Tensor, MattenError>

Creates a zero tensor with explicit limits.

Examples found in repository

examples/13_resource_limits.rs (line 40)

fn main() {
    // ── Default limits ────────────────────────────────────────────────────
    let limits = MattenLimits::default();
    println!("Default max_dimensions: {}", limits.max_dimensions);
    println!(
        "Default max_elements:   {} (~{} MiB f64)",
        limits.max_elements,
        limits.max_elements * 8 / 1_048_576
    );

    // ── Boundary-safe constructors ────────────────────────────────────────
    let t = Tensor::try_zeros(&[100, 100]).unwrap();
    assert_eq!(t.shape(), &[100, 100]);
    assert_eq!(t.len(), 10_000);
    println!("try_zeros([100, 100]): OK, {} elements", t.len());

    let t = Tensor::try_ones(&[50, 20]).unwrap();
    assert_eq!(t.as_slice().iter().sum::<f64>(), 1000.0);
    println!("try_ones([50, 20]):    OK, sum = {}", t.sum());

    let t = Tensor::try_full(&[10, 10], -1.0).unwrap();
    assert_eq!(t.as_slice()[0], -1.0);
    println!("try_full([10, 10], -1.0): OK");

    // ── Custom limits ─────────────────────────────────────────────────────
    let tight = MattenLimits {
        max_elements: 10,
        ..MattenLimits::default()
    };
    let err = Tensor::try_zeros_with_limits(&[100], &tight).unwrap_err();
    assert!(matches!(err, MattenError::Allocation { .. }));
    println!("Custom limit (max=10): correctly rejected [100]");

    // ── Panicking variants respect limits too ─────────────────────────────
    // These delegate to try_zeros/try_ones/try_full internally:
    let _t = Tensor::zeros(&[10, 10]); // fine — 100 elements
    println!("zeros([10, 10]):        OK (panicking form, within limit)");

    println!("done.");
}

pub fn try_ones(shape: &[usize]) -> Result<Tensor, MattenError>

Creates a ones tensor, returning an error instead of panicking.

Uses the default MattenLimits.

Examples

use matten::Tensor;

let t = Tensor::try_ones(&[2, 3]).unwrap();
assert_eq!(t.as_slice(), &[1.0f64; 6]);

Examples found in repository

examples/13_resource_limits.rs (line 27)

fn main() {
    // ── Default limits ────────────────────────────────────────────────────
    let limits = MattenLimits::default();
    println!("Default max_dimensions: {}", limits.max_dimensions);
    println!(
        "Default max_elements:   {} (~{} MiB f64)",
        limits.max_elements,
        limits.max_elements * 8 / 1_048_576
    );

    // ── Boundary-safe constructors ────────────────────────────────────────
    let t = Tensor::try_zeros(&[100, 100]).unwrap();
    assert_eq!(t.shape(), &[100, 100]);
    assert_eq!(t.len(), 10_000);
    println!("try_zeros([100, 100]): OK, {} elements", t.len());

    let t = Tensor::try_ones(&[50, 20]).unwrap();
    assert_eq!(t.as_slice().iter().sum::<f64>(), 1000.0);
    println!("try_ones([50, 20]):    OK, sum = {}", t.sum());

    let t = Tensor::try_full(&[10, 10], -1.0).unwrap();
    assert_eq!(t.as_slice()[0], -1.0);
    println!("try_full([10, 10], -1.0): OK");

    // ── Custom limits ─────────────────────────────────────────────────────
    let tight = MattenLimits {
        max_elements: 10,
        ..MattenLimits::default()
    };
    let err = Tensor::try_zeros_with_limits(&[100], &tight).unwrap_err();
    assert!(matches!(err, MattenError::Allocation { .. }));
    println!("Custom limit (max=10): correctly rejected [100]");

    // ── Panicking variants respect limits too ─────────────────────────────
    // These delegate to try_zeros/try_ones/try_full internally:
    let _t = Tensor::zeros(&[10, 10]); // fine — 100 elements
    println!("zeros([10, 10]):        OK (panicking form, within limit)");

    println!("done.");
}

pub fn try_ones_with_limits( shape: &[usize], limits: &MattenLimits, ) -> Result<Tensor, MattenError>

Creates a ones tensor with explicit limits.

pub fn try_full(shape: &[usize], value: f64) -> Result<Tensor, MattenError>

Creates a tensor filled with value, returning an error instead of panicking.

Uses the default MattenLimits.

Examples

use matten::Tensor;

let t = Tensor::try_full(&[2, 2], 7.0).unwrap();
assert_eq!(t.as_slice(), &[7.0f64; 4]);

Examples found in repository

examples/13_resource_limits.rs (line 31)

fn main() {
    // ── Default limits ────────────────────────────────────────────────────
    let limits = MattenLimits::default();
    println!("Default max_dimensions: {}", limits.max_dimensions);
    println!(
        "Default max_elements:   {} (~{} MiB f64)",
        limits.max_elements,
        limits.max_elements * 8 / 1_048_576
    );

    // ── Boundary-safe constructors ────────────────────────────────────────
    let t = Tensor::try_zeros(&[100, 100]).unwrap();
    assert_eq!(t.shape(), &[100, 100]);
    assert_eq!(t.len(), 10_000);
    println!("try_zeros([100, 100]): OK, {} elements", t.len());

    let t = Tensor::try_ones(&[50, 20]).unwrap();
    assert_eq!(t.as_slice().iter().sum::<f64>(), 1000.0);
    println!("try_ones([50, 20]):    OK, sum = {}", t.sum());

    let t = Tensor::try_full(&[10, 10], -1.0).unwrap();
    assert_eq!(t.as_slice()[0], -1.0);
    println!("try_full([10, 10], -1.0): OK");

    // ── Custom limits ─────────────────────────────────────────────────────
    let tight = MattenLimits {
        max_elements: 10,
        ..MattenLimits::default()
    };
    let err = Tensor::try_zeros_with_limits(&[100], &tight).unwrap_err();
    assert!(matches!(err, MattenError::Allocation { .. }));
    println!("Custom limit (max=10): correctly rejected [100]");

    // ── Panicking variants respect limits too ─────────────────────────────
    // These delegate to try_zeros/try_ones/try_full internally:
    let _t = Tensor::zeros(&[10, 10]); // fine — 100 elements
    println!("zeros([10, 10]):        OK (panicking form, within limit)");

    println!("done.");
}

pub fn try_full_with_limits( shape: &[usize], value: f64, limits: &MattenLimits, ) -> Result<Tensor, MattenError>

Creates a filled tensor with explicit limits.

impl Tensor

pub fn sum(&self) -> f64

Returns the sum of all elements.

NaN propagates naturally (IEEE 754).

use matten::Tensor;
assert_eq!(Tensor::from_vec(vec![1.0, 2.0, 3.0]).sum(), 6.0);
assert!(Tensor::from_vec(vec![1.0, f64::NAN]).sum().is_nan());

Examples found in repository

examples/rolling_windows_basic.rs (line 9)

fn rolling_sum(t: &Tensor, window: usize) -> Vec<f64> {
    (0..=(t.len() - window))
        .map(|i| t.slice().range(i..i + window).build().unwrap().sum())
        .collect()
}

examples/40_trapezoidal_integration.rs (line 49)

fn main() {
    // Evenly spaced sample grid on [0, 1].
    let x = Tensor::linspace(0.0, 1.0, 11);
    let xs = x.as_slice();
    let h = xs[1] - xs[0];

    // f(x) = x^2, evaluated with elementwise multiplication.
    let f = &x * &x;
    let fs = f.as_slice();
    let n = fs.len();

    // Composite trapezoidal rule: h * (Σ f - (f_first + f_last)/2).
    let estimate = h * (f.sum() - (fs[0] + fs[n - 1]) / 2.0);
    let exact = 1.0 / 3.0; // ∫_0^1 x^2 dx = 1/3
    let err = (estimate - exact).abs();

    println!("trapezoidal estimate: {estimate:.6}");
    println!("exact integral (1/3): {exact:.6}");
    println!("abs error:            {err:.6}");

    assert!(err < 0.01);
    println!("Trapezoidal integration: OK");
}

examples/23_sum_mean.rs (line 9)

fn main() {
    let v = Tensor::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0]);
    println!("v.sum()  = {}", v.sum()); // 15.0
    println!("v.mean() = {}", v.mean()); // 3.0

    // Axis reductions on a matrix
    // [[1,2,3],[4,5,6]]
    let m = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    println!("column sums   (axis 0) = {:?}", m.sum_axis(0).as_slice()); // [5,7,9]
    println!("row sums      (axis 1) = {:?}", m.sum_axis(1).as_slice()); // [6,15]
    println!("column means  (axis 0) = {:?}", m.mean_axis(0).as_slice()); // [2.5,3.5,4.5]
    println!("row means     (axis 1) = {:?}", m.mean_axis(1).as_slice()); // [2.0,5.0]

    assert_eq!(m.sum_axis(0).as_slice(), &[5.0, 7.0, 9.0]);
    assert_eq!(m.mean_axis(1).as_slice(), &[2.0, 5.0]);
    println!("Assertions passed: OK");
}

examples/13_resource_limits.rs (line 29)

fn main() {
    // ── Default limits ────────────────────────────────────────────────────
    let limits = MattenLimits::default();
    println!("Default max_dimensions: {}", limits.max_dimensions);
    println!(
        "Default max_elements:   {} (~{} MiB f64)",
        limits.max_elements,
        limits.max_elements * 8 / 1_048_576
    );

    // ── Boundary-safe constructors ────────────────────────────────────────
    let t = Tensor::try_zeros(&[100, 100]).unwrap();
    assert_eq!(t.shape(), &[100, 100]);
    assert_eq!(t.len(), 10_000);
    println!("try_zeros([100, 100]): OK, {} elements", t.len());

    let t = Tensor::try_ones(&[50, 20]).unwrap();
    assert_eq!(t.as_slice().iter().sum::<f64>(), 1000.0);
    println!("try_ones([50, 20]):    OK, sum = {}", t.sum());

    let t = Tensor::try_full(&[10, 10], -1.0).unwrap();
    assert_eq!(t.as_slice()[0], -1.0);
    println!("try_full([10, 10], -1.0): OK");

    // ── Custom limits ─────────────────────────────────────────────────────
    let tight = MattenLimits {
        max_elements: 10,
        ..MattenLimits::default()
    };
    let err = Tensor::try_zeros_with_limits(&[100], &tight).unwrap_err();
    assert!(matches!(err, MattenError::Allocation { .. }));
    println!("Custom limit (max=10): correctly rejected [100]");

    // ── Panicking variants respect limits too ─────────────────────────────
    // These delegate to try_zeros/try_ones/try_full internally:
    let _t = Tensor::zeros(&[10, 10]); // fine — 100 elements
    println!("zeros([10, 10]):        OK (panicking form, within limit)");

    println!("done.");
}

pub fn mean(&self) -> f64

Returns the arithmetic mean of all elements (sum / len).

NaN propagates. Behaviour on an empty tensor is unspecified (zero-sized dims are rejected by constructors in Phase 1).

use matten::Tensor;
assert_eq!(Tensor::from_vec(vec![1.0, 2.0, 3.0, 4.0]).mean(), 2.5);

Examples found in repository

examples/moving_average.rs (line 16)

fn main() {
    let series = Tensor::from_vec(vec![1.0, 3.0, 5.0, 7.0, 9.0, 11.0, 13.0]);
    let window = 3usize;
    let n = series.len();

    // Compute moving averages for windows [0..3], [1..4], ...
    let mut avgs = Vec::new();
    for start in 0..=(n - window) {
        let w = series.slice().range(start..start + window).build().unwrap();
        avgs.push(w.mean());
    }

    println!("series = {:?}", series.as_slice());
    println!("3-pt moving avg = {:?}", avgs);
    assert_eq!(avgs.len(), n - window + 1);
    assert!((avgs[0] - 3.0).abs() < 1e-10); // mean(1,3,5) = 3
    assert!((avgs[1] - 5.0).abs() < 1e-10); // mean(3,5,7) = 5
    println!("Moving average: OK");
}

examples/23_sum_mean.rs (line 10)

fn main() {
    let v = Tensor::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0]);
    println!("v.sum()  = {}", v.sum()); // 15.0
    println!("v.mean() = {}", v.mean()); // 3.0

    // Axis reductions on a matrix
    // [[1,2,3],[4,5,6]]
    let m = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    println!("column sums   (axis 0) = {:?}", m.sum_axis(0).as_slice()); // [5,7,9]
    println!("row sums      (axis 1) = {:?}", m.sum_axis(1).as_slice()); // [6,15]
    println!("column means  (axis 0) = {:?}", m.mean_axis(0).as_slice()); // [2.5,3.5,4.5]
    println!("row means     (axis 1) = {:?}", m.mean_axis(1).as_slice()); // [2.0,5.0]

    assert_eq!(m.sum_axis(0).as_slice(), &[5.0, 7.0, 9.0]);
    assert_eq!(m.mean_axis(1).as_slice(), &[2.0, 5.0]);
    println!("Assertions passed: OK");
}

pub fn min(&self) -> f64

Returns the minimum element.

Returns NaN if any element is NaN (explicit NaN-propagation; do not use f64::min which silently ignores NaN).

use matten::Tensor;
assert_eq!(Tensor::from_vec(vec![3.0, 1.0, 2.0]).min(), 1.0);
assert!(Tensor::from_vec(vec![1.0, f64::NAN, 3.0]).min().is_nan());

Examples found in repository

examples/24_min_max.rs (line 12)

fn main() {
    let v = Tensor::from_vec(vec![3.0, 1.0, 4.0, 1.0, 5.0, 9.0, 2.0]);
    println!("min = {}", v.min()); // 1.0
    println!("max = {}", v.max()); // 9.0

    // NaN policy: any NaN -> result is NaN
    let with_nan = Tensor::from_vec(vec![1.0, f64::NAN, 3.0]);
    println!("min with NaN = {}", with_nan.min()); // NaN
    println!("max with NaN = {}", with_nan.max()); // NaN
    assert!(with_nan.min().is_nan());
    assert!(with_nan.max().is_nan());

    // Inf is handled normally
    let with_inf = Tensor::from_vec(vec![1.0, f64::INFINITY, -1.0]);
    println!("min with +inf = {}", with_inf.min()); // -1.0
    println!("max with +inf = {}", with_inf.max()); // inf

    println!("NaN policy verified: OK");
}

pub fn max(&self) -> f64

Returns the maximum element.

Returns NaN if any element is NaN.

use matten::Tensor;
assert_eq!(Tensor::from_vec(vec![3.0, 1.0, 2.0]).max(), 3.0);
assert!(Tensor::from_vec(vec![1.0, f64::NAN, 3.0]).max().is_nan());

Examples found in repository

examples/rolling_windows_basic.rs (line 15)

fn rolling_max(t: &Tensor, window: usize) -> Vec<f64> {
    (0..=(t.len() - window))
        .map(|i| t.slice().range(i..i + window).build().unwrap().max())
        .collect()
}

examples/24_min_max.rs (line 13)

fn main() {
    let v = Tensor::from_vec(vec![3.0, 1.0, 4.0, 1.0, 5.0, 9.0, 2.0]);
    println!("min = {}", v.min()); // 1.0
    println!("max = {}", v.max()); // 9.0

    // NaN policy: any NaN -> result is NaN
    let with_nan = Tensor::from_vec(vec![1.0, f64::NAN, 3.0]);
    println!("min with NaN = {}", with_nan.min()); // NaN
    println!("max with NaN = {}", with_nan.max()); // NaN
    assert!(with_nan.min().is_nan());
    assert!(with_nan.max().is_nan());

    // Inf is handled normally
    let with_inf = Tensor::from_vec(vec![1.0, f64::INFINITY, -1.0]);
    println!("min with +inf = {}", with_inf.min()); // -1.0
    println!("max with +inf = {}", with_inf.max()); // inf

    println!("NaN policy verified: OK");
}

examples/rowwise_scoring.rs (line 25)

fn main() {
    // 3 items × 4 features
    let features = Tensor::new(
        vec![0.8, 0.6, 0.9, 0.7, 0.4, 0.9, 0.5, 0.8, 0.7, 0.7, 0.8, 0.6],
        &[3, 4],
    );

    // Importance weights per feature: shape [4], broadcast across rows
    let weights = Tensor::new(vec![0.3, 0.2, 0.4, 0.1], &[4]);

    // Weighted feature matrix: [3,4]
    let weighted = &features * &weights;

    // Score per item: sum across features (axis 1) -> shape [3]
    let scores = weighted.sum_axis(1);
    println!("scores = {:?}", scores.as_slice());

    // Best item (highest score)
    let best_score = scores.max();
    println!("best score = {best_score:.3}");

    assert_eq!(scores.shape(), &[3]);
    println!("Row-wise scoring: OK");
}

impl Tensor

pub fn sum_axis(&self, axis: usize) -> Tensor

Reduces along axis by summing, removing that axis from the output shape.

Panics

Panics if axis >= self.ndim().

use matten::Tensor;
// [[1,2,3],[4,5,6]] summed along axis 0 -> [5,7,9]
let m = Tensor::new(vec![1.0,2.0,3.0,4.0,5.0,6.0], &[2,3]);
let r = m.sum_axis(0);
assert_eq!(r.shape(), &[3]);
assert_eq!(r.as_slice(), &[5.0, 7.0, 9.0]);

Examples found in repository

examples/rowwise_scoring.rs (line 21)

fn main() {
    // 3 items × 4 features
    let features = Tensor::new(
        vec![0.8, 0.6, 0.9, 0.7, 0.4, 0.9, 0.5, 0.8, 0.7, 0.7, 0.8, 0.6],
        &[3, 4],
    );

    // Importance weights per feature: shape [4], broadcast across rows
    let weights = Tensor::new(vec![0.3, 0.2, 0.4, 0.1], &[4]);

    // Weighted feature matrix: [3,4]
    let weighted = &features * &weights;

    // Score per item: sum across features (axis 1) -> shape [3]
    let scores = weighted.sum_axis(1);
    println!("scores = {:?}", scores.as_slice());

    // Best item (highest score)
    let best_score = scores.max();
    println!("best score = {best_score:.3}");

    assert_eq!(scores.shape(), &[3]);
    println!("Row-wise scoring: OK");
}

examples/23_sum_mean.rs (line 15)

fn main() {
    let v = Tensor::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0]);
    println!("v.sum()  = {}", v.sum()); // 15.0
    println!("v.mean() = {}", v.mean()); // 3.0

    // Axis reductions on a matrix
    // [[1,2,3],[4,5,6]]
    let m = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    println!("column sums   (axis 0) = {:?}", m.sum_axis(0).as_slice()); // [5,7,9]
    println!("row sums      (axis 1) = {:?}", m.sum_axis(1).as_slice()); // [6,15]
    println!("column means  (axis 0) = {:?}", m.mean_axis(0).as_slice()); // [2.5,3.5,4.5]
    println!("row means     (axis 1) = {:?}", m.mean_axis(1).as_slice()); // [2.0,5.0]

    assert_eq!(m.sum_axis(0).as_slice(), &[5.0, 7.0, 9.0]);
    assert_eq!(m.mean_axis(1).as_slice(), &[2.0, 5.0]);
    println!("Assertions passed: OK");
}

examples/pairwise_distance.rs (line 14)

fn pairwise_euclidean(points: &Tensor) -> Tensor {
    let n = points.shape()[0];

    // Row-wise squared norms: shape [n]
    let sq = points * points;
    let row_sq_norms = sq.sum_axis(1); // [n]

    // Gram matrix: G[i,j] = points[i] · points[j], shape [n,n]
    let gram = points.matmul(&points.transpose());

    // dist²[i,j] = sq_norm[i] + sq_norm[j] - 2·G[i,j]
    // Broadcast [n] as column [n,1] + row [1,n]
    let col = row_sq_norms.reshape(&[n, 1]);
    let row = row_sq_norms.reshape(&[1, n]);
    let dist_sq = &(&col + &row) - &(&gram * 2.0);

    // Clamp small negatives from floating-point rounding, then sqrt
    let dists: Vec<f64> = dist_sq
        .as_slice()
        .iter()
        .map(|&v| if v < 0.0 { 0.0 } else { v.sqrt() })
        .collect();
    Tensor::new(dists, &[n, n])
}

examples/27_axis_reductions.rs (line 23)

fn main() {
    // Shape [3, 4]: 3 rows, 4 columns
    let m = Tensor::new(
        vec![
            1.0, 2.0, 3.0, 4.0, // row 0
            5.0, 6.0, 7.0, 8.0, // row 1
            9.0, 10.0, 11.0, 12.0, // row 2
        ],
        &[3, 4],
    );

    // Reduce rows → column sums: shape [4]
    let col_sums = m.sum_axis(0);
    assert_eq!(col_sums.shape(), &[4]);
    assert_eq!(col_sums.as_slice(), &[15.0, 18.0, 21.0, 24.0]);
    println!("col sums  = {:?}", col_sums.as_slice());

    // Reduce columns → row means: shape [3]
    let row_means = m.mean_axis(1);
    assert_eq!(row_means.shape(), &[3]);
    assert_eq!(row_means.as_slice(), &[2.5, 6.5, 10.5]);
    println!("row means = {:?}", row_means.as_slice());

    // Column-wise min and max
    let col_min = m.min_axis(0);
    let col_max = m.max_axis(0);
    assert_eq!(col_min.as_slice(), &[1.0, 2.0, 3.0, 4.0]);
    assert_eq!(col_max.as_slice(), &[9.0, 10.0, 11.0, 12.0]);
    println!("col min   = {:?}", col_min.as_slice());
    println!("col max   = {:?}", col_max.as_slice());

    // NaN propagation: one NaN contaminates its column's min
    let with_nan = Tensor::new(vec![1.0, f64::NAN, 3.0, 5.0, 6.0, 7.0], &[2, 3]);
    let nan_col_min = with_nan.min_axis(0);
    assert!(nan_col_min.as_slice()[1].is_nan()); // column 1 had a NaN
    assert_eq!(nan_col_min.as_slice()[0], 1.0); // column 0 clean
    println!("NaN propagation confirmed");

    println!("done.");
}

pub fn mean_axis(&self, axis: usize) -> Tensor

Reduces along axis by computing the arithmetic mean.

Panics

Panics if axis >= self.ndim().

use matten::Tensor;
let m = Tensor::new(vec![1.0,2.0,3.0,4.0,5.0,6.0], &[2,3]);
let r = m.mean_axis(0);
assert_eq!(r.shape(), &[3]);
assert_eq!(r.as_slice(), &[2.5, 3.5, 4.5]);

Examples found in repository

examples/28_column_statistics.rs (line 16)

fn column_std(data: &Tensor, col_means: &Tensor) -> Tensor {
    // Broadcast means over all rows, compute squared deviations
    let deviations = data - col_means; // [rows, cols] - [cols] → [rows, cols]
    let sq = &deviations * &deviations;
    sq.mean_axis(0) // → [cols] mean of squared deviations
        .as_slice()
        .iter()
        .map(|v| v.sqrt())
        .collect::<Vec<f64>>()
        .into()
}

fn main() {
    // 4 rows, 3 columns (features)
    let data = Tensor::new(
        vec![
            1.0, 10.0, 100.0, 2.0, 20.0, 200.0, 3.0, 30.0, 300.0, 4.0, 40.0, 400.0,
        ],
        &[4, 3],
    );

    let means = data.mean_axis(0);
    let mins = data.min_axis(0);
    let maxs = data.max_axis(0);
    let stds = column_std(&data, &means);

    println!("columns : 0      1      2");
    println!("mean    : {:?}", means.as_slice());
    println!("min     : {:?}", mins.as_slice());
    println!("max     : {:?}", maxs.as_slice());
    println!("std dev : {:?}", stds.as_slice());

    assert_eq!(means.as_slice(), &[2.5, 25.0, 250.0]);
    assert_eq!(mins.as_slice(), &[1.0, 10.0, 100.0]);
    assert_eq!(maxs.as_slice(), &[4.0, 40.0, 400.0]);

    // Std dev: sqrt of mean squared deviation from mean
    let expected_std0 = {
        // Column 0 values: 1,2,3,4. Mean=2.5. Deviations: -1.5,-0.5,0.5,1.5
        let sq_devs = [
            1.5f64.powi(2),
            0.5f64.powi(2),
            0.5f64.powi(2),
            1.5f64.powi(2),
        ];
        (sq_devs.iter().sum::<f64>() / 4.0).sqrt()
    };
    assert!((stds.as_slice()[0] - expected_std0).abs() < 1e-10);

    println!("done.");
}

examples/column_summary.rs (line 15)

fn main() {
    let data = Tensor::new(
        vec![
            2.0, 5.0, 10.0, 4.0, 7.0, 20.0, 6.0, 3.0, 15.0, 8.0, 11.0, 25.0, 10.0, 9.0, 30.0,
        ],
        &[5, 3],
    );

    let means = data.mean_axis(0);
    let mins = data.min_axis(0);
    let maxes = data.max_axis(0);
    let centred = &data - &means;
    let variances = (&centred * &centred).mean_axis(0);
    let stds: Vec<f64> = variances.as_slice().iter().map(|v| v.sqrt()).collect();
    let stds_t = Tensor::new(stds, &[3]);

    println!("col means = {:?}", means.as_slice());
    println!("col mins  = {:?}", mins.as_slice());
    println!("col maxes = {:?}", maxes.as_slice());
    println!("col stds  = {:?}", stds_t.as_slice());

    assert_eq!(means.shape(), &[3]);
    println!("Column summary: OK");
}

examples/23_sum_mean.rs (line 17)

fn main() {
    let v = Tensor::from_vec(vec![1.0, 2.0, 3.0, 4.0, 5.0]);
    println!("v.sum()  = {}", v.sum()); // 15.0
    println!("v.mean() = {}", v.mean()); // 3.0

    // Axis reductions on a matrix
    // [[1,2,3],[4,5,6]]
    let m = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    println!("column sums   (axis 0) = {:?}", m.sum_axis(0).as_slice()); // [5,7,9]
    println!("row sums      (axis 1) = {:?}", m.sum_axis(1).as_slice()); // [6,15]
    println!("column means  (axis 0) = {:?}", m.mean_axis(0).as_slice()); // [2.5,3.5,4.5]
    println!("row means     (axis 1) = {:?}", m.mean_axis(1).as_slice()); // [2.0,5.0]

    assert_eq!(m.sum_axis(0).as_slice(), &[5.0, 7.0, 9.0]);
    assert_eq!(m.mean_axis(1).as_slice(), &[2.0, 5.0]);
    println!("Assertions passed: OK");
}

examples/standardize_columns.rs (line 18)

fn main() {
    // 4 samples × 3 features
    let data = Tensor::new(
        vec![2.0, 4.0, 1.0, 4.0, 6.0, 3.0, 6.0, 8.0, 5.0, 8.0, 10.0, 7.0],
        &[4, 3],
    );

    // Column means: shape [3]
    let means = data.mean_axis(0);
    // Centre: broadcast [3] across [4, 3]
    let centred = &data - &means;

    // Column std dev: sqrt(mean of squared deviations)
    let sq = &centred * &centred;
    let variance = sq.mean_axis(0);
    let std_dev_vals: Vec<f64> = variance.as_slice().iter().map(|v| v.sqrt()).collect();
    let std_dev = Tensor::new(std_dev_vals, &[3]);

    // Standardise
    let standardised = &centred / &std_dev;

    println!("means    = {:?}", means.as_slice());
    println!("std devs = {:?}", std_dev.as_slice());
    println!("result shape = {:?}", standardised.shape());

    // Each column should have mean ≈ 0 and std ≈ 1
    let col_means = standardised.mean_axis(0);
    for &m in col_means.as_slice() {
        assert!(m.abs() < 1e-10, "column mean not zero: {m}");
    }
    println!("Column means ≈ 0: OK");
}

examples/27_axis_reductions.rs (line 29)

fn main() {
    // Shape [3, 4]: 3 rows, 4 columns
    let m = Tensor::new(
        vec![
            1.0, 2.0, 3.0, 4.0, // row 0
            5.0, 6.0, 7.0, 8.0, // row 1
            9.0, 10.0, 11.0, 12.0, // row 2
        ],
        &[3, 4],
    );

    // Reduce rows → column sums: shape [4]
    let col_sums = m.sum_axis(0);
    assert_eq!(col_sums.shape(), &[4]);
    assert_eq!(col_sums.as_slice(), &[15.0, 18.0, 21.0, 24.0]);
    println!("col sums  = {:?}", col_sums.as_slice());

    // Reduce columns → row means: shape [3]
    let row_means = m.mean_axis(1);
    assert_eq!(row_means.shape(), &[3]);
    assert_eq!(row_means.as_slice(), &[2.5, 6.5, 10.5]);
    println!("row means = {:?}", row_means.as_slice());

    // Column-wise min and max
    let col_min = m.min_axis(0);
    let col_max = m.max_axis(0);
    assert_eq!(col_min.as_slice(), &[1.0, 2.0, 3.0, 4.0]);
    assert_eq!(col_max.as_slice(), &[9.0, 10.0, 11.0, 12.0]);
    println!("col min   = {:?}", col_min.as_slice());
    println!("col max   = {:?}", col_max.as_slice());

    // NaN propagation: one NaN contaminates its column's min
    let with_nan = Tensor::new(vec![1.0, f64::NAN, 3.0, 5.0, 6.0, 7.0], &[2, 3]);
    let nan_col_min = with_nan.min_axis(0);
    assert!(nan_col_min.as_slice()[1].is_nan()); // column 1 had a NaN
    assert_eq!(nan_col_min.as_slice()[0], 1.0); // column 0 clean
    println!("NaN propagation confirmed");

    println!("done.");
}

impl Tensor

pub fn min_axis(&self, axis: usize) -> Tensor

Reduces along axis by taking the minimum, removing that axis from the output shape. Returns NaN if any element along the axis is NaN.

Panics

Panics if axis >= self.ndim().

use matten::Tensor;
let m = Tensor::new(vec![3.0,1.0,4.0,1.0,5.0,9.0], &[2,3]);
assert_eq!(m.min_axis(0).as_slice(), &[1.0, 1.0, 4.0]);

Examples found in repository

examples/column_summary.rs (line 16)

fn main() {
    let data = Tensor::new(
        vec![
            2.0, 5.0, 10.0, 4.0, 7.0, 20.0, 6.0, 3.0, 15.0, 8.0, 11.0, 25.0, 10.0, 9.0, 30.0,
        ],
        &[5, 3],
    );

    let means = data.mean_axis(0);
    let mins = data.min_axis(0);
    let maxes = data.max_axis(0);
    let centred = &data - &means;
    let variances = (&centred * &centred).mean_axis(0);
    let stds: Vec<f64> = variances.as_slice().iter().map(|v| v.sqrt()).collect();
    let stds_t = Tensor::new(stds, &[3]);

    println!("col means = {:?}", means.as_slice());
    println!("col mins  = {:?}", mins.as_slice());
    println!("col maxes = {:?}", maxes.as_slice());
    println!("col stds  = {:?}", stds_t.as_slice());

    assert_eq!(means.shape(), &[3]);
    println!("Column summary: OK");
}

examples/minmax_scaling.rs (line 14)

fn main() {
    let data = Tensor::new(
        vec![1.0, 10.0, 100.0, 2.0, 20.0, 200.0, 3.0, 30.0, 300.0],
        &[3, 3],
    );

    // Column min and max using axis reductions
    let col_min = data.min_axis(0);
    let col_max = data.max_axis(0);
    let range = &col_max - &col_min;

    // Broadcast: (data - min) / (max - min)
    let scaled = &(&data - &col_min) / ⦥

    println!("col_min  = {:?}", col_min.as_slice());
    println!("col_max  = {:?}", col_max.as_slice());
    println!("scaled shape = {:?}", scaled.shape());

    // First row should be all 0.0, last row all 1.0
    let row0 = scaled.slice().index(0).all().build().unwrap();
    let row2 = scaled.slice().index(2).all().build().unwrap();
    assert!(row0.as_slice().iter().all(|&v| (v - 0.0).abs() < 1e-10));
    assert!(row2.as_slice().iter().all(|&v| (v - 1.0).abs() < 1e-10));
    println!("Min-max scaling: OK");
}

examples/28_column_statistics.rs (line 34)

fn main() {
    // 4 rows, 3 columns (features)
    let data = Tensor::new(
        vec![
            1.0, 10.0, 100.0, 2.0, 20.0, 200.0, 3.0, 30.0, 300.0, 4.0, 40.0, 400.0,
        ],
        &[4, 3],
    );

    let means = data.mean_axis(0);
    let mins = data.min_axis(0);
    let maxs = data.max_axis(0);
    let stds = column_std(&data, &means);

    println!("columns : 0      1      2");
    println!("mean    : {:?}", means.as_slice());
    println!("min     : {:?}", mins.as_slice());
    println!("max     : {:?}", maxs.as_slice());
    println!("std dev : {:?}", stds.as_slice());

    assert_eq!(means.as_slice(), &[2.5, 25.0, 250.0]);
    assert_eq!(mins.as_slice(), &[1.0, 10.0, 100.0]);
    assert_eq!(maxs.as_slice(), &[4.0, 40.0, 400.0]);

    // Std dev: sqrt of mean squared deviation from mean
    let expected_std0 = {
        // Column 0 values: 1,2,3,4. Mean=2.5. Deviations: -1.5,-0.5,0.5,1.5
        let sq_devs = [
            1.5f64.powi(2),
            0.5f64.powi(2),
            0.5f64.powi(2),
            1.5f64.powi(2),
        ];
        (sq_devs.iter().sum::<f64>() / 4.0).sqrt()
    };
    assert!((stds.as_slice()[0] - expected_std0).abs() < 1e-10);

    println!("done.");
}

examples/27_axis_reductions.rs (line 35)

fn main() {
    // Shape [3, 4]: 3 rows, 4 columns
    let m = Tensor::new(
        vec![
            1.0, 2.0, 3.0, 4.0, // row 0
            5.0, 6.0, 7.0, 8.0, // row 1
            9.0, 10.0, 11.0, 12.0, // row 2
        ],
        &[3, 4],
    );

    // Reduce rows → column sums: shape [4]
    let col_sums = m.sum_axis(0);
    assert_eq!(col_sums.shape(), &[4]);
    assert_eq!(col_sums.as_slice(), &[15.0, 18.0, 21.0, 24.0]);
    println!("col sums  = {:?}", col_sums.as_slice());

    // Reduce columns → row means: shape [3]
    let row_means = m.mean_axis(1);
    assert_eq!(row_means.shape(), &[3]);
    assert_eq!(row_means.as_slice(), &[2.5, 6.5, 10.5]);
    println!("row means = {:?}", row_means.as_slice());

    // Column-wise min and max
    let col_min = m.min_axis(0);
    let col_max = m.max_axis(0);
    assert_eq!(col_min.as_slice(), &[1.0, 2.0, 3.0, 4.0]);
    assert_eq!(col_max.as_slice(), &[9.0, 10.0, 11.0, 12.0]);
    println!("col min   = {:?}", col_min.as_slice());
    println!("col max   = {:?}", col_max.as_slice());

    // NaN propagation: one NaN contaminates its column's min
    let with_nan = Tensor::new(vec![1.0, f64::NAN, 3.0, 5.0, 6.0, 7.0], &[2, 3]);
    let nan_col_min = with_nan.min_axis(0);
    assert!(nan_col_min.as_slice()[1].is_nan()); // column 1 had a NaN
    assert_eq!(nan_col_min.as_slice()[0], 1.0); // column 0 clean
    println!("NaN propagation confirmed");

    println!("done.");
}

pub fn max_axis(&self, axis: usize) -> Tensor

Reduces along axis by taking the maximum, removing that axis from the output shape. Returns NaN if any element along the axis is NaN.

Panics

Panics if axis >= self.ndim().

use matten::Tensor;
let m = Tensor::new(vec![3.0,1.0,4.0,1.0,5.0,9.0], &[2,3]);
assert_eq!(m.max_axis(0).as_slice(), &[3.0, 5.0, 9.0]);

Examples found in repository

examples/column_summary.rs (line 17)

fn main() {
    let data = Tensor::new(
        vec![
            2.0, 5.0, 10.0, 4.0, 7.0, 20.0, 6.0, 3.0, 15.0, 8.0, 11.0, 25.0, 10.0, 9.0, 30.0,
        ],
        &[5, 3],
    );

    let means = data.mean_axis(0);
    let mins = data.min_axis(0);
    let maxes = data.max_axis(0);
    let centred = &data - &means;
    let variances = (&centred * &centred).mean_axis(0);
    let stds: Vec<f64> = variances.as_slice().iter().map(|v| v.sqrt()).collect();
    let stds_t = Tensor::new(stds, &[3]);

    println!("col means = {:?}", means.as_slice());
    println!("col mins  = {:?}", mins.as_slice());
    println!("col maxes = {:?}", maxes.as_slice());
    println!("col stds  = {:?}", stds_t.as_slice());

    assert_eq!(means.shape(), &[3]);
    println!("Column summary: OK");
}

examples/minmax_scaling.rs (line 15)

fn main() {
    let data = Tensor::new(
        vec![1.0, 10.0, 100.0, 2.0, 20.0, 200.0, 3.0, 30.0, 300.0],
        &[3, 3],
    );

    // Column min and max using axis reductions
    let col_min = data.min_axis(0);
    let col_max = data.max_axis(0);
    let range = &col_max - &col_min;

    // Broadcast: (data - min) / (max - min)
    let scaled = &(&data - &col_min) / ⦥

    println!("col_min  = {:?}", col_min.as_slice());
    println!("col_max  = {:?}", col_max.as_slice());
    println!("scaled shape = {:?}", scaled.shape());

    // First row should be all 0.0, last row all 1.0
    let row0 = scaled.slice().index(0).all().build().unwrap();
    let row2 = scaled.slice().index(2).all().build().unwrap();
    assert!(row0.as_slice().iter().all(|&v| (v - 0.0).abs() < 1e-10));
    assert!(row2.as_slice().iter().all(|&v| (v - 1.0).abs() < 1e-10));
    println!("Min-max scaling: OK");
}

examples/28_column_statistics.rs (line 35)

fn main() {
    // 4 rows, 3 columns (features)
    let data = Tensor::new(
        vec![
            1.0, 10.0, 100.0, 2.0, 20.0, 200.0, 3.0, 30.0, 300.0, 4.0, 40.0, 400.0,
        ],
        &[4, 3],
    );

    let means = data.mean_axis(0);
    let mins = data.min_axis(0);
    let maxs = data.max_axis(0);
    let stds = column_std(&data, &means);

    println!("columns : 0      1      2");
    println!("mean    : {:?}", means.as_slice());
    println!("min     : {:?}", mins.as_slice());
    println!("max     : {:?}", maxs.as_slice());
    println!("std dev : {:?}", stds.as_slice());

    assert_eq!(means.as_slice(), &[2.5, 25.0, 250.0]);
    assert_eq!(mins.as_slice(), &[1.0, 10.0, 100.0]);
    assert_eq!(maxs.as_slice(), &[4.0, 40.0, 400.0]);

    // Std dev: sqrt of mean squared deviation from mean
    let expected_std0 = {
        // Column 0 values: 1,2,3,4. Mean=2.5. Deviations: -1.5,-0.5,0.5,1.5
        let sq_devs = [
            1.5f64.powi(2),
            0.5f64.powi(2),
            0.5f64.powi(2),
            1.5f64.powi(2),
        ];
        (sq_devs.iter().sum::<f64>() / 4.0).sqrt()
    };
    assert!((stds.as_slice()[0] - expected_std0).abs() < 1e-10);

    println!("done.");
}

examples/27_axis_reductions.rs (line 36)

fn main() {
    // Shape [3, 4]: 3 rows, 4 columns
    let m = Tensor::new(
        vec![
            1.0, 2.0, 3.0, 4.0, // row 0
            5.0, 6.0, 7.0, 8.0, // row 1
            9.0, 10.0, 11.0, 12.0, // row 2
        ],
        &[3, 4],
    );

    // Reduce rows → column sums: shape [4]
    let col_sums = m.sum_axis(0);
    assert_eq!(col_sums.shape(), &[4]);
    assert_eq!(col_sums.as_slice(), &[15.0, 18.0, 21.0, 24.0]);
    println!("col sums  = {:?}", col_sums.as_slice());

    // Reduce columns → row means: shape [3]
    let row_means = m.mean_axis(1);
    assert_eq!(row_means.shape(), &[3]);
    assert_eq!(row_means.as_slice(), &[2.5, 6.5, 10.5]);
    println!("row means = {:?}", row_means.as_slice());

    // Column-wise min and max
    let col_min = m.min_axis(0);
    let col_max = m.max_axis(0);
    assert_eq!(col_min.as_slice(), &[1.0, 2.0, 3.0, 4.0]);
    assert_eq!(col_max.as_slice(), &[9.0, 10.0, 11.0, 12.0]);
    println!("col min   = {:?}", col_min.as_slice());
    println!("col max   = {:?}", col_max.as_slice());

    // NaN propagation: one NaN contaminates its column's min
    let with_nan = Tensor::new(vec![1.0, f64::NAN, 3.0, 5.0, 6.0, 7.0], &[2, 3]);
    let nan_col_min = with_nan.min_axis(0);
    assert!(nan_col_min.as_slice()[1].is_nan()); // column 1 had a NaN
    assert_eq!(nan_col_min.as_slice()[0], 1.0); // column 0 clean
    println!("NaN propagation confirmed");

    println!("done.");
}

impl Tensor

pub fn dot(&self, rhs: &Tensor) -> Tensor

Vector/matrix multiplication.

Supported forms:

self shape	rhs shape	result shape
[n]	[n]	[] scalar
[m, n]	[n]	[m]
[n]	[n, p]	[p]
[m, n]	[n, p]	[m, p]

Panics

Panics on incompatible shapes or unsupported rank combinations.

use matten::Tensor;

// vector · vector -> scalar
let a = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
let b = Tensor::from_vec(vec![4.0, 5.0, 6.0]);
let d = a.dot(&b);
assert!(d.is_scalar());
assert_eq!(d.as_slice(), &[32.0]); // 1*4 + 2*5 + 3*6

// matrix × vector -> vector
let m = Tensor::new(vec![1.0,2.0,3.0,4.0,5.0,6.0], &[2,3]);
let v = Tensor::from_vec(vec![1.0, 0.0, 1.0]);
let r = m.dot(&v);
assert_eq!(r.shape(), &[2]);
assert_eq!(r.as_slice(), &[4.0, 10.0]);

Examples found in repository

examples/26_cosine_similarity.rs (line 15)

fn cosine_similarity(a: &Tensor, b: &Tensor) -> f64 {
    // a · b is the scalar dot product
    let dot = a.dot(b).as_slice()[0];
    dot / (l2_norm(a) * l2_norm(b))
}

examples/20_dot_product.rs (line 14)

fn main() {
    let a = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
    let b = Tensor::from_vec(vec![4.0, 5.0, 6.0]);

    let d = a.dot(&b); // 1*4 + 2*5 + 3*6 = 32
    assert!(d.is_scalar());
    println!("a · b = {}", d.as_slice()[0]); // 32.0

    // Orthogonal vectors have zero dot product
    let x = Tensor::from_vec(vec![1.0, 0.0]);
    let y = Tensor::from_vec(vec![0.0, 1.0]);
    assert_eq!(x.dot(&y).as_slice(), &[0.0]);
    println!("orthogonal dot = 0: OK");
}

pub fn matmul(&self, rhs: &Tensor) -> Tensor

Alias for dot for familiarity.

* is always element-wise multiplication; matrix multiplication requires this explicit method.

use matten::Tensor;
let a = Tensor::new(vec![1.0,2.0,3.0,4.0], &[2,2]);
let b = Tensor::new(vec![5.0,6.0,7.0,8.0], &[2,2]);
let c = a.matmul(&b);
assert_eq!(c.shape(), &[2,2]);
assert_eq!(c.as_slice(), &[19.0, 22.0, 43.0, 50.0]);

Examples found in repository

examples/36_heat_equation_1d.rs (line 38)

fn step(a: &Tensor, u: &Tensor) -> Tensor {
    a.matmul(u)
}

examples/33_markov_chain_weather.rs (line 39)

fn step(dist: &Tensor, p: &Tensor) -> Tensor {
    dist.matmul(p)
}

examples/32_graph_path_counting.rs (line 52)

fn matrix_power(a: &Tensor, k: u32) -> Tensor {
    let mut acc = a.clone();
    for _ in 1..k {
        acc = acc.matmul(a);
    }
    acc
}

examples/34_tiny_pagerank.rs (line 43)

fn pagerank_step(m: &Tensor, r: &Tensor, damping: f64, n: usize) -> Tensor {
    let mr = m.matmul(r); // [n, n] × [n] -> [n]
    let base = (1.0 - damping) / n as f64;
    let next: Vec<f64> = mr.as_slice().iter().map(|&x| base + damping * x).collect();
    Tensor::from_vec(next)
}

examples/31_fibonacci_matrix_power.rs (line 44)

fn fib(n: u32) -> u64 {
    let q = Tensor::new(vec![1.0, 1.0, 1.0, 0.0], &[2, 2]);
    // Start from the 2×2 identity so that `fib(0)` returns 0.
    let mut acc = Tensor::new(vec![1.0, 0.0, 0.0, 1.0], &[2, 2]);
    for _ in 0..n {
        acc = acc.matmul(&q);
    }
    // F(n) is the top-right entry of Q^n.
    acc.get(&[0, 1]).expect("index in bounds") as u64
}

examples/35_linear_regression_gradient_descent.rs (line 36)

fn gd_step(x: &Tensor, xt: &Tensor, theta: &Tensor, y: &[f64], lr: f64) -> Tensor {
    let n = y.len() as f64;
    let pred = x.matmul(theta); // [n]
    let residual: Vec<f64> = pred.as_slice().iter().zip(y).map(|(p, t)| p - t).collect();
    let grad = xt.matmul(&Tensor::from_vec(residual)); // [features]
    let updated: Vec<f64> = theta
        .as_slice()
        .iter()
        .zip(grad.as_slice())
        .map(|(w, g)| w - lr * (2.0 / n) * g)
        .collect();
    Tensor::from_vec(updated)
}

Additional examples can be found in:

• examples/21_matrix_vector_product.rs
• examples/22_matrix_multiplication.rs
• examples/gram_matrix.rs
• examples/pairwise_distance.rs

impl Tensor

pub fn abs(&self) -> Tensor

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]);

pub fn sqrt(&self) -> Tensor

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]);

pub fn exp(&self) -> Tensor

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);

pub fn ln(&self) -> Tensor

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);

pub fn clip(&self, min: f64, max: f64) -> Tensor

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]);

pub fn try_clip(&self, min: f64, max: f64) -> Result<Tensor, MattenError>

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());

impl Tensor

pub fn argmin(&self) -> usize

Flat (row-major) index of the smallest element; first occurrence on ties.

Panics

Panics if any element is NaN (the index would be ill-defined), or if called on a dynamic tensor. Use Tensor::try_argmin for the non-panicking form.

use matten::Tensor;
let t = Tensor::new(vec![3.0, 1.0, 5.0, 1.0], &[2, 2]);
assert_eq!(t.argmin(), 1); // first of the two 1.0s

Examples found in repository

examples/37_kmeans_small.rs (line 47)

fn nearest(point: &[f64], centroids: &[Vec<f64>]) -> usize {
    let dists: Vec<f64> = centroids.iter().map(|c| sq_dist(point, c)).collect();
    Tensor::from_vec(dists).argmin()
}

examples/38_nearest_neighbor_classification.rs (line 47)

fn classify(query: &[f64], train: &Tensor, labels: &[u8]) -> u8 {
    let dim = train.shape()[1];
    let data = train.as_slice();
    let dists: Vec<f64> = (0..train.shape()[0])
        .map(|i| sq_dist(query, &data[i * dim..(i + 1) * dim]))
        .collect();
    labels[Tensor::from_vec(dists).argmin()]
}

pub fn argmax(&self) -> usize

Flat (row-major) index of the largest element; first occurrence on ties.

Panics

Panics if any element is NaN, or if called on a dynamic tensor. Use Tensor::try_argmax for the non-panicking form.

use matten::Tensor;
let t = Tensor::from_vec(vec![3.0, 1.0, 5.0, 5.0]);
assert_eq!(t.argmax(), 2); // first of the two 5.0s

pub fn try_argmin(&self) -> Result<usize, MattenError>

Non-panicking Tensor::argmin.

Returns MattenError::InvalidArgument if any element is NaN, or MattenError::Unsupported if called on a dynamic tensor.

use matten::Tensor;
assert_eq!(Tensor::from_vec(vec![3.0, 1.0, 2.0]).try_argmin().unwrap(), 1);
assert!(Tensor::from_vec(vec![1.0, f64::NAN]).try_argmin().is_err());

pub fn try_argmax(&self) -> Result<usize, MattenError>

Non-panicking Tensor::argmax.

Returns MattenError::InvalidArgument if any element is NaN, or MattenError::Unsupported if called on a dynamic tensor.

use matten::Tensor;
assert_eq!(Tensor::from_vec(vec![3.0, 1.0, 2.0]).try_argmax().unwrap(), 0);
assert!(Tensor::from_vec(vec![1.0, f64::NAN]).try_argmax().is_err());

impl Tensor

pub fn reshape(&self, new_shape: &[usize]) -> Tensor

Reshapes the tensor to new_shape, returning a new owned tensor.

The total element count must be unchanged. Data order is preserved (row-major flat order).

Panics

Panics on element-count mismatch or invalid shape. Use try_reshape for recoverable construction.

use matten::Tensor;
let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
let flat = t.reshape(&[4]);
assert_eq!(flat.shape(), &[4]);
assert_eq!(flat.as_slice(), &[1.0, 2.0, 3.0, 4.0]);

Examples found in repository

examples/03_reshape_flatten.rs (line 11)

fn main() {
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    println!("original  {t:?}");

    let r = t.reshape(&[3, 2]);
    println!("reshaped  {r:?}");

    let flat = t.flatten();
    println!("flat      {flat:?}");

    // try_reshape for user-provided shapes
    let bad = t.try_reshape(&[4, 2]);
    println!("bad reshape: {}", bad.unwrap_err());

    // Flat data order is preserved through reshape
    assert_eq!(t.as_slice(), r.as_slice());
    println!("Flat data order preserved: OK");
}

examples/pairwise_distance.rs (line 21)

fn pairwise_euclidean(points: &Tensor) -> Tensor {
    let n = points.shape()[0];

    // Row-wise squared norms: shape [n]
    let sq = points * points;
    let row_sq_norms = sq.sum_axis(1); // [n]

    // Gram matrix: G[i,j] = points[i] · points[j], shape [n,n]
    let gram = points.matmul(&points.transpose());

    // dist²[i,j] = sq_norm[i] + sq_norm[j] - 2·G[i,j]
    // Broadcast [n] as column [n,1] + row [1,n]
    let col = row_sq_norms.reshape(&[n, 1]);
    let row = row_sq_norms.reshape(&[1, n]);
    let dist_sq = &(&col + &row) - &(&gram * 2.0);

    // Clamp small negatives from floating-point rounding, then sqrt
    let dists: Vec<f64> = dist_sq
        .as_slice()
        .iter()
        .map(|&v| if v < 0.0 { 0.0 } else { v.sqrt() })
        .collect();
    Tensor::new(dists, &[n, n])
}

pub fn try_reshape(&self, new_shape: &[usize]) -> Result<Tensor, MattenError>

Reshapes the tensor, returning an error instead of panicking.

Errors

Returns MattenError::Shape on element-count mismatch or invalid shape.

Examples found in repository

examples/03_reshape_flatten.rs (line 18)

fn main() {
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    println!("original  {t:?}");

    let r = t.reshape(&[3, 2]);
    println!("reshaped  {r:?}");

    let flat = t.flatten();
    println!("flat      {flat:?}");

    // try_reshape for user-provided shapes
    let bad = t.try_reshape(&[4, 2]);
    println!("bad reshape: {}", bad.unwrap_err());

    // Flat data order is preserved through reshape
    assert_eq!(t.as_slice(), r.as_slice());
    println!("Flat data order preserved: OK");
}

pub fn flatten(&self) -> Tensor

Flattens the tensor to a 1-D tensor, preserving row-major order.

A scalar (shape []) is returned as shape [1].

use matten::Tensor;
let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
let flat = t.flatten();
assert_eq!(flat.shape(), &[4]);

Examples found in repository

examples/00_quickstart.rs (line 20)

fn main() {
    let a = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    let b = Tensor::ones(&[2, 2]);

    let c = &a + &b;
    println!("a      = {a:?}");
    println!("b      = {b:?}");
    println!("a + b  = {c:?}");

    let flat = c.flatten();
    println!("flat   = {flat:?}");

    assert_eq!(flat.shape(), &[4]);
    assert_eq!(flat.as_slice(), &[2.0, 3.0, 4.0, 5.0]);
    println!("All assertions passed.");
}

examples/03_reshape_flatten.rs (line 14)

fn main() {
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    println!("original  {t:?}");

    let r = t.reshape(&[3, 2]);
    println!("reshaped  {r:?}");

    let flat = t.flatten();
    println!("flat      {flat:?}");

    // try_reshape for user-provided shapes
    let bad = t.try_reshape(&[4, 2]);
    println!("bad reshape: {}", bad.unwrap_err());

    // Flat data order is preserved through reshape
    assert_eq!(t.as_slice(), r.as_slice());
    println!("Flat data order preserved: OK");
}

pub fn transpose(&self) -> Tensor

Transposes the tensor by reversing the axis order.

For a rank-2 tensor this swaps rows and columns. For rank > 2 the axis order is reversed: [d0, d1, d2] → [d2, d1, d0].

Panics

Panics for a rank-0 scalar (no axes to transpose).

use matten::Tensor;
let m = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
let mt = m.transpose();
assert_eq!(mt.shape(), &[3, 2]);
assert_eq!(mt.as_slice(), &[1.0, 4.0, 2.0, 5.0, 3.0, 6.0]);

Examples found in repository

examples/21_matrix_vector_product.rs (line 24)

fn main() {
    // [[1,2,3],[4,5,6]] × [1,0,1] = [4, 10]
    let m = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    let v = Tensor::from_vec(vec![1.0, 0.0, 1.0]);

    let r = m.matmul(&v);
    println!("m    = {m:?}");
    println!("v    = {v:?}");
    println!("m·v  = {r:?}"); // [4.0, 10.0]

    assert_eq!(r.shape(), &[2]);
    assert_eq!(r.as_slice(), &[4.0, 10.0]);

    // Vector × matrix: [n] × [n, p] -> [p]
    let w = Tensor::from_vec(vec![1.0, 2.0]);
    let r2 = w.matmul(&m.transpose());
    println!("w·mᵀ = {r2:?}");

    println!("Shapes and values verified: OK");
}

examples/07_transpose_swap_axes.rs (line 11)

fn main() {
    // 2-D transpose: swap rows and columns
    let m = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    println!("original  {m:?}");
    let mt = m.transpose();
    println!("transposed {mt:?}");
    assert_eq!(mt.shape(), &[3, 2]);

    // t() is an alias
    assert_eq!(m.t(), mt);

    // Transpose twice is identity
    assert_eq!(m.transpose().transpose(), m);
    println!("transpose twice == identity: OK");

    // swap_axes on rank-3
    let r3 = Tensor::new((1..=24).map(|x| x as f64).collect(), &[2, 3, 4]);
    let s = r3.swap_axes(0, 2);
    println!("rank-3 swap_axes(0,2) shape: {:?}", s.shape()); // [4,3,2]
}

examples/gram_matrix.rs (line 15)

fn main() {
    // 4 data points × 3 features
    let x = Tensor::new(
        vec![1.0, 0.0, 1.0, 0.0, 1.0, 1.0, 1.0, 1.0, 0.0, 0.0, 0.0, 1.0],
        &[4, 3],
    );

    // G = X · Xᵀ: shape [4,4]
    let g = x.matmul(&x.transpose());
    println!("Gram matrix shape = {:?}", g.shape()); // [4,4]

    // Diagonal: ||x_i||²
    for i in 0..4 {
        let diag = g.get(&[i, i]).unwrap();
        println!("G[{i},{i}] = {diag:.1}");
    }

    // Symmetric check
    for i in 0..4 {
        for j in 0..4 {
            assert!((g.get(&[i, j]).unwrap() - g.get(&[j, i]).unwrap()).abs() < 1e-10);
        }
    }
    println!("Gram matrix is symmetric: OK");
}

examples/pairwise_distance.rs (line 17)

fn pairwise_euclidean(points: &Tensor) -> Tensor {
    let n = points.shape()[0];

    // Row-wise squared norms: shape [n]
    let sq = points * points;
    let row_sq_norms = sq.sum_axis(1); // [n]

    // Gram matrix: G[i,j] = points[i] · points[j], shape [n,n]
    let gram = points.matmul(&points.transpose());

    // dist²[i,j] = sq_norm[i] + sq_norm[j] - 2·G[i,j]
    // Broadcast [n] as column [n,1] + row [1,n]
    let col = row_sq_norms.reshape(&[n, 1]);
    let row = row_sq_norms.reshape(&[1, n]);
    let dist_sq = &(&col + &row) - &(&gram * 2.0);

    // Clamp small negatives from floating-point rounding, then sqrt
    let dists: Vec<f64> = dist_sq
        .as_slice()
        .iter()
        .map(|&v| if v < 0.0 { 0.0 } else { v.sqrt() })
        .collect();
    Tensor::new(dists, &[n, n])
}

examples/35_linear_regression_gradient_descent.rs (line 62)

fn main() {
    // Data generated from the true line y = 2x + 1.
    // Design matrix X carries a leading bias column, so theta = [b, w].
    let x = Tensor::new(
        vec![
            1.0, 0.0, //
            1.0, 1.0, //
            1.0, 2.0, //
            1.0, 3.0, //
            1.0, 4.0, //
        ],
        &[5, 2],
    );
    let y = [1.0, 3.0, 5.0, 7.0, 9.0];
    let xt = x.transpose(); // [2, 5], formed once and reused each step

    let mut theta = Tensor::from_vec(vec![0.0, 0.0]); // [b, w]
    let lr = 0.05;
    for _ in 0..2000 {
        theta = gd_step(&x, &xt, &theta, &y, lr);
    }

    let p = theta.as_slice();
    println!("fitted: y = {:.4}*x + {:.4}", p[1], p[0]);
    println!("target: y = 2*x + 1");

    assert!((p[0] - 1.0).abs() < 0.05, "intercept ~ 1");
    assert!((p[1] - 2.0).abs() < 0.05, "slope ~ 2");
    println!("Linear regression (gradient descent): OK");
}

pub fn t(&self) -> Tensor

Alias for transpose.

Examples found in repository

examples/07_transpose_swap_axes.rs (line 16)

fn main() {
    // 2-D transpose: swap rows and columns
    let m = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    println!("original  {m:?}");
    let mt = m.transpose();
    println!("transposed {mt:?}");
    assert_eq!(mt.shape(), &[3, 2]);

    // t() is an alias
    assert_eq!(m.t(), mt);

    // Transpose twice is identity
    assert_eq!(m.transpose().transpose(), m);
    println!("transpose twice == identity: OK");

    // swap_axes on rank-3
    let r3 = Tensor::new((1..=24).map(|x| x as f64).collect(), &[2, 3, 4]);
    let s = r3.swap_axes(0, 2);
    println!("rank-3 swap_axes(0,2) shape: {:?}", s.shape()); // [4,3,2]
}

pub fn swap_axes(&self, axis1: usize, axis2: usize) -> Tensor

Returns a new tensor with axis1 and axis2 swapped.

Panics

Panics if either axis is out of range.

use matten::Tensor;
let t = Tensor::new((1..=24).map(|x| x as f64).collect(), &[2, 3, 4]);
let s = t.swap_axes(0, 2);
assert_eq!(s.shape(), &[4, 3, 2]);

Examples found in repository

examples/07_transpose_swap_axes.rs (line 24)

fn main() {
    // 2-D transpose: swap rows and columns
    let m = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    println!("original  {m:?}");
    let mt = m.transpose();
    println!("transposed {mt:?}");
    assert_eq!(mt.shape(), &[3, 2]);

    // t() is an alias
    assert_eq!(m.t(), mt);

    // Transpose twice is identity
    assert_eq!(m.transpose().transpose(), m);
    println!("transpose twice == identity: OK");

    // swap_axes on rank-3
    let r3 = Tensor::new((1..=24).map(|x| x as f64).collect(), &[2, 3, 4]);
    let s = r3.swap_axes(0, 2);
    println!("rank-3 swap_axes(0,2) shape: {:?}", s.shape()); // [4,3,2]
}

pub fn squeeze(&self) -> Tensor

Removes all axes of length 1, returning a new owned tensor.

Data order is unchanged. A scalar stays a scalar, and a tensor whose every axis is 1 (e.g. [1, 1]) becomes a scalar (shape []).

Panics

Panics on a dynamic tensor; call try_numeric() first.

use matten::Tensor;
let t = Tensor::new(vec![1.0, 2.0, 3.0], &[1, 3, 1]);
assert_eq!(t.squeeze().shape(), &[3]);

pub fn expand_dims(&self, axis: usize) -> Tensor

Inserts a new axis of length 1 at axis, returning a new owned tensor.

axis may be 0..=ndim (inserting at ndim appends a trailing axis). Data order is unchanged.

Panics

Panics if axis > ndim, or on a dynamic tensor. Use try_expand_dims for the non-panicking form.

use matten::Tensor;
let t = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
assert_eq!(t.expand_dims(0).shape(), &[1, 3]);
assert_eq!(t.expand_dims(1).shape(), &[3, 1]);

pub fn try_expand_dims(&self, axis: usize) -> Result<Tensor, MattenError>

Non-panicking expand_dims.

Errors

Returns MattenError::InvalidArgument if axis > ndim, or MattenError::Unsupported on a dynamic tensor.

use matten::Tensor;
let t = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
assert!(t.try_expand_dims(5).is_err());

pub fn get(&self, coord: &[usize]) -> Option<f64>

Returns the element at the multidimensional coord, or None if the coordinate rank doesn’t match or any component is out of bounds.

use matten::Tensor;
let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
assert_eq!(t.get(&[0, 1]), Some(2.0));
assert_eq!(t.get(&[5, 0]), None);

Examples found in repository

examples/32_graph_path_counting.rs (line 63)

fn print_matrix(label: &str, m: &Tensor) {
    let (rows, cols) = (m.shape()[0], m.shape()[1]);
    println!("{label}:");
    for i in 0..rows {
        let row: Vec<String> = (0..cols)
            .map(|j| format!("{:.0}", m.get(&[i, j]).expect("index in bounds")))
            .collect();
        println!("  [{}]", row.join(", "));
    }
}

fn main() {
    // Directed graph on 4 nodes:
    //   0 -> 1, 0 -> 2, 1 -> 2, 1 -> 3, 2 -> 3
    //
    //        to: 0  1  2  3
    //   from 0 [ 0  1  1  0 ]
    //        1 [ 0  0  1  1 ]
    //        2 [ 0  0  0  1 ]
    //        3 [ 0  0  0  0 ]
    let a = Tensor::new(
        vec![
            0.0, 1.0, 1.0, 0.0, //
            0.0, 0.0, 1.0, 1.0, //
            0.0, 0.0, 0.0, 1.0, //
            0.0, 0.0, 0.0, 0.0, //
        ],
        &[4, 4],
    );

    let a2 = matrix_power(&a, 2);
    let a3 = matrix_power(&a, 3);

    print_matrix("A^2", &a2);
    print_matrix("A^3", &a3);

    // From node 0 to node 3: two length-2 walks (0->1->3, 0->2->3)
    // and one length-3 walk (0->1->2->3).
    let walks2 = a2.get(&[0, 3]).expect("index in bounds");
    let walks3 = a3.get(&[0, 3]).expect("index in bounds");
    println!("walks of length 2 from 0 to 3 = {walks2:.0}");
    println!("walks of length 3 from 0 to 3 = {walks3:.0}");

    assert_eq!(walks2, 2.0);
    assert_eq!(walks3, 1.0);
    println!("Graph path counting: OK");
}

examples/31_fibonacci_matrix_power.rs (line 47)

fn fib(n: u32) -> u64 {
    let q = Tensor::new(vec![1.0, 1.0, 1.0, 0.0], &[2, 2]);
    // Start from the 2×2 identity so that `fib(0)` returns 0.
    let mut acc = Tensor::new(vec![1.0, 0.0, 0.0, 1.0], &[2, 2]);
    for _ in 0..n {
        acc = acc.matmul(&q);
    }
    // F(n) is the top-right entry of Q^n.
    acc.get(&[0, 1]).expect("index in bounds") as u64
}

examples/pairwise_distance.rs (line 45)

fn main() {
    let points = Tensor::new(vec![0.0, 0.0, 3.0, 4.0, 6.0, 0.0], &[3, 2]);

    let dists = pairwise_euclidean(&points);
    println!("pairwise distances:");
    for i in 0..3 {
        let row = dists.slice().index(i).all().build().unwrap();
        println!("  row {i}: {:?}", row.as_slice());
    }

    // (0,0)→(3,4) = 5, (3,4)→(6,0) = 5, (0,0)→(6,0) = 6
    assert!((dists.get(&[0, 1]).unwrap() - 5.0).abs() < 1e-9);
    assert!((dists.get(&[1, 2]).unwrap() - 5.0).abs() < 1e-9);
    assert!((dists.get(&[0, 2]).unwrap() - 6.0).abs() < 1e-9);
    println!("Pairwise distances: OK");
}

examples/gram_matrix.rs (line 20)

fn main() {
    // 4 data points × 3 features
    let x = Tensor::new(
        vec![1.0, 0.0, 1.0, 0.0, 1.0, 1.0, 1.0, 1.0, 0.0, 0.0, 0.0, 1.0],
        &[4, 3],
    );

    // G = X · Xᵀ: shape [4,4]
    let g = x.matmul(&x.transpose());
    println!("Gram matrix shape = {:?}", g.shape()); // [4,4]

    // Diagonal: ||x_i||²
    for i in 0..4 {
        let diag = g.get(&[i, i]).unwrap();
        println!("G[{i},{i}] = {diag:.1}");
    }

    // Symmetric check
    for i in 0..4 {
        for j in 0..4 {
            assert!((g.get(&[i, j]).unwrap() - g.get(&[j, i]).unwrap()).abs() < 1e-10);
        }
    }
    println!("Gram matrix is symmetric: OK");
}

examples/02_shape_and_size.rs (line 32)

fn main() {
    let scalar = Tensor::scalar(1.0);
    let vec1d = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
    let mat = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    let rank3 = Tensor::zeros(&[2, 3, 4]);

    for (name, t) in [
        ("scalar", &scalar),
        ("vector", &vec1d),
        ("matrix", &mat),
        ("rank-3", &rank3),
    ] {
        println!(
            "{name:6}: shape={:?}  ndim={}  len={}  is_scalar={}  is_vector={}  is_matrix={}",
            t.shape(),
            t.ndim(),
            t.len(),
            t.is_scalar(),
            t.is_vector(),
            t.is_matrix()
        );
    }

    // Safe element access: Option<f64>, never panics
    println!("\nmat.get([0,1]) = {:?}", mat.get(&[0, 1])); // Some(2.0)
    println!("mat.get([5,0]) = {:?}", mat.get(&[5, 0])); // None
}

examples/30_magic_square_checker.rs (line 43)

fn magic_sum(m: &Tensor) -> Option<f64> {
    let shape = m.shape();
    if shape.len() != 2 || shape[0] != shape[1] || shape[0] == 0 {
        return None;
    }
    let n = shape[0];
    let at = |i: usize, j: usize| m.get(&[i, j]).expect("index in bounds");

    // Target is the sum of the first row.
    let target: f64 = (0..n).map(|j| at(0, j)).sum();

    // Every row must match.
    for i in 0..n {
        let row: f64 = (0..n).map(|j| at(i, j)).sum();
        if row != target {
            return None;
        }
    }
    // Every column must match.
    for j in 0..n {
        let col: f64 = (0..n).map(|i| at(i, j)).sum();
        if col != target {
            return None;
        }
    }
    // Both diagonals must match.
    let main_diag: f64 = (0..n).map(|i| at(i, i)).sum();
    let anti_diag: f64 = (0..n).map(|i| at(i, n - 1 - i)).sum();
    if main_diag != target || anti_diag != target {
        return None;
    }

    Some(target)
}

pub fn get_flat(&self, index: usize) -> Option<f64>

Returns the element at flat row-major index, or None if out of bounds.

This is the flat-index companion to get. The index follows the same row-major layout as as_slice.

use matten::Tensor;
let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
assert_eq!(t.get_flat(1), Some(2.0));
assert_eq!(t.get_flat(10), None);

pub fn slice(&self) -> SliceBuilder<'_>

Starts a slice builder for this tensor. The builder is the canonical slicing API; slice_str is a convenience wrapper.

use matten::Tensor;
let t = Tensor::new(vec![1.0,2.0,3.0,4.0,5.0,6.0], &[2, 3]);
let row = t.slice().index(0).all().build().unwrap();
assert_eq!(row.as_slice(), &[1.0, 2.0, 3.0]);

Examples found in repository

examples/rolling_windows_basic.rs (line 9)

fn rolling_sum(t: &Tensor, window: usize) -> Vec<f64> {
    (0..=(t.len() - window))
        .map(|i| t.slice().range(i..i + window).build().unwrap().sum())
        .collect()
}

fn rolling_max(t: &Tensor, window: usize) -> Vec<f64> {
    (0..=(t.len() - window))
        .map(|i| t.slice().range(i..i + window).build().unwrap().max())
        .collect()
}

examples/pairwise_distance.rs (line 40)

fn main() {
    let points = Tensor::new(vec![0.0, 0.0, 3.0, 4.0, 6.0, 0.0], &[3, 2]);

    let dists = pairwise_euclidean(&points);
    println!("pairwise distances:");
    for i in 0..3 {
        let row = dists.slice().index(i).all().build().unwrap();
        println!("  row {i}: {:?}", row.as_slice());
    }

    // (0,0)→(3,4) = 5, (3,4)→(6,0) = 5, (0,0)→(6,0) = 6
    assert!((dists.get(&[0, 1]).unwrap() - 5.0).abs() < 1e-9);
    assert!((dists.get(&[1, 2]).unwrap() - 5.0).abs() < 1e-9);
    assert!((dists.get(&[0, 2]).unwrap() - 6.0).abs() < 1e-9);
    println!("Pairwise distances: OK");
}

examples/moving_average.rs (line 15)

fn main() {
    let series = Tensor::from_vec(vec![1.0, 3.0, 5.0, 7.0, 9.0, 11.0, 13.0]);
    let window = 3usize;
    let n = series.len();

    // Compute moving averages for windows [0..3], [1..4], ...
    let mut avgs = Vec::new();
    for start in 0..=(n - window) {
        let w = series.slice().range(start..start + window).build().unwrap();
        avgs.push(w.mean());
    }

    println!("series = {:?}", series.as_slice());
    println!("3-pt moving avg = {:?}", avgs);
    assert_eq!(avgs.len(), n - window + 1);
    assert!((avgs[0] - 3.0).abs() < 1e-10); // mean(1,3,5) = 3
    assert!((avgs[1] - 5.0).abs() < 1e-10); // mean(3,5,7) = 5
    println!("Moving average: OK");
}

examples/08_slicing_builder.rs (line 14)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let t = Tensor::new((1..=12).map(|x| x as f64).collect(), &[3, 4]);
    println!("tensor   {t:?}");

    // First row (index 0, axis removed from output shape)
    let row0 = t.slice().index(0).all().build()?;
    println!("row 0    {row0:?}"); // shape [4]

    // First two rows, all columns
    let top2 = t.slice().range(0..2).all().build()?;
    println!("top 2    {top2:?}"); // shape [2,4]

    // All rows, columns 1..3
    let cols = t.slice().all().range(1..3).build()?;
    println!("cols 1:3 {cols:?}"); // shape [3,2]

    // Single element -> scalar
    let elem = t.slice().index(1).index(2).build()?;
    assert!(elem.is_scalar());
    println!("t[1,2]   {elem:?}");

    Ok(())
}

examples/09_slice_str.rs (line 25)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let t = Tensor::new((1..=12).map(|x| x as f64).collect(), &[3, 4]);

    println!("\"0, :\"    = {:?}", t.slice_str("0, :")?);
    println!("\"0:2, :\" = {:?}", t.slice_str("0:2, :")?);
    println!("\":, 1:3\" = {:?}", t.slice_str(":, 1:3")?);

    // Whitespace is ignored
    let a = t.slice_str("0:2, :")?;
    let b = t.slice_str(" 0:2 , : ")?;
    assert_eq!(a, b);
    println!("whitespace-insensitive: OK");

    // builder and slice_str agree
    let from_str = t.slice_str("0:2, :")?;
    let from_builder = t.slice().range(0..2).all().build()?;
    assert_eq!(from_str, from_builder);
    println!("builder == slice_str: OK");

    // Malformed specs never panic
    println!("bad spec: {:?}", t.slice_str("0::")); // Err

    Ok(())
}

examples/minmax_scaling.rs (line 26)

fn main() {
    let data = Tensor::new(
        vec![1.0, 10.0, 100.0, 2.0, 20.0, 200.0, 3.0, 30.0, 300.0],
        &[3, 3],
    );

    // Column min and max using axis reductions
    let col_min = data.min_axis(0);
    let col_max = data.max_axis(0);
    let range = &col_max - &col_min;

    // Broadcast: (data - min) / (max - min)
    let scaled = &(&data - &col_min) / ⦥

    println!("col_min  = {:?}", col_min.as_slice());
    println!("col_max  = {:?}", col_max.as_slice());
    println!("scaled shape = {:?}", scaled.shape());

    // First row should be all 0.0, last row all 1.0
    let row0 = scaled.slice().index(0).all().build().unwrap();
    let row2 = scaled.slice().index(2).all().build().unwrap();
    assert!(row0.as_slice().iter().all(|&v| (v - 0.0).abs() < 1e-10));
    assert!(row2.as_slice().iter().all(|&v| (v - 1.0).abs() < 1e-10));
    println!("Min-max scaling: OK");
}

Additional examples can be found in:

• examples/12_boundary_error_handling.rs

pub fn slice_str(&self, spec: &str) -> Result<Tensor, MattenError>

Slices this tensor using a NumPy-like string specification.

This is a convenience wrapper over the builder API. It always returns Result and never panics on malformed input.

Errors

Returns MattenError::Slice for any parse or bounds error.

use matten::Tensor;
let t = Tensor::new(vec![1.0,2.0,3.0,4.0,5.0,6.0], &[2, 3]);
let top = t.slice_str("0, :").unwrap();
assert_eq!(top.as_slice(), &[1.0, 2.0, 3.0]);

Examples found in repository

examples/09_slice_str.rs (line 13)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let t = Tensor::new((1..=12).map(|x| x as f64).collect(), &[3, 4]);

    println!("\"0, :\"    = {:?}", t.slice_str("0, :")?);
    println!("\"0:2, :\" = {:?}", t.slice_str("0:2, :")?);
    println!("\":, 1:3\" = {:?}", t.slice_str(":, 1:3")?);

    // Whitespace is ignored
    let a = t.slice_str("0:2, :")?;
    let b = t.slice_str(" 0:2 , : ")?;
    assert_eq!(a, b);
    println!("whitespace-insensitive: OK");

    // builder and slice_str agree
    let from_str = t.slice_str("0:2, :")?;
    let from_builder = t.slice().range(0..2).all().build()?;
    assert_eq!(from_str, from_builder);
    println!("builder == slice_str: OK");

    // Malformed specs never panic
    println!("bad spec: {:?}", t.slice_str("0::")); // Err

    Ok(())
}

impl Tensor

pub fn from_json(input: &str) -> Result<Tensor, MattenError>

Parses a JSON string into a Tensor.

Accepts the canonical {"shape":[…],"data":[…]} object form and the convenience nested-array form (rank 1 and 2). Returns MattenError::Parse for any error; never panics.

use matten::Tensor;

// Canonical object form
let t = Tensor::from_json(r#"{"shape":[2,2],"data":[1.0,2.0,3.0,4.0]}"#).unwrap();
assert_eq!(t.shape(), &[2, 2]);

// Nested-array convenience form
let t = Tensor::from_json("[[1.0,2.0],[3.0,4.0]]").unwrap();
assert_eq!(t.shape(), &[2, 2]);

Examples found in repository

examples/10_json_roundtrip.rs (line 22)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ── serde round-trip ────────────────────────────────────────────────
    let original = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    let json = serde_json::to_string(&original)?;
    println!("serialised: {json}");

    let restored: Tensor = serde_json::from_str(&json)?;
    assert_eq!(original, restored);
    println!("round-trip: OK  shape={:?}", restored.shape());

    // ── from_json: canonical object form ────────────────────────────────
    let t = Tensor::from_json(r#"{"shape":[2,2],"data":[1.0,2.0,3.0,4.0]}"#)?;
    println!("object form:  {t:?}");

    // ── from_json: nested-array convenience form ─────────────────────────
    let t2 = Tensor::from_json("[[1.0,2.0],[3.0,4.0]]")?;
    println!("nested form:  {t2:?}");

    // ── load_json from file ──────────────────────────────────────────────
    let t3 = Tensor::load_json("examples/data/tensor_2x2.json")?;
    println!("from file:    {t3:?}");

    Ok(())
}

examples/12_boundary_error_handling.rs (line 20)

fn main() {
    // ── shape/data mismatch ──────────────────────────────────────────────
    match Tensor::try_new(vec![1.0, 2.0], &[3]) {
        Err(MattenError::Shape { operation, message }) => {
            println!("[Shape]  {operation}: {message}")
        }
        other => println!("{other:?}"),
    }

    // ── malformed JSON ───────────────────────────────────────────────────
    match Tensor::from_json(r#"[[1.0,"text"]]"#) {
        Err(MattenError::Parse { format, message }) => println!("[Parse/{format}]  {message}"),
        other => println!("{other:?}"),
    }

    // ── ragged JSON array ────────────────────────────────────────────────
    match Tensor::from_json("[[1.0,2.0],[3.0]]") {
        Err(MattenError::Parse { format, message }) => println!("[Parse/{format}]  {message}"),
        other => println!("{other:?}"),
    }

    // ── non-numeric CSV field ────────────────────────────────────────────
    match Tensor::load_csv("examples/data/malformed_numeric.csv") {
        Err(MattenError::Parse { format, message }) => println!("[Parse/{format}]  {message}"),
        other => println!("{other:?}"),
    }

    // ── missing file ─────────────────────────────────────────────────────
    match Tensor::load_json("/no/such/file.json") {
        Err(MattenError::Io { path, source }) => println!("[Io]  {}: {source}", path.display()),
        other => println!("{other:?}"),
    }

    // ── slice out of range ───────────────────────────────────────────────
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    match t.slice().index(5).all().build() {
        Err(MattenError::Slice { message, .. }) => println!("[Slice]  {message}"),
        other => println!("{other:?}"),
    }

    println!("All boundary errors handled gracefully — no panics.");
}

pub fn from_csv(input: &str) -> Result<Tensor, MattenError>

Parses a CSV string into a Tensor with shape [rows, cols].

All fields must be valid f64 values. Returns MattenError::Parse for ragged rows or non-numeric fields; never panics.

use matten::Tensor;

let t = Tensor::from_csv("1.0,2.0\n3.0,4.0\n").unwrap();
assert_eq!(t.shape(), &[2, 2]);
assert_eq!(t.as_slice(), &[1.0, 2.0, 3.0, 4.0]);

Examples found in repository

examples/11_csv_numeric_loading.rs (line 12)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ── from_csv: inline string ──────────────────────────────────────────
    let t = Tensor::from_csv("1.0,2.0,3.0\n4.0,5.0,6.0\n")?;
    println!(
        "inline CSV:   shape={:?}  data={:?}",
        t.shape(),
        t.as_slice()
    );

    // ── load_csv: from file ──────────────────────────────────────────────
    let t2 = Tensor::load_csv("examples/data/numeric_2x3.csv")?;
    println!(
        "from file:    shape={:?}  data={:?}",
        t2.shape(),
        t2.as_slice()
    );

    let t3 = Tensor::load_csv("examples/data/numeric_3x3.csv")?;
    println!("3×3 from file: shape={:?}", t3.shape());

    Ok(())
}

pub fn load_json(path: impl AsRef<Path>) -> Result<Tensor, MattenError>

Loads and parses a JSON file into a Tensor.

Returns MattenError::Io for file errors, MattenError::Parse for parse errors.

Errors

Returns an error if the file cannot be read or the content is invalid.

Examples found in repository

examples/10_json_roundtrip.rs (line 30)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ── serde round-trip ────────────────────────────────────────────────
    let original = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    let json = serde_json::to_string(&original)?;
    println!("serialised: {json}");

    let restored: Tensor = serde_json::from_str(&json)?;
    assert_eq!(original, restored);
    println!("round-trip: OK  shape={:?}", restored.shape());

    // ── from_json: canonical object form ────────────────────────────────
    let t = Tensor::from_json(r#"{"shape":[2,2],"data":[1.0,2.0,3.0,4.0]}"#)?;
    println!("object form:  {t:?}");

    // ── from_json: nested-array convenience form ─────────────────────────
    let t2 = Tensor::from_json("[[1.0,2.0],[3.0,4.0]]")?;
    println!("nested form:  {t2:?}");

    // ── load_json from file ──────────────────────────────────────────────
    let t3 = Tensor::load_json("examples/data/tensor_2x2.json")?;
    println!("from file:    {t3:?}");

    Ok(())
}

examples/12_boundary_error_handling.rs (line 38)

fn main() {
    // ── shape/data mismatch ──────────────────────────────────────────────
    match Tensor::try_new(vec![1.0, 2.0], &[3]) {
        Err(MattenError::Shape { operation, message }) => {
            println!("[Shape]  {operation}: {message}")
        }
        other => println!("{other:?}"),
    }

    // ── malformed JSON ───────────────────────────────────────────────────
    match Tensor::from_json(r#"[[1.0,"text"]]"#) {
        Err(MattenError::Parse { format, message }) => println!("[Parse/{format}]  {message}"),
        other => println!("{other:?}"),
    }

    // ── ragged JSON array ────────────────────────────────────────────────
    match Tensor::from_json("[[1.0,2.0],[3.0]]") {
        Err(MattenError::Parse { format, message }) => println!("[Parse/{format}]  {message}"),
        other => println!("{other:?}"),
    }

    // ── non-numeric CSV field ────────────────────────────────────────────
    match Tensor::load_csv("examples/data/malformed_numeric.csv") {
        Err(MattenError::Parse { format, message }) => println!("[Parse/{format}]  {message}"),
        other => println!("{other:?}"),
    }

    // ── missing file ─────────────────────────────────────────────────────
    match Tensor::load_json("/no/such/file.json") {
        Err(MattenError::Io { path, source }) => println!("[Io]  {}: {source}", path.display()),
        other => println!("{other:?}"),
    }

    // ── slice out of range ───────────────────────────────────────────────
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    match t.slice().index(5).all().build() {
        Err(MattenError::Slice { message, .. }) => println!("[Slice]  {message}"),
        other => println!("{other:?}"),
    }

    println!("All boundary errors handled gracefully — no panics.");
}

pub fn load_csv(path: impl AsRef<Path>) -> Result<Tensor, MattenError>

Loads and parses a CSV file into a Tensor with shape [rows, cols].

Returns MattenError::Io for file errors, MattenError::Parse for parse errors.

Errors

Returns an error if the file cannot be read or the content is invalid.

Examples found in repository

examples/11_csv_numeric_loading.rs (line 20)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ── from_csv: inline string ──────────────────────────────────────────
    let t = Tensor::from_csv("1.0,2.0,3.0\n4.0,5.0,6.0\n")?;
    println!(
        "inline CSV:   shape={:?}  data={:?}",
        t.shape(),
        t.as_slice()
    );

    // ── load_csv: from file ──────────────────────────────────────────────
    let t2 = Tensor::load_csv("examples/data/numeric_2x3.csv")?;
    println!(
        "from file:    shape={:?}  data={:?}",
        t2.shape(),
        t2.as_slice()
    );

    let t3 = Tensor::load_csv("examples/data/numeric_3x3.csv")?;
    println!("3×3 from file: shape={:?}", t3.shape());

    Ok(())
}

examples/12_boundary_error_handling.rs (line 32)

fn main() {
    // ── shape/data mismatch ──────────────────────────────────────────────
    match Tensor::try_new(vec![1.0, 2.0], &[3]) {
        Err(MattenError::Shape { operation, message }) => {
            println!("[Shape]  {operation}: {message}")
        }
        other => println!("{other:?}"),
    }

    // ── malformed JSON ───────────────────────────────────────────────────
    match Tensor::from_json(r#"[[1.0,"text"]]"#) {
        Err(MattenError::Parse { format, message }) => println!("[Parse/{format}]  {message}"),
        other => println!("{other:?}"),
    }

    // ── ragged JSON array ────────────────────────────────────────────────
    match Tensor::from_json("[[1.0,2.0],[3.0]]") {
        Err(MattenError::Parse { format, message }) => println!("[Parse/{format}]  {message}"),
        other => println!("{other:?}"),
    }

    // ── non-numeric CSV field ────────────────────────────────────────────
    match Tensor::load_csv("examples/data/malformed_numeric.csv") {
        Err(MattenError::Parse { format, message }) => println!("[Parse/{format}]  {message}"),
        other => println!("{other:?}"),
    }

    // ── missing file ─────────────────────────────────────────────────────
    match Tensor::load_json("/no/such/file.json") {
        Err(MattenError::Io { path, source }) => println!("[Io]  {}: {source}", path.display()),
        other => println!("{other:?}"),
    }

    // ── slice out of range ───────────────────────────────────────────────
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    match t.slice().index(5).all().build() {
        Err(MattenError::Slice { message, .. }) => println!("[Slice]  {message}"),
        other => println!("{other:?}"),
    }

    println!("All boundary errors handled gracefully — no panics.");
}

impl Tensor

pub fn new(data: Vec<f64>, shape: &[usize]) -> Tensor

Examples found in repository

examples/hello_tensor.rs (line 8)

fn main() {
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    println!("{t:?}");
    println!(
        "shape = {:?}, len = {}, ndim = {}",
        t.shape(),
        t.len(),
        t.ndim()
    );
}

examples/31_fibonacci_matrix_power.rs (line 40)

fn fib(n: u32) -> u64 {
    let q = Tensor::new(vec![1.0, 1.0, 1.0, 0.0], &[2, 2]);
    // Start from the 2×2 identity so that `fib(0)` returns 0.
    let mut acc = Tensor::new(vec![1.0, 0.0, 0.0, 1.0], &[2, 2]);
    for _ in 0..n {
        acc = acc.matmul(&q);
    }
    // F(n) is the top-right entry of Q^n.
    acc.get(&[0, 1]).expect("index in bounds") as u64
}

examples/00_quickstart.rs (line 12)

fn main() {
    let a = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    let b = Tensor::ones(&[2, 2]);

    let c = &a + &b;
    println!("a      = {a:?}");
    println!("b      = {b:?}");
    println!("a + b  = {c:?}");

    let flat = c.flatten();
    println!("flat   = {flat:?}");

    assert_eq!(flat.shape(), &[4]);
    assert_eq!(flat.as_slice(), &[2.0, 3.0, 4.0, 5.0]);
    println!("All assertions passed.");
}

examples/04_elementwise_ops.rs (line 8)

fn main() {
    let a = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    let b = Tensor::full(&[2, 2], 2.0);

    println!("a        = {a:?}");
    println!("b        = {b:?}");
    println!("a + b    = {:?}", &a + &b);
    println!("a - b    = {:?}", &a - &b);
    println!("a * b    = {:?}", &a * &b); // element-wise, NOT matrix product
    println!("a / b    = {:?}", &a / &b);
    println!("-a       = {:?}", -&a);
}

examples/05_scalar_ops.rs (line 8)

fn main() {
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);

    // tensor op scalar
    println!("t + 10  = {:?}", &t + 10.0);
    println!("t - 1   = {:?}", &t - 1.0);
    println!("t * 2   = {:?}", &t * 2.0);
    println!("t / 2   = {:?}", &t / 2.0);

    // scalar op tensor
    println!("10 + t  = {:?}", 10.0_f64 + &t);
    println!("10 - t  = {:?}", 10.0_f64 - &t);
    println!("2 * t   = {:?}", 2.0_f64 * &t);
    println!("8 / t   = {:?}", 8.0_f64 / &t);
}

examples/03_reshape_flatten.rs (line 8)

fn main() {
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    println!("original  {t:?}");

    let r = t.reshape(&[3, 2]);
    println!("reshaped  {r:?}");

    let flat = t.flatten();
    println!("flat      {flat:?}");

    // try_reshape for user-provided shapes
    let bad = t.try_reshape(&[4, 2]);
    println!("bad reshape: {}", bad.unwrap_err());

    // Flat data order is preserved through reshape
    assert_eq!(t.as_slice(), r.as_slice());
    println!("Flat data order preserved: OK");
}

Additional examples can be found in:

• examples/21_matrix_vector_product.rs
• examples/07_transpose_swap_axes.rs
• examples/38_nearest_neighbor_classification.rs
• examples/22_matrix_multiplication.rs
• examples/gram_matrix.rs
• examples/rowwise_scoring.rs
• examples/08_slicing_builder.rs
• examples/column_summary.rs
• examples/30_magic_square_checker.rs
• examples/23_sum_mean.rs
• examples/09_slice_str.rs
• examples/06_broadcasting.rs
• examples/pairwise_distance.rs
• examples/02_shape_and_size.rs
• examples/minmax_scaling.rs
• examples/01_create_tensor.rs
• examples/35_linear_regression_gradient_descent.rs
• examples/33_markov_chain_weather.rs
• examples/32_graph_path_counting.rs
• examples/standardize_columns.rs
• examples/36_heat_equation_1d.rs
• examples/28_column_statistics.rs
• examples/10_json_roundtrip.rs
• examples/34_tiny_pagerank.rs
• examples/27_axis_reductions.rs
• examples/37_kmeans_small.rs
• examples/12_boundary_error_handling.rs

pub fn try_new(data: Vec<f64>, shape: &[usize]) -> Result<Tensor, MattenError>

Creates a tensor from row-major data and shape, returning an error instead of panicking.

Errors

Returns MattenError::Shape for a length mismatch or invalid shape, or MattenError::Allocation on product overflow.

Examples found in repository

examples/01_create_tensor.rs (line 33)

fn main() {
    // From data + shape
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    println!("new:         {t:?}");

    // Fill constructors
    println!("zeros [3]:   {:?}", Tensor::zeros(&[3]));
    println!("ones  [2,2]: {:?}", Tensor::ones(&[2, 2]));
    println!("full  [3]:   {:?}", Tensor::full(&[3], -1.0));
    println!("scalar:      {:?}", Tensor::scalar(42.0));

    // From flat vec
    println!(
        "from_vec:    {:?}",
        Tensor::from_vec(vec![10.0, 20.0, 30.0])
    );

    // Range
    println!("arange:      {:?}", Tensor::arange(0.0, 5.0, 1.0));

    // From nested rows (convenient for trusted literals)
    let rows: Tensor = vec![vec![1.0, 2.0], vec![3.0, 4.0]].into();
    println!("from rows:   {rows:?}");

    // Boundary-safe construction
    let result = Tensor::try_new(vec![1.0, 2.0], &[3]);
    println!("try_new err: {}", result.unwrap_err());
}

examples/12_boundary_error_handling.rs (line 12)

fn main() {
    // ── shape/data mismatch ──────────────────────────────────────────────
    match Tensor::try_new(vec![1.0, 2.0], &[3]) {
        Err(MattenError::Shape { operation, message }) => {
            println!("[Shape]  {operation}: {message}")
        }
        other => println!("{other:?}"),
    }

    // ── malformed JSON ───────────────────────────────────────────────────
    match Tensor::from_json(r#"[[1.0,"text"]]"#) {
        Err(MattenError::Parse { format, message }) => println!("[Parse/{format}]  {message}"),
        other => println!("{other:?}"),
    }

    // ── ragged JSON array ────────────────────────────────────────────────
    match Tensor::from_json("[[1.0,2.0],[3.0]]") {
        Err(MattenError::Parse { format, message }) => println!("[Parse/{format}]  {message}"),
        other => println!("{other:?}"),
    }

    // ── non-numeric CSV field ────────────────────────────────────────────
    match Tensor::load_csv("examples/data/malformed_numeric.csv") {
        Err(MattenError::Parse { format, message }) => println!("[Parse/{format}]  {message}"),
        other => println!("{other:?}"),
    }

    // ── missing file ─────────────────────────────────────────────────────
    match Tensor::load_json("/no/such/file.json") {
        Err(MattenError::Io { path, source }) => println!("[Io]  {}: {source}", path.display()),
        other => println!("{other:?}"),
    }

    // ── slice out of range ───────────────────────────────────────────────
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    match t.slice().index(5).all().build() {
        Err(MattenError::Slice { message, .. }) => println!("[Slice]  {message}"),
        other => println!("{other:?}"),
    }

    println!("All boundary errors handled gracefully — no panics.");
}

pub fn scalar(value: f64) -> Tensor

Creates a rank-0 scalar tensor (shape [], length 1).

use matten::Tensor;
let s = Tensor::scalar(3.14);
assert!(s.is_scalar());
assert_eq!(s.len(), 1);

Examples found in repository

examples/06_broadcasting.rs (line 12)

fn main() {
    // Scalar [] + matrix [2,2] -> [2,2]
    let scalar = Tensor::scalar(10.0);
    let mat = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    println!("scalar + mat = {:?}", &scalar + &mat);

    // Row vector [3] + matrix [2,3] -> [2,3]  (bias addition)
    let matrix = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    let bias = Tensor::new(vec![10.0, 20.0, 30.0], &[3]);
    println!("matrix + bias = {:?}", &matrix + &bias);

    // Column [3,1] + row [1,4] -> [3,4]  (outer product pattern)
    let col = Tensor::new(vec![1.0, 2.0, 3.0], &[3, 1]);
    let row = Tensor::new(vec![10.0, 20.0, 30.0, 40.0], &[1, 4]);
    let result = &col + &row;
    println!("col + row shape = {:?}", result.shape()); // [3, 4]
    println!("col + row data  = {:?}", result.as_slice());
}

examples/02_shape_and_size.rs (line 9)

fn main() {
    let scalar = Tensor::scalar(1.0);
    let vec1d = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
    let mat = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    let rank3 = Tensor::zeros(&[2, 3, 4]);

    for (name, t) in [
        ("scalar", &scalar),
        ("vector", &vec1d),
        ("matrix", &mat),
        ("rank-3", &rank3),
    ] {
        println!(
            "{name:6}: shape={:?}  ndim={}  len={}  is_scalar={}  is_vector={}  is_matrix={}",
            t.shape(),
            t.ndim(),
            t.len(),
            t.is_scalar(),
            t.is_vector(),
            t.is_matrix()
        );
    }

    // Safe element access: Option<f64>, never panics
    println!("\nmat.get([0,1]) = {:?}", mat.get(&[0, 1])); // Some(2.0)
    println!("mat.get([5,0]) = {:?}", mat.get(&[5, 0])); // None
}

examples/01_create_tensor.rs (line 17)

fn main() {
    // From data + shape
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    println!("new:         {t:?}");

    // Fill constructors
    println!("zeros [3]:   {:?}", Tensor::zeros(&[3]));
    println!("ones  [2,2]: {:?}", Tensor::ones(&[2, 2]));
    println!("full  [3]:   {:?}", Tensor::full(&[3], -1.0));
    println!("scalar:      {:?}", Tensor::scalar(42.0));

    // From flat vec
    println!(
        "from_vec:    {:?}",
        Tensor::from_vec(vec![10.0, 20.0, 30.0])
    );

    // Range
    println!("arange:      {:?}", Tensor::arange(0.0, 5.0, 1.0));

    // From nested rows (convenient for trusted literals)
    let rows: Tensor = vec![vec![1.0, 2.0], vec![3.0, 4.0]].into();
    println!("from rows:   {rows:?}");

    // Boundary-safe construction
    let result = Tensor::try_new(vec![1.0, 2.0], &[3]);
    println!("try_new err: {}", result.unwrap_err());
}

pub fn zeros(shape: &[usize]) -> Tensor

Creates a tensor filled with 0.0.

Panics

Panics on an invalid shape (same rules as new).

use matten::Tensor;
let z = Tensor::zeros(&[2, 3]);
assert_eq!(z.shape(), &[2, 3]);
assert_eq!(z.len(), 6);
assert!(z.as_slice().iter().all(|&v| v == 0.0));

Examples found in repository

examples/02_shape_and_size.rs (line 12)

fn main() {
    let scalar = Tensor::scalar(1.0);
    let vec1d = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
    let mat = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    let rank3 = Tensor::zeros(&[2, 3, 4]);

    for (name, t) in [
        ("scalar", &scalar),
        ("vector", &vec1d),
        ("matrix", &mat),
        ("rank-3", &rank3),
    ] {
        println!(
            "{name:6}: shape={:?}  ndim={}  len={}  is_scalar={}  is_vector={}  is_matrix={}",
            t.shape(),
            t.ndim(),
            t.len(),
            t.is_scalar(),
            t.is_vector(),
            t.is_matrix()
        );
    }

    // Safe element access: Option<f64>, never panics
    println!("\nmat.get([0,1]) = {:?}", mat.get(&[0, 1])); // Some(2.0)
    println!("mat.get([5,0]) = {:?}", mat.get(&[5, 0])); // None
}

examples/01_create_tensor.rs (line 14)

fn main() {
    // From data + shape
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    println!("new:         {t:?}");

    // Fill constructors
    println!("zeros [3]:   {:?}", Tensor::zeros(&[3]));
    println!("ones  [2,2]: {:?}", Tensor::ones(&[2, 2]));
    println!("full  [3]:   {:?}", Tensor::full(&[3], -1.0));
    println!("scalar:      {:?}", Tensor::scalar(42.0));

    // From flat vec
    println!(
        "from_vec:    {:?}",
        Tensor::from_vec(vec![10.0, 20.0, 30.0])
    );

    // Range
    println!("arange:      {:?}", Tensor::arange(0.0, 5.0, 1.0));

    // From nested rows (convenient for trusted literals)
    let rows: Tensor = vec![vec![1.0, 2.0], vec![3.0, 4.0]].into();
    println!("from rows:   {rows:?}");

    // Boundary-safe construction
    let result = Tensor::try_new(vec![1.0, 2.0], &[3]);
    println!("try_new err: {}", result.unwrap_err());
}

examples/13_resource_limits.rs (line 46)

fn main() {
    // ── Default limits ────────────────────────────────────────────────────
    let limits = MattenLimits::default();
    println!("Default max_dimensions: {}", limits.max_dimensions);
    println!(
        "Default max_elements:   {} (~{} MiB f64)",
        limits.max_elements,
        limits.max_elements * 8 / 1_048_576
    );

    // ── Boundary-safe constructors ────────────────────────────────────────
    let t = Tensor::try_zeros(&[100, 100]).unwrap();
    assert_eq!(t.shape(), &[100, 100]);
    assert_eq!(t.len(), 10_000);
    println!("try_zeros([100, 100]): OK, {} elements", t.len());

    let t = Tensor::try_ones(&[50, 20]).unwrap();
    assert_eq!(t.as_slice().iter().sum::<f64>(), 1000.0);
    println!("try_ones([50, 20]):    OK, sum = {}", t.sum());

    let t = Tensor::try_full(&[10, 10], -1.0).unwrap();
    assert_eq!(t.as_slice()[0], -1.0);
    println!("try_full([10, 10], -1.0): OK");

    // ── Custom limits ─────────────────────────────────────────────────────
    let tight = MattenLimits {
        max_elements: 10,
        ..MattenLimits::default()
    };
    let err = Tensor::try_zeros_with_limits(&[100], &tight).unwrap_err();
    assert!(matches!(err, MattenError::Allocation { .. }));
    println!("Custom limit (max=10): correctly rejected [100]");

    // ── Panicking variants respect limits too ─────────────────────────────
    // These delegate to try_zeros/try_ones/try_full internally:
    let _t = Tensor::zeros(&[10, 10]); // fine — 100 elements
    println!("zeros([10, 10]):        OK (panicking form, within limit)");

    println!("done.");
}

pub fn ones(shape: &[usize]) -> Tensor

Creates a tensor filled with 1.0.

Panics

Panics on an invalid shape.

use matten::Tensor;
let o = Tensor::ones(&[3]);
assert!(o.as_slice().iter().all(|&v| v == 1.0));

Examples found in repository

examples/00_quickstart.rs (line 13)

fn main() {
    let a = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    let b = Tensor::ones(&[2, 2]);

    let c = &a + &b;
    println!("a      = {a:?}");
    println!("b      = {b:?}");
    println!("a + b  = {c:?}");

    let flat = c.flatten();
    println!("flat   = {flat:?}");

    assert_eq!(flat.shape(), &[4]);
    assert_eq!(flat.as_slice(), &[2.0, 3.0, 4.0, 5.0]);
    println!("All assertions passed.");
}

examples/01_create_tensor.rs (line 15)

fn main() {
    // From data + shape
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    println!("new:         {t:?}");

    // Fill constructors
    println!("zeros [3]:   {:?}", Tensor::zeros(&[3]));
    println!("ones  [2,2]: {:?}", Tensor::ones(&[2, 2]));
    println!("full  [3]:   {:?}", Tensor::full(&[3], -1.0));
    println!("scalar:      {:?}", Tensor::scalar(42.0));

    // From flat vec
    println!(
        "from_vec:    {:?}",
        Tensor::from_vec(vec![10.0, 20.0, 30.0])
    );

    // Range
    println!("arange:      {:?}", Tensor::arange(0.0, 5.0, 1.0));

    // From nested rows (convenient for trusted literals)
    let rows: Tensor = vec![vec![1.0, 2.0], vec![3.0, 4.0]].into();
    println!("from rows:   {rows:?}");

    // Boundary-safe construction
    let result = Tensor::try_new(vec![1.0, 2.0], &[3]);
    println!("try_new err: {}", result.unwrap_err());
}

pub fn full(shape: &[usize], value: f64) -> Tensor

Creates a tensor filled with value.

Panics

Panics on an invalid shape.

use matten::Tensor;
let t = Tensor::full(&[2, 2], 7.0);
assert!(t.as_slice().iter().all(|&v| v == 7.0));

Examples found in repository

examples/04_elementwise_ops.rs (line 9)

fn main() {
    let a = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    let b = Tensor::full(&[2, 2], 2.0);

    println!("a        = {a:?}");
    println!("b        = {b:?}");
    println!("a + b    = {:?}", &a + &b);
    println!("a - b    = {:?}", &a - &b);
    println!("a * b    = {:?}", &a * &b); // element-wise, NOT matrix product
    println!("a / b    = {:?}", &a / &b);
    println!("-a       = {:?}", -&a);
}

examples/01_create_tensor.rs (line 16)

fn main() {
    // From data + shape
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    println!("new:         {t:?}");

    // Fill constructors
    println!("zeros [3]:   {:?}", Tensor::zeros(&[3]));
    println!("ones  [2,2]: {:?}", Tensor::ones(&[2, 2]));
    println!("full  [3]:   {:?}", Tensor::full(&[3], -1.0));
    println!("scalar:      {:?}", Tensor::scalar(42.0));

    // From flat vec
    println!(
        "from_vec:    {:?}",
        Tensor::from_vec(vec![10.0, 20.0, 30.0])
    );

    // Range
    println!("arange:      {:?}", Tensor::arange(0.0, 5.0, 1.0));

    // From nested rows (convenient for trusted literals)
    let rows: Tensor = vec![vec![1.0, 2.0], vec![3.0, 4.0]].into();
    println!("from rows:   {rows:?}");

    // Boundary-safe construction
    let result = Tensor::try_new(vec![1.0, 2.0], &[3]);
    println!("try_new err: {}", result.unwrap_err());
}

pub fn from_vec(data: Vec<f64>) -> Tensor

Creates a 1-D tensor from a flat vector; shape is [data.len()].

Panics

Panics if data is empty (zero-sized dimension).

use matten::Tensor;
let t = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
assert_eq!(t.shape(), &[3]);

Examples found in repository

examples/37_kmeans_small.rs (line 47)

fn nearest(point: &[f64], centroids: &[Vec<f64>]) -> usize {
    let dists: Vec<f64> = centroids.iter().map(|c| sq_dist(point, c)).collect();
    Tensor::from_vec(dists).argmin()
}

examples/34_tiny_pagerank.rs (line 46)

fn pagerank_step(m: &Tensor, r: &Tensor, damping: f64, n: usize) -> Tensor {
    let mr = m.matmul(r); // [n, n] × [n] -> [n]
    let base = (1.0 - damping) / n as f64;
    let next: Vec<f64> = mr.as_slice().iter().map(|&x| base + damping * x).collect();
    Tensor::from_vec(next)
}

fn main() {
    // Directed graph on 4 nodes:
    //   0 -> 1, 0 -> 2, 1 -> 2, 2 -> 0, 3 -> 2
    // Column-stochastic link matrix M (M[i, j] = share of j's rank flowing to i):
    //          from: 0    1   2   3
    //   to 0 [ 0     0    1   0  ]
    //   to 1 [ 0.5   0    0   0  ]
    //   to 2 [ 0.5   1    0   1  ]
    //   to 3 [ 0     0    0   0  ]
    let m = Tensor::new(
        vec![
            0.0, 0.0, 1.0, 0.0, //
            0.5, 0.0, 0.0, 0.0, //
            0.5, 1.0, 0.0, 1.0, //
            0.0, 0.0, 0.0, 0.0, //
        ],
        &[4, 4],
    );

    let n = 4;
    let damping = 0.85;
    let mut r = Tensor::from_vec(vec![0.25, 0.25, 0.25, 0.25]);
    for _ in 0..50 {
        r = pagerank_step(&m, &r, damping, n);
    }

    let ranks = r.as_slice();
    println!("PageRank after 50 iterations (d = {damping}):");
    for (i, &rank) in ranks.iter().enumerate() {
        println!("  node {i}: {rank:.4}");
    }

    // The best-connected node should win; the link-less node 3 only gets teleport.
    let top = ranks
        .iter()
        .enumerate()
        .max_by(|a, b| a.1.partial_cmp(b.1).unwrap())
        .map(|(i, _)| i)
        .unwrap();
    println!("highest-ranked node: {top}");

    let total: f64 = ranks.iter().sum();
    assert!((total - 1.0).abs() < 1e-9, "ranks must sum to 1");
    assert_eq!(top, 2, "node 2 receives the most links");
    println!("Tiny PageRank: OK");
}

examples/38_nearest_neighbor_classification.rs (line 47)

fn classify(query: &[f64], train: &Tensor, labels: &[u8]) -> u8 {
    let dim = train.shape()[1];
    let data = train.as_slice();
    let dists: Vec<f64> = (0..train.shape()[0])
        .map(|i| sq_dist(query, &data[i * dim..(i + 1) * dim]))
        .collect();
    labels[Tensor::from_vec(dists).argmin()]
}

examples/25_normalize_vector.rs (line 22)

fn main() {
    let v = Tensor::from_vec(vec![3.0, 4.0]);
    println!("v        = {:?}", v.as_slice());
    println!("‖v‖      = {}", l2_norm(&v)); // 5.0

    let u = normalize(&v);
    println!("norm(v)  = {:?}", u.as_slice()); // [0.6, 0.8]

    let norm_u = l2_norm(&u);
    println!("‖norm(v)‖ = {norm_u:.6}"); // ≈ 1.0
    assert!((norm_u - 1.0).abs() < 1e-10, "unit vector check failed");
    println!("Unit vector check: OK");
}

examples/rolling_windows_basic.rs (line 20)

fn main() {
    let series = Tensor::from_vec(vec![3.0, 1.0, 4.0, 1.0, 5.0, 9.0, 2.0, 6.0]);
    let w = 3;

    let sums = rolling_sum(&series, w);
    let maxes = rolling_max(&series, w);

    println!("series       = {:?}", series.as_slice());
    println!("rolling sum  = {:?}", sums);
    println!("rolling max  = {:?}", maxes);

    assert_eq!(sums[0], 8.0); // 3+1+4
    assert_eq!(maxes[0], 4.0); // max(3,1,4)
    println!("Rolling windows: OK");
}

examples/20_dot_product.rs (line 11)

fn main() {
    let a = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
    let b = Tensor::from_vec(vec![4.0, 5.0, 6.0]);

    let d = a.dot(&b); // 1*4 + 2*5 + 3*6 = 32
    assert!(d.is_scalar());
    println!("a · b = {}", d.as_slice()[0]); // 32.0

    // Orthogonal vectors have zero dot product
    let x = Tensor::from_vec(vec![1.0, 0.0]);
    let y = Tensor::from_vec(vec![0.0, 1.0]);
    assert_eq!(x.dot(&y).as_slice(), &[0.0]);
    println!("orthogonal dot = 0: OK");
}

Additional examples can be found in:

• examples/35_linear_regression_gradient_descent.rs
• examples/21_matrix_vector_product.rs
• examples/26_cosine_similarity.rs
• examples/moving_average.rs
• examples/24_min_max.rs
• examples/23_sum_mean.rs
• examples/02_shape_and_size.rs
• examples/01_create_tensor.rs
• examples/33_markov_chain_weather.rs
• examples/36_heat_equation_1d.rs

pub fn arange(start: f64, end: f64, step: f64) -> Tensor

Creates a 1-D tensor with values start, start + step, ... (half-open, so end is excluded).

This is a panic-zone convenience. Use try_arange when start/end/step come from user input.

Panics

Panics if step == 0.0, any argument is non-finite, or the computed element count would exceed the allocation limit.

use matten::Tensor;
let r = Tensor::arange(0.0, 5.0, 1.0);
assert_eq!(r.as_slice(), &[0.0, 1.0, 2.0, 3.0, 4.0]);

let r2 = Tensor::arange(1.0, 0.0, -0.5);
assert_eq!(r2.as_slice(), &[1.0, 0.5]);

Examples found in repository

examples/01_create_tensor.rs (line 26)

fn main() {
    // From data + shape
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    println!("new:         {t:?}");

    // Fill constructors
    println!("zeros [3]:   {:?}", Tensor::zeros(&[3]));
    println!("ones  [2,2]: {:?}", Tensor::ones(&[2, 2]));
    println!("full  [3]:   {:?}", Tensor::full(&[3], -1.0));
    println!("scalar:      {:?}", Tensor::scalar(42.0));

    // From flat vec
    println!(
        "from_vec:    {:?}",
        Tensor::from_vec(vec![10.0, 20.0, 30.0])
    );

    // Range
    println!("arange:      {:?}", Tensor::arange(0.0, 5.0, 1.0));

    // From nested rows (convenient for trusted literals)
    let rows: Tensor = vec![vec![1.0, 2.0], vec![3.0, 4.0]].into();
    println!("from rows:   {rows:?}");

    // Boundary-safe construction
    let result = Tensor::try_new(vec![1.0, 2.0], &[3]);
    println!("try_new err: {}", result.unwrap_err());
}

pub fn try_arange( start: f64, end: f64, step: f64, ) -> Result<Tensor, MattenError>

Creates a 1-D tensor with values start, start + step, ... (half-open), returning an error instead of panicking.

Errors

Returns MattenError::Shape for a zero or non-finite step/bound, or MattenError::Allocation if the computed element count exceeds the allocation limit.

pub fn try_from_rows(rows: Vec<Vec<f64>>) -> Result<Tensor, MattenError>

Creates a 2-D tensor from rectangular row data; shape is [rows, cols].

This is the recoverable version of From<Vec<Vec<f64>>>.

Errors

Returns MattenError::Shape on an empty outer vector, any zero-length row, or ragged rows.

pub fn shape(&self) -> &[usize]

The shape as a slice of dimension lengths. Non-allocating.

Examples found in repository

examples/hello_tensor.rs (line 12)

fn main() {
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    println!("{t:?}");
    println!(
        "shape = {:?}, len = {}, ndim = {}",
        t.shape(),
        t.len(),
        t.ndim()
    );
}

examples/38_nearest_neighbor_classification.rs (line 42)

fn classify(query: &[f64], train: &Tensor, labels: &[u8]) -> u8 {
    let dim = train.shape()[1];
    let data = train.as_slice();
    let dists: Vec<f64> = (0..train.shape()[0])
        .map(|i| sq_dist(query, &data[i * dim..(i + 1) * dim]))
        .collect();
    labels[Tensor::from_vec(dists).argmin()]
}

examples/32_graph_path_counting.rs (line 59)

fn print_matrix(label: &str, m: &Tensor) {
    let (rows, cols) = (m.shape()[0], m.shape()[1]);
    println!("{label}:");
    for i in 0..rows {
        let row: Vec<String> = (0..cols)
            .map(|j| format!("{:.0}", m.get(&[i, j]).expect("index in bounds")))
            .collect();
        println!("  [{}]", row.join(", "));
    }
}

examples/00_quickstart.rs (line 23)

fn main() {
    let a = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    let b = Tensor::ones(&[2, 2]);

    let c = &a + &b;
    println!("a      = {a:?}");
    println!("b      = {b:?}");
    println!("a + b  = {c:?}");

    let flat = c.flatten();
    println!("flat   = {flat:?}");

    assert_eq!(flat.shape(), &[4]);
    assert_eq!(flat.as_slice(), &[2.0, 3.0, 4.0, 5.0]);
    println!("All assertions passed.");
}

examples/21_matrix_vector_product.rs (line 19)

fn main() {
    // [[1,2,3],[4,5,6]] × [1,0,1] = [4, 10]
    let m = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    let v = Tensor::from_vec(vec![1.0, 0.0, 1.0]);

    let r = m.matmul(&v);
    println!("m    = {m:?}");
    println!("v    = {v:?}");
    println!("m·v  = {r:?}"); // [4.0, 10.0]

    assert_eq!(r.shape(), &[2]);
    assert_eq!(r.as_slice(), &[4.0, 10.0]);

    // Vector × matrix: [n] × [n, p] -> [p]
    let w = Tensor::from_vec(vec![1.0, 2.0]);
    let r2 = w.matmul(&m.transpose());
    println!("w·mᵀ = {r2:?}");

    println!("Shapes and values verified: OK");
}

examples/07_transpose_swap_axes.rs (line 13)

fn main() {
    // 2-D transpose: swap rows and columns
    let m = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    println!("original  {m:?}");
    let mt = m.transpose();
    println!("transposed {mt:?}");
    assert_eq!(mt.shape(), &[3, 2]);

    // t() is an alias
    assert_eq!(m.t(), mt);

    // Transpose twice is identity
    assert_eq!(m.transpose().transpose(), m);
    println!("transpose twice == identity: OK");

    // swap_axes on rank-3
    let r3 = Tensor::new((1..=24).map(|x| x as f64).collect(), &[2, 3, 4]);
    let s = r3.swap_axes(0, 2);
    println!("rank-3 swap_axes(0,2) shape: {:?}", s.shape()); // [4,3,2]
}

Additional examples can be found in:

• examples/22_matrix_multiplication.rs
• examples/gram_matrix.rs
• examples/rowwise_scoring.rs
• examples/column_summary.rs
• examples/06_broadcasting.rs
• examples/pairwise_distance.rs
• examples/02_shape_and_size.rs
• examples/11_csv_numeric_loading.rs
• examples/minmax_scaling.rs
• examples/30_magic_square_checker.rs
• examples/standardize_columns.rs
• examples/10_json_roundtrip.rs
• examples/27_axis_reductions.rs
• examples/37_kmeans_small.rs
• examples/13_resource_limits.rs

pub fn ndim(&self) -> usize

The rank (number of dimensions): shape().len().

Examples found in repository

examples/hello_tensor.rs (line 14)

fn main() {
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    println!("{t:?}");
    println!(
        "shape = {:?}, len = {}, ndim = {}",
        t.shape(),
        t.len(),
        t.ndim()
    );
}

examples/02_shape_and_size.rs (line 23)

fn main() {
    let scalar = Tensor::scalar(1.0);
    let vec1d = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
    let mat = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    let rank3 = Tensor::zeros(&[2, 3, 4]);

    for (name, t) in [
        ("scalar", &scalar),
        ("vector", &vec1d),
        ("matrix", &mat),
        ("rank-3", &rank3),
    ] {
        println!(
            "{name:6}: shape={:?}  ndim={}  len={}  is_scalar={}  is_vector={}  is_matrix={}",
            t.shape(),
            t.ndim(),
            t.len(),
            t.is_scalar(),
            t.is_vector(),
            t.is_matrix()
        );
    }

    // Safe element access: Option<f64>, never panics
    println!("\nmat.get([0,1]) = {:?}", mat.get(&[0, 1])); // Some(2.0)
    println!("mat.get([5,0]) = {:?}", mat.get(&[5, 0])); // None
}

pub fn len(&self) -> usize

The logical element count: the product of the shape.

Examples found in repository

examples/rolling_windows_basic.rs (line 8)

fn rolling_sum(t: &Tensor, window: usize) -> Vec<f64> {
    (0..=(t.len() - window))
        .map(|i| t.slice().range(i..i + window).build().unwrap().sum())
        .collect()
}

fn rolling_max(t: &Tensor, window: usize) -> Vec<f64> {
    (0..=(t.len() - window))
        .map(|i| t.slice().range(i..i + window).build().unwrap().max())
        .collect()
}

examples/hello_tensor.rs (line 13)

fn main() {
    let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    println!("{t:?}");
    println!(
        "shape = {:?}, len = {}, ndim = {}",
        t.shape(),
        t.len(),
        t.ndim()
    );
}

examples/moving_average.rs (line 10)

fn main() {
    let series = Tensor::from_vec(vec![1.0, 3.0, 5.0, 7.0, 9.0, 11.0, 13.0]);
    let window = 3usize;
    let n = series.len();

    // Compute moving averages for windows [0..3], [1..4], ...
    let mut avgs = Vec::new();
    for start in 0..=(n - window) {
        let w = series.slice().range(start..start + window).build().unwrap();
        avgs.push(w.mean());
    }

    println!("series = {:?}", series.as_slice());
    println!("3-pt moving avg = {:?}", avgs);
    assert_eq!(avgs.len(), n - window + 1);
    assert!((avgs[0] - 3.0).abs() < 1e-10); // mean(1,3,5) = 3
    assert!((avgs[1] - 5.0).abs() < 1e-10); // mean(3,5,7) = 5
    println!("Moving average: OK");
}

examples/02_shape_and_size.rs (line 24)

fn main() {
    let scalar = Tensor::scalar(1.0);
    let vec1d = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
    let mat = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    let rank3 = Tensor::zeros(&[2, 3, 4]);

    for (name, t) in [
        ("scalar", &scalar),
        ("vector", &vec1d),
        ("matrix", &mat),
        ("rank-3", &rank3),
    ] {
        println!(
            "{name:6}: shape={:?}  ndim={}  len={}  is_scalar={}  is_vector={}  is_matrix={}",
            t.shape(),
            t.ndim(),
            t.len(),
            t.is_scalar(),
            t.is_vector(),
            t.is_matrix()
        );
    }

    // Safe element access: Option<f64>, never panics
    println!("\nmat.get([0,1]) = {:?}", mat.get(&[0, 1])); // Some(2.0)
    println!("mat.get([5,0]) = {:?}", mat.get(&[5, 0])); // None
}

examples/13_resource_limits.rs (line 24)

fn main() {
    // ── Default limits ────────────────────────────────────────────────────
    let limits = MattenLimits::default();
    println!("Default max_dimensions: {}", limits.max_dimensions);
    println!(
        "Default max_elements:   {} (~{} MiB f64)",
        limits.max_elements,
        limits.max_elements * 8 / 1_048_576
    );

    // ── Boundary-safe constructors ────────────────────────────────────────
    let t = Tensor::try_zeros(&[100, 100]).unwrap();
    assert_eq!(t.shape(), &[100, 100]);
    assert_eq!(t.len(), 10_000);
    println!("try_zeros([100, 100]): OK, {} elements", t.len());

    let t = Tensor::try_ones(&[50, 20]).unwrap();
    assert_eq!(t.as_slice().iter().sum::<f64>(), 1000.0);
    println!("try_ones([50, 20]):    OK, sum = {}", t.sum());

    let t = Tensor::try_full(&[10, 10], -1.0).unwrap();
    assert_eq!(t.as_slice()[0], -1.0);
    println!("try_full([10, 10], -1.0): OK");

    // ── Custom limits ─────────────────────────────────────────────────────
    let tight = MattenLimits {
        max_elements: 10,
        ..MattenLimits::default()
    };
    let err = Tensor::try_zeros_with_limits(&[100], &tight).unwrap_err();
    assert!(matches!(err, MattenError::Allocation { .. }));
    println!("Custom limit (max=10): correctly rejected [100]");

    // ── Panicking variants respect limits too ─────────────────────────────
    // These delegate to try_zeros/try_ones/try_full internally:
    let _t = Tensor::zeros(&[10, 10]); // fine — 100 elements
    println!("zeros([10, 10]):        OK (panicking form, within limit)");

    println!("done.");
}

pub fn is_scalar(&self) -> bool

Returns true for a rank-0 scalar tensor (shape []).

Examples found in repository

examples/20_dot_product.rs (line 15)

fn main() {
    let a = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
    let b = Tensor::from_vec(vec![4.0, 5.0, 6.0]);

    let d = a.dot(&b); // 1*4 + 2*5 + 3*6 = 32
    assert!(d.is_scalar());
    println!("a · b = {}", d.as_slice()[0]); // 32.0

    // Orthogonal vectors have zero dot product
    let x = Tensor::from_vec(vec![1.0, 0.0]);
    let y = Tensor::from_vec(vec![0.0, 1.0]);
    assert_eq!(x.dot(&y).as_slice(), &[0.0]);
    println!("orthogonal dot = 0: OK");
}

examples/08_slicing_builder.rs (line 27)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let t = Tensor::new((1..=12).map(|x| x as f64).collect(), &[3, 4]);
    println!("tensor   {t:?}");

    // First row (index 0, axis removed from output shape)
    let row0 = t.slice().index(0).all().build()?;
    println!("row 0    {row0:?}"); // shape [4]

    // First two rows, all columns
    let top2 = t.slice().range(0..2).all().build()?;
    println!("top 2    {top2:?}"); // shape [2,4]

    // All rows, columns 1..3
    let cols = t.slice().all().range(1..3).build()?;
    println!("cols 1:3 {cols:?}"); // shape [3,2]

    // Single element -> scalar
    let elem = t.slice().index(1).index(2).build()?;
    assert!(elem.is_scalar());
    println!("t[1,2]   {elem:?}");

    Ok(())
}

examples/02_shape_and_size.rs (line 25)

fn main() {
    let scalar = Tensor::scalar(1.0);
    let vec1d = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
    let mat = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    let rank3 = Tensor::zeros(&[2, 3, 4]);

    for (name, t) in [
        ("scalar", &scalar),
        ("vector", &vec1d),
        ("matrix", &mat),
        ("rank-3", &rank3),
    ] {
        println!(
            "{name:6}: shape={:?}  ndim={}  len={}  is_scalar={}  is_vector={}  is_matrix={}",
            t.shape(),
            t.ndim(),
            t.len(),
            t.is_scalar(),
            t.is_vector(),
            t.is_matrix()
        );
    }

    // Safe element access: Option<f64>, never panics
    println!("\nmat.get([0,1]) = {:?}", mat.get(&[0, 1])); // Some(2.0)
    println!("mat.get([5,0]) = {:?}", mat.get(&[5, 0])); // None
}

pub fn is_vector(&self) -> bool

Returns true for a rank-1 tensor.

Examples found in repository

examples/02_shape_and_size.rs (line 26)

fn main() {
    let scalar = Tensor::scalar(1.0);
    let vec1d = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
    let mat = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    let rank3 = Tensor::zeros(&[2, 3, 4]);

    for (name, t) in [
        ("scalar", &scalar),
        ("vector", &vec1d),
        ("matrix", &mat),
        ("rank-3", &rank3),
    ] {
        println!(
            "{name:6}: shape={:?}  ndim={}  len={}  is_scalar={}  is_vector={}  is_matrix={}",
            t.shape(),
            t.ndim(),
            t.len(),
            t.is_scalar(),
            t.is_vector(),
            t.is_matrix()
        );
    }

    // Safe element access: Option<f64>, never panics
    println!("\nmat.get([0,1]) = {:?}", mat.get(&[0, 1])); // Some(2.0)
    println!("mat.get([5,0]) = {:?}", mat.get(&[5, 0])); // None
}

pub fn is_matrix(&self) -> bool

Returns true for a rank-2 tensor.

Examples found in repository

examples/02_shape_and_size.rs (line 27)

fn main() {
    let scalar = Tensor::scalar(1.0);
    let vec1d = Tensor::from_vec(vec![1.0, 2.0, 3.0]);
    let mat = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);
    let rank3 = Tensor::zeros(&[2, 3, 4]);

    for (name, t) in [
        ("scalar", &scalar),
        ("vector", &vec1d),
        ("matrix", &mat),
        ("rank-3", &rank3),
    ] {
        println!(
            "{name:6}: shape={:?}  ndim={}  len={}  is_scalar={}  is_vector={}  is_matrix={}",
            t.shape(),
            t.ndim(),
            t.len(),
            t.is_scalar(),
            t.is_vector(),
            t.is_matrix()
        );
    }

    // Safe element access: Option<f64>, never panics
    println!("\nmat.get([0,1]) = {:?}", mat.get(&[0, 1])); // Some(2.0)
    println!("mat.get([5,0]) = {:?}", mat.get(&[5, 0])); // None
}

pub fn is_dynamic(&self) -> bool

Returns true if this tensor uses dynamic ([Element]) storage.

This method is available in all builds, regardless of whether the dynamic feature is enabled:

• When dynamic is off, no dynamic tensor can be constructed, so this always returns false.
• When dynamic is on, it returns true for tensors built via the dynamic API (e.g. [Tensor::from_elements]) and false for ordinary numeric tensors.

Companion crates call this unconditionally before numeric conversion so that a dynamic Tensor is rejected with a typed Err rather than reaching internal numeric accessors and panicking — even when Cargo feature unification enables core dynamic while the companion’s own mirror feature is off.

pub fn as_slice(&self) -> &[f64]

The flat, row-major data as a slice.

Examples found in repository

examples/25_normalize_vector.rs (line 12)

fn l2_norm(v: &Tensor) -> f64 {
    v.as_slice().iter().map(|x| x * x).sum::<f64>().sqrt()
}

/// Returns the L2-normalised version of `v` (unit vector).
fn normalize(v: &Tensor) -> Tensor {
    let norm = l2_norm(v);
    v / norm
}

fn main() {
    let v = Tensor::from_vec(vec![3.0, 4.0]);
    println!("v        = {:?}", v.as_slice());
    println!("‖v‖      = {}", l2_norm(&v)); // 5.0

    let u = normalize(&v);
    println!("norm(v)  = {:?}", u.as_slice()); // [0.6, 0.8]

    let norm_u = l2_norm(&u);
    println!("‖norm(v)‖ = {norm_u:.6}"); // ≈ 1.0
    assert!((norm_u - 1.0).abs() < 1e-10, "unit vector check failed");
    println!("Unit vector check: OK");
}

examples/26_cosine_similarity.rs (line 10)

fn l2_norm(v: &Tensor) -> f64 {
    v.as_slice().iter().map(|x| x * x).sum::<f64>().sqrt()
}

fn cosine_similarity(a: &Tensor, b: &Tensor) -> f64 {
    // a · b is the scalar dot product
    let dot = a.dot(b).as_slice()[0];
    dot / (l2_norm(a) * l2_norm(b))
}

examples/34_tiny_pagerank.rs (line 45)

fn pagerank_step(m: &Tensor, r: &Tensor, damping: f64, n: usize) -> Tensor {
    let mr = m.matmul(r); // [n, n] × [n] -> [n]
    let base = (1.0 - damping) / n as f64;
    let next: Vec<f64> = mr.as_slice().iter().map(|&x| base + damping * x).collect();
    Tensor::from_vec(next)
}

fn main() {
    // Directed graph on 4 nodes:
    //   0 -> 1, 0 -> 2, 1 -> 2, 2 -> 0, 3 -> 2
    // Column-stochastic link matrix M (M[i, j] = share of j's rank flowing to i):
    //          from: 0    1   2   3
    //   to 0 [ 0     0    1   0  ]
    //   to 1 [ 0.5   0    0   0  ]
    //   to 2 [ 0.5   1    0   1  ]
    //   to 3 [ 0     0    0   0  ]
    let m = Tensor::new(
        vec![
            0.0, 0.0, 1.0, 0.0, //
            0.5, 0.0, 0.0, 0.0, //
            0.5, 1.0, 0.0, 1.0, //
            0.0, 0.0, 0.0, 0.0, //
        ],
        &[4, 4],
    );

    let n = 4;
    let damping = 0.85;
    let mut r = Tensor::from_vec(vec![0.25, 0.25, 0.25, 0.25]);
    for _ in 0..50 {
        r = pagerank_step(&m, &r, damping, n);
    }

    let ranks = r.as_slice();
    println!("PageRank after 50 iterations (d = {damping}):");
    for (i, &rank) in ranks.iter().enumerate() {
        println!("  node {i}: {rank:.4}");
    }

    // The best-connected node should win; the link-less node 3 only gets teleport.
    let top = ranks
        .iter()
        .enumerate()
        .max_by(|a, b| a.1.partial_cmp(b.1).unwrap())
        .map(|(i, _)| i)
        .unwrap();
    println!("highest-ranked node: {top}");

    let total: f64 = ranks.iter().sum();
    assert!((total - 1.0).abs() < 1e-9, "ranks must sum to 1");
    assert_eq!(top, 2, "node 2 receives the most links");
    println!("Tiny PageRank: OK");
}

examples/38_nearest_neighbor_classification.rs (line 43)

fn classify(query: &[f64], train: &Tensor, labels: &[u8]) -> u8 {
    let dim = train.shape()[1];
    let data = train.as_slice();
    let dists: Vec<f64> = (0..train.shape()[0])
        .map(|i| sq_dist(query, &data[i * dim..(i + 1) * dim]))
        .collect();
    labels[Tensor::from_vec(dists).argmin()]
}

examples/28_column_statistics.rs (line 17)

fn column_std(data: &Tensor, col_means: &Tensor) -> Tensor {
    // Broadcast means over all rows, compute squared deviations
    let deviations = data - col_means; // [rows, cols] - [cols] → [rows, cols]
    let sq = &deviations * &deviations;
    sq.mean_axis(0) // → [cols] mean of squared deviations
        .as_slice()
        .iter()
        .map(|v| v.sqrt())
        .collect::<Vec<f64>>()
        .into()
}

fn main() {
    // 4 rows, 3 columns (features)
    let data = Tensor::new(
        vec![
            1.0, 10.0, 100.0, 2.0, 20.0, 200.0, 3.0, 30.0, 300.0, 4.0, 40.0, 400.0,
        ],
        &[4, 3],
    );

    let means = data.mean_axis(0);
    let mins = data.min_axis(0);
    let maxs = data.max_axis(0);
    let stds = column_std(&data, &means);

    println!("columns : 0      1      2");
    println!("mean    : {:?}", means.as_slice());
    println!("min     : {:?}", mins.as_slice());
    println!("max     : {:?}", maxs.as_slice());
    println!("std dev : {:?}", stds.as_slice());

    assert_eq!(means.as_slice(), &[2.5, 25.0, 250.0]);
    assert_eq!(mins.as_slice(), &[1.0, 10.0, 100.0]);
    assert_eq!(maxs.as_slice(), &[4.0, 40.0, 400.0]);

    // Std dev: sqrt of mean squared deviation from mean
    let expected_std0 = {
        // Column 0 values: 1,2,3,4. Mean=2.5. Deviations: -1.5,-0.5,0.5,1.5
        let sq_devs = [
            1.5f64.powi(2),
            0.5f64.powi(2),
            0.5f64.powi(2),
            1.5f64.powi(2),
        ];
        (sq_devs.iter().sum::<f64>() / 4.0).sqrt()
    };
    assert!((stds.as_slice()[0] - expected_std0).abs() < 1e-10);

    println!("done.");
}

examples/00_quickstart.rs (line 24)

fn main() {
    let a = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
    let b = Tensor::ones(&[2, 2]);

    let c = &a + &b;
    println!("a      = {a:?}");
    println!("b      = {b:?}");
    println!("a + b  = {c:?}");

    let flat = c.flatten();
    println!("flat   = {flat:?}");

    assert_eq!(flat.shape(), &[4]);
    assert_eq!(flat.as_slice(), &[2.0, 3.0, 4.0, 5.0]);
    println!("All assertions passed.");
}

Additional examples can be found in:

• examples/rolling_windows_basic.rs
• examples/20_dot_product.rs
• examples/35_linear_regression_gradient_descent.rs
• examples/03_reshape_flatten.rs
• examples/21_matrix_vector_product.rs
• examples/22_matrix_multiplication.rs
• examples/moving_average.rs
• examples/40_trapezoidal_integration.rs
• examples/rowwise_scoring.rs
• examples/column_summary.rs
• examples/23_sum_mean.rs
• examples/06_broadcasting.rs
• examples/pairwise_distance.rs
• examples/11_csv_numeric_loading.rs
• examples/minmax_scaling.rs
• examples/39_finite_difference_derivative.rs
• examples/33_markov_chain_weather.rs
• examples/standardize_columns.rs
• examples/36_heat_equation_1d.rs
• examples/27_axis_reductions.rs
• examples/37_kmeans_small.rs
• examples/13_resource_limits.rs

pub fn to_vec(&self) -> Vec<f64>

Returns an owned copy of the flat, row-major data.

pub fn into_vec(self) -> Vec<f64>

Consumes the tensor and returns the flat, row-major data. No copy.

Trait Implementations

impl Add for &Tensor

fn add(self, rhs: &Tensor) -> Tensor

Element-wise addition with NumPy-style broadcasting.

Panics

Panics with "matten broadcast error in add: ..." if the shapes are incompatible.

use matten::Tensor;
let a = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
let b = Tensor::ones(&[2, 2]);
let c = &a + &b;
assert_eq!(c.as_slice(), &[2.0, 3.0, 4.0, 5.0]);

type Output = Tensor

The resulting type after applying the + operator.

impl Add<&Tensor> for f64

fn add(self, rhs: &Tensor) -> Tensor

Adds every element of the tensor to a scalar (scalar + &tensor).

use matten::Tensor;
let t = Tensor::new(vec![1.0, 2.0, 3.0], &[3]);
let r = 10.0 + &t;
assert_eq!(r.as_slice(), &[11.0, 12.0, 13.0]);

type Output = Tensor

The resulting type after applying the + operator.

impl Add<f64> for &Tensor

fn add(self, rhs: f64) -> Tensor

Adds a scalar to every element.

use matten::Tensor;
let t = Tensor::new(vec![1.0, 2.0, 3.0], &[3]);
let r = &t + 10.0;
assert_eq!(r.as_slice(), &[11.0, 12.0, 13.0]);

type Output = Tensor

The resulting type after applying the + operator.

impl Clone for Tensor

fn clone(&self) -> Tensor

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Tensor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Tensor

Available on crate feature serde only.

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Div for &Tensor

fn div(self, rhs: &Tensor) -> Tensor

Element-wise division with broadcasting. Division by zero follows IEEE 754 f64 behavior (yields inf, -inf, or NaN); no error is produced.

Panics

Panics on incompatible shapes.

use matten::Tensor;
let a = Tensor::new(vec![4.0, 9.0], &[2]);
let b = Tensor::new(vec![2.0, 3.0], &[2]);
let c = &a / &b;
assert_eq!(c.as_slice(), &[2.0, 3.0]);

type Output = Tensor

The resulting type after applying the / operator.

impl Div<&Tensor> for f64

fn div(self, rhs: &Tensor) -> Tensor

Divides a scalar by each tensor element (scalar / &tensor). Division by zero follows IEEE 754.

use matten::Tensor;
let t = Tensor::new(vec![2.0, 4.0, 8.0], &[3]);
let r = 16.0 / &t;
assert_eq!(r.as_slice(), &[8.0, 4.0, 2.0]);

type Output = Tensor

The resulting type after applying the / operator.

impl Div<f64> for &Tensor

fn div(self, rhs: f64) -> Tensor

Divides every element by a scalar. Division by zero follows IEEE 754.

use matten::Tensor;
let t = Tensor::new(vec![6.0, 4.0, 2.0], &[3]);
let r = &t / 2.0;
assert_eq!(r.as_slice(), &[3.0, 2.0, 1.0]);

type Output = Tensor

The resulting type after applying the / operator.

impl From<&Tensor> for Vec<f64>

fn from(t: &Tensor) -> Vec<f64>

Returns an owned copy of the tensor’s flat, row-major data.

impl From<Tensor> for Vec<f64>

fn from(t: Tensor) -> Vec<f64>

Consumes the tensor and returns the flat, row-major data. No copy.

impl From<Vec<Vec<f64>>> for Tensor

fn from(rows: Vec<Vec<f64>>) -> Self

Creates a 2-D tensor from rectangular row data; shape is [rows, cols].

This is a convenience for trusted literals and examples. It panics on ragged rows, an empty outer vector, or any row with zero columns. Use Tensor::try_from_rows for recoverable, boundary-safe construction.

Panics

Panics on ragged rows, an empty outer vector, or any zero-length row.

impl From<Vec<f64>> for Tensor

fn from(data: Vec<f64>) -> Self

Creates a 1-D tensor from a flat vector; shape is [len].

Panics

Panics only if the resulting [len] shape is somehow invalid (not possible for non-empty Vec<f64> unless len is 0, which triggers the zero-sized-dimension policy). An empty vector will panic.

impl Mul for &Tensor

fn mul(self, rhs: &Tensor) -> Tensor

Element-wise multiplication with broadcasting (* is not matrix multiply; use matmul for that).

Panics

Panics on incompatible shapes.

use matten::Tensor;
let a = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
let b = Tensor::full(&[2, 2], 2.0);
let c = &a * &b;
assert_eq!(c.as_slice(), &[2.0, 4.0, 6.0, 8.0]);

type Output = Tensor

The resulting type after applying the * operator.

impl Mul<&Tensor> for f64

fn mul(self, rhs: &Tensor) -> Tensor

Multiplies every element of the tensor by a scalar (scalar * &tensor).

use matten::Tensor;
let t = Tensor::new(vec![1.0, 2.0, 3.0], &[3]);
let r = 3.0 * &t;
assert_eq!(r.as_slice(), &[3.0, 6.0, 9.0]);

type Output = Tensor

The resulting type after applying the * operator.

impl Mul<f64> for &Tensor

fn mul(self, rhs: f64) -> Tensor

Multiplies every element by a scalar.

use matten::Tensor;
let t = Tensor::new(vec![1.0, 2.0, 3.0], &[3]);
let r = &t * 3.0;
assert_eq!(r.as_slice(), &[3.0, 6.0, 9.0]);

type Output = Tensor

The resulting type after applying the * operator.

impl Neg for &Tensor

fn neg(self) -> Tensor

Negates every element.

use matten::Tensor;
let t = Tensor::new(vec![1.0, -2.0, 3.0], &[3]);
let r = -&t;
assert_eq!(r.as_slice(), &[-1.0, 2.0, -3.0]);

type Output = Tensor

The resulting type after applying the - operator.

impl PartialEq for Tensor

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Tensor

Available on crate feature serde only.

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl Sub for &Tensor

fn sub(self, rhs: &Tensor) -> Tensor

Element-wise subtraction with broadcasting.

Panics

Panics on incompatible shapes.

use matten::Tensor;
let a = Tensor::new(vec![5.0, 4.0, 3.0, 2.0], &[2, 2]);
let b = Tensor::ones(&[2, 2]);
let c = &a - &b;
assert_eq!(c.as_slice(), &[4.0, 3.0, 2.0, 1.0]);

type Output = Tensor

The resulting type after applying the - operator.

impl Sub<&Tensor> for f64

fn sub(self, rhs: &Tensor) -> Tensor

Subtracts each tensor element from a scalar (scalar - &tensor).

use matten::Tensor;
let t = Tensor::new(vec![1.0, 2.0, 3.0], &[3]);
let r = 10.0 - &t;
assert_eq!(r.as_slice(), &[9.0, 8.0, 7.0]);

type Output = Tensor

The resulting type after applying the - operator.

impl Sub<f64> for &Tensor

fn sub(self, rhs: f64) -> Tensor

Subtracts a scalar from every element.

use matten::Tensor;
let t = Tensor::new(vec![5.0, 3.0, 1.0], &[3]);
let r = &t - 1.0;
assert_eq!(r.as_slice(), &[4.0, 2.0, 0.0]);

type Output = Tensor

The resulting type after applying the - operator.

impl TryFrom<Tensor> for Vec<Vec<f64>>

fn try_from(t: Tensor) -> Result<Vec<Vec<f64>>, MattenError>

Consumes a 2-D tensor and returns rows of owned data.

Errors

Returns MattenError::Shape if the tensor is not rank 2.

type Error = MattenError

The type returned in the event of a conversion error.