Skip to content

Contributing

Thank you for your interest in contributing to QPyth! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

Please be respectful and constructive in all interactions. We aim to maintain a welcoming and inclusive community.

Getting Started

Prerequisites

  • Python 3.10 or higher
  • Git
  • GitHub account

Development Setup

  1. Fork the repository on GitHub
  2. Clone your fork:
git clone https://github.com/your-username/QPyth.git
cd QPyth
  1. Create a virtual environment:
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Install in development mode:
pip install -e .[dev,physical,web,hardware]
  1. Install pre-commit hooks:
pre-commit install

Development Workflow

Branch Strategy

  • main - Stable production code
  • feature/* - New features
  • bugfix/* - Bug fixes
  • docs/* - Documentation updates

Creating a Branch

git checkout -b feature/your-feature-name

Making Changes

  1. Make your changes
  2. Run tests: pytest
  3. Run linter: ruff check .
  4. Format code: ruff format .
  5. Commit changes: git commit -m "Your commit message"

Commit Messages

Follow conventional commits format:

type(scope): description

[optional body]

[optional footer]

Types: - feat - New feature - fix - Bug fix - docs - Documentation changes - style - Code style changes (formatting) - refactor - Code refactoring - test - Test changes - chore - Maintenance tasks

Example: 

feat(vqe): add support for LiH molecule

- Add LiH molecule configuration
- Update VQE core to handle multi-electron systems
- Add tests for LiH VQE

Closes #123

Pull Requests

  1. Push your branch:
git push origin feature/your-feature-name
  1. Create a pull request on GitHub
  2. Fill out the PR template
  3. Wait for review

Testing

Running Tests

Run all tests:

pytest

Run specific test file:

pytest tests/test_bloch_ascii.py

Run with coverage:

pytest --cov=quantumpytho --cov-report=html

Run specific test:

pytest tests/test_bloch_ascii.py::test_one_qubit_from_angles

Writing Tests

Follow these guidelines:

  1. Use descriptive test names
  2. Test both success and failure cases
  3. Use fixtures for common setup
  4. Mock external dependencies

Example:

import pytest
from quantumpytho.modules.bloch_ascii import run_bloch_ascii

def test_run_bloch_ascii_zero_state(capsys):
    """Test Bloch visualization for |0⟩ state."""
    run_bloch_ascii(theta=0, phi=0)
    captured = capsys.readouterr()
    assert "|0> state:" in captured.out
    assert "100.00%" in captured.out

Code Style

Formatting

We use Ruff for code formatting:

ruff format .

Linting

Check for issues:

ruff check .

Auto-fix issues:

ruff check --fix .

Style Guidelines

  • Use type hints for function signatures
  • Write docstrings for all public functions and classes
  • Keep functions focused and small
  • Use descriptive variable names
  • Follow PEP 8 guidelines

Documentation

Docstrings

Use Google-style docstrings:

def run_bloch_ascii(theta: float, phi: float, shots: int = 1024) -> None:
    """Visualize quantum state on Bloch sphere.

    Args:
        theta: Polar angle in radians [0, π].
        phi: Azimuthal angle in radians [0, 2π].
        shots: Number of measurement shots.

    Returns:
        None (prints to stdout)
    """
    pass

Documentation Updates

  • Update relevant documentation when adding features
  • Add examples for new functionality
  • Keep API reference up to date
  • Update CHANGELOG.md for user-facing changes

Project Structure

QPyth/
├── quantumpytho/          # Main package
│   ├── modules/          # Quantum modules
│   ├── data/             # Calibration data
│   ├── config.py         # Configuration
│   ├── engine.py         # Core engine
│   └── menu.py           # CLI interface
├── tests/                # Test suite
├── docs/                 # Documentation
├── web/                  # Web UI
├── notebooks/            # Jupyter notebooks
└── pyproject.toml        # Project configuration

Adding Features

New Module

  1. Create module in quantumpytho/modules/
  2. Add tests in tests/
  3. Update documentation
  4. Add to CLI menu if applicable
  5. Add web UI endpoint if applicable

New Molecule

  1. Add configuration in quantumpytho/modules/vqe_molecules.py
  2. Add reference energy
  3. Add tests
  4. Update documentation

New Noise Profile

  1. Add calibration CSV to quantumpytho/data/backends/
  2. Update noise builder
  3. Add tests
  4. Update documentation

Issue Reporting

Bug Reports

Include: - Python version - QPyth version - Steps to reproduce - Expected behavior - Actual behavior - Error messages

Feature Requests

Include: - Use case - Proposed solution - Alternatives considered

Questions

  • Use GitHub Discussions for questions
  • Check existing issues first
  • Be specific and provide context

Release Process

Releases are managed by maintainers:

  1. Update version in pyproject.toml
  2. Update CHANGELOG.md
  3. Create release branch
  4. Tag release
  5. Build and publish to PyPI
  6. Create GitHub release

License

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

Getting Help

  • GitHub Issues: https://github.com/quantumdynamics927-dotcom/QPyth/issues
  • GitHub Discussions: https://github.com/quantumdynamics927-dotcom/QPyth/discussions
  • Email: quantumdynamics927@gmail.com

Thank you for contributing to QPyth!