matten: The core `Tensor`

This is the second of four short posts about matten. The first post explained the motivation. This one shows what the library looks like in practice.

Getting started

# Cargo.toml
[dependencies]
matten = "0.28"

Enter fullscreen mode Exit fullscreen mode

The default feature set includes serde, json, and csv. If you want the smallest possible dependency footprint, you can turn them off:

matten = { version = "0.28", default-features = false }

Enter fullscreen mode Exit fullscreen mode

Creating tensors

The whole import is use matten::Tensor;. No generic parameters, no lifetime annotations.

use matten::Tensor;

// From data and an explicit shape
let a = Tensor::new(vec![1.0, 2.0, 3.0, 4.0], &[2, 2]);
assert_eq!(a.shape(), &[2, 2]);
assert_eq!(a.ndim(), 2);

// Convenience constructors
let z = Tensor::zeros(&[3, 3]);
let o = Tensor::ones(&[3, 3]);
let f = Tensor::full(&[2, 4], 5.0);

Enter fullscreen mode Exit fullscreen mode

Shape mismatches produce an actionable error rather than a panic when you use the boundary-style constructor:

use matten::{MattenError, Tensor};

let result = Tensor::try_new(vec![1.0, 2.0, 3.0], &[2, 2]);
assert!(matches!(result, Err(MattenError::Shape { .. })));

Enter fullscreen mode Exit fullscreen mode

Arithmetic and broadcasting

The operators work on references, so you keep ownership of the originals. Shape broadcasting follows NumPy-style right-alignment rules.

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;          // [2.0, 3.0, 4.0, 5.0]
let d = &a * 2.0;         // scalar broadcast: [2.0, 4.0, 6.0, 8.0]

// Broadcasting a row across a matrix
let row = Tensor::new(vec![1.0, 2.0], &[1, 2]);
let mat = Tensor::ones(&[3, 2]);
let result = &mat + &row; // shape [3, 2]

Enter fullscreen mode Exit fullscreen mode

Shape operations

use matten::Tensor;

let t = Tensor::new(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0], &[2, 3]);

let flat = t.flatten();           // shape [6]
let reshaped = t.reshape(&[3, 2])?;
let transposed = t.transpose()?;  // shape [3, 2]

// Reductions
let s = t.sum();          // scalar
let m = t.mean()?;
let col_sums = t.sum_axis(0)?;    // shape [3]

Enter fullscreen mode Exit fullscreen mode

JSON and CSV

Both are on by default. The API returns Result at the boundary, so a malformed input gives you an error rather than a panic.

use matten::Tensor;

// JSON — two accepted forms
let t = Tensor::from_json(r#"{"shape":[2,2],"data":[1.0,2.0,3.0,4.0]}"#)?;
let t = Tensor::from_json("[[1.0, 2.0], [3.0, 4.0]]")?;

// From a file
let t = Tensor::load_json("data/tensor.json")?;

// CSV
let t = Tensor::from_csv("1.0,2.0,3.0n4.0,5.0,6.0n")?;
let t = Tensor::load_csv("data/matrix.csv")?;

Enter fullscreen mode Exit fullscreen mode

Serialisation goes through serde, so serde_json::to_string(&t) and serde_json::from_str(&json_str) round-trip correctly when the json or serde feature is active.

Error handling

matten has two deliberate error zones.

• Internal shape operations (constructing from new, reshaping, slicing) panic with an actionable message — useful during fast prototyping because you see the problem immediately.
• External boundary operations (from_json, from_csv, load_*) always return Result<Tensor, MattenError>, because real input data is not always clean.
  • MattenError is #[non_exhaustive], so match on the variant you care about and use a wildcard for the rest:

use matten::{MattenError, Tensor};

match Tensor::from_csv("1.0,not_a_numbern") {
    Ok(t) => println!("got shape {:?}", t.shape()),
    Err(MattenError::Parse { .. }) => println!("bad input"),
    Err(e) => println!("other error: {e:?}"),
}

Enter fullscreen mode Exit fullscreen mode

That covers the everyday numeric core. The next post covers something different: what happens when the input data is not a clean f64 matrix — when it has mixed types, missing values, or integers alongside floats.

Links: crates.io · docs.rs · mdBook · repository