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.

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), frame-change gates listed in VIRTUAL_Z_GATES contribute zero depth.

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

    1. The platform submit language can express the gates.

    2. The qubit count fits within backend_info.num_qubits.

    3. Every gate appears in the effective basis or supported set.

    4. Every two-qubit interaction has a corresponding topology edge. CZ, ISWAP, and SWAP are undirected; CNOT, CX, and ECR remain directional unless the backend marks the edge 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.

backend_id
compatible
errors
gate_depth
used_gates
used_qubits
warnings
uniqc.compile.validation.VIRTUAL_Z_GATES = 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 – The circuit to validate.

  • backend_info – 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 – Optional explicit basis set to check against. Falls back to backend_info.extra["basis_gates"] if not given.

  • language – 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 – 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 – Input UnifiedQuantum Circuit.

  • virtual_z – 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().