diagrams

Author: t81dev

ARCHITECTURE.md

@@ -66,8 +66,8 @@ in `docs/design/limb-design.md`, `docs/design/bigint-design.md`, and `docs/desig
 
 ## Visual guides
 
-- `docs/diagrams/architecture-stack-mermaid.md` — module layering from application to helper utilities.
-- `docs/diagrams/build-flow-mermaid.md` — configure/build/test/bindings workflow so new contributors can run the project end-to-end.
+- `docs/diagrams/core-architecture.mermaid.md` — layered helpers from `limb` → `bigint` → the umbrella helpers and GEMM stack.
+- [`docs/diagrams/docs-sitemap.mermaid.md`](diagrams/docs-sitemap.mermaid.md) — site map summarizing the docs portal and related resources.
 
 This guide is intentionally light and developer-facing—if you need a runnable overview, `docs/index.md`
 acts as the higher-level docs portal introduced in the README.

BENCHMARKS.md

@@ -43,6 +43,10 @@ Each row contains:
 
 Use this CSV to plot accuracy vs. storage or compare latency across the three modes.
 
+## Diagrams
+
+View the [benchmark comparison diagram](docs/diagrams/benchmarks.mermaid.md) for a quick latency/storage summary that highlights the 15–22× wins.
+
 ## Results sharing
 
 When opening a pull request, add the latest benchmark rows (or a summary table) to this file or reference the CSV as part of your performance discussion so reviewers can reproduce the numbers.

README.md

@@ -102,7 +102,7 @@ target_link_libraries(... t81::t81lib)
 
 ## GPU backends
 
-Optional CUDA/ROCm backends can be enabled with `-DUSE_CUDA=ON` / `-DUSE_ROCM=ON` so the Python bindings link against the GPU kernels. `t81lib` exposes a compact `TensorMetadata` ABI that carries device, dtype, shape, and stride info, allowing `where`, `clamp`, `lerp`, and `addcmul` to work directly on NumPy arrays or Torch tensors. See [docs/gpu.md](docs/gpu.md) and [docs/torch.md](docs/torch.md) for build flags, device routing, supported ops, and lifetime details.
+Optional CUDA/ROCm backends can be enabled with `-DUSE_CUDA=ON` / `-DUSE_ROCM=ON` so the Python bindings link against the GPU kernels. `t81lib` exposes a compact `TensorMetadata` ABI that carries device, dtype, shape, and stride info, allowing `where`, `clamp`, `lerp`, and `addcmul` to work directly on NumPy arrays or Torch tensors. See [docs/gpu.md](docs/gpu.md), [docs/torch.md](docs/torch.md), and the [GPU dispatch diagram](docs/diagrams/gpu-dispatch.mermaid.md) for build flags, device routing, supported ops, and lifetime details.
 
 ## CLI helpers
 

docs/api-overview.md

@@ -1,6 +1,6 @@
 # API overview
 
-This page captures the high-level helpers exposed by the umbrella header so you can understand the building blocks without diving into every header.
+This page captures the high-level helpers exposed by the umbrella header so you can understand the building blocks without diving into every header. Review the [core architecture diagram](diagrams/core-architecture.mermaid.md) for an inheritance/data-flow sketch of the same helpers.
 
 ## Core numerics
 

docs/diagrams/benchmarks.mermaid.md

@@ -0,0 +1,9 @@
+```mermaid
+pie title Latency & storage comparison (relative)
+    "FP32 latency" : 100
+    "PTQ latency" : 45
+    "QAT latency" : 38
+    "FP32 storage" : 100
+    "PTQ storage" : 22
+    "QAT storage" : 24
+```

docs/diagrams/core-architecture.mermaid.md

@@ -0,0 +1,30 @@
+```mermaid
+flowchart LR
+    subgraph Core [t81::core]
+        limb[l1:limb (48 trits)]
+        bigint[bigint (limb slices)]
+    end
+    subgraph HighLevel [Umbrella helpers]
+        Int[t81::Int]
+        Float[t81::Float / FloatN]
+        BigInt[t81::BigInt alias]
+        Ratio[t81::Ratio]
+        Vector[t81::Vector]
+    end
+    limb --> Int
+    limb --> Float
+    bigint --> BigInt
+    BigInt --> Ratio
+    Vector --> Float
+    Float --> Ratio
+    Vector --> Int
+    subgraph Ops [Arithmetic & GEMM]
+        GEMM[t81::linalg::gemm_ternary]
+        Fixed[t81::Fixed<N>]
+    end
+    Int --> Ops
+    Float --> Ops
+    Vector --> GEMM
+    Fixed --> GEMM
+    click Float "docs/api-overview.md" "See the helper summary"
+```

docs/diagrams/docs-sitemap.mermaid.md

@@ -0,0 +1,28 @@
+```mermaid
+graph TD
+    Docs[Docs portal]
+    GettingStarted[Getting started]
+    Specs[Specs & design]
+    Examples[Examples & testing]
+    Docs --> GettingStarted
+    Docs --> Specs
+    Docs --> Examples
+    GettingStarted --> README
+    GettingStarted --> PythonInstall
+    GettingStarted --> CLI
+    Specs --> Spec
+    Specs --> Design
+    Specs --> APIOverview
+    Examples --> Demos
+    Examples --> Tests
+    Examples --> Benchmarks
+    README[README.md]
+    PythonInstall[docs/python-install.md]
+    CLI[docs/references/cli-usage.md]
+    Spec[docs/t81lib-spec-v1.0.0.md]
+    Design[docs/design/]
+    APIOverview[docs/api-overview.md]
+    Demos[examples/README.md]
+    Tests[tests/]
+    Benchmarks[BENCHMARKS.md]
+```

docs/diagrams/gpu-dispatch.mermaid.md

@@ -0,0 +1,20 @@
+```mermaid
+flowchart LR
+    torch[PyTorch tensor] --> extract[Extract metadata]
+    numpy[NumPy array] --> extract
+    extract --> validate[Validate device/dtype]
+    validate --> dispatch[Dispatch to backend]
+    dispatch --> cuda[CUDA kernel]
+    dispatch --> rocm[ROCm kernel]
+    dispatch --> cpu[CPU fallback]
+    cuda --> wrap[Wrap GPU tensor]
+    rocm --> wrap
+    cpu --> wrap
+    wrap --> return[Return to caller]
+    subgraph Errors
+        mismatch[Device mismatch] --> error[Error path]
+        unsupported[Unsupported dtype] --> error
+    end
+    validate --> mismatch
+    validate --> unsupported
+```

docs/diagrams/hardware-kernels.mermaid.md

@@ -0,0 +1,13 @@
+```mermaid
+flowchart TB
+    tryte[Packed trytes (limbs)]
+    load[Load registers (AVX/NEON)]
+    mask[Mask & expand trits]
+    multiply[Multiply columns]
+    accumulate[Accumulate into FP32/BF16]
+    store[Store to output buffer]
+    tryte --> load --> mask --> multiply --> accumulate --> store
+    style load stroke:#333,stroke-width:1px
+    style mask stroke:#f66,stroke-width:1px
+    style multiply stroke:#36c,stroke-width:1px
+```

docs/diagrams/quantization-workflow.mermaid.md

@@ -0,0 +1,14 @@
+```mermaid
+sequenceDiagram
+    participant PyTorch
+    participant Quantizer
+    participant CLI
+    participant Runtime
+
+    PyTorch->>Quantizer: export float model
+    Quantizer->>Quantizer: `t81.torch` quantizes (TernaryTensor)
+    Quantizer->>CLI: pack weights, store GGUF
+    CLI->>Runtime: load GGUF
+    Runtime->>Runtime: run `gemm_ternary` + accumulators
+    Runtime->>PyTorch: return inference results
+```