Contributing to Event-Driven SNN FPGA Accelerator

Thank you for your interest in contributing to this project! This guide will help you get started with contributing to the Event-Driven Spiking Neural Network (SNN) FPGA Accelerator.

Code of Conduct
Getting Started
Development Environment Setup
Project Structure
Contributing Guidelines
Hardware Development
Software Development
Testing Requirements
Documentation Standards
Pull Request Process
Coding Standards
Community

Code of Conduct

This project adheres to a code of conduct that all contributors are expected to follow:

Be respectful: Treat everyone with respect and consideration
Be collaborative: Work together constructively
Be professional: Focus on technical merit and project goals
Be inclusive: Welcome contributors of all backgrounds and experience levels

Getting Started

Prerequisites

Before contributing, ensure you have:

For Software Development:
- Python 3.10 or higher
- PyTorch 2.5.1 or higher
- NumPy, pytest, and other Python dependencies
For Hardware Development:
- Xilinx Vivado 2025.2 or compatible version
- Xilinx Vitis HLS 2025.2 or compatible version
- Icarus Verilog 11.0+ (for open-source simulation)
- PYNQ-Z2 board (for hardware testing)
General Tools:
- Git for version control
- A GitHub account
- Text editor or IDE (VS Code, PyCharm, etc.)

Initial Setup

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/Event-Driven-Spiking-Neural-Network-Accelerator-for-FPGA.git
cd Event-Driven-Spiking-Neural-Network-Accelerator-for-FPGA

Add upstream remote:

git remote add upstream https://github.com/metr0jw/Event-Driven-Spiking-Neural-Network-Accelerator-for-FPGA.git

Run setup script:
```
./setup.sh
```

Development Environment Setup

See the Developer Guide for detailed setup instructions.

Quick Setup

Python Environment

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in development mode
cd software/python
pip install -e .
pip install pytest pytest-cov black flake8 mypy

Hardware Environment

# Source Xilinx tools (Vitis 2025.2+)
source /tools/Xilinx/2025.2/Vivado/settings64.sh
source /tools/Xilinx/2025.2/Vitis/settings64.sh

Note: Vitis 2025.2 uses v++ CLI for HLS. Legacy vitis_hls -f script.tcl is deprecated.

For detailed environment setup, build procedures, and development workflows, refer to the Developer Guide.

Project Structure

Understanding the project structure will help you navigate and contribute effectively:

├── hardware/                    # FPGA implementation
│   ├── hdl/                    # Hardware Description Language
│   │   ├── rtl/                # Synthesizable Verilog-2001/SystemVerilog
│   │   │   ├── common/         # Utilities (FIFO, synchronizers)
│   │   │   ├── core/           # Core group, event router, connectivity table
│   │   │   ├── neurons/        # LIF neuron implementations
│   │   │   ├── synapses/       # Synaptic arrays
│   │   │   ├── router/         # Legacy spike routing logic
│   │   │   ├── layers/         # Conv1D/2D, pooling
│   │   │   ├── learning/       # STDP engine
│   │   │   └── top/            # Top-level modules
│   │   ├── sim/                # Simulation scripts
│   │   └── tb/                 # Testbenches (19 + 2 comprehensive)
│   ├── hls/                    # High-Level Synthesis (C++)
│   │   ├── src/                # HLS source files
│   │   ├── include/            # Headers
│   │   ├── scripts/            # Build automation
│   │   └── test/               # HLS testbenches
│   ├── constraints/            # Timing and pin constraints
│   └── scripts/                # Build scripts (TCL)
│
├── software/python/            # Python software stack
│   ├── snn_fpga_accelerator/   # Main package (19 modules)
│   │   ├── accelerator.py      # FPGA interface
│   │   ├── neuron.py           # HW-accurate core group sim
│   │   ├── hw_accurate_simulator.py # Bit-accurate LIF/STDP/CoreGroup sim
│   │   ├── pytorch_interface.py # PyTorch integration
│   │   ├── spike_encoding.py   # Spike encoders/decoders
│   │   ├── learning.py         # STDP/R-STDP
│   │   ├── pytorch_snn_layers.py # Custom PyTorch layers
│   │   └── ...                 # + 12 more modules
│   └── tests/                  # Test suite (15 test files)
│
├── examples/                   # Usage examples
│   └── pytorch/                # PyTorch training examples
│
└── docs/                       # Documentation

