PySparQ backend

oracq.infrastructure.backends.pysparq

Optional PySparQ execution adapter. RIR root registers correspond to native integer registers.

oracq.infrastructure.backends.pysparq.run_pysparq(program, memory=None, *, max_steps=1000000, max_states=65536, native_registry=None, report=None)[source]

Execute a program event by event through the PySparQ sparse register simulator.

RIR root registers map to PySparQ native named registers, with gates and QRAM queries applied one by one on the sparse state. An interpreter with pysparq installed is required; a missing dependency raises ValidationError. The whole execution holds a module-level mutex, requires the PySparQ global register table to be empty before taking over, and cleans up the registers created by this adapter on normal or exceptional exit.

Parameters:

  • program – The program to execute; it must be closed when native_registry is not provided.

  • memory – QRAM data keyed by resource name, either a full word sequence or a sparse address-to-word dictionary; all zeros when omitted, and when provided it must cover exactly all resources of the entry.

  • max_steps – Expansion budget; execution is refused once the estimated step count exceeds it.

  • max_states – Sparse basis-state budget; execution aborts once it is exceeded after a gate or native operator application.

  • native_registry – Module-level native implementation registry; when provided, open oracles can be closed by native implementations.

  • report – The passed-in dictionary is filled in place with execution statistics, keyed native_calls, gate_events, native_labels and correctness (the last initialized to pending).

Returns:

Sparse complex amplitudes keyed by tuples of the entry registers’ integer values, with components below 1e-15 dropped.

Return type:

RegisterState

Raises:

  • ValidationError – The program is illegal, contains a runtime Store, a native implementation is missing or mismatches the module description,

  • the QRAM materialization exceeds 2^20 entries, the expansion or sparse-state budget is exceeded, a local workspace is not restored to zero, –

  • the PySparQ global register table is non-empty, or pysparq is not installed. –

oracq.infrastructure.backends.pysparq.run_pysparq_rir(program, memory=None, *, max_steps=1000000, max_states=65536)[source]

Execute through the PySparQ native RIR interpreter; an implementation independent of run_pysparq, used for cross-validation.

Parameters:

  • program – The closed RIR program to execute; it must not contain runtime QRAM writes via Store.

  • memory – Binding from resource names to QRAM contents; sequences give data words by index, mappings by address.

  • max_steps – The interpreter’s instruction-step budget cap for expanded execution.

  • max_states – The interpreter’s budget cap on the number of maintained basis states.

Returns:

The final state over the entry’s public register space, as sparse complex amplitudes keyed by tuples of the registers’ integer values.

Return type:

RegisterState