# yonilc/ecct architecture

> Architecture diagram of the GitHub repository yonilc/ecct, 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/yonilc/ecct
- Repository: https://github.com/yonilc/ecct

## Overview

This repository trains and evaluates a Transformer-based decoder for linear error-correcting codes. The workflow selects a code, loads its parity-check specification, generates noisy training and test examples, trains the decoder, and measures bit- and frame-error performance across channel conditions. The model combines channel observations and syndromes using code-structure-masked attention. The README also documents support for several code families. Some orchestration details in Main.py are omitted from the excerpt, so the graph includes only relationships supported by the visible code and documented workflow.

Main entry points: [`Main.py`](https://github.com/yonilc/ecct/blob/main/Main.py) (Experiment runner), [`Model.py`](https://github.com/yonilc/ecct/blob/main/Model.py) (ECCT model), [`Codes.py`](https://github.com/yonilc/ecct/blob/main/Codes.py) (Code matrices), [`Codes_DB`](https://github.com/yonilc/ecct/tree/main/Codes_DB) (Code specifications)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_codes["Code definitions"]
  node_code_loader["Code matrices<br/>[Codes.py]"]
  node_code_specs["Code specifications"]
  node_metrics["Error metrics<br/>[Codes.py]"]
end

subgraph group_experiment["Experiment workflow"]
  node_main["Experiment runner<br/>[Main.py]"]
  node_dataset["Sample generation<br/>[Main.py]"]
  node_training["Training loop<br/>[Main.py]"]
  node_evaluation["Evaluation loop<br/>[Main.py]"]
end

subgraph group_decoder["Neural decoder"]
  node_transformer["ECCT model<br/>[Model.py]"]
  node_encoder["Transformer encoder<br/>[Model.py]"]
  node_attention["Masked attention<br/>[Model.py]"]
  node_feedforward["Feed-forward layer<br/>[Model.py]"]
end

node_user(("Experimenter"))

node_user -->|"configures and runs"| node_main
node_main -->|"loads code matrices"| node_code_loader
node_code_loader -->|"reads specification"| node_code_specs
node_main -->|"creates loaders"| node_dataset
node_dataset -->|"uses code parameters"| node_code_specs
node_main -->|"constructs model"| node_transformer
node_main -->|"runs epochs"| node_training
node_main -->|"evaluates model"| node_evaluation
node_training -->|"consumes batches"| node_dataset
node_evaluation -->|"consumes batches"| node_dataset
node_training -->|"trains decoder"| node_transformer
node_evaluation -->|"decodes batches"| node_transformer
node_training -->|"measures BER FER"| node_metrics
node_evaluation -->|"measures BER FER"| node_metrics
node_transformer -->|"processes embeddings"| node_encoder
node_encoder -->|"applies attention"| node_attention
node_encoder -->|"applies feed-forward"| node_feedforward

click node_main "https://github.com/yonilc/ecct/blob/main/Main.py"
click node_dataset "https://github.com/yonilc/ecct/blob/main/Main.py"
click node_training "https://github.com/yonilc/ecct/blob/main/Main.py"
click node_evaluation "https://github.com/yonilc/ecct/blob/main/Main.py"
click node_code_loader "https://github.com/yonilc/ecct/blob/main/Codes.py"
click node_code_specs "https://github.com/yonilc/ecct/tree/main/Codes_DB"
click node_metrics "https://github.com/yonilc/ecct/blob/main/Codes.py"
click node_transformer "https://github.com/yonilc/ecct/blob/main/Model.py"
click node_encoder "https://github.com/yonilc/ecct/blob/main/Model.py"
click node_attention "https://github.com/yonilc/ecct/blob/main/Model.py"
click node_feedforward "https://github.com/yonilc/ecct/blob/main/Model.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_code_loader,node_code_specs,node_metrics toneBlue
class node_main,node_dataset,node_training,node_evaluation toneAmber
class node_transformer,node_encoder,node_attention,node_feedforward toneMint
class node_user toneIndigo
```

## Components

### Code definitions

- [Code matrices](https://github.com/yonilc/ecct/blob/main/Codes.py): `Codes.py`
- [Code specifications](https://github.com/yonilc/ecct/tree/main/Codes_DB): `Codes_DB`
- [Error metrics](https://github.com/yonilc/ecct/blob/main/Codes.py): `Codes.py`

### Experiment workflow

- [Experiment runner](https://github.com/yonilc/ecct/blob/main/Main.py): `Main.py`
- [Sample generation](https://github.com/yonilc/ecct/blob/main/Main.py): `Main.py`
- [Training loop](https://github.com/yonilc/ecct/blob/main/Main.py): `Main.py`
- [Evaluation loop](https://github.com/yonilc/ecct/blob/main/Main.py): `Main.py`

### Neural decoder

- [ECCT model](https://github.com/yonilc/ecct/blob/main/Model.py): `Model.py`
- [Transformer encoder](https://github.com/yonilc/ecct/blob/main/Model.py): `Model.py`
- [Masked attention](https://github.com/yonilc/ecct/blob/main/Model.py): `Model.py`
- [Feed-forward layer](https://github.com/yonilc/ecct/blob/main/Model.py): `Model.py`

### Other components

- **Experimenter**

## Connections

- Experimenter → Experiment runner: configures and runs
- Experiment runner → Code matrices: loads code matrices
- Code matrices → Code specifications: reads specification
- Experiment runner → Sample generation: creates loaders
- Sample generation → Code specifications: uses code parameters
- Experiment runner → ECCT model: constructs model
- Experiment runner → Training loop: runs epochs
- Experiment runner → Evaluation loop: evaluates model
- Training loop → Sample generation: consumes batches
- Evaluation loop → Sample generation: consumes batches
- Training loop → ECCT model: trains decoder
- Evaluation loop → ECCT model: decodes batches
- Training loop → Error metrics: measures BER FER
- Evaluation loop → Error metrics: measures BER FER
- ECCT model → Transformer encoder: processes embeddings
- Transformer encoder → Masked attention: applies attention
- Transformer encoder → Feed-forward layer: applies feed-forward