Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
196 lines (134 loc) · 4.69 KB

CONTRIBUTING.md

File metadata and controls

196 lines (134 loc) · 4.69 KB

🤝 Contributing to QPyth

QPyth is a professionally engineered, physically rigorous quantum computing library built on Qiskit. Moving beyond ideal statevector simulations, QPyth provides canonical implementations of advanced quantum algorithms, including Variational Quantum Eigensolvers (VQE) for multi-electron molecules, robust Quantum Error Correction (QEC) protocols, and seamless quantum hardware execution. Featuring hardware-calibrated simulation with vendor-neutral backend profiles supporting multiple quantum hardware providers, QPyth ensures every component follows standard physical implementations—delivering real simulation, authentic hardware routing, and graceful dependency handling within a full-stack environment. We welcome contributions from the community!

📜 Code of Conduct

By participating, you agree to abide by our Code of Conduct.

🚀 How to Contribute

1. Find an Issue

Browse existing issues or create a new one for:

  • Bug reports
  • Feature requests
  • Documentation improvements
  • Performance optimizations

When opening a feature request, include the concrete feature idea, affected surface area, and success criteria so it can be evaluated or turned into an implementation plan without guesswork.

2. Fork and Branch

# Fork the repository on GitHub, then:
git clone https://github.com/quantumdynamics927-dotcom/QPyth.git
cd QPyth
git checkout -b feature/your-feature-name

3. Develop

  • Make your changes with tests
  • Follow our coding standards (see below)
  • Ensure all tests pass

4. Submit

Open a Pull Request with:

  • Clear title and description
  • Related issue reference (if any)
  • Test results
  • Documentation updates (if needed)

🛠 Development Setup

# Clone the repository
git clone https://github.com/quantumdynamics927-dotcom/QPyth.git
cd QPyth

# Install development dependencies
pip install -e .[dev,physical,web]

# Install pre-commit hooks
pre-commit install

✅ Coding Standards

Python Style

  • Linting: Ruff with strict checks
  • Formatting: Ruff format (auto-formatted)
  • Type hints: Required for all new functions
  • Docstrings: Google-style docstrings
# Check code quality
ruff check .
ruff format .

# Run tests
pytest tests/ --tb=short

# Type checking (optional)
mypy quantumpytho/

Circuit Design

  • Scientific correctness: No fabricated physics
  • Standard implementations: Follow Qiskit best practices
  • Documentation: Every circuit has docstring references
  • Physical units: Energies in Hartree, angles in radians

Tests

  • All new code must have tests
  • Tests should cover edge cases
  • Use realistic quantum values

🧪 Testing Guidelines

# Run all tests
pytest tests/ --tb=short

# With coverage report
pytest --cov=quantumpytho --cov-report=term-missing

# Run specific test file
pytest tests/test_bloch_ascii.py

# Run with verbose output
pytest -v

# Run tests matching pattern
pytest -k "bloch"

Coverage targets:

  • Core modules: >90%
  • New features: 100%

📚 Documentation

Module Docstrings

Every module and function needs a docstring:

def my_function(param: str) -> int:
    """Short description of what this does.

    Args:
        param: Description of the parameter

    Returns:
        Description of the return value

    Raises:
        ValueError: When something goes wrong
    """
    pass

Examples

Include usage examples in:

  • Module docstrings
  • README.md
  • CLI help text

🎯 Contribution Areas

We welcome help in:

Area Description
Circuits New quantum circuits, gate optimizations
Modules Additional quantum operations and algorithms
Web UI Frontend enhancements, new visualizations
Documentation Tutorials, API docs, usage examples
Tests More test coverage, edge cases, integration tests
Performance Speed and memory optimizations
CI/CD Pipeline improvements, new checks

🔄 Pull Request Checklist

Before submitting:

  • Lint passes: ruff check .
  • Format passes: ruff format .
  • Tests pass: pytest
  • Type hints added for new functions
  • Docstrings updated
  • CHANGELOG.md updated (if applicable)
  • README.md updated (if new feature)

💬 Getting Help

🙏 Thank You!

Your contributions help make QuantumPytho better for everyone in the quantum computing community!