# tenferro

> tenferro is a Rust-native tensor computation stack with opt-in autodiff for scientific workloads: typed tensors, PyTorch-style eager execution, JAX-style traced graphs, einsum, linear algebra, and explicit CPU, CUDA, and experimental WebGPU backend control.

## Conventions you must know before writing code

- **Column-major storage.** Dense buffers are column-major: the leftmost dimension varies fastest. Row-major data passed to `from_vec_col_major` is silently reinterpreted as column-major — permuted/wrong values, never rejected.
- **No facade crate.** `cargo add tenferro` fails 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 is rejected during parsing with `Error::InvalidSubscripts`. Flat notation supports one right-aligned, broadcastable `...` ellipsis per term, and `EinsumNotation` is the programmatic form. Parenthesized contraction order containing ellipsis is also rejected during parsing.
- **Result-returning operators.** Traced operators return `Result`; propagate with `?`.

## Recipes and references

- [README](https://github.com/tensor4all/tenferro-rs/blob/main/README.md): The canonical router — every user-facing artifact (guides, recipes, rustdoc, and this index) is reachable from it.
- [API cheatsheet](https://tensor4all.org/tenferro-rs/skill-references/api-cheatsheet.md): Tier-by-tier method arities and extension-trait imports, including the zero-copy recipe for wrapping external faer/ndarray memory.
- [Crate selection](https://tensor4all.org/tenferro-rs/skill-references/crate-selection.md): Which crates to add for each API tier, and CPU provider feature rules.
- [Performance idioms](https://tensor4all.org/tenferro-rs/skill-references/performance-idioms.md): Construct-once-reuse and compile-once/run-many execution patterns.
- [Pitfalls](https://tensor4all.org/tenferro-rs/skill-references/pitfalls.md): Column-major input, einsum syntax, extension registration, and per-origin traps for ndarray/nalgebra/PyTorch arrivals.

## Getting started

- [Getting Started](https://tensor4all.org/tenferro-rs/getting-started/): Walks through tenferro's tensor layer, execution model, and backend/device choices, including a first CPU program.
- [API migration guide](https://tensor4all.org/tenferro-rs/getting-started/api-migration.html): Maps removed modules, free functions, fallible constructors, and changed signatures to the current trait-based API.
- [Coming from ndarray / nalgebra / ndarray-linalg](https://tensor4all.org/tenferro-rs/getting-started/ndarray-nalgebra-mapping.html): For Rust users with ndarray or nalgebra priors: the column-major asymmetry, crate selection, explicit backends, faer vs BLAS providers, and zero-copy interop with existing buffers.
- [PyTorch and JAX Mapping](https://tensor4all.org/tenferro-rs/getting-started/pytorch-jax-mapping.html): Translates common `torch` and `jax.numpy` operations into tenferro's direct, eager, and traced APIs.
- [Choosing a Tensor API](https://tensor4all.org/tenferro-rs/guides/choosing-an-api.html): Explains how to select the tensor API by value type, execution timing, and backend/device.

## Guides

- [Ordinary calls and prepared execution](https://tensor4all.org/tenferro-rs/guides/ordinary-and-prepared-execution.html): Choosing ordinary einsum, compatible ConcreteEinsumPlan reuse and programmatic labels, with scoped historical Linux measurements.

- [Einsum](https://tensor4all.org/tenferro-rs/guides/einsum.html): WARNING — missing arrows and parenthesized ellipses are parse-time `Error::InvalidSubscripts` failures; use flat `...` ellipsis or `EinsumNotation`.
- [Linear Algebra](https://tensor4all.org/tenferro-rs/guides/linear-algebra.html): Covers the `tenferro-linalg` operation crate and its direct, eager, and traced execution surfaces.
- [External Linear Algebra Interop](https://tensor4all.org/tenferro-rs/guides/external-linalg-interop.html): Calling faer or BLAS/LAPACK directly on tenferro-owned storage: the direct-dependency contract, column-major leading dimensions, non-contiguous/non-host rejection, and provider thread control.
- [Autodiff](https://tensor4all.org/tenferro-rs/guides/autodiff.html): Describes eager `backward()` and functional or traced `grad`, `vjp`, and `jvp` workflows.
- [Parallelism and Caching](https://tensor4all.org/tenferro-rs/guides/parallelism-and-caching.html): WARNING — backend/runtime instances own thread pools and caches; per-call construction throws them away.
- [Memory Order](https://tensor4all.org/tenferro-rs/guides/memory-order.html): WARNING — buffers are column-major; row-major data passed to `from_vec_col_major` is silently reinterpreted as column-major (wrong values), never rejected.
- [Devices and GPU](https://tensor4all.org/tenferro-rs/guides/devices-and-gpu.html): Documents explicit CPU/GPU placement, transfer boundaries, CUDA/WebGPU capability coverage, and the supported versus CI-tested CUDA, cuTENSOR, cuBLAS, cuSOLVER, and cuFFT compatibility matrix.
- [Custom CUDA kernels](https://tensor4all.org/tenferro-rs/guides/custom-cuda-kernels.html): Downstream PTX, CUBIN, NVRTC, raw tensor borrowing, stream ordering, and launch safety through the public CUDA extension API.
- [Troubleshooting](https://tensor4all.org/tenferro-rs/guides/troubleshooting.html): Covers feature selection, BLAS providers, CUDA setup, workspace traps, and common runtime failures.

## Specification

- [API Conventions](https://tensor4all.org/tenferro-rs/spec/api-conventions.html): Normative public API naming, module shape, feature naming, and documentation-surface conventions.
- [Tensor Semantics](https://tensor4all.org/tenferro-rs/spec/tensor-semantics.html): Defines dense tensor metadata, storage, placement, typed views, and backend boundaries.
- [Backend Contract](https://tensor4all.org/tenferro-rs/spec/backend-contract.html): Defines the execution pipeline from traced values and extension registration through compiled backend execution.

## Agent skills

- [tenferro-compute skill](https://github.com/tensor4all/tenferro-rs/blob/main/.agents/skills/tenferro-compute/SKILL.md): Helps downstream coding agents choose API tiers, crates, extension-trait imports, performance idioms, and known pitfalls.