Contributing to TQC¶

We welcome contributions to the Topological Quantum Compiler! This guide will help you get started with contributing to the project.

Development Setup¶

Prerequisites¶

Python 3.10 or higher
Poetry for dependency management
Git for version control

Setting up the Development Environment¶

Fork and Clone

Fork the repository on GitHub and clone your fork:

git clone https://github.com/yourusername/topological-quantum-compiler.git
cd topological-quantum-compiler

Install Dependencies

Use Poetry to install all dependencies including development tools:

poetry install

Setup Pre-commit Hooks

Install pre-commit hooks for code quality:

poetry run pre-commit install

Verify Installation

Run the test suite to make sure everything works:

poetry run pytest

Development Workflow¶

Branching Strategy¶

We use a Git Flow-inspired branching strategy:

main - Production-ready code
develop - Integration branch for features
feature/feature-name - Feature development
bugfix/issue-description - Bug fixes
hotfix/critical-fix - Critical production fixes

Creating a Feature¶

Create Feature Branch

git checkout develop
git pull origin develop
git checkout -b feature/my-new-feature

Make Changes

Write your code following our coding standards (see below).

Run Tests

Ensure all tests pass and coverage is maintained:

poetry run pytest --cov=src/tqc
poetry run mypy src/tqc

Commit Changes

Use conventional commit messages:

git add .
git commit -m "feat: add support for SU(2)_k anyons"

Push and Create PR

git push origin feature/my-new-feature

Then create a Pull Request on GitHub.

Coding Standards¶

Code Style¶

We use several tools to maintain code quality:

Black for code formatting
isort for import sorting
flake8 for linting
mypy for type checking

All of these run automatically with pre-commit hooks.

Type Hints¶

All public functions and methods must have type hints:

def compile_circuit(circuit: QuantumCircuit, 
                   anyon_type: AnyonType) -> CompilationResult:
    """Compile quantum circuit to braids.

    Args:
        circuit: Input quantum circuit
        anyon_type: Type of anyons to use

    Returns:
        Compilation result with braid program
    """

Documentation¶

Use Google-style docstrings:

class NewAnyonType(AnyonType):
    """A new type of anyons with special properties.

    This class implements anyons that have unique braiding
    characteristics useful for specific applications.

    Attributes:
        special_property: Description of special property

    Example:
        >>> anyons = NewAnyonType(parameter=0.5)
        >>> labels = anyons.get_labels()
        >>> print(labels)
        ['I', 'a', 'b']
    """

Testing¶

Write tests for all new functionality
Aim for >80% code coverage
Use descriptive test names
Include both unit and integration tests

def test_new_anyon_fusion_rules():
    """Test that new anyon fusion rules are correct."""
    anyons = NewAnyonType()
    result = anyons.fusion_rules("a", "b")

    assert "I" in result
    assert result["I"] == pytest.approx(1.0)

Types of Contributions¶

Bug Reports¶

When reporting bugs, please include:

Clear description of the problem
Steps to reproduce
Expected vs actual behavior
System information (OS, Python version, TQC version)
Minimal code example if applicable

Feature Requests¶

For new features:

Describe the motivation and use case
Provide examples of how it would be used
Consider implementation complexity
Be open to discussion about design

Code Contributions¶

We welcome:

New anyon types - Implement additional anyonic systems
Optimization algorithms - Improve braid optimization
Simulation enhancements - Better performance or accuracy
Visualization improvements - Enhanced braid diagrams
Documentation - Examples, tutorials, API docs
Bug fixes - Any size, small fixes are valuable too

Project Structure¶

Understanding the codebase structure helps with contributions:

src/tqc/
├── __init__.py          # Public API exports
├── _version.py          # Version information  
├── anyons.py           # Anyon type implementations
├── braids.py           # Braid group operations
├── compiler.py         # Main compilation engine
├── simulation.py       # Anyonic simulation
├── optimization.py     # Braid optimization algorithms
└── cli.py             # Command-line interface

tests/
├── test_core.py        # Core functionality tests
└── test_advanced.py    # Advanced feature tests

docs/
├── mkdocs.yml         # Documentation configuration
├── index.md           # Homepage
├── installation.md    # Installation instructions
├── quickstart.md      # Quick start guide
├── api.md            # API reference
└── tutorials/         # Tutorial guides

Adding New Anyon Types¶

To add a new anyon type:

Create the Class

Inherit from AnyonType and implement required methods:

class MyAnyons(AnyonType):
    def __init__(self):
        super().__init__("MyAnyons", quantum_dimension=2.0)

    def get_labels(self) -> List[str]:
        return ["I", "a", "b"]

    def fusion_rules(self, a: str, b: str) -> Dict[str, complex]:
        # Implement fusion rules
        pass

    def f_matrix(self, a: str, b: str, c: str, d: str) -> np.ndarray:
        # Implement F-matrices
        pass

    def r_matrix(self, a: str, b: str) -> complex:
        # Implement R-matrices  
        pass

Add to Factory Function

Update get_anyon_type() in anyons.py:

def get_anyon_type(name: str) -> AnyonType:
    name_lower = name.lower()
    if name_lower == "myanyons":
        return MyAnyons()
    # ... existing types

Write Tests

Add comprehensive tests for your anyon type:

def test_my_anyons_fusion():
    anyons = MyAnyons()
    # Test fusion rules, F-matrices, R-matrices

Update Documentation

Add your anyon type to the documentation and examples.

Testing Guidelines¶

Running Tests¶

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=src/tqc --cov-report=html

# Run specific test file
poetry run pytest tests/test_core.py

# Run specific test
poetry run pytest tests/test_core.py::TestAnyons::test_fibonacci_fusion_rules

Test Categories¶

Unit tests - Test individual functions/methods
Integration tests - Test component interactions
Property tests - Test mathematical properties hold
Performance tests - Test scaling and performance

Test Fixtures¶

Use pytest fixtures for reusable test data:

@pytest.fixture
def bell_circuit():
    """Bell state circuit fixture."""
    qc = QuantumCircuit(2)
    qc.h(0)
    qc.cx(0, 1)
    return qc

Documentation¶

Building Documentation¶

# Serve documentation locally
poetry run mkdocs serve

# Build documentation
poetry run mkdocs build

Documentation Types¶

API Reference - Auto-generated from docstrings
Tutorials - Step-by-step guides
How-to Guides - Solution-oriented documentation
Explanations - Theory and background

Writing Good Documentation¶

Use clear, concise language
Include code examples
Test all code examples
Use consistent formatting
Link between related concepts

Release Process¶

Releases are managed by maintainers, but understanding the process helps:

Version Bump - Update version in _version.py
Changelog - Update CHANGELOG.md with new features/fixes
Tag Release - Create git tag with version
CI Pipeline - Automated tests and PyPI upload
Documentation - Deploy updated docs

Community Guidelines¶

Code of Conduct¶

Be respectful and inclusive
Focus on what's best for the community
Show empathy towards other community members
Give constructive feedback
Accept constructive criticism gracefully

Communication¶

GitHub Issues - Bug reports and feature requests
GitHub Discussions - General questions and community chat
Pull Requests - Code review and collaboration
Documentation - Clear communication through docs

Getting Help¶

If you need help with contributing:

Check existing documentation and examples
Search GitHub Issues for similar questions
Ask in GitHub Discussions
Reach out to maintainers

Recognition¶

All contributors are recognized in:

CONTRIBUTORS.md file
Release notes for their contributions
GitHub contributor statistics

Thank you for contributing to TQC and advancing topological quantum computing! 🎉