# hellwithcode0/mabs-public architecture

> Architecture diagram of the GitHub repository hellwithcode0/mabs-public, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hellwithcode0/mabs-public
- Repository: https://github.com/hellwithcode0/mabs-public

## Overview

MABS is a streaming quantum error-correction decoder for rotated surface-code memory. Its principal workflow builds a circuit bundle, prepares syndrome data, decodes each shot in overlapping windows, routes each window through fast local/lookup paths or blossom, then commits corrections and carries unresolved syndrome forward to produce logical-observable predictions. The README also documents legacy adaptive/SLEM decoders, batch and fixed-streaming baselines, and timing/reporting capabilities. The excerpts establish key CASCADE calls; wiring for unsampled CLI and decoder modules is left out where uncertain.

Main entry points: [`src/mabs/v4/cascade_stream.py`](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/cascade_stream.py) (CASCADE stream), [`src/mabs/baselines.py`](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/baselines.py) (Baseline runners), [`src/mabs/v4/cascade_route.py`](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/cascade_route.py) (FLASH routing), [`src/mabs/v3/cli_bench.py`](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v3/cli_bench.py) (Benchmark CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_main["Package CLI<br/>[__main__.py]"]
  node_bench_cli["Benchmark CLI<br/>[cli_bench.py]"]
end

subgraph group_stream["Streaming data"]
  node_bundle["Circuit bundle<br/>[streaming.py]"]
  node_dem["DEM processing<br/>[streaming_dem.py]"]
  node_graph["Window graph<br/>[streaming_graph.py]"]
  node_windows["Window matching"]
end

subgraph group_decode["Decode routes"]
  node_cascade_stream["CASCADE stream<br/>[cascade_stream.py]"]
  node_cascade_route["FLASH routing<br/>[cascade_route.py]"]
  node_cascade_core["CASCADE config<br/>[cascade_core.py]"]
  node_flash_lut[("FLASH lookup<br/>[flash_lut.py]")]
  node_cluster["Certified clusters<br/>[cluster_route.py]"]
  node_commit["Commit actions<br/>[commit_action.py]"]
  node_blossom["Blossom decode<br/>[local_decode.py]"]
  node_slem["SLEM decoder<br/>[slem.py]"]
  node_adaptive["Adaptive decoder<br/>[adaptive.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_baselines["Baseline runners<br/>[baselines.py]"]
  node_reporting["Timing reports<br/>[reporting.py]"]
end

node_user(("Operator"))
node_stim["Stim"]
node_pymatching["PyMatching"]

node_user -->|"launches"| node_main
node_user -->|"benchmarks"| node_bench_cli
node_bench_cli -->|"runs methods"| node_baselines
node_baselines -->|"uses bundle"| node_bundle
node_bundle -->|"builds circuit"| node_stim
node_bundle -->|"derives detector data"| node_dem
node_cascade_stream -->|"gets schedule"| node_graph
node_graph -->|"builds window matchers"| node_windows
node_cascade_stream -->|"routes windows"| node_cascade_route
node_cascade_stream -->|"commits results"| node_commit
node_cascade_stream -->|"commits blossom edges"| node_windows
node_cascade_route -->|"looks up actions"| node_flash_lut
node_cascade_route -->|"tries cluster route"| node_cluster
node_cascade_route -->|"falls back"| node_blossom
node_cascade_stream -->|"uses configuration"| node_cascade_core
node_cluster -->|"uses actions"| node_flash_lut
node_baselines -->|"batch decode"| node_pymatching
node_windows -->|"window matching"| node_pymatching
node_baselines -.->|"runs decoder"| node_slem
node_baselines -.->|"runs decoder"| node_adaptive
node_bench_cli -->|"summarizes measurements"| node_reporting

click node_main "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/__main__.py"
click node_bench_cli "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v3/cli_bench.py"
click node_bundle "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/streaming.py"
click node_dem "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/streaming_dem.py"
click node_graph "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/streaming_graph.py"
click node_windows "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/streaming_windows.py"
click node_cascade_stream "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/cascade_stream.py"
click node_cascade_route "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/cascade_route.py"
click node_cascade_core "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/cascade_core.py"
click node_flash_lut "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/flash_lut.py"
click node_cluster "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/cluster_route.py"
click node_commit "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/commit_action.py"
click node_blossom "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v3/local_decode.py"
click node_slem "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v3/slem.py"
click node_adaptive "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/adaptive.py"
click node_baselines "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/baselines.py"
click node_reporting "https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/reporting.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_bench_cli toneBlue
class node_bundle,node_dem,node_graph,node_windows toneAmber
class node_cascade_stream,node_cascade_route,node_cascade_core,node_flash_lut,node_cluster,node_commit,node_blossom,node_slem,node_adaptive toneMint
class node_baselines,node_reporting toneRose
class node_user,node_stim,node_pymatching toneIndigo
```

## Components

### Entry points

- [Package CLI](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/__main__.py): `src/mabs/__main__.py`
- [Benchmark CLI](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v3/cli_bench.py): `src/mabs/v3/cli_bench.py`

### Streaming data

- [Circuit bundle](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/streaming.py): `src/mabs/streaming.py`
- [DEM processing](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/streaming_dem.py): `src/mabs/streaming_dem.py`
- [Window graph](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/streaming_graph.py): `src/mabs/streaming_graph.py`
- [Window matching](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/streaming_windows.py): `src/mabs/streaming_windows.py`

### Decode routes

- [CASCADE stream](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/cascade_stream.py): `src/mabs/v4/cascade_stream.py`
- [FLASH routing](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/cascade_route.py): `src/mabs/v4/cascade_route.py`
- [CASCADE config](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/cascade_core.py): `src/mabs/v4/cascade_core.py`
- [FLASH lookup](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/flash_lut.py): `src/mabs/v4/flash_lut.py`
- [Certified clusters](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/cluster_route.py): `src/mabs/v4/cluster_route.py`
- [Commit actions](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v4/commit_action.py): `src/mabs/v4/commit_action.py`
- [Blossom decode](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v3/local_decode.py): `src/mabs/v3/local_decode.py`
- [SLEM decoder](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/v3/slem.py): `src/mabs/v3/slem.py`
- [Adaptive decoder](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/adaptive.py): `src/mabs/adaptive.py`

### Evaluation

- [Baseline runners](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/baselines.py): `src/mabs/baselines.py`
- [Timing reports](https://github.com/hellwithcode0/mabs-public/blob/main/src/mabs/reporting.py): `src/mabs/reporting.py`

### Other components

- **Operator**
- **Stim**
- **PyMatching**

## Connections

- Operator → Package CLI: launches
- Operator → Benchmark CLI: benchmarks
- Benchmark CLI → Baseline runners: runs methods
- Baseline runners → Circuit bundle: uses bundle
- Circuit bundle → Stim: builds circuit
- Circuit bundle → DEM processing: derives detector data
- CASCADE stream → Window graph: gets schedule
- Window graph → Window matching: builds window matchers
- CASCADE stream → FLASH routing: routes windows
- CASCADE stream → Commit actions: commits results
- CASCADE stream → Window matching: commits blossom edges
- FLASH routing → FLASH lookup: looks up actions
- FLASH routing → Certified clusters: tries cluster route
- FLASH routing → Blossom decode: falls back
- CASCADE stream → CASCADE config: uses configuration
- Certified clusters → FLASH lookup: uses actions
- Baseline runners → PyMatching: batch decode
- Window matching → PyMatching: window matching
- Baseline runners → SLEM decoder: runs decoder
- Baseline runners → Adaptive decoder: runs decoder
- Benchmark CLI → Timing reports: summarizes measurements