# lengqingsnow/cns2fpga architecture

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

## Overview

CNS2FPGA is a research workflow for extracting connectome-constrained neural circuits, modeling and checking them, compiling fixed-point images, and validating execution on FPGA hardware. Its central user-to-result path runs from MaleCNS data through extraction, CPU references, compilation, RTL checks, and board measurements. Separate branches cover biological-plausibility analysis, courtship robustness, visual steering, baselines, and runtime image replacement. The README documents these stages; sampled source confirms selected runner dependencies, but not every subsystem’s internal wiring.

Main entry points: [`code/6_Connectome Compiler/compile_hardware_ir.py`](https://github.com/lengqingsnow/cns2fpga/blob/main/code/6_Connectome%20Compiler/compile_hardware_ir.py) (Image compiler), [`code/3_CPU Floating-Point Golden Model`](https://github.com/lengqingsnow/cns2fpga/tree/main/code/3_CPU%20Floating-Point%20Golden%20Model) (Float reference), [`code/10_Complete Courtship-Song Circuit Experiment/run_experiment.py`](https://github.com/lengqingsnow/cns2fpga/blob/main/code/10_Complete%20Courtship-Song%20Circuit%20Experiment/run_experiment.py) (Courtship experiment), [`code/15_Ethernet_Runtime_Deployment`](https://github.com/lengqingsnow/cns2fpga/tree/main/code/15_Ethernet_Runtime_Deployment) (Ethernet image loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extract["Circuit Extraction"]
  node_extractor1["Circuit extraction"]
  node_extractor2["Subcircuit extraction<br/>[run_extractor.py]"]
end

subgraph group_model["Modeling and Analysis"]
  node_golden["Float reference"]
  node_plausibility["Plausibility checks"]
  node_fixed["Fixed-point analysis"]
end

subgraph group_hardware["FPGA Implementation"]
  node_compiler["Image compiler"]
  node_architecture["FPGA architecture"]
  node_cosim["RTL co-simulation"]
  node_boardhost["Board validation host<br/>[step9_host.py]"]
end

subgraph group_deployment["Runtime Deployment"]
  node_jtag["JTAG image loading"]
  node_ethernet["Ethernet image loading"]
end

subgraph group_studies["Circuit Studies"]
  node_courtship["Courtship experiment<br/>[run_experiment.py]"]
  node_robustness["Robustness study<br/>[run_robustness.py]"]
  node_visual["Visual steering circuit"]
  node_baselines["Baselines and ablations<br/>[run_baselines.py]"]
end

node_dataset[("MaleCNS data")]
node_board{{"AXKU115 board"}}

node_dataset -->|"extracts from"| node_extractor1
node_extractor1 -->|"selects subgraphs"| node_extractor2
node_extractor2 -->|"supplies circuit IR"| node_golden
node_golden -->|"evaluates model"| node_plausibility
node_golden -->|"compares precision"| node_fixed
node_fixed -->|"selects format"| node_compiler
node_extractor2 -->|"supplies graph IR"| node_compiler
node_compiler -->|"generates images"| node_architecture
node_architecture -->|"checks RTL"| node_cosim
node_compiler -->|"provides reference image"| node_boardhost
node_boardhost -->|"prepares board trials"| node_board
node_board -->|"provides captures"| node_courtship
node_golden -->|"provides CPU reference"| node_courtship
node_courtship -->|"supplies baseline"| node_robustness
node_visual -->|"supplies circuit"| node_baselines
node_compiler -.->|"loads compiled image"| node_jtag
node_jtag -.->|"configures at runtime"| node_board
node_compiler -->|"loads compiled image"| node_ethernet
node_ethernet -->|"uploads over UDP"| node_board
node_visual -->|"provides visual image"| node_ethernet
node_courtship -->|"provides courtship image"| node_ethernet

click node_extractor1 "https://github.com/lengqingsnow/cns2fpga/tree/main/code/1_biological%20circuit"
click node_extractor2 "https://github.com/lengqingsnow/cns2fpga/blob/main/code/2_Subcircuit%20Automatic%20Extraction%20Tool/run_extractor.py"
click node_golden "https://github.com/lengqingsnow/cns2fpga/tree/main/code/3_CPU%20Floating-Point%20Golden%20Model"
click node_plausibility "https://github.com/lengqingsnow/cns2fpga/tree/main/code/4_Verify%20whether%20this%20model%20has%20basic%20biological%20plausibility"
click node_fixed "https://github.com/lengqingsnow/cns2fpga/blob/main/code/5_Fixed-Point%20Quantization%20Analysis/run_quantization_analysis.py"
click node_compiler "https://github.com/lengqingsnow/cns2fpga/blob/main/code/6_Connectome%20Compiler/compile_hardware_ir.py"
click node_architecture "https://github.com/lengqingsnow/cns2fpga/tree/main/code/7_Minimum%20FPGA%20Architecture"
click node_cosim "https://github.com/lengqingsnow/cns2fpga/tree/main/code/8_RTL%20Bit-Exact%20Co-Simulation"
click node_boardhost "https://github.com/lengqingsnow/cns2fpga/blob/main/code/9_KU115%20FPGA%20Validation/host/step9_host.py"
click node_courtship "https://github.com/lengqingsnow/cns2fpga/blob/main/code/10_Complete%20Courtship-Song%20Circuit%20Experiment/run_experiment.py"
click node_robustness "https://github.com/lengqingsnow/cns2fpga/blob/main/code/11_Courtship-Song%20Robustness/run_robustness.py"
click node_visual "https://github.com/lengqingsnow/cns2fpga/tree/main/code/12_Visual-to-Steering%20Circuit"
click node_baselines "https://github.com/lengqingsnow/cns2fpga/blob/main/code/13_Baselines%20and%20Ablations/run_baselines.py"
click node_jtag "https://github.com/lengqingsnow/cns2fpga/tree/main/code/14_Runtime%20Reconfigurable%20Deployment"
click node_ethernet "https://github.com/lengqingsnow/cns2fpga/tree/main/code/15_Ethernet_Runtime_Deployment"

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_extractor1,node_extractor2 toneBlue
class node_golden,node_plausibility,node_fixed,node_dataset toneAmber
class node_compiler,node_architecture,node_cosim,node_boardhost toneMint
class node_jtag,node_ethernet toneRose
class node_courtship,node_robustness,node_visual,node_baselines,node_board toneIndigo
```

## Components

### Circuit Extraction

- [Circuit extraction](https://github.com/lengqingsnow/cns2fpga/tree/main/code/1_biological%20circuit): `code/1_biological circuit`
- [Subcircuit extraction](https://github.com/lengqingsnow/cns2fpga/blob/main/code/2_Subcircuit%20Automatic%20Extraction%20Tool/run_extractor.py): `code/2_Subcircuit Automatic Extraction Tool/run_extractor.py`

### Modeling and Analysis

- [Float reference](https://github.com/lengqingsnow/cns2fpga/tree/main/code/3_CPU%20Floating-Point%20Golden%20Model): `code/3_CPU Floating-Point Golden Model`
- [Plausibility checks](https://github.com/lengqingsnow/cns2fpga/tree/main/code/4_Verify%20whether%20this%20model%20has%20basic%20biological%20plausibility): `code/4_Verify whether this model has basic biological plausibility`
- [Fixed-point analysis](https://github.com/lengqingsnow/cns2fpga/blob/main/code/5_Fixed-Point%20Quantization%20Analysis/run_quantization_analysis.py): `code/5_Fixed-Point Quantization Analysis/run_quantization_analysis.py`

### FPGA Implementation

- [Image compiler](https://github.com/lengqingsnow/cns2fpga/blob/main/code/6_Connectome%20Compiler/compile_hardware_ir.py): `code/6_Connectome Compiler/compile_hardware_ir.py`
- [FPGA architecture](https://github.com/lengqingsnow/cns2fpga/tree/main/code/7_Minimum%20FPGA%20Architecture): `code/7_Minimum FPGA Architecture`
- [RTL co-simulation](https://github.com/lengqingsnow/cns2fpga/tree/main/code/8_RTL%20Bit-Exact%20Co-Simulation): `code/8_RTL Bit-Exact Co-Simulation`
- [Board validation host](https://github.com/lengqingsnow/cns2fpga/blob/main/code/9_KU115%20FPGA%20Validation/host/step9_host.py): `code/9_KU115 FPGA Validation/host/step9_host.py`

### Runtime Deployment

- [JTAG image loading](https://github.com/lengqingsnow/cns2fpga/tree/main/code/14_Runtime%20Reconfigurable%20Deployment): `code/14_Runtime Reconfigurable Deployment`
- [Ethernet image loading](https://github.com/lengqingsnow/cns2fpga/tree/main/code/15_Ethernet_Runtime_Deployment): `code/15_Ethernet_Runtime_Deployment`

### Circuit Studies

- [Courtship experiment](https://github.com/lengqingsnow/cns2fpga/blob/main/code/10_Complete%20Courtship-Song%20Circuit%20Experiment/run_experiment.py): `code/10_Complete Courtship-Song Circuit Experiment/run_experiment.py`
- [Robustness study](https://github.com/lengqingsnow/cns2fpga/blob/main/code/11_Courtship-Song%20Robustness/run_robustness.py): `code/11_Courtship-Song Robustness/run_robustness.py`
- [Visual steering circuit](https://github.com/lengqingsnow/cns2fpga/tree/main/code/12_Visual-to-Steering%20Circuit): `code/12_Visual-to-Steering Circuit`
- [Baselines and ablations](https://github.com/lengqingsnow/cns2fpga/blob/main/code/13_Baselines%20and%20Ablations/run_baselines.py): `code/13_Baselines and Ablations/run_baselines.py`

### Other components

- **MaleCNS data**
- **AXKU115 board**

## Connections

- MaleCNS data → Circuit extraction: extracts from
- Circuit extraction → Subcircuit extraction: selects subgraphs
- Subcircuit extraction → Float reference: supplies circuit IR
- Float reference → Plausibility checks: evaluates model
- Float reference → Fixed-point analysis: compares precision
- Fixed-point analysis → Image compiler: selects format
- Subcircuit extraction → Image compiler: supplies graph IR
- Image compiler → FPGA architecture: generates images
- FPGA architecture → RTL co-simulation: checks RTL
- Image compiler → Board validation host: provides reference image
- Board validation host → AXKU115 board: prepares board trials
- AXKU115 board → Courtship experiment: provides captures
- Float reference → Courtship experiment: provides CPU reference
- Courtship experiment → Robustness study: supplies baseline
- Visual steering circuit → Baselines and ablations: supplies circuit
- Image compiler → JTAG image loading: loads compiled image
- JTAG image loading → AXKU115 board: configures at runtime
- Image compiler → Ethernet image loading: loads compiled image
- Ethernet image loading → AXKU115 board: uploads over UDP
- Visual steering circuit → Ethernet image loading: provides visual image
- Courtship experiment → Ethernet image loading: provides courtship image