# hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine architecture

> Architecture diagram of the GitHub repository hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine, 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/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine
- Repository: https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine

## Overview

FANE is an approximate-FP8 neural-network accelerator project with two complementary user workflows: Python users encode tensors, run FANE arithmetic, and evaluate numerical error; hardware users integrate the documented MVM or convolution RTL datapaths. The software path is grounded in sampled Python sources. Hardware relationships are limited to capabilities and module roles stated in the README; unsampled RTL internals are not inferred. The vector generator is included because it is a central indexed module and connects the software model to hardware-oriented reference vectors.

Main entry points: [`sw/dist_sim/fp8.py`](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/sw/dist_sim/fp8.py) (FP8 codec), [`sw/dist_sim/validate.py`](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/sw/dist_sim/validate.py) (Error evaluation), [`hw/fane_opt/sim/generate_vectors.py`](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/sim/generate_vectors.py) (RTL vector generation), [`sw/dist_sim/fane.py`](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/sw/dist_sim/fane.py) (Matrix operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_software["Software model"]
  node_codec["FP8 codec<br/>[fp8.py]"]
  node_arithmetic["FANE arithmetic<br/>[fane.py]"]
  node_matmul["Matrix operations<br/>[fane.py]"]
  node_evaluation["Error evaluation<br/>[validate.py]"]
  node_vectors["RTL vector generation"]
end

subgraph group_mvm["MVM hardware"]
  node_mvm_mac["FP8 MAC pipeline<br/>[fpmac_mm.v]"]
  node_mvm_engine["Matrix engine<br/>[mm.v]"]
  node_mvm_control["MVM control and memory<br/>[mm_top.v]"]
  node_mvm_chip["MVM chip wrapper<br/>[mm_chip.sv]"]
end

subgraph group_convolution["Convolution hardware"]
  node_conv_mac["FP8 MAC pipeline<br/>[fpmac_conv.v]"]
  node_conv_engine["Convolution engine<br/>[conv.v]"]
  node_conv_control["Convolution control<br/>[conv_top.v]"]
  node_conv_chip["Convolution wrapper<br/>[conv_chip.sv]"]
end

subgraph group_rtl_variants["RTL variants"]
  node_paper_mvm["Paper MVM RTL"]
  node_paper_conv["Paper convolution RTL"]
  node_standalone_mac["Standalone FP8 MAC<br/>[fane_mac.v]"]
  node_minimum_blocks["Minimum-unit experiments"]
end

node_user(("Model user"))

node_user -->|"encodes inputs"| node_codec
node_codec -->|"supplies FP8 bits"| node_arithmetic
node_arithmetic -->|"reduces products"| node_matmul
node_user -->|"runs evaluation"| node_evaluation
node_evaluation -->|"quantizes and decodes"| node_codec
node_evaluation -->|"compares results"| node_matmul
node_user -->|"generates vectors"| node_vectors
node_vectors -->|"computes golden outputs"| node_matmul
node_vectors -->|"encodes test data"| node_codec
node_mvm_engine -->|"uses MAC pipeline"| node_mvm_mac
node_mvm_control -->|"integrates engine"| node_mvm_engine
node_mvm_chip -->|"wraps top level"| node_mvm_control
node_conv_engine -->|"uses MAC pipeline"| node_conv_mac
node_conv_control -->|"integrates engine"| node_conv_engine
node_conv_chip -->|"wraps top level"| node_conv_control

click node_codec "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/sw/dist_sim/fp8.py"
click node_arithmetic "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/sw/dist_sim/fane.py"
click node_matmul "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/sw/dist_sim/fane.py"
click node_evaluation "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/sw/dist_sim/validate.py"
click node_vectors "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/sim/generate_vectors.py"
click node_mvm_mac "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/mm/v_opt/fpmac_mm.v"
click node_mvm_engine "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/mm/v_opt/mm.v"
click node_mvm_control "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/mm/v_opt/mm_top.v"
click node_mvm_chip "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/mm/v_opt/mm_chip.sv"
click node_conv_mac "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/conv/v_opt/fpmac_conv.v"
click node_conv_engine "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/conv/v_opt/conv.v"
click node_conv_control "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/conv/v_opt/conv_top.v"
click node_conv_chip "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/conv/v_opt/conv_chip.sv"
click node_paper_mvm "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/tree/main/hw/fane_paper/mm/v_paper"
click node_paper_conv "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/tree/main/hw/fane_paper/conv/v_paper"
click node_standalone_mac "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fp8_mac/src/fane_mac.v"
click node_minimum_blocks "https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/tree/main/hw/minimal_unit"

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_codec,node_arithmetic,node_matmul,node_evaluation,node_vectors,node_user toneBlue
class node_mvm_mac,node_mvm_engine,node_mvm_control,node_mvm_chip toneAmber
class node_conv_mac,node_conv_engine,node_conv_control,node_conv_chip toneMint
class node_paper_mvm,node_paper_conv,node_standalone_mac,node_minimum_blocks toneRose
```

## Components

### Software model

- [FP8 codec](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/sw/dist_sim/fp8.py): `sw/dist_sim/fp8.py`
- [FANE arithmetic](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/sw/dist_sim/fane.py): `sw/dist_sim/fane.py`
- [Matrix operations](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/sw/dist_sim/fane.py): `sw/dist_sim/fane.py`
- [Error evaluation](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/sw/dist_sim/validate.py): `sw/dist_sim/validate.py`
- [RTL vector generation](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/sim/generate_vectors.py): `hw/fane_opt/sim/generate_vectors.py`

### MVM hardware

- [FP8 MAC pipeline](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/mm/v_opt/fpmac_mm.v): `hw/fane_opt/mm/v_opt/fpmac_mm.v`
- [Matrix engine](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/mm/v_opt/mm.v): `hw/fane_opt/mm/v_opt/mm.v`
- [MVM control and memory](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/mm/v_opt/mm_top.v): `hw/fane_opt/mm/v_opt/mm_top.v`
- [MVM chip wrapper](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/mm/v_opt/mm_chip.sv): `hw/fane_opt/mm/v_opt/mm_chip.sv`

### Convolution hardware

- [FP8 MAC pipeline](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/conv/v_opt/fpmac_conv.v): `hw/fane_opt/conv/v_opt/fpmac_conv.v`
- [Convolution engine](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/conv/v_opt/conv.v): `hw/fane_opt/conv/v_opt/conv.v`
- [Convolution control](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/conv/v_opt/conv_top.v): `hw/fane_opt/conv/v_opt/conv_top.v`
- [Convolution wrapper](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fane_opt/conv/v_opt/conv_chip.sv): `hw/fane_opt/conv/v_opt/conv_chip.sv`

### RTL variants

- [Paper MVM RTL](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/tree/main/hw/fane_paper/mm/v_paper): `hw/fane_paper/mm/v_paper`
- [Paper convolution RTL](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/tree/main/hw/fane_paper/conv/v_paper): `hw/fane_paper/conv/v_paper`
- [Standalone FP8 MAC](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/blob/main/hw/fp8_mac/src/fane_mac.v): `hw/fp8_mac/src/fane_mac.v`
- [Minimum-unit experiments](https://github.com/hanbao04/fane-fpga-based-fp8-approximate-neural-network-engine/tree/main/hw/minimal_unit): `hw/minimal_unit`

### Other components

- **Model user**

## Connections

- Model user → FP8 codec: encodes inputs (evidence: `README.md`)
- FP8 codec → FANE arithmetic: supplies FP8 bits (evidence: `sw/dist_sim/fane.py`)
- FANE arithmetic → Matrix operations: reduces products (evidence: `sw/dist_sim/fane.py`)
- Model user → Error evaluation: runs evaluation (evidence: `README.md`)
- Error evaluation → FP8 codec: quantizes and decodes (evidence: `sw/dist_sim/validate.py`)
- Error evaluation → Matrix operations: compares results (evidence: `sw/dist_sim/validate.py`)
- Model user → RTL vector generation: generates vectors (evidence: `README.md`)
- RTL vector generation → Matrix operations: computes golden outputs (evidence: `hw/fane_opt/sim/generate_vectors.py`)
- RTL vector generation → FP8 codec: encodes test data (evidence: `hw/fane_opt/sim/generate_vectors.py`)
- Matrix engine → FP8 MAC pipeline: uses MAC pipeline (evidence: `README.md`)
- MVM control and memory → Matrix engine: integrates engine (evidence: `README.md`)
- MVM chip wrapper → MVM control and memory: wraps top level (evidence: `README.md`)
- Convolution engine → FP8 MAC pipeline: uses MAC pipeline (evidence: `README.md`)
- Convolution control → Convolution engine: integrates engine (evidence: `README.md`)
- Convolution wrapper → Convolution control: wraps top level (evidence: `README.md`)