# vipinkmenon/neuralnetwork architecture

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

- Interactive diagram: https://gitdiagram.com/vipinkmenon/neuralnetwork
- Repository: https://github.com/vipinkmenon/neuralnetwork

## Overview

This repository is a tutorial series for training MNIST neural networks, translating models into fixed-point ZyNet FPGA designs, and running inference from embedded software. The main workflow trains a network and saves parameters; the ZyNet API compiles a layer description into RTL and parameter-memory files; FPGA-side logic accepts inputs and produces a classification that embedded code reads. The tree and excerpts support the training and generation calls; RTL-internal and board-level connections are only partially shown, so those links are marked unverified.

Main entry points: [`Tut-6/trainNN.py`](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-6/trainNN.py) (Training script), [`Tut-4/zynet.v`](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-4/zynet.v) (ZyNet top), [`Tut-9/nnTest.c`](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-9/nnTest.c) (Inference firmware), [`Tut-5/mnistZyNet.py`](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-5/mnistZyNet.py) (MNIST model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["MNIST training"]
  node_trainer["Training script<br/>[trainNN.py]"]
  node_mnist["MNIST loader<br/>[mnist_loader.py]"]
  node_network["Neural network<br/>[network2.py]"]
  node_savedparams["Saved parameters"]
end

subgraph group_generation["Model generation"]
  node_mnistmodel["MNIST model<br/>[mnistZyNet.py]"]
  node_api["ZyNet model API<br/>[zynet.py]"]
  node_utils["Parameter reader<br/>[utils.py]"]
  node_rtlgen["RTL generator<br/>[gen_nn.py]"]
  node_paramgen["Fixed-point converter"]
  node_rtlout["Generated RTL"]
  node_paramfiles["Weight memories"]
end

subgraph group_hardware["FPGA inference"]
  node_top["ZyNet top<br/>[zynet.v]"]
  node_layers["Dense layers<br/>[Layer_1.v]"]
  node_neuron["Neuron compute<br/>[neuron.v]"]
  node_memory[("Weight memory<br/>[Weight_Memory.v]")]
  node_axi["AXI interface<br/>[axi_lite_wrapper.v]"]
  node_winner["Class selector<br/>[maxFinder.v]"]
end

subgraph group_embedded["Embedded runtime"]
  node_inputdata["Digit input<br/>[dataValues.h]"]
  node_firmware["Inference firmware<br/>[nnTest.c]"]
end

node_engineer(("Model developer"))
node_dma["AXI DMA"]
node_fpga["ZyNet accelerator"]

node_engineer -->|"runs training"| node_trainer
node_trainer -->|"loads data"| node_mnist
node_trainer -->|"trains network"| node_network
node_trainer -.->|"saves parameters"| node_savedparams
node_engineer -->|"configures model"| node_mnistmodel
node_mnistmodel -->|"builds model"| node_api
node_mnistmodel -->|"reads parameters"| node_utils
node_api -->|"generates RTL"| node_rtlgen
node_api -->|"converts parameters"| node_paramgen
node_rtlgen -->|"writes design"| node_rtlout
node_paramgen -->|"writes memories"| node_paramfiles
node_top -.->|"instantiates layers"| node_layers
node_layers -.->|"uses neurons"| node_neuron
node_neuron -.->|"reads weights"| node_memory
node_top -.->|"exposes interface"| node_axi
node_top -.->|"selects output"| node_winner
node_firmware -->|"transfers input"| node_inputdata
node_firmware -->|"starts transfer"| node_dma
node_dma -.->|"sends input"| node_fpga
node_firmware -->|"reads result"| node_fpga

click node_trainer "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-6/trainNN.py"
click node_mnist "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-6/mnist_loader.py"
click node_network "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-6/network2.py"
click node_savedparams "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-5/WeigntsAndBiasesReLuNew.txt"
click node_mnistmodel "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-5/mnistZyNet.py"
click node_api "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-5/zynet/zynet.py"
click node_utils "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-5/zynet/utils.py"
click node_rtlgen "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-5/zynet/gen_nn.py"
click node_paramgen "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-5/zynet/genWegitsAndBias.py"
click node_rtlout "https://github.com/vipinkmenon/neuralnetwork/tree/master/Tut-5/src/fpga/rtl"
click node_paramfiles "https://github.com/vipinkmenon/neuralnetwork/tree/master/Tut-5/src/fpga/rtl"
click node_top "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-4/zynet.v"
click node_layers "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-4/Layer_1.v"
click node_neuron "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-4/neuron.v"
click node_memory "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-4/Weight_Memory.v"
click node_axi "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-4/axi_lite_wrapper.v"
click node_winner "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-4/maxFinder.v"
click node_inputdata "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-9/dataValues.h"
click node_firmware "https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-9/nnTest.c"

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_trainer,node_mnist,node_network,node_savedparams toneBlue
class node_mnistmodel,node_api,node_utils,node_rtlgen,node_paramgen,node_rtlout,node_paramfiles toneAmber
class node_top,node_layers,node_neuron,node_memory,node_axi,node_winner toneMint
class node_inputdata,node_firmware toneRose
class node_engineer,node_dma,node_fpga toneIndigo
```

## Components

### MNIST training

- [Training script](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-6/trainNN.py): `Tut-6/trainNN.py`
- [MNIST loader](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-6/mnist_loader.py): `Tut-6/mnist_loader.py`
- [Neural network](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-6/network2.py): `Tut-6/network2.py`
- [Saved parameters](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-5/WeigntsAndBiasesReLuNew.txt): `Tut-5/WeigntsAndBiasesReLuNew.txt`

### Model generation

- [MNIST model](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-5/mnistZyNet.py): `Tut-5/mnistZyNet.py`
- [ZyNet model API](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-5/zynet/zynet.py): `Tut-5/zynet/zynet.py`
- [Parameter reader](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-5/zynet/utils.py): `Tut-5/zynet/utils.py`
- [RTL generator](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-5/zynet/gen_nn.py): `Tut-5/zynet/gen_nn.py`
- [Fixed-point converter](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-5/zynet/genWegitsAndBias.py): `Tut-5/zynet/genWegitsAndBias.py`
- [Generated RTL](https://github.com/vipinkmenon/neuralnetwork/tree/master/Tut-5/src/fpga/rtl): `Tut-5/src/fpga/rtl`
- [Weight memories](https://github.com/vipinkmenon/neuralnetwork/tree/master/Tut-5/src/fpga/rtl): `Tut-5/src/fpga/rtl`

### FPGA inference

- [ZyNet top](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-4/zynet.v): `Tut-4/zynet.v`
- [Dense layers](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-4/Layer_1.v): `Tut-4/Layer_1.v`
- [Neuron compute](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-4/neuron.v): `Tut-4/neuron.v`
- [Weight memory](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-4/Weight_Memory.v): `Tut-4/Weight_Memory.v`
- [AXI interface](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-4/axi_lite_wrapper.v): `Tut-4/axi_lite_wrapper.v`
- [Class selector](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-4/maxFinder.v): `Tut-4/maxFinder.v`

### Embedded runtime

- [Digit input](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-9/dataValues.h): `Tut-9/dataValues.h`
- [Inference firmware](https://github.com/vipinkmenon/neuralnetwork/blob/master/Tut-9/nnTest.c): `Tut-9/nnTest.c`

### Other components

- **Model developer**
- **AXI DMA**
- **ZyNet accelerator**

## Connections

- Model developer → Training script: runs training (evidence: `Tut-6/trainNN.py`)
- Training script → MNIST loader: loads data (evidence: `Tut-6/trainNN.py`)
- Training script → Neural network: trains network (evidence: `Tut-6/trainNN.py`)
- Training script → Saved parameters: saves parameters
- Model developer → MNIST model: configures model (evidence: `Tut-5/mnistZyNet.py`)
- MNIST model → ZyNet model API: builds model (evidence: `Tut-5/mnistZyNet.py`)
- MNIST model → Parameter reader: reads parameters (evidence: `Tut-5/mnistZyNet.py`)
- ZyNet model API → RTL generator: generates RTL (evidence: `Tut-5/zynet/zynet.py`)
- ZyNet model API → Fixed-point converter: converts parameters (evidence: `Tut-5/zynet/zynet.py`)
- RTL generator → Generated RTL: writes design (evidence: `Tut-5/zynet/gen_nn.py`)
- Fixed-point converter → Weight memories: writes memories (evidence: `Tut-5/zynet/genWegitsAndBias.py`)
- ZyNet top → Dense layers: instantiates layers
- Dense layers → Neuron compute: uses neurons
- Neuron compute → Weight memory: reads weights
- ZyNet top → AXI interface: exposes interface
- ZyNet top → Class selector: selects output
- Inference firmware → Digit input: transfers input (evidence: `Tut-9/nnTest.c`)
- Inference firmware → AXI DMA: starts transfer (evidence: `Tut-9/nnTest.c`)
- AXI DMA → ZyNet accelerator: sends input
- Inference firmware → ZyNet accelerator: reads result (evidence: `Tut-9/nnTest.c`)