RIR Interpreter API Reference¶
This module interprets and executes RIR JSON documents from QECC.Lang directly on PySparQ sparse states, making PySparQ a native backend for RIR. The concept and usage guide is RIR Interpretive Execution.
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.
Example
>>> 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[source]¶
Bases:
ValueErrorRaised for malformed RIR documents or execution-limit violations.
- class pysparq.rir.RIRResult(registers: tuple[tuple[str, int], ...], amplitudes: dict[tuple[int, ...], complex])[source]¶
Bases:
objectOutcome of an RIR execution.
registerslists the entry-module registers as(name, width)pairs in declaration order;amplitudesmaps each tuple of register integer values (same order) to its complex amplitude.
- pysparq.rir.load_rir(source: str | Path | Mapping[str, Any]) dict[str, Any][source]¶
Load and minimally validate an RIR JSON document.
sourcemay be a mapping that already holds the decoded document, a filesystem path, or a JSON string. Returns the decodeddict.
- 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[source]¶
Execute an RIR document on a fresh
pysparq.SparseState.- Parameters:
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.
- Returns:
RIRResultwith per-register integer amplitudes.