Coming from ndarray / nalgebra / ndarray-linalg
This page is a translation guide for Rust users who arrive with ndarray, nalgebra, or ndarray-linalg priors. PyTorch/JAX users have their own mapping page; read Core Concepts for tenferro’s own mental model.
The short version is the five conventions every tenferro program must follow:
- Column-major storage. Dense buffers are column-major: the leftmost dimension varies fastest. Row-major data passed to
from_vec_col_majoris silently reinterpreted as column-major — permuted/wrong values, never rejected. - No facade crate.
cargo add tenferrofails by design; depend on the crates you need (tenferro-runtime,tenferro-cpu, and operation crates). - Explicit backend. Direct operations take an explicit backend argument; construct the backend/runtime once and reuse it — per-call construction discards the buffer pool.
- WARNING — einsum dialect. Equations need the explicit arrow (
"ij,jk->ik"); omitting it returnsError::InvalidSubscriptsduring parsing. Flat notation supports one right-aligned, broadcastable...ellipsis per term; parenthesized ellipsis is also rejected during parsing. UseEinsumNotationfor programmatic notation. - Result-returning operators. Traced operators return
Result; propagate with?.
Each is explained below with the concrete ndarray/nalgebra divergence.
The column-major asymmetry
| Prior | Storage order | from_vec_col_major hazard |
|---|---|---|
ndarray / NumPy |
Row-major (C order) | Dangerous: a row-major flat buffer is silently reinterpreted as column-major (permuted/wrong values), never rejected |
nalgebra |
Column-major (F order) | Safe: as_slice() / .data map directly |
This is the one prior that actively hurts. ndarray and NumPy store rows contiguously, so the natural flat buffer you already have is in the wrong physical order for tenferro — and construction does not detect the mistake. A [2, 3] tenferro tensor reads elements down each column first. Reorder the buffer explicitly before from_vec_col_major, or wrap it without copying (see Zero-copy interop). nalgebra uses the same Fortran/column-major order as tenferro, LAPACK, and Julia, so a Matrix’s as_slice() or .data maps directly into from_vec_col_major with its shape.
Crate selection: cargo add tenferro does not exist
There is deliberately no facade crate, so cargo add tenferro fails. Add the smallest set of crates for your API tier directly:
| Program | Minimum direct crates |
|---|---|
Concrete Tensor / TypedTensor compute |
tenferro-runtime, tenferro-cpu |
| Eager forward / AD | tenferro-ad, tenferro-cpu |
| Traced graph | tenferro-runtime, tenferro-cpu (+ tenferro-ad for graph transforms) |
| Linear algebra / einsum / FFT | add tenferro-linalg / tenferro-einsum / tenferro-fft |
| CUDA | the value/op crates plus tenferro-gpu with the cuda feature |
See the crate selection reference for full dependency blocks and feature rules.
The backend is an explicit value
In ndarray/nalgebra/ndarray-linalg the execution context is ambient: the BLAS that was linked at build time is whatever your ops run through. tenferro reifies it as a value you hold — CpuEngine (or an EagerRuntime for eager AD, or a Runtime for traced graphs) — because the engine owns the device, the provider dispatch, the plan cache and the buffer pool.
The companion idiom is construct once, reuse. An engine is owned state:
let mut engine = tenferro_cpu::CpuEngine::serial();
// ... many operations through the same `engine` ...Constructing an engine per call discards the buffer pool and cache each time, and defeats reuse of compiled programs. The same rule applies across the tiers — see the performance idioms reference.
One CPU provider: faer
ndarray-linalg users know feature-based BLAS selection. tenferro has no such knob: the CPU crates declare no backend feature, and every build links the same faer-backed tlinalg/cpueinsum/tcontract stack. A dependency list copied from an older tenferro version still carrying native, blas, or blas-openblas fails with “feature does not exist” — remove the feature and the default-features = false that went with it.
Like ndarray-linalg’s system BLAS, the numeric library is fixed at build time; unlike it, nothing about it has to match a system installation, so cargo build on any host produces a working CpuEngine. The GPU crates keep explicit features (tenferro-gpu cuda), which is where ndarray users would otherwise expect an ambient choice.
Operation arity: .dot() to matmul
The receiver-and-arity shape changes across the three tenferro tiers, and the backends are pushed into method signatures. Compare with ndarray’s a.dot(&b):
| Tier | Tenferro | Notes |
|---|---|---|
| Direct | a.matmul(&b, &mut engine)? |
explicit engine argument |
| Eager | runtime.with_eager_session(&mut engine, \|s\| s.matmul(&a, &b))? |
the session borrows the caller’s engine |
| Traced | a.matmul(&b)? |
builds a graph; returns Result |
use tenferro_cpu::CpuEngine;
use tenferro_runtime::{TypedTensor, CoreOps};
let mut engine = CpuEngine::serial();
// The leftmost dimension varies fastest: this is a 2 x 3 column-major tensor.
let x = TypedTensor::<f64>::from_vec_col_major(
vec![2, 3],
vec![1.0, 4.0, 2.0, 5.0, 3.0, 6.0],
)?;
let weights = TypedTensor::<f64>::from_vec_col_major(
vec![3, 2],
vec![0.5, -1.0, 1.5, 1.0, 2.0, -0.5],
)?;
let projected = x.matmul(&weights, &mut engine)?;
assert_eq!(projected.shape(), &[2, 2]);
assert_eq!(projected.host_data()?, &[3.0, 6.0, 3.5, 11.0]);In the direct tier the explicit backend moves from “linked somehow” to “passed into a backend session per operation chain”; in the eager and traced tiers it is owned by the runtime and the signature matches what ndarray users expect.
Tensor vs TypedTensor
ndarray’s Array<A, IxN> and nalgebra’s Matrix<T, ...> are generic over the element type — your priors map to TypedTensor<T>:
| Your prior | Tenferro |
|---|---|
ndarray::Array2<f64> |
TypedTensor<f64> (rank-generic) |
nalgebra::DMatrix<f64> |
TypedTensor<f64> |
| dtype chosen at runtime | Tensor (dtype-erased, has no ndarray counterpart) |
Tensor has no ndarray/nalgebra analogue: its element type is selected at runtime. Reach for it when you need runtime dtype dispatch or direct backend dispatch; for the ordinary fixed-element-type case the generic TypedTensor<T> is the direct match.
Zero-copy interop: keep your faer/ndarray buffers
Adopting tenferro kernels does not require migrating tensor ownership. You can wrap an existing column-major buffer — a faer::Mat, an ndarray view, or any slice plus strides — zero-copy with TypedTensorView::from_slice, and write through it with TypedTensorViewMut::from_slice:
your faer::Mat / ndarray view -> TypedTensorView::from_slice(shape, strides, offset, data)
The full runnable recipe (faer column padding, ndarray row-major wrap, and the mutable variant) is in the API cheatsheet “Borrowing external memory”. Because strides are arbitrary, row-major data wraps without transposition — but kernels are tuned for column-major contiguity, so materialize a copy when performance matters and the wrapped buffer is row-major.
The “do I have to own a new tensor type” objection is partly cost, and the measured answer is small: adding tenferro on top of an existing faer dependency costs about +10 unique crates and +28 s of one-time cold build (see tenferro-rs#1602). For a larger GEMM, the kernel-run portion is what you are adopting; the memory stays yours.
Next steps
- Core Concepts — tenferro’s own mental model.
- Choosing a Tensor API —
TypedTensor,Tensor,EagerTensor, orTracedTensor. - PyTorch and JAX Mapping — the same translation for torch/JAX priors.
- API cheatsheet — tier-by-tier arities and recipes.