# pervasiveautonomylab/bern2edge architecture

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

- Interactive diagram: https://gitdiagram.com/pervasiveautonomylab/bern2edge
- Repository: https://github.com/pervasiveautonomylab/bern2edge

## Overview

Bern2Edge is a research framework for compressing pretrained teachers into Bernstein students, then deploying those students either as FPGA-oriented HLS or as interpretable rules. Its reusable package supplies data, models, distillation, and rule extraction; HLS provides separate compilers for networks and rules. The repository also contains experiment branches for certification, distribution shift, and TinyBERT substitution. Connections for unsampled subsystems are limited to README statements; source-level edges use indexed references or excerpts.

Main entry points: [`bern2edge/models.py`](https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/models.py) (Bernstein students), [`bern2edge/rule_extraction/extraction.py`](https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/rule_extraction/extraction.py) (Rule extraction), [`hls/bern2hls/fc/compile.py`](https://github.com/pervasiveautonomylab/bern2edge/blob/main/hls/bern2hls/fc/compile.py) (FC compiler), [`bern2edge/kdtrain.py`](https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/kdtrain.py) (Knowledge distillation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning Core"]
  node_datasets["Data loaders<br/>[data.py]"]
  node_teacher["Teacher models<br/>[models.py]"]
  node_student["Bernstein students<br/>[models.py]"]
  node_bernstein["Bernstein layer<br/>[bernstein.py]"]
  node_distillation["Knowledge distillation<br/>[kdtrain.py]"]
end

subgraph group_rules["Symbolic Rules"]
  node_rule_geometry["Activation regimes<br/>[bern_regimes.py]"]
  node_rule_extraction["Rule extraction<br/>[extraction.py]"]
  node_quantization["Rule quantization<br/>[quantize.py]"]
  node_fallback["Rule fallback<br/>[fallback.py]"]
end

subgraph group_hardware["HLS Deployment"]
  node_fc_compiler["FC compiler<br/>[compile.py]"]
  node_fc_codegen["FC code generation<br/>[axi_family.py]"]
  node_rule_compiler["Rule compiler<br/>[compile.py]"]
  node_synthesis["Synthesis workflow<br/>[synth.py]"]
  node_hardware_collect["Hardware collection<br/>[collect.py]"]
end

subgraph group_experiments["Research Experiments"]
  node_certification["Robustness certification"]
  node_magic_rules["MAGIC rule studies<br/>[extract_rules.py]"]
  node_acs_shift["ACS shift studies<br/>[run_multiseed.py]"]
end

subgraph group_transformer["Transformer Path"]
  node_transformer_stages["FFN substitution"]
  node_transformer_utils["Transformer utilities<br/>[shared_utils.py]"]
end

node_user(("Researcher"))
node_edge_device["Edge hardware"]

node_user -->|"selects data"| node_datasets
node_datasets -->|"feeds batches"| node_distillation
node_teacher -->|"provides targets"| node_distillation
node_distillation -->|"trains student"| node_student
node_student -->|"uses layer"| node_bernstein
node_student -->|"extracts rules"| node_rule_extraction
node_rule_extraction -->|"analyzes regimes"| node_rule_geometry
node_rule_extraction -->|"quantizes rules"| node_quantization
node_student -->|"compiles network"| node_fc_compiler
node_rule_extraction -->|"compiles rules"| node_rule_compiler
node_fc_compiler -->|"emits HLS"| node_fc_codegen
node_fc_codegen -->|"targets FPGA"| node_edge_device
node_rule_compiler -.->|"uses fallback"| node_fallback
node_fc_compiler -.->|"runs synthesis"| node_synthesis
node_hardware_collect -->|"uses out-of-context"| node_synthesis
node_user -->|"runs study"| node_certification
node_user -->|"runs study"| node_magic_rules
node_user -->|"runs study"| node_acs_shift
node_user -->|"runs experiment"| node_transformer_stages
node_transformer_stages -->|"uses utilities"| node_transformer_utils

click node_datasets "https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/data.py"
click node_teacher "https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/models.py"
click node_student "https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/models.py"
click node_bernstein "https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/bernstein.py"
click node_distillation "https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/kdtrain.py"
click node_rule_geometry "https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/rule_extraction/bern_regimes.py"
click node_rule_extraction "https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/rule_extraction/extraction.py"
click node_quantization "https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/rule_extraction/quantize.py"
click node_fallback "https://github.com/pervasiveautonomylab/bern2edge/blob/main/hls/bern2hls/rules/fallback.py"
click node_fc_compiler "https://github.com/pervasiveautonomylab/bern2edge/blob/main/hls/bern2hls/fc/compile.py"
click node_fc_codegen "https://github.com/pervasiveautonomylab/bern2edge/blob/main/hls/bern2hls/fc/codegen/axi_family.py"
click node_rule_compiler "https://github.com/pervasiveautonomylab/bern2edge/blob/main/hls/bern2hls/rules/compile.py"
click node_synthesis "https://github.com/pervasiveautonomylab/bern2edge/blob/main/hls/bern2hls/core/synth.py"
click node_hardware_collect "https://github.com/pervasiveautonomylab/bern2edge/blob/main/hls/bern2hls/core/collect.py"
click node_certification "https://github.com/pervasiveautonomylab/bern2edge/blob/main/MAGIC/relu_lirpa_certify.py"
click node_magic_rules "https://github.com/pervasiveautonomylab/bern2edge/blob/main/MAGIC/extract_rules.py"
click node_acs_shift "https://github.com/pervasiveautonomylab/bern2edge/blob/main/ACS/run_multiseed.py"
click node_transformer_stages "https://github.com/pervasiveautonomylab/bern2edge/blob/main/Transformer/stage3_substitute.py"
click node_transformer_utils "https://github.com/pervasiveautonomylab/bern2edge/blob/main/Transformer/shared_utils.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_datasets,node_teacher,node_student,node_bernstein,node_distillation toneBlue
class node_rule_geometry,node_rule_extraction,node_quantization,node_fallback toneAmber
class node_fc_compiler,node_fc_codegen,node_rule_compiler,node_synthesis,node_hardware_collect toneMint
class node_certification,node_magic_rules,node_acs_shift toneRose
class node_transformer_stages,node_transformer_utils,node_user,node_edge_device toneIndigo
```

## Components

### Learning Core

- [Data loaders](https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/data.py): `bern2edge/data.py`
- [Teacher models](https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/models.py): `bern2edge/models.py`
- [Bernstein students](https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/models.py): `bern2edge/models.py`
- [Bernstein layer](https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/bernstein.py): `bern2edge/bernstein.py`
- [Knowledge distillation](https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/kdtrain.py): `bern2edge/kdtrain.py`

### Symbolic Rules

- [Activation regimes](https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/rule_extraction/bern_regimes.py): `bern2edge/rule_extraction/bern_regimes.py`
- [Rule extraction](https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/rule_extraction/extraction.py): `bern2edge/rule_extraction/extraction.py`
- [Rule quantization](https://github.com/pervasiveautonomylab/bern2edge/blob/main/bern2edge/rule_extraction/quantize.py): `bern2edge/rule_extraction/quantize.py`
- [Rule fallback](https://github.com/pervasiveautonomylab/bern2edge/blob/main/hls/bern2hls/rules/fallback.py): `hls/bern2hls/rules/fallback.py`

### HLS Deployment

- [FC compiler](https://github.com/pervasiveautonomylab/bern2edge/blob/main/hls/bern2hls/fc/compile.py): `hls/bern2hls/fc/compile.py`
- [FC code generation](https://github.com/pervasiveautonomylab/bern2edge/blob/main/hls/bern2hls/fc/codegen/axi_family.py): `hls/bern2hls/fc/codegen/axi_family.py`
- [Rule compiler](https://github.com/pervasiveautonomylab/bern2edge/blob/main/hls/bern2hls/rules/compile.py): `hls/bern2hls/rules/compile.py`
- [Synthesis workflow](https://github.com/pervasiveautonomylab/bern2edge/blob/main/hls/bern2hls/core/synth.py): `hls/bern2hls/core/synth.py`
- [Hardware collection](https://github.com/pervasiveautonomylab/bern2edge/blob/main/hls/bern2hls/core/collect.py): `hls/bern2hls/core/collect.py`

### Research Experiments

- [Robustness certification](https://github.com/pervasiveautonomylab/bern2edge/blob/main/MAGIC/relu_lirpa_certify.py): `MAGIC/relu_lirpa_certify.py`
- [MAGIC rule studies](https://github.com/pervasiveautonomylab/bern2edge/blob/main/MAGIC/extract_rules.py): `MAGIC/extract_rules.py`
- [ACS shift studies](https://github.com/pervasiveautonomylab/bern2edge/blob/main/ACS/run_multiseed.py): `ACS/run_multiseed.py`

### Transformer Path

- [FFN substitution](https://github.com/pervasiveautonomylab/bern2edge/blob/main/Transformer/stage3_substitute.py): `Transformer/stage3_substitute.py`
- [Transformer utilities](https://github.com/pervasiveautonomylab/bern2edge/blob/main/Transformer/shared_utils.py): `Transformer/shared_utils.py`

### Other components

- **Researcher**
- **Edge hardware**

## Connections

- Researcher → Data loaders: selects data (evidence: `README.md`)
- Data loaders → Knowledge distillation: feeds batches (evidence: `README.md`)
- Teacher models → Knowledge distillation: provides targets (evidence: `README.md`)
- Knowledge distillation → Bernstein students: trains student (evidence: `README.md`)
- Bernstein students → Bernstein layer: uses layer (evidence: `bern2edge/models.py`)
- Bernstein students → Rule extraction: extracts rules (evidence: `README.md`)
- Rule extraction → Activation regimes: analyzes regimes (evidence: `bern2edge/rule_extraction/extraction.py`)
- Rule extraction → Rule quantization: quantizes rules
- Bernstein students → FC compiler: compiles network (evidence: `README.md`)
- Rule extraction → Rule compiler: compiles rules (evidence: `README.md`)
- FC compiler → FC code generation: emits HLS (evidence: `hls/bern2hls/fc/codegen/axi_family.py`)
- FC code generation → Edge hardware: targets FPGA (evidence: `README.md`)
- Rule compiler → Rule fallback: uses fallback
- FC compiler → Synthesis workflow: runs synthesis
- Hardware collection → Synthesis workflow: uses out-of-context (evidence: `hls/bern2hls/core/collect.py`)
- Researcher → Robustness certification: runs study (evidence: `README.md`)
- Researcher → MAGIC rule studies: runs study (evidence: `README.md`)
- Researcher → ACS shift studies: runs study (evidence: `README.md`)
- Researcher → FFN substitution: runs experiment (evidence: `README.md`)
- FFN substitution → Transformer utilities: uses utilities (evidence: `Transformer/stage3_substitute.py`)