Skip to content

Contributing

Thank you for your interest in contributing to qgate!

Development Setup

git clone https://github.com/qgate-systems/qgate-shots-filter.git
cd qgate-shots-filter/packages/qgate
pip install -e ".[dev]"

The [dev] extra installs all test and quality dependencies: pytest, pytest-cov, ruff, mypy, pandas, pyarrow, qiskit, etc.

Running Tests

pytest -v tests/                 # 376 tests, ~1 s
pytest --cov=qgate tests/        # with coverage report
pytest tests/test_edge_cases.py  # run a single file
pytest -k "test_frozen"          # run by keyword

Code Quality

ruff check src/ tests/           # lint
ruff format src/ tests/          # auto-format
mypy src/qgate/                  # type-check

All code must pass ruff check and mypy --strict before merge.

Project Conventions

  • Immutable configs — GateConfig and all sub-models are Pydantic frozen=True models. Never mutate after construction.
  • NumPy for hot paths — ParityOutcome.parity_matrix is an np.ndarray. Avoid Python loops in scoring and decision code.
  • pandas is optional — never import pandas at module level. Use the lazy _get_pandas() helper in run_logging.py.
  • Structured logging — use logging.getLogger("qgate.<module>"). Never print to stdout from library code.
  • Type annotations — all public functions must have full type hints.

Areas for Contribution

  • Cirq adapter — Full implementation of CirqAdapter
  • PennyLane adapter — Full implementation of PennyLaneAdapter
  • Additional conditioning strategies — New decision rules beyond global / hierarchical / score-fusion
  • Benchmarks — Performance comparison across backends and problem sizes
  • Documentation — Examples, tutorials, API docs improvements
  • Property-based tests — Hypothesis-powered fuzz testing

Commit Messages

Use conventional commits:

feat: add CirqAdapter with full Bell-pair circuit support
fix: prevent ndarray aliasing in QiskitAdapter.parse_results
docs: update CLI reference with --error-rate flag
test: add edge-case tests for empty outcomes

Patent Notice

This package explores runtime trajectory filtering concepts from The underlying methods are covered by pending patent applications. The underlying invention is patent pending.

License

QGATE Source Available Evaluation License v1.2 — see License