Concepts

This section documents the semantic model shared by the Python layer, the CPU backend, and the Metal backend. The goal is to make the codebase predictable: features own the public semantics, and backends implement those semantics with specialized kernels where useful.

• Sparse tensor model
  • Core invariant
  • Capacity and active rows
  • Stride metadata
  • Coordinate identity
  • Batch metadata
  • Operation effects
  • Manual array edits
  • Related API and references
• Coordinates and relations
  • Kernel offsets
  • Relation edge arrays
  • Execution views
  • Sorted view construction
  • Neighbor relations
  • Relation caching
  • Related API and references
• Coordinate-aligned sparse algebra
  • Join model
  • Operation defaults
  • Operator shortcuts
  • Identity fast path
  • Row-changing utilities
  • Collation
  • Related API and references

Design center

The library is feature-first from the user’s perspective. “Sparse convolution,” “point/voxel conversion,” “coordinate-aligned algebra,” and “quantized inference” are features with backend implementations underneath them. This is different from a backend-first API where users choose cpu_conv or metal_conv directly.

That design has two consequences:

• public operations define their result without reference to a specific kernel;

• backend routes are replaceable as long as they preserve the operation’s sparse semantics.

This separation is especially important in Metal code, where high-performance kernels may require specialized packing, tiling, and launch policies. Those details belong below the semantic layer. The Python API and benchmark suite describe the sparse operation, not the internal route.

Concept-to-API map

Concept	API page	Backend page
Sparse tensor identity	Sparse tensor	Backend path selection
Coordinate manager and relations	Coordinate management	Convolution routes
Relation views	Relations	Convolution routes
Coordinate-aligned algebra	Sparse tensor algebra	Backend path selection