Crate systile 

systile — matmul-native data structures & algorithms

systile takes one idea to its conclusion: build data structures and algorithms whose dominant operation is a dense matrix multiply. On a CPU that is often a bad trade, but on a systolic accelerator (a TPU’s matrix unit, a GPU’s tensor cores) dense matmul is the cheap primitive and branch-y pointer chasing is the expensive one — so the trade flips.

It begins with a substrate — the PaddedTileLattice, a tensor laid out the way a TPU’s memory is actually addressed (8 × 128 (sublane, lane) tiles, padding, bf16/int8 dtypes) with a CPU reference simulator of the systolic matmul (systolic) — and builds a stack of pillars on top of it.

The pillars

Pillar	Type	Idea
holo, holoset, sequence, resonator	data	hold a whole structure in superposition, recover by matmul cleanup
graph, semiring	algorithm	graph algorithms as semiring matrix powers
automaton	computation	a finite-state machine run as matmuls
classifier	learning	train by bundling, classify by matmul
index	retrieval	exact k-NN as one matmul over the corpus
bloom	membership	a Bloom filter whose query is a matmul
sort, topk	order	sort and select via comparison matmuls
scan	scan	prefix sums as a triangular matmul
conv	search	pattern search as im2col cross-correlation
sketch	frequency	Count-Min estimation as a matmul per hash row
editdist	strings	Levenshtein as a tropical (min-plus) shortest path
pagerank	ranking	PageRank as power iteration
dft	spectra	the discrete Fourier transform as a Fourier-matrix matmul
viterbi	decoding	most-likely HMM path as max-plus matmul stepping
attention	retrieval	scaled dot-product attention as a soft memory

Everything is honestly matmul-native (maps efficiently onto the MXU), not TPU-exclusive: it all runs on the CPU reference model. The full design rationale, capacity math, and citations are in HOLOGRAPHIC.md.

Designing around the hardware buys, for the substrate:

1. Zero-copy handoff. PaddedTileLattice::as_storage_slice is already in device order; moving it to a TPU is a memcpy, not a transpose.
2. Honest padding. The structure tracks logical vs. padded shape and keeps a Mask, so reductions and dense round-trips never fold in garbage.
3. Hardware-shaped operations. Matmul, sparsity, quantisation, and transpose are all expressed in terms of tiles and mxu blocks.

Quick start

use systile::prelude::*;

// A 3x5 matrix on the canonical TPU geometry pads up to an 8x128 tile.
let a = PaddedTileLattice::from_dense(
    2, 3,
    &[1.0f32, 2.0, 3.0, 4.0, 5.0, 6.0],
    Geometry::TPU_V,
).unwrap();
let b = PaddedTileLattice::from_dense(
    3, 2,
    &[7.0f32, 8.0, 9.0, 10.0, 11.0, 12.0],
    Geometry::TPU_V,
).unwrap();

let c = a.matmul(&b).unwrap();
assert_eq!(c.to_dense(), vec![58.0, 64.0, 139.0, 154.0]);

See the examples/ directory for end-to-end walkthroughs.

Re-exports

pub use attention::TensorAttention;

pub use automaton::TensorAutomaton;

pub use bf16::Bf16;

pub use bloom::TensorBloom;

pub use classifier::HoloClassifier;

pub use codebook::Codebook;

pub use conv::TensorConv;

pub use dft::TensorDFT;

pub use editdist::TensorEditDistance;

pub use error::LatticeError;

pub use error::Result;

pub use geometry::Geometry;

pub use graph::TensorGraph;

pub use holo::HoloMemory;

pub use holoset::HoloSet;

pub use hyper::Hyper;

pub use index::Hit;

pub use index::TensorIndex;

pub use lattice::PaddedTileLattice;

pub use mask::Mask;

pub use pagerank::TensorPageRank;

pub use quantize::QuantParams;

pub use resonator::Factorization;

pub use resonator::Resonator;

pub use scan::TensorScan;

pub use sequence::HoloSequence;

pub use shape::Shape;

pub use sketch::CountMinSketch;

pub use sort::TensorSort;

pub use systolic::SystolicStats;

pub use topk::TensorTopK;

pub use viterbi::TensorViterbi;

Modules

attention

TensorAttention — scaled dot-product attention as a soft retrieval memory.

automaton

TensorAutomaton — a finite-state machine whose execution is matrix multiply.

bf16

bf16 — the brain-floating-point format that is the native compute dtype of a TPU.

bloom

TensorBloom — a counting Bloom filter whose membership test is a matmul.

classifier

HoloClassifier — classification where training is addition and inference is a matmul.

codebook

A codebook: a vocabulary of atomic symbols stored as a tile-aligned matrix so that cleanup — finding the symbol most similar to a noisy hypervector — is a single matrix multiply on the systolic engine.

conv

TensorConv — 1-D pattern search as an im2col cross-correlation matmul.

dft

TensorDFT — the discrete Fourier transform as a matmul.

editdist

TensorEditDistance — Levenshtein distance as a tropical (min-plus) matmul.

elementwise

Element-wise maps and binary combinators over the logical region.

error

Error type for fallible lattice operations.

geometry

Tile geometry: the hardware-dictated tile shape every lattice is built around.

graph

TensorGraph — a directed weighted graph whose algorithms are matrix powers.

holo

HoloMemory — a key→value store that lives in superposition inside a single hypervector, and whose batch lookup is one matrix multiply.

holoset

HoloSet — a set held in superposition, with membership testing as a matmul.

hyper

Hyperdimensional algebra: the primitive operations of a Vector Symbolic Architecture (VSA), in the bipolar Multiply-Add-Permute (MAP) flavour.

index

TensorIndex — exact nearest-neighbour search, where the search is a matmul.

iter

Iterators over a lattice in both logical and hardware-tile order.

lattice

The PaddedTileLattice: a dense 2-D tensor stored as a padded grid of hardware tiles in (sublane, lane) order.

layout

Address arithmetic that maps logical (row, col) coordinates to the linear offset where the element actually lives in tiled (sublane, lane) order.

mask

Validity masks.

pagerank

TensorPageRank — PageRank as power iteration.

prelude

The common imports. use systile::prelude::*; brings in everything you need to build, transform, and multiply lattices.

quantize

Affine int8 quantisation.

reduce

Reductions over the logical region.

resonator

Resonator networks: factoring a bound product back into its unknown symbols with iterated matmuls.

scan

TensorScan — prefix sums as a triangular matmul.

semiring

Semirings, and matrix multiply over them.

sequence

HoloSequence — an ordered sequence packed into one hypervector by binding each element to its position with a permutation.

shape

Logical and padded shapes.

sketch

CountMinSketch — frequency estimation as a matmul per hash row.

sort

TensorSort — sorting as a comparison matmul.

sparse

Tile-level sparsity.

systolic

A CPU reference simulator of weight-stationary systolic matmul.

topk

TensorTopK — selecting the k largest as a comparison-count matmul.

transpose

Transpose and relayout.

viterbi

TensorViterbi — most-likely hidden-state decoding as max-plus matmul.