README.md

Simulation and Verification

This directory contains testbenches, test scripts, and simulation infrastructure for verifying VHDL implementations of neural network components.

Table of Contents

• Overview
• Directory Structure
• Testbench Architecture
• Running Simulations
• Validation Workflow
• Related Documentation

Overview

The simulation environment provides comprehensive verification capabilities for all neural network components through:

Key features:

• Automated stimuli generation via Python scripts
• Cycle-accurate VHDL testbenches for all components
• ModelSim/Questa simulation support
• Reference model comparison (C/Python)
• Result validation and output capture

Verification coverage:

• Dense and convolutional layer testbenches
• Neuron and processing unit testbenches
• Memory and buffer testbenches
• Full network integration testbenches

Directory Structure

simulation/
├── README.md           # This file
│
├── Testbenches (1D Components):
├── *_tb.vhd           # Component testbenches
├── layer_tb.vhd       # Dense layer testbench
├── conv_layer_tb.vhd  # Convolutional layer testbench
├── neuron_tb.vhd      # Neuron testbench
├── threshold_tb.vhd   # Threshold testbench
├── argmax_tb.vhd      # Argmax testbench
│
├── Testbenches (Network):
├── network_tb_test.vhd      # Network testbench
├── network_pipe_tb.vhd      # Pipelined network testbench
├── network_axi_tb.vhd       # AXI network testbench
│
├── Test Scripts:
├── scripts/           # Python stimuli generation and DO files
│   ├── README.md     # Detailed script documentation
│   ├── *_test.py     # Python test generators
│   ├── *.do          # ModelSim/Questa scripts
│   └── wave_*.do     # Waveform configuration
│
├── Test Data & Results:
├── data/             # Test data and simulation results
│   ├── param*.json   # Weights and biases from Keras
│   ├── out.json      # C/Python model reference output
│   └── vhdl_out.csv  # VHDL simulation output
│
└── Reference Model:
    └── model/        # C reference implementation

Testbench Architecture

All testbenches follow a consistent structure for predictable verification workflows.

Standard Testbench Pattern

1. Stimuli Generation (Python):

   • Each DUT port is represented as a Python list
   • Lists are constructed using comprehensions and loops
   • Values are formatted into .dat files for VHDL consumption

2. Data File Format:

   • Each line represents one simulation cycle
   • Columns correspond to DUT ports (inputs, outputs)
   • Space-separated values for easy parsing

3. VHDL Testbench:

   • Reads .dat file during simulation
   • Applies stimuli to DUT ports
   • Captures and validates outputs
   • Reports mismatches or errors

Example Data Flow

Python Script                  DAT File              VHDL Testbench
-------------                  --------              --------------
d = [d1, d2, d3]              d1 w1 o1              read file
w = [w1, w2, w3]      -->     d2 w2 o2      -->     apply stimuli
o = [o1, o2, o3]              d3 w3 o3              verify outputs

For detailed test script structure, see scripts/README.md.

Naming Conventions

Testbench files: <component>_tb.vhd Test scripts: <component>_test.py Simulation scripts: sim_<component>.do Waveform configs: wave_<component>.do

Running Simulations

Prerequisites

• ModelSim or Questa installed and in PATH
• VHDL source files compiled (see ../source/README.md)
• Generated ROMs present in source/ directory

Running a Component Simulation

Using DO files (recommended):

cd simulation/scripts

# In ModelSim/Questa console:
do sim_neuron.do
do sim_layer.do
do sim_conv_layer.do

Manual compilation:

# Compile sources
vcom ../source/nn_pkg.vhd
vcom ../source/neuron.vhd
vcom neuron_tb.vhd

# Run simulation
vsim -c neuron_tb -do "run -all; quit"

Running Network Simulations

cd simulation/scripts

# Generate stimuli first (if needed)
python network_test.py

# Run network simulation
do sim_qonnxtest.do

Viewing Waveforms

DO scripts automatically load waveform configurations. For custom views:

# In ModelSim/Questa GUI:
do sim_component.do
do wave_component.do  # Load specific waveform config

Tip: If waveforms are cluttered, edit wave_*.do files to comment out unnecessary signals.

Validation Workflow

Step-by-Step Verification

1. Generate test stimuli:

   # See scripts/README.md for details
   python scripts/component_test.py

2. Run VHDL simulation:

   cd scripts
   do sim_component.do

3. Compare results:

   • Check console output for mismatches
   • Compare data/vhdl_out.csv with data/out.json
   • Review waveforms for timing issues

4. Iterate:

   • Fix identified issues in VHDL source
   • Regenerate if parameters changed
   • Re-run simulation

Validation Metrics

Accuracy validation:

• Bit-accurate comparison with reference model
• Statistical analysis for classification networks
• Error rate reporting

Performance validation:

• Cycle count measurement
• Throughput calculation
• Latency analysis

Related Documentation

Detailed test information:

• scripts/README.md - Test script structure and stimuli generation

Component specifications:

• ../source/README.md - VHDL layer architectures and delays

Project overview:

• ../README.md - Quick start and complete workflow examples