uniqc.compile.validation module

Pre-submission circuit validation and depth analysis.

This module provides backend-agnostic helpers used by every uniqc submission path to make sure a Circuit is actually runnable on a target backend before any cloud round-trip happens.

Two public entry points

compute_gate_depth(circuit, *, virtual_z=True)

Returns the parallelism-aware physical depth of circuit. Each layer is the earliest position at which all qubits used by an operation are free. When virtual_z=True (the default), gates implemented as a frame change on superconducting qubits — VIRTUAL_Z_GATES — contribute 0 depth.

compatibility_report(circuit, backend_info, *, basis_gates=None, language=None) and the boolean shortcut is_compatible(...)

Validate, in this order:

  1. Language acceptance (the platform’s submit language can express the gates).

  2. Qubit count fits within backend_info.num_qubits.

  3. Every gate appears in the (effective) basis set / supported set.

  4. Every two-qubit interaction has a corresponding edge in the topology (CZ, ISWAP, SWAP are undirected; CNOT / CX / ECR are directional unless the backend marks the edge as reversible).

The returned CompatibilityReport is the same object surfaced by submit_task(..., dry_run=True) and printed by the CLI.

This module deliberately does no platform-specific compilation; for that see uniqc.compile.policy.

class uniqc.compile.validation.CompatibilityReport(compatible, backend_id, used_qubits, used_gates, gate_depth, errors=<factory>, warnings=<factory>)[source]

Bases: object

Result of compatibility_report().

Variables:

  • compatible (bool) – True iff every check passed. submit_task() refuses to submit when this is False.

  • backend_id (str | None) – Full backend identifier (platform:name) the report was computed for.

  • used_qubits (frozenset[int]) – Set of qubit indices touched by any gate or measurement.

  • used_gates (frozenset[str]) – Set of gate names (post-alias-normalisation) used by the circuit.

  • gate_depth (int) – Parallelism-aware physical depth (with virtual-Z if requested).

  • errors (tuple[str, ...]) – Hard failures — caller must not submit.

  • warnings (tuple[str, ...]) – Soft issues, e.g. partial validation due to missing topology data.

Parameters:
backend_id: str | None
compatible: bool
errors: tuple[str, ...]
gate_depth: int
used_gates: frozenset[str]
used_qubits: frozenset[int]
warnings: tuple[str, ...]
uniqc.compile.validation.VIRTUAL_Z_GATES: frozenset[str] = frozenset({'RZ', 'S', 'T', 'U1', 'Z'})

Gates that are typically implemented as virtual phase/frame changes on superconducting hardware and therefore contribute 0 physical depth. Conservative default — only includes gates whose physical implementation is a software phase update on every major superconducting cloud platform.

uniqc.compile.validation.compatibility_report(circuit, backend_info, *, basis_gates=None, language=None, virtual_z=True)[source]

Validate circuit against backend_info and return a full report.

Parameters:

  • circuit (Circuit) – The circuit to validate.

  • backend_info (BackendInfo | None) – Target backend descriptor. May be None for purely-local checks (gate depth, language); in that case topology and qubit-count checks are skipped with warnings.

  • basis_gates (list[str] | tuple[str, ...] | None) – Optional explicit basis set to check against. Falls back to backend_info.extra["basis_gates"] if not given.

  • language (str | None) – Submission language for the target platform — see uniqc.compile.policy.PLATFORM_SUBMIT_LANGUAGE. Used for language-level rejections (e.g. RPhi cannot reach QASM2).

  • virtual_z (bool) – Forwarded to compute_gate_depth().

Returns:

See class docstring.

Return type:

CompatibilityReport

uniqc.compile.validation.compute_gate_depth(circuit, *, virtual_z=True)[source]

Return the parallelism-aware physical depth of circuit.

Parameters:

  • circuit (Circuit) – Input UnifiedQuantum Circuit.

  • virtual_z (bool) – When True (default), gates in VIRTUAL_Z_GATES contribute zero depth — they are implemented as a frame change on superconducting qubits. They still occupy their qubit’s “schedule cursor” so that non-commuting gates around them are not collapsed into one layer.

Returns:

The depth, i.e. the maximum number of non-virtual layers any qubit participates in. A circuit with no non-virtual gates has depth 0.

Return type:

int

Notes

  • MEASURE and BARRIER are not counted as gate depth, but BARRIER synchronises every qubit it touches: subsequent gates on those qubits start at the maximum cursor among them.

  • Multi-qubit gates use the maximum cursor over their qubits + 1 (or +0 if virtual).

  • The result is platform-agnostic; it estimates depth on a hardware that can implement Z gates virtually.

uniqc.compile.validation.is_compatible(circuit, backend_info, *, basis_gates=None, language=None)[source]

Boolean shortcut around compatibility_report().

Returns True iff topology, gate set and language all check out. For the full report (depth, used gates, warnings, error messages), use compatibility_report().

Parameters:
Return type:

bool