Development

q2m3 uses a src-layout package, uv for dependency management, Ruff for linting, Black for formatting, and pytest for tests.

Environment Setup

uv sync --extra dev --extra catalyst --extra solvation --extra viz

Use narrower extras when working on isolated parts of the project:

uv sync --extra dev
uv sync --extra catalyst --extra solvation
uv sync --extra docs --extra catalyst --extra solvation --extra viz

Testing

Use the narrowest useful command first.

uv run pytest tests/test_basic.py -v
uv run pytest tests/solvation -v -m "not slow and not gpu"
uv run pytest tests/ --collect-only -q --no-cov
uv run pytest tests/ --cov=src/q2m3 --cov-report=term-missing

Registered markers include slow, solvation, catalyst, gpu, and rdm. The standard CI path skips slow and GPU tests.

Linting And Formatting

uv run ruff check src/ tests/
uv run black --check src/ tests/ --line-length 100
uv run black src/ tests/ --line-length 100

For GitHub-facing changes, also run:

uv run pre-commit run check-yaml --all-files

Documentation Workflow

Build the Sphinx site with warnings treated as errors:

make docs-clean docs
make docs-doctest

The equivalent explicit build command is:

uv run --extra docs --extra catalyst --extra solvation --extra viz sphinx-build -W --keep-going -b html doc/source doc/build/html

Documentation examples should be lightweight by default. H3O+, 8-bit QPE, dynamic Trotter scans, and memory profiles belong in optional diagnostic sections, not in first-run tutorials.

Contribution Notes

Public documentation should be checked against source code, tests, maintained examples, and the current README. Prefer current source and tests over older planning notes when they conflict.

Scientific claims should name the active space, qubit count, QPE precision, Trotter settings, and unit conversion assumptions when those values affect the interpretation.

Generated coverage reports, Sphinx build output, Catalyst IR cache files, benchmark outputs, and temporary profiling artifacts should not be committed.