Installation and environment

English · 简体中文

The language core requires Python 3.11 or newer and depends only on PyYAML for text serialization. Quantum simulators and documentation tooling are installed separately. The optional pyqsp extra (uv sync --extra pyqsp) installs pyqsp for the replaceable QSP phase-synthesis adapter.

Set up a development environment in the repository directory:

uv sync --locked --extra dev --extra docs
uv run python examples/algorithm_gallery.py

The second command generates the RIR, OriginIR-ext, and validation summaries of a set of small algorithms; the output lands in out/algorithm-gallery/. For using and modifying the showcase examples see Running and modifying the algorithm gallery.

If you only need to call the core interfaces from source, add src to your Python path:

PYTHONPATH=src python examples/algorithm_gallery.py

Optional backends

Running real-backend tests requires a separate Python environment with pysparq and uniqc installed. This repository does not download or compile them when the core package is installed. Executing arithmetic native operators additionally requires a working C++17 compiler.

PYTHONPATH=src /path/to/backend/python examples/algorithm_gallery.py --native

--native compares the full complex amplitudes of the reference executor, PySparQ, and the OriginIR backend. It does more than check that the exported text can be parsed. For everyday command-line usage once the environment is ready see Command line.

Building the documentation

uv run python tools/build_docs.py --lang all

This runs the HTML and doctest builders for both language trees with warnings as errors: English HTML to out/docs (the published site root), Chinese HTML to out/docs/zh, and doctest output to out/docs-doctest/{en,zh}. Open out/docs/index.html to browse this site; the Chinese mirror starts at out/docs/zh/index.html. A failed HTML build or a failed tutorial assertion both return a non-zero exit code. For build configuration and writing conventions (including the cross-linking rules) see Writing documentation.