oracq

English · 简体中文

oracq is a scientific-computing algorithm implementation framework for quantum algorithm researchers. Composable algorithms are written in Python against access models and compiled to a register-level intermediate representation (RIR) that preserves module structure; oracle placeholders stay unimplemented until you compare gate-network, QRAM, and reversible-arithmetic candidates, bind them, and proceed to numerical validation and resource analysis.

The current package version is 0.1.0 and the RIR format is 0.1 (full specification). Algorithms declare inputs and outputs through plain Python protocols; no language-level type-system extension is required.

Core concepts at a glance

A minimal program

from oracq import Bits, Builder, export_originir, simulate

b = Builder("bell_pair", {"pair": Bits(2)})
b.h(b["pair"][0])
b.xor(b["pair"][0], b["pair"][1])
program = b.finish().program()

print(simulate(program).amplitudes)
print(export_originir(program).text)

The result has equal amplitudes on 00 and 11. Module calls and Repeat structures are preserved in RIR and in the YAML/JSON text forms; they are not expanded during generation.

APIs used in this example: Builder · Bits · simulate · export_originir. For a step-by-step walkthrough see the first register program tutorial.

Typical workflow

Algorithm library

The algorithm library is organized into ten subpackages by purpose; the complete catalog with selection guidance is the algorithm index, with one manual page per algorithm (interface, implementation notes, validation approach, and known gaps). Representatives per category:

Input models and operators

Algorithms consume inputs through five composable access-model families:

• Operator wrappers and basic composition (identity/product/scale/LCU): manual, API; block-encoding algebra in block_encoding.
• Oracle paradigms (XorDatabase, StatePreparation, StateOracle, SparseAccess): API.
• Quantum data structures QVector/QMatrix: manual, API.
• Density matrices and Gibbs states, spectral and low-rank decompositions: density, spectral, lowrank.

Applications

• QFVM (quantum fluid solving): manual, API, input-model review spec.
• QHAM (PDE → HAM → QHAM pipeline): manual, derivation spec, API, tutorial.
• Roe matrix elements: roe, roe_formulas.
• Case catalog: 22 reference workloads (catalog) and the gallery generator (gallery, tutorial).

Documentation map

Pick a reading path by role:

• Getting started: first program → core concepts → replacing oracles.
• Algorithm research: algorithm-research tutorial → algorithm index → validation coverage matrix; applicability boundaries in validation and scope.
• Differential-equation applications: tutorial → manual → QHAM manual.
• Backend engineering: backend manual → compatibility review → infrastructure API.
• Language and specs: RIR spec, generation-layer boundary, open IR, QRAM memory format, math IR.

Install · build · check

uv sync --locked --extra dev --extra docs
uv run python tools/build_docs.py --lang all

This builds both language trees (warnings are errors): English to out/docs/en/html and Chinese to out/docs/zh/html, plus doctest runs. Open out/docs/en/html/index.html to browse the generated site. Algorithm gallery and engineering checks:

uv run python examples/algorithm_gallery.py
uv run python tools/check_project.py --docs

The algorithm gallery generates RIR, OriginIR-ext, and readout notes for 22 small examples. The full native check requires a separate environment with pysparq and uniqc installed:

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

The language core depends only on PyYAML for text serialization. Optional backends are imported at their execution entry points; generated artifacts, environments, and build files are never committed. See CONTRIBUTING.md for the development workflow and the documentation style guide; source-tree classification and migration notes are in architecture and import paths. Documentation is also maintained in Chinese: see README.zh-CN.md.

Advanced algorithms such as QLS/QODE/QHAM still have pending verification items on numerical accuracy, success channels, or convergence (per-item status in the validation coverage matrix). A general-purpose QSP-HamSim kernel is still to be provided; the current modular multiplication uses finite-size permutation synthesis, and classical optimizers for VQE/QAOA are chosen by the application.