Contributing¶
This guide covers the dev setup, the tests, the docs build and how to send a change. Paths are from the repository root.
Set up a checkout¶
You need Python 3.11 or newer (a conda or venv environment) and git.
git clone https://github.com/Quantcore-Technologies/Quantcore-Circuits.git
cd Quantcore-Circuits
pip install torch --index-url https://download.pytorch.org/whl/cpu # SQcircuit (analysis extra) needs PyTorch
pip install -e ".[all,dev]"
qcc kqc-files # KQCircuits' scripts and font; not needed when kqcircuits is a checkout in editable mode
qcc selftest
all is analysis + sim + notebook. dev is pytest, ruff and pre-commit. requirements/tested.txt lists the
exact versions the tests run with.
Upstream snapshots (optional)¶
The library depends on KQCircuits, Quantum Metal, SQcircuit, QuCat and PyAEDT. pip installs them from PyPI. If you
want their current main branches instead, for example to test against a fix that is not released yet,
scripts/fetch_other_libs.sh clones them (shallow) into third_party/ from their upstream repositories. It takes
optional repository names (bash scripts/fetch_other_libs.sh klive pyPalace, or all) and honours KQC_REF,
METAL_REF, QUCAT_REF and SQC_REF to pin a branch or commit. Install the clones you want with
pip install -e third_party/<name> (KQCircuits: third_party/KQCircuits/klayout_package/python).
The dashboard¶
The live dashboard’s source is in reviewer/ (Vite + React). The built app is tracked in
src/quantcore_circuits/review/static/. Only if you change the dashboard:
cd reviewer && npm install && npm run build
The tests¶
Run them from the checkout. On a shared machine set OPENBLAS_NUM_THREADS=2.
Tier |
Command |
What |
|---|---|---|
fast |
|
No GUI, no solver. Skips the notebook runs, the full export sweep and the co-design loop |
slow |
|
Notebook runs, the full export sweep, the co-design loop. Minutes to hours |
solver |
|
Needs |
one file |
|
While you work, run only the tests of what you touched |
Tests marked analysis are skipped when the analysis stack is missing. qcc selftest is the 30-second check of an
install. Some tests need extra local material and skip without it: the legacy components, and the AEDT projects
under tests/data/aedt_2024r1 (marker aedt_fixture; AEDT projects are not kept in git because every AEDT
edition writes its own, and the notebooks make them).
Style and checks¶
Code style is ruff with a line length of 120 (
ruff check src tests).pre-commit installruns the checks on every commit.Notebooks:
python scripts/check_notebook_api.py NOTEBOOK.ipynbchecks a notebook without running it (the nbformat schema, the syntax, every name, every import, and the call signatures against the library). Add--cleanfor notebooks that must have no outputs.Use the spelling “Quantcore” (lowercase c) in text, UI and docs.
Build the docs¶
The docs are Sphinx + MyST in docs/. Use a separate environment so the library environment stays as tested.
pip install -r docs/requirements.txt
QCC_DOCS_FAST=1 sphinx-build -b html docs docs/_build/html -q # fast: skips the API reference
sphinx-build -b html docs docs/_build/html # full: also builds the API reference
On Windows set the variable first (set QCC_DOCS_FAST=1, or $env:QCC_DOCS_FAST = "1" in PowerShell). The fast build
takes seconds; the full build writes docs/reference/api/ into the source tree while it runs, so use it for the final
check. The generated component and CLI pages come from python scripts/make_docs.py (needs the library installed).
More in docs/hosting.md.
Work on the KLayout plugin¶
The plugin is kplugin/ (a KLayout Salt package; it uses only KLayout’s own Python). To try your changes without
installing it, start KLayout with the plugin loaded from the checkout:
klayout_app -e -rm kplugin/load_dev.py
(On Windows klayout_app.exe, from KLayout’s install folder.) Designer(..., live=True) starts KLayout the same way.
qcc must be on the PATH, or set in Quantcore → Settings…. The plugin’s structure and its tests are described in
kplugin/README.md.
Issues and pull requests¶
Open an issue for a bug or an idea first if the change is large. For a bug, give the
qcc --version, your operating system, and the smallest design or script that shows it.Branch from
main, keep a pull request to one topic, and add or update a test for a behaviour change.Make sure
pytest -m "not slow"andruff check src testspass, and the docs build has no warnings from the pages you touched.Open the pull request against
main.
License¶
quantcore-circuits is licensed under GPL-3.0-or-later (it builds on KQCircuits, which is GPL-3.0). By contributing you agree that your contribution is licensed under the same terms.