Skip to main content

Contributing to QCOS

Thank you for your interest in contributing to QCOS! This document provides guidelines and information for contributors.

Code of Conduct​

By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.

Getting Started​

Development Setup​

  1. Fork and clone the repository:
git clone https://github.com/YOUR_USERNAME/softqcos.git
cd softqcos
  1. Create a virtual environment:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install development dependencies:
pip install -e ".[dev,test]"
  1. Install pre-commit hooks:
pre-commit install

Running Tests​

# Run all tests
pytest

# Run with coverage
pytest --cov=softqcos--cov-report=html

# Run specific test file
pytest softqcos/tests/test_optimizer.py

# Run tests matching a pattern
pytest -k "test_ghz"

Code Quality​

We use several tools to maintain code quality:

# Linting
ruff check softqcos/

# Formatting
black softqcos/
isort softqcos/

# Type checking
mypy softqcos/

# All checks (via pre-commit)
pre-commit run --all-files

How to Contribute​

Reporting Bugs​

  1. Check if the bug has already been reported in Issues
  2. If not, create a new issue with:
    • Clear title and description
    • Steps to reproduce
    • Expected vs actual behavior
    • Environment details (OS, Python version, QCOS version)
    • Code samples if applicable

Suggesting Features​

  1. Check existing issues and discussions
  2. Create a new issue with:
    • Clear description of the feature
    • Use cases and motivation
    • Potential implementation approach (optional)

Pull Requests​

  1. Create a branch:
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

  1. Make your changes:

    • Follow the code style (enforced by ruff, black, isort)
    • Add tests for new functionality
    • Update documentation as needed

  2. Commit your changes:

git add .
git commit -m "feat: add new feature X"

We follow Conventional Commits:

PrefixDescription
feat:New feature
fix:Bug fix
docs:Documentation only
style:Formatting, no code change
refactor:Code refactoring
test:Adding tests
chore:Maintenance tasks
  1. Push and create PR:
git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Code Style Guide​

Python Style​

  • Follow PEP 8 (enforced by ruff)
  • Use type hints for all public APIs
  • Maximum line length: 100 characters
  • Use descriptive variable names

Documentation Style​

  • Use Google-style docstrings
  • Include examples in docstrings for complex functions
  • Keep README and docs in sync

Example docstring:

def optimize_ghz(
    self,
    max_iters: int = 100,
    neighbors: int = 8,
    callback: Callable | None = None,
) -> OptimizationResult:
    """Optimize circuit for GHZ state preparation.

    Uses first-improvement local search with correlation-based
    cost function to find optimal gate parameters.

    Args:
        max_iters: Maximum number of optimization iterations.
        neighbors: Number of neighbors to evaluate per iteration.
        callback: Optional callback(iteration, cost, fidelity, params)
            called after each iteration.

    Returns:
        OptimizationResult containing fidelity, cost, and parameters.

    Example:
        >>> backend = AerBackend(num_qubits=10)
        >>> opt = Optimizer(backend, num_qubits=10)
        >>> result = opt.optimize_ghz(max_iters=100)
        >>> print(f"Fidelity: {result.fidelity:.4f}")

    Raises:
        ValueError: If num_qubits < 2.
    """

Testing Guidelines​

  • Write unit tests for all new functions
  • Use pytest fixtures for common setup
  • Test edge cases and error conditions
  • Aim for >80% code coverage
import pytest
from softqcosimport Optimizer, AerBackend

class TestOptimizer:
    @pytest.fixture
    def optimizer(self):
        backend = AerBackend(num_qubits=5)
        return Optimizer(backend, num_qubits=5, seed=42)

    def test_optimize_ghz_returns_result(self, optimizer):
        result = optimizer.optimize_ghz(max_iters=10)
        assert result.fidelity > 0
        assert result.total_evaluations > 0

    def test_optimize_ghz_improves_fidelity(self, optimizer):
        result = optimizer.optimize_ghz(max_iters=50)
        assert result.fidelity > 0.5

Architecture​

Project Structure​

softqcos/
├── __init__.py          # Public exports
├── core/
│   ├── optimizer.py     # Main Optimizer class
│   ├── cost_functions.py # Cost function implementations
│   └── circuit_builder.py # Circuit utilities
├── backends/
│   ├── base.py          # Backend protocol
│   ├── aer.py           # Qiskit Aer
│   ├── cirq.py          # Cirq adapter
│   ├── pennylane.py     # PennyLane adapter
│   └── braket.py        # Braket adapter
├── cli/
│   └── main.py          # CLI application
├── api/
│   ├── models.py        # Pydantic models
│   └── server.py        # FastAPI server
├── utils/
│   └── logging.py       # Logging utilities
└── tests/
    ├── test_optimizer.py
    └── test_backends.py

Key Design Principles​

  1. Backend Abstraction: All backends implement the Backend protocol
  2. Lazy Imports: Optional dependencies loaded only when needed
  3. Type Safety: Full type hints with Protocol-based interfaces
  4. Testability: Dependency injection for easy mocking

Release Process​

Releases are automated via GitHub Actions:

  1. Update version in softqcos/__init__.py
  2. Update changelog.md
  3. Create and push a tag:
git tag v0.1.0
git push origin v0.1.0
  1. GitHub Actions will build and publish to PyPI

Getting Help​

License​

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

Thank you for contributing to QCOS! 🚀