Loom Documentation

M-POLY-VTD Engine Docs

Complete reference for Loom's poly package — the Multi-numerical POLYmorphic Volumetric Tiled-tensor Dispatcher that powers every Loom integration.

Architecture Overview Quick Reference GitHub

Where to start?

New? Read Overview → Layers → Training. Deploying to web or mobile? Go to Deployment. Need a snippet? Quick Reference has everything copy-paste ready.

Architecture Layers Training Deployment GPU Quick Reference

M-POLY-VTD: Architecture Overview

Multi-numerical POLYmorphic Volumetric Tiled-tensor Dispatcher

Deployment: TypeScript, WASM, Flutter, and NPM

Loom is designed to be **isomorphic** across runtimes: the same mathematical engine runs in Node.js and the browser (WASM), and the same **Welvet C-ABI** is exposed to **Flutter/Dart** via `welvet` on pub.dev.

Flutter & Dart: `welvet` on pub.dev

Loom runs in **Flutter** and plain **Dart** through the `welvet` FFI plugin. Same Welvet C-ABI as Python ctypes and TypeScript WASM — `createNetwork`, polymorphic forward/backward, CPU training, DNA, JSON + `.entity...

Donate compute (TCP)

The **`donate_compute_*.go`** files in `poly/` implement an optional **TCP protocol** so a **donor** machine can accept inference-style work from clients on the same network (or loopback). Work is exchanged as **lengt...

TANHI — UDP layer telemetry

TANHI** streams **sparse, non-blocking JSON-line events** over **UDP** so external tools (notably the **SoulGlitch → TANHI** HUD) can visualize **per-layer forward/backward** activity, timing, dtypes, and **routing ...

Numerical Types, DType System, and WeightStore

This document covers all 21 `DType` values, the `Numeric` generic constraint, the `WeightStore` master/versioned architecture, and the Metamorphosis mechanism that lets a layer switch precision on the fly.

Layer Reference

This document describes every `LayerType` in `poly/`. For each layer: what it computes, which fields of `VolumetricLayer` configure it, weight layout in the `WeightStore`, and an ASCII data-flow diagram.

The Dispatcher Pattern and 3D Coordinate System

This document explains how `DispatchLayer` and `DispatchLayerBackward` work as runtime jump tables, how the 3D coordinate system maps to `VolumetricLayer` positions, and how `IsRemoteLink` enables spatial hopping acro...

Training: Forward Pass, Backward Pass, Optimizers, and Learning

This document covers the full training pipeline: the forward and backward pass mechanics, loss computation, weight update strategies, gradient clipping, Tween, and the `VGStepBP` adaptive rate.

GPU Backend: WebGPU (WGPU)

This document covers the WebGPU backend: initialization, the `BeginFrame`/`FlushFrame` command batching pattern, the buffer pool and pipeline cache, which layers have GPU support, and the tiling strategy.

The step mesh engine

This document covers the `StepState`, `StepForward`, `StepBackward`, and `StepApplyTween` functions that implement a clock-cycle-accurate discrete-time neural mesh.

The DNA Engine: Topological Network Fingerprinting

This document covers `ExtractDNA`, `CosineSimilarity`, `CompareNetworks`, `LogicShift` detection, and the recursive signature extraction for all 19 layer types in `dna.go`.

The Evolution Engine: DNA Splice & NEAT Topology Evolution

This document covers `SpliceDNA`, `SpliceDNAWithReport`, `NEATMutate`, and `NEATPopulation` from `evolution.go`. The evolution engine builds on the DNA fingerprinting system described in dna.md.

Softmax Variants

LayerSoftmax` (type 15) implements ten distinct softmax variants, controlled by the `SoftmaxType` field on `VolumetricLayer`. All variants are fully differentiable and work across all 21 DTypes.

Serialization, Persistence, and Loading

This document covers how `VolumetricNetwork` instances are saved and loaded, the bit-packed persistence format for low-bit types, the idempotency guarantee, and SafeTensors support.

Parallel and Sequential Layers

This document explains `LayerParallel` and `LayerSequential` in depth: how they fan out and chain sub-layers, the five combination modes, the recursive activation tree, and how backpropagation flows through nested str...

Quantization: DType Conversion and PTQ Pipeline

