A comprehensive Python-based digital circuit verification and simulation framework designed for hardware engineers and verification specialists.
VeriFlow provides a unified, Python-native environment for digital circuit simulation, verification, and analysis. It bridges the gap between hardware description languages and modern software development practices, offering type-safe bit vector operations, multi-simulator support, and advanced signal processing metrics.
- Icarus Verilog - Open-source Verilog simulator
- ModelSim/QuestaSim - Industry-standard simulation
- Synopsys VCS - High-performance commercial simulator
- Xilinx Vivado(developing) - FPGA-focused simulation environment
- VerilogBits class with hardware-accurate behavior
- Verilog-style
[MSB:LSB]indexing and slicing - Type-safe operations preventing common verification errors
- Seamless integration with Python's numeric ecosystem
- MRED (Maximum Relative Error Distance)
- NMED (Normalized Mean Error Distance)
- SNR (Signal-to-Noise Ratio)
- PSNR (Peak Signal-to-Noise Ratio)
- Enhanced data matching with mismatch analysis
- Support for Verilog
$readmemhand$readmembformats - Type-safe memory file I/O operations
- Integration with VerilogBits for consistent data handling
- SimulationTask runner with pre/post-simulation hooks
- Unified logging system with multiple output formats
- Cross-platform path management and project organization
- Comprehensive error handling and reporting
- Python 3.8 or higher
- NumPy >= 1.20.0
- bitstring >= 3.1.0
git clone https://github.com/Liyue-Cheng/Veriflow.git
cd Veriflow
pip install -e .pip install numpy>=1.20.0 bitstring>=3.1.0The easiest way to get started with VeriFlow is to run the provided demo projects:
# Navigate to the demo project directory
cd framework/demo-projects/counter
# Run the simulation script
python scripts/run_counter_test.py
# Or run the minimal example
cd ../minimal
python scripts/simulation.pyThese examples demonstrate how to use VeriFlow for Verilog simulation, including automated compilation, execution, and waveform generation.
VeriFlow uses marker files to automatically detect project and framework roots. Understanding the project structure is essential for organizing your Verilog projects effectively.
The VeriFlow framework follows this structure:
your-veriflow-installation/
├── .veriflow-root # Framework root marker file
├── veriflow/ # Core VeriFlow modules
├── framework/
│ ├── demo-projects/ # Example projects
│ └── utils/ # Utility tools (iverilog, gtkwave, etc.)
└── projects/ # Your custom projects go here
Each VeriFlow project should follow this standard structure:
your-project/
├── .veriflow-project # Project root marker file
├── rtl/ # RTL source files (.v, .sv)
├── tb/ # Testbench files
├── sim_outputs/ # Simulation outputs and waveforms
├── scripts/ # Simulation scripts
├── data/ # Test data files
├── matlab/ # MATLAB analysis scripts
└── python/ # Python analysis scripts
You can create a new project structure programmatically:
from veriflow.path_tools import PathManager
# Create path manager
pm = PathManager()
# Create a new project with standard structure
success = pm.create_project_structure("my_new_project")
if success:
print("Project created successfully!")Or manually create the structure:
# Navigate to the projects directory
cd projects/
# Create your project directory
mkdir my_new_project
cd my_new_project
# Create the marker file
echo "# VeriFlow Project: my_new_project" > .veriflow-project
# Create standard directories
mkdir rtl tb sim_outputs scripts data matlab pythonVeriFlow automatically finds framework and project roots using the marker files:
from veriflow.path_tools import find_framework_root, find_project_root, PathManager
# Find roots automatically
framework_root = find_framework_root()
project_root = find_project_root()
# Use PathManager for advanced path operations
pm = PathManager()
print(f"Framework root: {pm.framework_root}")
print(f"Project root: {pm.project_root}")
# Get standard paths
paths = pm.get_standard_paths()
print(f"RTL directory: {paths['project_rtl']}")
print(f"Testbench directory: {paths['project_tb']}")from veriflow import VerilogBits
# Create bit vectors
a = VerilogBits('0b10101010') # 8-bit binary
b = VerilogBits(0xFF, 8) # 8-bit from integer
c = VerilogBits('0xA5') # Hex format
# Verilog-style indexing and slicing
msb = a[7] # Get MSB (returns VerilogBits)
slice_val = a[7:4] # Get bits [7:4] (returns VerilogBits)
# Concatenation (+ operator is disabled for safety)
result = VerilogBits.concat(a, b) # Explicit concatenation
replicated = a.replicate(3) # Replicate 3 times: {3{a}}
# Convert to different formats
print(f"Binary: {a.bin}") # Binary string
print(f"Unsigned: {a.uint}") # Unsigned integer value
print(f"Signed: {a.sint}") # Signed integer value (2's complement)import numpy as np
from veriflow import MetricsCalculator, calculate_snr
# Create test data
reference = np.array([1.0, 2.0, 3.0, 4.0])
test_data = np.array([1.1, 1.9, 3.1, 3.9])
# Calculate metrics
calc = MetricsCalculator()
mred = calc.calculate_mred(reference, test_data)
snr = calculate_snr(reference, test_data)
print(f"MRED: {mred:.6f}")
print(f"SNR: {snr:.2f} dB")from veriflow import MemTools, VerilogBits
# Read hex memory file
mem_tools = MemTools()
data = mem_tools.read_mem_file('memory.hex', word_width=32, is_hex=True)
# Each element is a VerilogBits object
for i, word in enumerate(data):
print(f"Address {i:04x}: {word.hex}")
# Write memory file
output_data = [VerilogBits(i * 2, 32) for i in range(256)]
mem_tools.write_mem_file('output.hex', output_data, is_hex=True)VeriFlow/
├── veriflow/ # Core framework
│ ├── sim/ # Simulator interfaces
│ │ ├── run_sim_iverilog.py # Icarus Verilog support
│ │ ├── run_sim_modelsim.py # ModelSim support
│ │ ├── run_sim_vcs.py # VCS support
│ │ └── run_sim_vivado.py # Vivado support
│ ├── task_runner.py # Simulation task management
│ ├── verilog_bits.py # Strongly-typed bit vectors
│ ├── metrics.py # Signal processing metrics
│ ├── mem_tools.py # Memory file utilities
│ ├── path_tools.py # Cross-platform path handling
│ └── verilogger.py # Unified logging system
├── framework/ # Demo projects and utilities
│ ├── demo-projects/ # Example projects
│ └── utils/ # Bundled EDA tools
└── tests/ # Comprehensive test suite
The framework includes complete demo projects showcasing different features:
cd framework/demo-projects/counter
python scripts/run_counter_test.pyThis demonstrates:
- Multi-simulator support (Icarus Verilog, ModelSim)
- Automated waveform generation
- Comprehensive logging and reporting
cd framework/demo-projects/minimal
python scripts/simulation.pyA streamlined example perfect for getting started with VeriFlow.
def my_pre_sim(task):
"""Custom setup before simulation"""
logger.info("Setting up test environment...")
# Custom initialization code
def my_post_sim(task):
"""Custom analysis after simulation"""
# Parse results, generate reports
task.passed = check_simulation_results()
task.pre_sim_handler = my_pre_sim
task.post_sim_handler = my_post_simtask.sim_config = {
'simulator': 'iverilog',
'defines': {
'DEBUG_MODE': None, # Simple define
'CLK_FREQ': '100000000', # Define with value
'DATA_WIDTH': '32'
}
}# Windows
tool_paths = {
'iverilog': r'C:\iverilog\bin\iverilog.exe',
'vvp': r'C:\iverilog\bin\vvp.exe'
}
# Linux/Mac
tool_paths = {
'iverilog': '/usr/bin/iverilog',
'vvp': '/usr/bin/vvp'
}
task.sim_config['tool_paths'] = tool_pathsVeriFlow includes a comprehensive test suite:
# Run all tests
python -m pytest veriflow/internal_test/
# Run specific test categories
python -m pytest veriflow/internal_test/test_verilog_bits.py
python -m pytest veriflow/internal_test/test_metrics.py
python -m pytest veriflow/internal_test/test_mem_tools.pyWe welcome contributions! Please see our contributing guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
git clone https://github.com/Liyue-Cheng/Veriflow.git
cd Veriflow
pip install -e ".[dev]"
pre-commit installThis project is licensed under the MIT License - see the LICENSE file for details.
- Built on the excellent bitstring library
- Inspired by industry-standard EDA workflows
- Designed for the hardware verification community
- 📧 Email: liyue_cheng@163.com
- 🐛 Issues: GitHub Issues
- 📖 Documentation: Coming soon
- SystemVerilog support
- UVM integration
- Waveform analysis tools
- Cloud simulation support
- GUI interface
- Formal verification integration
VeriFlow - Bridging Hardware and Software Verification 🚀