Contributing Guidelines

Types of Contributions

We welcome various types of contributions:

Bug Fixes: Fix issues in existing code
New Features: Add new functionality
Documentation: Improve or add documentation
Tests: Add or improve test coverage
Performance: Optimize existing code
Examples: Add new usage examples

Finding Issues to Work On

Check the GitHub Issues page
Look for issues tagged good first issue or help wanted
Feel free to propose new features by opening an issue first

Before Starting Work

Check for existing work: Search issues and PRs to avoid duplicate effort
Discuss major changes: For significant features, open an issue first

Create a branch: Use a descriptive branch name

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-number-description

Hardware Development

For comprehensive hardware development guidelines, RTL coding standards, HLS best practices, and detailed examples, see the Developer Guide.

Quick Reference

RTL Guidelines:

Use Verilog-2001 for portability
Add ifndef __ICARUS__ guards for SystemVerilog features
Follow naming conventions: snake_case for signals, UPPER_CASE for parameters

HLS Guidelines:

Include appropriate #pragma HLS directives
Write comprehensive testbenches
Test with C simulation and cosimulation

See Developer Guide - Hardware Development for complete details.

Software Development

For comprehensive Python development guidelines, see the Developer Guide.

Coding Style

Follow PEP 8 and use type hints for all functions. See Developer Guide - Python Development for complete guidelines and examples.

Quick Reference

Use type hints for function signatures
Write Google-style docstrings
Provide clear error messages
Follow naming conventions

Example:

def encode_spikes(
    data: np.ndarray,
    max_rate: float = 100.0
) -> np.ndarray:
    """Encode data as spike trains.
    
    Args:
        data: Input data normalized to [0, 1]
        max_rate: Maximum firing rate in Hz
        
    Returns:
        Spike trains array
    """
    pass

Testing Requirements

Python Tests

All Python code must have tests using pytest:

# test_spike_encoding.py
import pytest
import numpy as np
from snn_fpga_accelerator.spike_encoding import PoissonEncoder

def test_poisson_encoder_reproducibility():
    """Test that encoder produces reproducible results with seed."""
    encoder1 = PoissonEncoder(num_neurons=10, duration=0.1, seed=42)
    encoder2 = PoissonEncoder(num_neurons=10, duration=0.1, seed=42)
    
    data = np.random.rand(10)
    spikes1 = encoder1.encode(data)
    spikes2 = encoder2.encode(data)
    
    assert np.array_equal(spikes1, spikes2), "Results not reproducible"

def test_poisson_encoder_spike_rate():
    """Test that encoder respects max_rate."""
    encoder = PoissonEncoder(num_neurons=10, duration=1.0, max_rate=100.0)
    data = np.ones(10)  # Maximum input
    spikes = encoder.encode(data)
    
    spike_rate = np.sum(spikes, axis=1).mean()
    assert spike_rate <= 100.0, f"Spike rate {spike_rate} exceeds max_rate"

@pytest.mark.parametrize("num_neurons", [1, 10, 100])
def test_poisson_encoder_shapes(num_neurons):
    """Test encoder output shapes for various configurations."""
    encoder = PoissonEncoder(num_neurons=num_neurons, duration=0.1)
    data = np.random.rand(num_neurons)
    spikes = encoder.encode(data)
    
    assert spikes.shape[0] == num_neurons

Running Tests

# Run all tests
pytest software/python/tests -v

# Run with coverage
pytest software/python/tests --cov=snn_fpga_accelerator --cov-report=html

# Run specific test file
pytest software/python/tests/test_spike_encoding.py

# Run tests matching pattern
pytest -k "encoder"

Hardware Tests

# Run RTL simulations
cd hardware/hdl/sim
./simple_sim.sh tb_simple_lif

# Run HLS tests
cd hardware/hls/test
./run_tests.sh

Documentation Standards

Code Comments

What, not how: Explain why, not what the code does
Document assumptions: Especially for hardware constraints
Update with changes: Keep comments in sync with code

# Good comment
# Use exponential moving average to smooth reward signal
# This prevents weight oscillations during RL training
reward_ema = 0.9 * reward_ema + 0.1 * current_reward

# Bad comment
# Multiply reward_ema by 0.9 and add 0.1 times current_reward

Markdown Documentation

Use clear headings and structure
Include code examples
Add links to related documentation
Keep language simple and concise

