# notayan1505/retrainable-neural-decoder architecture

> Architecture diagram of the GitHub repository notayan1505/retrainable-neural-decoder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/notayan1505/retrainable-neural-decoder
- Repository: https://github.com/notayan1505/retrainable-neural-decoder

## Overview

qdrift is a repetition-code neural-decoder experiment: its CLI coordinates loading or generating hardware data, training/comparing decoders, and writing evaluation results. The main data path converts Stein bitstrings into detector tensors and labels; evaluation compares matching and lookup baselines with trained neural models on held-out data. The README also documents fresh fake- or real-IBM runs for drift testing. Connections below follow shown CLI references, source-index references, and explicit README statements; unsampled implementation details are not inferred.

Main entry points: [`qdrift/cli.py`](https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/cli.py) (Command CLI), [`qdrift/evaluate.py`](https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/evaluate.py) (Evaluation), [`qdrift/data/stein.py`](https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/data/stein.py) (Stein loader), [`qdrift/data/circuits.py`](https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/data/circuits.py) (Repetition circuits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command interface"]
  node_cli["Command CLI<br/>[cli.py]"]
end

subgraph group_data["Experiment data"]
  node_stein["Stein loader<br/>[stein.py]"]
  node_dataset["Detector dataset<br/>[stein.py]"]
  node_circuits["Repetition circuits<br/>[circuits.py]"]
end

subgraph group_decoding["Decoder methods"]
  node_baselines["Baseline decoders<br/>[baselines.py]"]
  node_network["Neural models<br/>[net.py]"]
end

subgraph group_assessment["Training and assessment"]
  node_training["Model training<br/>[train.py]"]
  node_evaluation["Evaluation<br/>[evaluate.py]"]
  node_results["Result files"]
end

node_user(("Experimenter"))
node_zenodo["Zenodo dataset"]
node_ibm["IBM backends"]

node_user -->|"runs commands"| node_cli
node_cli -->|"loads and parses"| node_stein
node_cli -->|"runs baseline"| node_baselines
node_cli -->|"evaluates"| node_evaluation
node_cli -->|"trains models"| node_training
node_cli -->|"runs circuits"| node_circuits
node_zenodo -->|"provides raw data"| node_stein
node_stein -->|"derives detectors"| node_dataset
node_evaluation -->|"loads and splits"| node_stein
node_evaluation -->|"compares decoders"| node_baselines
node_evaluation -->|"uses neural decoder"| node_training
node_training -->|"builds model"| node_network
node_evaluation -->|"writes CSV"| node_results
node_circuits -->|"submits circuits"| node_ibm
node_circuits -->|"writes parser format"| node_stein

click node_cli "https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/cli.py"
click node_stein "https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/data/stein.py"
click node_dataset "https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/data/stein.py"
click node_circuits "https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/data/circuits.py"
click node_baselines "https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/decoders/baselines.py"
click node_network "https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/models/net.py"
click node_training "https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/train.py"
click node_evaluation "https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/evaluate.py"
click node_results "https://github.com/notayan1505/retrainable-neural-decoder/tree/main/results/qdrift"

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_cli toneBlue
class node_stein,node_dataset,node_circuits toneAmber
class node_baselines,node_network toneMint
class node_training,node_evaluation,node_results toneRose
class node_user,node_zenodo,node_ibm toneIndigo
```

## Components

### Command interface

- [Command CLI](https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/cli.py): `qdrift/cli.py`

### Experiment data

- [Stein loader](https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/data/stein.py): `qdrift/data/stein.py`
- [Detector dataset](https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/data/stein.py): `qdrift/data/stein.py`
- [Repetition circuits](https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/data/circuits.py): `qdrift/data/circuits.py`

### Decoder methods

- [Baseline decoders](https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/decoders/baselines.py): `qdrift/decoders/baselines.py`
- [Neural models](https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/models/net.py): `qdrift/models/net.py`

### Training and assessment

- [Model training](https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/train.py): `qdrift/train.py`
- [Evaluation](https://github.com/notayan1505/retrainable-neural-decoder/blob/main/qdrift/evaluate.py): `qdrift/evaluate.py`
- [Result files](https://github.com/notayan1505/retrainable-neural-decoder/tree/main/results/qdrift): `results/qdrift`

### Other components

- **Experimenter**
- **Zenodo dataset**
- **IBM backends**

## Connections

- Experimenter → Command CLI: runs commands (evidence: `README.md`)
- Command CLI → Stein loader: loads and parses (evidence: `qdrift/cli.py`)
- Command CLI → Baseline decoders: runs baseline (evidence: `qdrift/cli.py`)
- Command CLI → Evaluation: evaluates (evidence: `qdrift/cli.py`)
- Command CLI → Model training: trains models (evidence: `qdrift/cli.py`)
- Command CLI → Repetition circuits: runs circuits (evidence: `qdrift/cli.py`)
- Zenodo dataset → Stein loader: provides raw data (evidence: `README.md`)
- Stein loader → Detector dataset: derives detectors (evidence: `qdrift/data/stein.py`)
- Evaluation → Stein loader: loads and splits (evidence: `qdrift/evaluate.py`)
- Evaluation → Baseline decoders: compares decoders (evidence: `qdrift/evaluate.py`)
- Evaluation → Model training: uses neural decoder (evidence: `qdrift/evaluate.py`)
- Model training → Neural models: builds model (evidence: `qdrift/train.py`)
- Evaluation → Result files: writes CSV (evidence: `README.md`)
- Repetition circuits → IBM backends: submits circuits (evidence: `qdrift/data/circuits.py`)
- Repetition circuits → Stein loader: writes parser format (evidence: `qdrift/data/circuits.py`)