API Guide

viva_tensor exposes a small stable surface from the root viva_tensor module. Implementation modules for native backends, quantization, sparse kernels, telemetry, benchmarking, and experimental neural-network helpers are kept internal until their contracts are stable. Development-only benchmark and example entrypoints live under dev/ so they can be run locally without becoming part of the packaged library surface.

See Stability Policy for the stable/experimental boundary and the compatibility expectations for root-module additions. See Project Structure for the package layout and module boundary rules.

Stable Imports

import gleam/result
import viva_tensor as t

Use the root module for normal tensor work. Import viva_tensor/layout when you need to inspect storage metadata, and viva_tensor/axis or viva_tensor/named when working with semantic dimensions.

Tensor Creation

let a = t.zeros([2, 3])
let b = t.fill([2, 3], 1.5)

Fallible Operations

Shape-changing and binary tensor operations return Result rather than panicking. Chain them with gleam/result.try. Use try_to_list() instead of to_list() inside fallible code when native materialization failures need to be preserved.

pub fn example() {
  let a = t.ones([2, 3])
  let b = t.fill([2, 3], 2.0)

  use c <- result.try(t.add(a, b))
  use flat <- result.try(t.reshape(c, [6]))

  Ok(t.mean(flat))
}

Element-wise Math

Use broadcasting-specific functions when shapes differ.

Reductions

Linear Algebra

Native-backed variants such as matmul_into, to_accelerated, and matmul_accelerated_into are available from the root module for hot paths that can reuse buffers or persistent GPU memory.

Use capabilities() to inspect whether the current VM loaded the native NIF, the Zig SIMD backend, which TFLOPS backends are visible, and the stable backend capability records. Use backend_capabilities() when you only need the capability table, or plan_backend(operation) to see which backend the stable planner would choose for an operation. Plans include rejected backend entries with human-readable reasons for unavailable or unsuitable backends. Use hardware_profiles() when planning ahead for accelerator-specific work: current hardware is marked available only when detected, while future profiles such as Blackwell, Rubin, Vera, and Rubin CPX remain explicit but unavailable until a runtime path can prove support.

let plan = t.plan_backend(t.OperationMatmul(m: 1024, n: 1024, k: 1024))

Quantization Readiness

Shape And Layout

let info = t.layout(t.zeros([2, 3]))

Broadcasting, squeeze, unsqueeze, and contiguous reshape preserve strided views where possible. Call to_contiguous() before a heavy native hot path if a view would be slower than a dense buffer.

Utilities

Public Companion Modules

Stability Policy

Public modules are documented by gleam docs build and should avoid panics, prefer Result for recoverable errors, preserve semantic-versioning compatibility, and keep a portable fallback when possible. Internal modules may change while the native acceleration, quantization, sparse, and neural-network APIs continue to mature. The detailed policy lives in Stability Policy.