API Documentation

All public APIs must be documented:

class SNNAccelerator:
    """FPGA-based spiking neural network accelerator.
    
    This class provides a high-level interface for configuring and
    running SNN inference on FPGA hardware.
    
    Attributes:
        num_neurons: Number of neurons in the network
        bitstream_path: Path to FPGA bitstream file
        is_configured: Whether the network is configured
        
    Example:
        >>> accelerator = SNNAccelerator(bitstream_path="snn.bit")
        >>> accelerator.configure_network(network_config)
        >>> output = accelerator.infer(input_spikes)
    """
    pass

Pull Request Process

1. Prepare Your Changes

# Ensure your branch is up to date
git fetch upstream
git rebase upstream/main

# Run tests
pytest software/python/tests
cd hardware/hdl/sim && ./simple_sim.sh tb_simple_lif

# Format code
black software/python/snn_fpga_accelerator
black software/python/tests

# Check style
flake8 software/python/snn_fpga_accelerator

2. Commit Your Changes

Use clear, descriptive commit messages:

# Good commit messages
git commit -m "Add temporal spike encoder for rate-based encoding"
git commit -m "Fix width mismatch in spike router neuron ID signals"
git commit -m "Update README with hardware testing instructions"

# Bad commit messages
git commit -m "fix bug"
git commit -m "updates"
git commit -m "WIP"

Follow this format for detailed commits:

Short summary (50 chars or less)

More detailed explanation if needed. Wrap at 72 characters.
Explain the problem this commit solves and why this approach
was chosen.

- Bullet points are okay
- Use present tense: "Add feature" not "Added feature"

Fixes #123

3. Push and Create PR

# Push to your fork
git push origin feature/your-feature-name

# Create PR on GitHub
# Use the PR template and fill in all sections

4. PR Guidelines

Your PR should include:

Clear title: Summarize the change
Description: Explain what and why
Tests: Include tests for new functionality
Documentation: Update docs as needed
Changelog: Note any breaking changes

PR Template:

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Testing
- [ ] All existing tests pass
- [ ] New tests added for new functionality
- [ ] Hardware simulation tested (if applicable)

## Documentation
- [ ] README updated
- [ ] API documentation updated
- [ ] Code comments added/updated

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] No compiler warnings
- [ ] Changes are backwards compatible (or breaking changes noted)

5. Code Review Process

Be responsive to feedback
Make requested changes promptly
Discuss concerns constructively
Update PR based on reviews

Coding Standards

General Principles

Readability: Code is read more than written
Simplicity: Prefer simple solutions
Modularity: Keep functions/modules focused
DRY: Don't Repeat Yourself
Testing: Test your code thoroughly

Performance Considerations

Profile first: Don't optimize prematurely
Document tradeoffs: Explain performance-related decisions
Benchmark: Provide measurements for optimizations

Version Control

Small commits: One logical change per commit
Meaningful messages: Explain what and why
Clean history: Rebase/squash when appropriate

Community

Communication Channels

GitHub Issues: Bug reports and feature requests
GitHub Discussions: General questions and ideas
Pull Requests: Code review and collaboration
Email: jwlee@linux.com

Getting Help

Check existing documentation and examples
Search GitHub issues for similar problems
Ask questions in GitHub Discussions
Be specific about your problem and what you've tried

Acknowledgments

Contributors will be acknowledged in:

Repository contributors page
Release notes for significant contributions
README.md (for major features)

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to the Event-Driven SNN FPGA Accelerator project! Your contributions help make neuromorphic computing more accessible to researchers and developers.

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to Event-Driven SNN FPGA Accelerator

Table of Contents

Code of Conduct

Getting Started

Prerequisites

Initial Setup

Development Environment Setup

Quick Setup

Python Environment

Hardware Environment

Project Structure

Contributing Guidelines

Types of Contributions

Finding Issues to Work On

Before Starting Work

Hardware Development

Quick Reference

Software Development

Coding Style

Quick Reference

Testing Requirements

Python Tests

Running Tests

Hardware Tests

Documentation Standards

Code Comments

Markdown Documentation

API Documentation

Pull Request Process

1. Prepare Your Changes

2. Commit Your Changes

3. Push and Create PR

4. PR Guidelines

5. Code Review Process

Coding Standards

General Principles

Performance Considerations

Version Control

Community

Communication Channels

Getting Help

Acknowledgments

License