RIR 解释器 API 参考

本模块在 PySparQ 稀疏态上直接解释执行 QECC.Lang 的 RIR JSON 文档, 使 PySparQ 成为 RIR 的原生后端。概念与用法指南见 RIR 解释执行。

Execute QECC.Lang RIR JSON documents directly on PySparQ sparse states.

RIR (the QECC.Lang intermediate representation produced by the pyqecclang package) is a typed, register-level IR: programs declare named registers with kinds (bits / uint / sint / rational) and widths, QRAM resources, and a module graph whose bodies mix gate-level primitives with structured control nodes (Call / Repeat / Control / Adjoint). This module turns PySparQ into a native RIR backend: it loads the versioned JSON encoding (schema versions 0.1, 0.2 and 0.3) and interprets it on pysparq.SparseState, expanding modules at interpretation time — calls are inlined through register renaming, Repeat bodies are replayed, Adjoint walks the body backwards with inverted operations, and Control accumulates multi-bit conditions — while mapping register-level arithmetic onto native PySparQ operators (Add_ConstUInt_InPlace, GlobalPhase, QRAMLoad) whenever the RIR operand aligns with a whole register.

The interpreter is deliberately independent of pyqecclang itself: it consumes only the JSON document, so the two implementations can be cross-validated against each other and against the OriginIR-ext / UnifiedQuantum path.

示例

>>> import pysparq
>>> result = pysparq.run_rir(program_json, memory={"values": [1, 2, 3, 0]})
>>> result.amplitudes[(0, 1)]
(0.7071067811865476+0j)
exception pysparq.rir.RIRError[源代码]

基类:ValueError

Raised for malformed RIR documents or execution-limit violations.

class pysparq.rir.RIRResult(registers: tuple[tuple[str, int], ...], amplitudes: dict[tuple[int, ...], complex])[源代码]

基类:object

Outcome of an RIR execution.

registers lists the entry-module registers as (name, width) pairs in declaration order; amplitudes maps each tuple of register integer values (same order) to its complex amplitude.

statevector(max_qubits: int = 20) → list[complex][源代码]

Dense little-endian statevector over the entry registers.

pysparq.rir.load_rir(source: str | Path | Mapping[str, Any]) → dict[str, Any][源代码]

Load and minimally validate an RIR JSON document.

source may be a mapping that already holds the decoded document, a filesystem path, or a JSON string. Returns the decoded dict.

pysparq.rir.run_rir(document: str | Path | Mapping[str, Any], memory: Mapping[str, Any] | None = None, *, max_steps: int = 1000000, max_states: int = 65536) → RIRResult[源代码]

Execute an RIR document on a fresh pysparq.SparseState.

参数:
  • document -- RIR JSON as a decoded mapping, JSON string, or file path.

  • memory -- QRAM contents keyed by resource name; each value is a word sequence or a sparse {address: word} mapping.

  • max_steps -- expansion budget over the module graph (calls, repeats and controlled regions); exceeded budgets raise RIRError.

  • max_states -- sparse-state budget (number of basis states); exceeded budgets raise RIRError.

返回:

RIRResult with per-register integer amplitudes.

pysparq.rir.run_rir_file(path: str | Path, memory: Mapping[str, Any] | None = None, *, max_steps: int = 1000000, max_states: int = 65536) → RIRResult[源代码]

Convenience wrapper: load an RIR JSON file and execute it.