This document covers the Post-Training Quantization (PTQ) pipeline in `poly/`: how weights move from FP32 masters into lower-precision formats, the `WeightStore` versioning system, the `Q4_0Block` block-quantization f...

Transformer Architecture: MHA, RoPE, GQA, and Full Block Assembly

This document covers `LayerMultiHeadAttention` (MHA), how RoPE positional encoding is applied, Grouped-Query Attention (GQA) and Multi-Query Attention (MQA), the KV cache, SwiGLU and RMSNorm layers, full transformer b...

Quick Reference: Common Code Snippets

Concise, copy-paste-ready patterns for the most common `poly/` tasks. Each snippet assumes `import poly "github.com/openfluke/soul/loom/poly"` (adjust to your module path).

Testing, validation, and Lucy logs

This page ties together **how we stress `poly/`**, where **artifacts land**, and how to read **parity tables** in captured logs (for example `lucy_testing_output/log.txt` in the Lucy Bloom Rivers repo).

Bedrock Validation (v0.79.0)

Release:** **0.78.0 "ASM CPU"** → **0.79.0 "Bedrock Validation"

v0.80.0 — Native Ship (ENTITY + Modern GPU)

v0.84+:** Lucy lives in lucy_bloom_rivers (was `loom/lucy/`). Log and harness paths below are relative to the Lucy repo root.

v0.81.0 — Accelerator Bridge (Intel NPU + vendor plugin model)

v0.84+:** Lucy lives in lucy_bloom_rivers (was `loom/lucy/`). Log and harness paths below are relative to the Lucy repo root.

v0.82.0 — Snapdragon Bridge (SIMD CPU + Qualcomm/Hexagon NPU)

v0.84+:** Lucy lives in lucy_bloom_rivers (was `loom/lucy/`). Log and harness paths below are relative to the Lucy repo root.

v0.83.0 — Apple Bridge (Apple GPU / Metal + BF16)

v0.84+:** Lucy lives in lucy_bloom_rivers (was `loom/lucy/`). Log and harness paths below are relative to the Lucy repo root.

Vendor accelerators (NPU / TPU)

Version:** Loom **v0.83.0** — experimental

Plan 9 SIMD — Forward and Backward

Loom's CPU SIMD path uses **Plan 9 assembly** (`.s` files) for hot GEMV-style kernels on **amd64** (AVX2) and **arm64** (NEON). Forward passes use **`DotTile`**; backward passes use **`SaxpyF32AccF64`** (and strided v...

Snapdragon (Hexagon NPU) bridge

Version:** Loom **v0.82.0 "Snapdragon Bridge"** — **experimental** (same maturity bar as the Intel NPU bridge)

Apple (Metal GPU / MPSGraph) bridge

Version:** Loom **v0.83.0 "Apple Bridge"** — **experimental** (same maturity bar as the Intel & Qualcomm NPU bridges)

BitNet CPU Ternary Path

poly` has an explicit CPU path for BitNet b1.58-style ternary weights.

ENTITY format (`.entity`)

E**very **N**umerical **T**ype **I**n **N**ative **T**opolog**Y

Planet Bridging

Universal bridging between AI engines through Loom.

Memory history, GPU load, and HF→entity convert

This page covers **`poly/memory_history.go`**: timed samples during LLM GPU upload, the in-terminal chart Lucy prints after load, and how memory policy ties to **block-wise safetensor import** (HF → `.entity` conver...

Windows ARM64 native builds

Use **one script** from WSL/Linux:

ASM & Volumetric Executor Exploration (Archive)

Status:** Exploratory work — **not merged as a long-term direction.

Cross-path CPU suite (Lucy menu [15])

Run:** Lucy Bloom Rivers → **[15]** → pick grid (default **2³**) → layer type (or **[0]** for all).

Lucy Bloom Rivers (integration harness)

Repo:** github.com/openfluke/lucy_bloom_rivers

Native layer suite (Lucy menu [14])

Run:** Lucy Bloom Rivers → **[14]** (or **[0]** for all layer types).

Neural Fountain — shard specialists · LT peel · Master ensemble

Neural Fountain** is a training / assembly paradigm in `poly/` that mirrors LT fountain codes on **network weights** instead of data bytes.

Seed manifests — topology + layer seeds (no weight blobs)

Loom can represent a neural network as **recipes**, not checkpoints: