{"id":51281335,"url":"https://github.com/bajpainaman/systile","last_synced_at":"2026-06-30T02:00:44.445Z","repository":{"id":368284344,"uuid":"1284414905","full_name":"bajpainaman/systile","owner":"bajpainaman","description":"A TPU-native tiled tensor data structure in Rust: the Padded Tile Lattice — sublane/lane layout, bf16/int8 dtypes, and a CPU reference simulator of systolic dataflow.","archived":false,"fork":false,"pushed_at":"2026-06-29T21:38:19.000Z","size":182,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-29T23:07:19.809Z","etag":null,"topics":["bf16","data-structures","machine-learning","quantization","rust","systolic-array","tensor","tpu"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bajpainaman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-29T20:57:34.000Z","updated_at":"2026-06-29T21:38:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bajpainaman/systile","commit_stats":null,"previous_names":["bajpainaman/systile"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bajpainaman/systile","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bajpainaman%2Fsystile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bajpainaman%2Fsystile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bajpainaman%2Fsystile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bajpainaman%2Fsystile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bajpainaman","download_url":"https://codeload.github.com/bajpainaman/systile/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bajpainaman%2Fsystile/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34949234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bf16","data-structures","machine-learning","quantization","rust","systolic-array","tensor","tpu"],"created_at":"2026-06-30T02:00:31.383Z","updated_at":"2026-06-30T02:00:44.432Z","avatar_url":"https://github.com/bajpainaman.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# systile\n\n**Matmul-native data structures \u0026 algorithms, written from scratch in Rust.**\n\n[![crates.io](https://img.shields.io/crates/v/systile.svg)](https://crates.io/crates/systile)\n[![docs.rs](https://img.shields.io/docsrs/systile)](https://docs.rs/systile)\n[![CI](https://github.com/bajpainaman/systile/actions/workflows/ci.yml/badge.svg)](https://github.com/bajpainaman/systile/actions/workflows/ci.yml)\n[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)\n\nOne idea, taken to its conclusion: **build data structures and algorithms whose\ndominant operation is a dense matrix multiply.** On a CPU that is usually a bad\ntrade — a hash map beats a matmul-based map, a queue beats matrix powers. But on a\nsystolic accelerator (a TPU's matrix unit, a GPU's tensor cores) dense matmul is the\n*cheap* primitive and branch-y pointer chasing is the expensive one, so the trade\nflips. `systile` is a library of structures built for that world.\n\nIt starts with a substrate — the **Padded Tile Lattice**, a tensor laid out the way\na TPU's memory is actually addressed (`8 × 128` `(sublane, lane)` tiles, padding,\nbf16/int8 dtypes) with a CPU reference simulator of the systolic matmul — and then\nbuilds a stack of pillars on top of it. You do **not** need a TPU: everything runs\non the CPU model, honestly framed as *matmul-native* (maps efficiently onto the\nMXU), not *TPU-exclusive*.\n\n## The pillars\n\n| # | Pillar | Structures | One-line demo |\n| --- | --- | --- | --- |\n| 0 | **Tensor substrate** | `PaddedTileLattice`, `Bf16`, `systolic`, `quantize` | a matmul in true device layout |\n| 1 | **Data as superposition** (VSA) | `HoloMemory`, `HoloSet`, `HoloSequence`, `Resonator` | 200 KV pairs in one 32 KB vector, 1 matmul, 100% recall |\n| 2 | **Algorithms as semiring matrix powers** | `TensorGraph`, `semiring` | shortest paths as `⌈log₂n⌉` GEMMs |\n| 3 | **Computation as matmul** | `TensorAutomaton` | decide divisibility by matrix multiply |\n| 4 | **Learning as bundling** | `HoloClassifier` | train by addition, classify by one matmul |\n| 5 | **Retrieval as matmul** | `TensorIndex` | exact k-NN over a corpus in one GEMM |\n| 6 | **Probabilistic membership as matmul** | `TensorBloom` | a Bloom filter whose batch query is one matmul |\n| 7 | **Sorting as comparison matmul** | `TensorSort` | ranks = `C·1`, sort = `P·x` |\n| 8 | **Scan as triangular matmul** | `TensorScan` | prefix sums as `L·x`, `O(1)` depth |\n| 9 | **Pattern search as convolution matmul** | `TensorConv` | locate a motif via one im2col matmul |\n| 10 | **Frequency as matmul** | `CountMinSketch` | Count-Min estimates as one matmul per hash row |\n| 11 | **Selection as comparison matmul** | `TensorTopK` | top-k via `count = C·1`, no full sort |\n| 12 | **Edit distance as tropical matmul** | `TensorEditDistance` | Levenshtein as min-plus shortest path |\n| 13 | **Ranking as power iteration** | `TensorPageRank` | PageRank as repeated `M·r` matmuls |\n\nEvery structure reduces its core operation to a matmul through the same systolic\nengine. The honest framing, capacity math, and citations live in\n**[HOLOGRAPHIC.md](HOLOGRAPHIC.md)**.\n\n## Why a data structure \"for TPUs\"?\n\nA TPU is not a flat array machine. Three hardware facts drive its data layout, and\n`systile` encodes all three:\n\n| Hardware fact | What it forces | Where `systile` handles it |\n| --- | --- | --- |\n| Vector memory is addressed as `8 × 128` `(sublane, lane)` tiles | Data must be tiled and padded to tile boundaries | [`Geometry`], [`Layout`], [`Shape`] |\n| The matrix unit is a `128 × 128` systolic array | Matmul runs in square `mxu` blocks, padding included | [`systolic`] |\n| Native dtypes are `bf16` and `int8`, not `f32` | You quantise/narrow before compute, accumulate in `f32` | [`bf16`], [`quantize`] |\n\nBecause padding is mandatory, the structure tracks both the *logical* shape you\nasked for and the *padded* shape it actually stores, plus a validity [`Mask`] so\nreductions and dense round-trips never fold in garbage.\n\n## Install\n\n```sh\ncargo add systile\n```\n\n```toml\n# Cargo.toml\n[dependencies]\nsystile = \"0.8\"\n```\n\nNo required dependencies; `#![forbid(unsafe_code)]`; builds on stable Rust ≥ 1.74.\n\n## Quick start\n\n```rust\nuse systile::prelude::*;\n\nlet a = PaddedTileLattice::from_dense(\n    2, 3, \u0026[1.0f32, 2.0, 3.0, 4.0, 5.0, 6.0], Geometry::TPU_V,\n).unwrap();\nlet b = PaddedTileLattice::from_dense(\n    3, 2, \u0026[7.0f32, 8.0, 9.0, 10.0, 11.0, 12.0], Geometry::TPU_V,\n).unwrap();\n\n// Matmul runs in the same blocked dataflow a systolic array uses.\nlet (c, stats) = a.matmul_with_stats(\u0026b).unwrap();\nassert_eq!(c.to_dense(), vec![58.0, 64.0, 139.0, 154.0]);\nprintln!(\"array utilisation: {:.1}%\", stats.utilisation() * 100.0);\n```\n\n## The headline: a data structure whose operations *are* matmuls\n\nOn top of the tiling substrate, `systile` ships an invented container — the\n**Holographic Tensor Store** ([`HoloMemory`]) — a key→value map that holds **every\nentry summed on top of every other** inside a single fixed-width vector, and\nrecovers a value by algebra plus one matrix multiply.\n\n```rust\nuse systile::prelude::*;\n\nlet mut book = HoloMemory::new(8192, 1000, 0xC0FFEE); // 8192-dim, 1000 value symbols\nfor name in 0..200 {\n    book.insert(name, (name * 7 + 3) % 1000);          // bind + bundle into ONE vector\n}\n\n// Look up all 200 names at once — a single (200 × 8192)·(8192 × 1000) matmul.\nlet hits = book.batch_get(\u0026(0..200).collect::\u003cVec\u003c_\u003e\u003e());\nlet correct = (0..200).filter(|\u0026n| hits[n].0 == (n * 7 + 3) % 1000).count();\nassert_eq!(correct, 200); // 100% recall, well under the d/(2 ln M) capacity bound\n```\n\n200 entries live in 32 KB of `f32`; lookup of the whole batch is one MXU-shaped\nGEMM. On a CPU this is a *worse* map than a hash table — it only pays off where\ndense matmul is the cheap primitive and you batch thousands of probes: a TPU. It's\napproximate and bounded (`K_max ≈ d / (2 ln M)`), degrading gracefully past\ncapacity. The full mechanism, capacity math, honest novelty assessment, and\ncitations are in **[HOLOGRAPHIC.md](HOLOGRAPHIC.md)**. Try it:\n\n```\ncargo run --release --example holo_kv          # 200 pairs in one vector, 1 matmul\ncargo run --release --example holo_capacity    # recall vs the d/(2 ln M) bound\ncargo run --release --example resonator_factor # factor a product with no known factors\ncargo run --release --example holo_precision   # f32 vs bf16 cleanup recall\ncargo run           --example holo_analogy      # \"Dollar of Mexico?\" -\u003e peso, zero training\ncargo run --release --example graph_paths      # shortest paths as tropical matrix powers\ncargo run --release --example automaton_divisibility  # decide divisibility by matmul\ncargo run --release --example classifier_demo  # train by bundling, classify by matmul\ncargo run --release --example index_search     # exact k-NN search as one matmul\ncargo run --release --example bloom_membership # Bloom membership as one matmul\ncargo run --release --example sort_by_matmul   # sort via comparison + permutation matmul\ncargo run --release --example scan_prefix      # prefix sums as a triangular matmul\ncargo run --release --example conv_search      # pattern search as im2col correlation\ncargo run --release --example sketch_frequency # Count-Min frequency estimates by matmul\ncargo run --release --example topk_select      # top-k via comparison-count matmul\ncargo run --release --example edit_distance    # Levenshtein as tropical matmul\ncargo run --release --example pagerank_demo    # PageRank as power-iteration matmuls\n```\n\n## Features\n\n- **A family of matmul-native containers** on a hyperdimensional (VSA) substrate\n  (`Hyper` algebra + `Codebook` matmul cleanup):\n  - `HoloMemory` — key→value store in superposition; batched lookup is one matmul.\n  - `HoloSet` — set membership as a matmul; union by bundling; norm-based cardinality.\n  - `HoloSequence` — order via permutation binding; whole-sequence decode in one matmul.\n  - `Resonator` — factor a bound product back into its unknown symbols by iterated\n    matmul cleanup (an `Mᶠ` search run as a short sequence of GEMMs), with exact\n    verification and restarts.\n- **`TensorGraph`** — graph algorithms as semiring matrix powers (GraphBLAS-style):\n  reachability (boolean), all-pairs shortest paths (tropical/min-plus), and walk\n  counting (ordinary) — each in `⌈log₂ n⌉` dense matmuls via repeated squaring.\n- **`TensorAutomaton`** — a finite-state machine run as matmuls: one-hot state\n  vector × per-symbol transition matrix. Branchless string recognition; a whole\n  batch advances with `|alphabet|` masked matmuls per position (e.g. decide\n  divisibility by matrix multiply).\n- **`HoloClassifier`** — a hyperdimensional classifier: *train by bundling* (no\n  gradients, no epochs — fitting is vector addition) and *classify by matmul*\n  against the class-prototype matrix. 100% on the synthetic clustering demo.\n- **`TensorIndex`** — exact nearest-neighbour / similarity search (the vector-DB\n  workload): score a batch of queries against the whole corpus in one\n  `(b × dim)·(dim × n)` matmul, then take top-k.\n- **`TensorBloom`** — a counting Bloom filter whose batch membership test is one\n  matmul of item signatures against the filter's presence vector; no false\n  negatives, deletion supported, false-positive rate exposed.\n- **`TensorSort`** — sorting as comparison matmul: the rank vector is `C·1` (row\n  sums of the pairwise comparison matrix) and the sorted output is `P·x`, an\n  `O(n²)`-matmul trade against `O(n log n)` branches.\n- **`TensorScan`** — prefix sums as a triangular matmul (`L·x`): inclusive,\n  exclusive, and suffix scans with `O(1)` dependency depth.\n- **`TensorConv`** — 1-D pattern search as im2col cross-correlation: gather all\n  windows and dot them against the kernel in one matmul, then argmax for the match.\n- **`CountMinSketch`** — frequency estimation where each row's query is a matmul of\n  a one-hot column selection against that row's counters; never underestimates.\n- **`TensorTopK`** — top-k selection as a comparison-count matmul (`count = C·1`,\n  keep `count \u003c k`), batched, no full sort.\n- **`TensorEditDistance`** — Levenshtein distance as a tropical (min-plus) shortest\n  path through the alignment grid, relaxed by iterated min-plus matmuls.\n- **`TensorPageRank`** — PageRank by power iteration: repeated `M·r` matmuls against\n  the column-stochastic Google matrix until the ranks converge.\n- **`PaddedTileLattice\u003cT\u003e`** — the core 2-D tiled tensor, generic over element type.\n- **`bf16`** — a from-scratch bfloat16 with round-to-nearest-even and a full set of\n  arithmetic / comparison / conversion impls.\n- **Systolic matmul simulator** — weight-stationary, `f32`-accumulated, verified\n  bit-for-bit against a naive triple loop, and it reports MAC utilisation.\n- **Tile-level sparsity** — find and skip the all-zero tiles a kernel would waste\n  cycles on.\n- **Affine int8 quantisation** — symmetric and asymmetric calibration that\n  preserves the hardware tiling end to end.\n- **Transpose \u0026 relayout** — re-tile the same logical data under a new geometry.\n- **Element-wise maps and reductions** — padding-correct by construction.\n- `#![forbid(unsafe_code)]`, no required dependencies.\n\n## Examples\n\n```\ncargo run --example quickstart\ncargo run --example bf16_roundtrip\ncargo run --example quantize_matmul\ncargo run --example sparsity_report\ncargo run --example padding_inspect\ncargo bench\n```\n\n## Layout, in one picture\n\nA `3 × 5` logical matrix on `Geometry::TPU_V` (8 sublanes × 128 lanes) pads up to a\nsingle `8 × 128` tile. Element `(row, col)` lives at:\n\n```\noffset = tile_index * (sublanes * lanes) + sublane * lanes + lane\n```\n\n`tile_index` walks tiles in row-major order; within a tile the order is row-major\nover `(sublane, lane)`. That is exactly the order a TPU's vector memory expects, so\n`as_storage_slice()` is copy-ready.\n\n## Status\n\n`systile` is young and the API may shift before `1.0`. The simulator is a reference\nmodel, not a cycle-accurate one: it reproduces the **blocking and accumulation\norder** of a systolic array (and so its numerics), not its timing.\n\n## License\n\nLicensed under either of [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE) at your\noption.\n\n[`HoloMemory`]: https://docs.rs/systile/latest/systile/holo/struct.HoloMemory.html\n[`Geometry`]: https://docs.rs/systile/latest/systile/geometry/struct.Geometry.html\n[`Layout`]: https://docs.rs/systile/latest/systile/layout/struct.Layout.html\n[`Shape`]: https://docs.rs/systile/latest/systile/shape/struct.Shape.html\n[`Mask`]: https://docs.rs/systile/latest/systile/mask/struct.Mask.html\n[`bf16`]: https://docs.rs/systile/latest/systile/bf16/index.html\n[`systolic`]: https://docs.rs/systile/latest/systile/systolic/index.html\n[`quantize`]: https://docs.rs/systile/latest/systile/quantize/index.html\n[`transpose`]: https://docs.rs/systile/latest/systile/transpose/index.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbajpainaman%2Fsystile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbajpainaman%2Fsystile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbajpainaman%2Fsystile/lists"}