uniqc.algorithms.workflows.xeb_workflow module

High-level XEB workflow combining calibration, readout EM, and fidelity fitting.

Chip-agnostic: works with any backend supported by UnifiedQuantum. For WK180-specific usage, see examples/wk180/xeb.py.

uniqc.algorithms.workflows.xeb_workflow.run_1q_xeb_workflow(backend='dummy:local:simulator', qubits=None, depths=None, n_circuits=50, shots=1000, use_readout_em=True, max_age_hours=24.0, chip_characterization=None, noise_model=None, seed=None, cache_dir=None)

Run 1-qubit XEB on one or more qubits.

Parameters:

• backend (str) – Backend name (e.g. “dummy”, “originq:wuyuan:wk180”).

• qubits (list[int] | None) – List of qubit indices to benchmark. Defaults to [0, 1, 2].

• depths (list[int] | None) – List of circuit depths. Defaults to [5, 10, 20, 50, 100].

• n_circuits (int) – Number of random circuits per depth.

• shots (int) – Shots per circuit.

• use_readout_em (bool) – Whether to apply readout EM before fidelity computation.

• max_age_hours (float) – Maximum age of cached calibration data (hours).

• chip_characterization (Any) – Optional ChipCharacterization for noise-aware simulation.

• noise_model (dict[str, Any] | None) – Optional explicit DummyAdapter noise model.

• seed (int | None) – Random seed for circuit generation.

• cache_dir (str | None)

Returns:

Dict mapping qubit index → XEBResult.

Return type:

dict[int, Any]

uniqc.algorithms.workflows.xeb_workflow.run_2q_xeb_workflow(backend='dummy:local:simulator', pairs=None, depths=None, n_circuits=50, shots=1000, use_readout_em=True, max_age_hours=24.0, chip_characterization=None, noise_model=None, seed=None, entangler_gates=None, cache_dir=None)

Run 2-qubit XEB on one or more qubit pairs.

Parameters:

• backend (str) – Backend name.

• pairs (list[tuple[int, int]] | None) – List of (u, v) qubit pairs. Defaults to [(0,1), (1,2)].

• depths (list[int] | None) – List of circuit depths.

• n_circuits (int) – Number of random circuits per depth.

• shots (int) – Shots per circuit.

• use_readout_em (bool) – Whether to apply readout EM before fidelity computation.

• max_age_hours (float) – Maximum age of cached calibration data.

• chip_characterization (Any) – Optional ChipCharacterization.

• noise_model (dict[str, Any] | None) – Optional explicit DummyAdapter noise model.

• seed (int | None) – Random seed.

• entangler_gates (dict[tuple[int, int], str] | None) – Per-pair 2-qubit gate name override.

• cache_dir (str | None)

Returns:

Dict mapping (u, v) → XEBResult.

Return type:

dict[tuple[int, int], Any]

uniqc.algorithms.workflows.xeb_workflow.run_parallel_cz_xeb_workflow(backend='local', *, chip_characterization=None, region_qubits=None, n_qubits=None, patterns=None, pattern_mode='auto', color_idx=0, depths=None, instances=20, shots=5000, noise_model=None, seed=2026, cache_dir=None, max_age_hours=None)

Run parallel-CZ XEB on a chip and return per-pair fidelities.

Before doing anything this calls uniqc.backend_adapter.preflight.ensure_backend_ready() on backend. Missing SDKs, missing or stale chip cache cause an immediate, loud error — there are no silent fallbacks.

A generic chip pre-flight calibration: pick (or accept) a region of qubits, build parallel CZ patterns, run Haar-U3 + parallel-CZ XEB at multiple depths, and fit per-pair F(d) = beta · alpha^d on the 2-qubit marginals. Returns a dict whose per_pair_results field maps each (u, v) pair to an uniqc.XEBResult encoding alpha (per-cycle CZ fidelity) and its uncertainty.

Parameters:

• backend (str) – Backend name ("local", "dummy:local:simulator", "dummy:originq:WK_C180", "originq:WK_C180", …).

• chip_characterization (Any) – Required when region_qubits/patterns need to be derived from the chip topology, or when noise-aware simulation is desired (passed to DummyAdapter).

• region_qubits (list[int] | None) – Explicit list of region qubits. If omitted, derived from the chip topology + n_qubits via pick_region.

• n_qubits (int | None) – Region size when picking automatically.

• patterns (list[list[tuple[int, int]]] | None) – Explicit list of CZ patterns. If omitted, derived from pattern_mode.

• pattern_mode (str) –

  "auto" — DSatur-color the region’s induced edges into

  disjoint matchings (one parallel-XEB run covers all of them).

  "three_color" — chip-wide 3-coloring of every CZ edge,

  use the matching at index color_idx (one matching).

  "single_pair_per_pattern" — every pair in the region

  becomes its own one-edge pattern (isolated XEB).

• color_idx (int) – Which color to keep when pattern_mode="three_color".

• depths (list[int] | None) – Sweep over circuit depths. Defaults to [5, 10, 15, 20, 25, 30].

• instances (int) – Random circuit instances per (pattern, depth).

• shots (int) – Shots per circuit.

• noise_model (dict[str, Any] | None) – Optional explicit DummyAdapter noise model.

• seed (int | None) – Master corpus RNG seed.

• cache_dir (str | None) – If set, per-pair XEBResult files are saved here.

• max_age_hours (float | None)

Returns:

• region_qubits: list[int]

• patterns: list[list[tuple[int,int]]]

• pairs: list[(u,v)] (every pair touched by any pattern)

• per_pair_fits: list[PairCircuitFit]

• per_pair_decays: dict[(u,v), PairDecay]

• per_pair_results: dict[(u,v), XEBResult]

• corpus_size: int

Return type:

Dict with keys

uniqc.algorithms.workflows.xeb_workflow.run_parallel_xeb_workflow(backend='dummy:local:simulator', chip_characterization=None, depths=None, n_circuits=50, shots=1000, use_readout_em=True, max_age_hours=24.0, noise_model=None, seed=None, target_qubits=None, cache_dir=None)

Run full-chip parallel 2-qubit XEB using auto-generated patterns.

The chip topology is read from chip_characterization.connectivity. All edges in the topology are grouped into parallel rounds using DSatur coloring, then XEB is run on all pairs simultaneously in each round.

Parameters:

• backend (str) – Backend name.

• chip_characterization (Any) – ChipCharacterization providing topology.

• depths (list[int] | None) – List of circuit depths.

• n_circuits (int) – Number of circuits per depth.

• shots (int) – Shots per circuit.

• use_readout_em (bool) – Apply readout EM.

• max_age_hours (float) – Maximum calibration data age.

• noise_model (dict[str, Any] | None) – Optional explicit DummyAdapter noise model.

• seed (int | None) – Random seed.

• target_qubits (list[int] | None) – Optional subset of qubits to include (uses full topology if None).

• cache_dir (str | None)

Returns:

patterns (ParallelPatternResult), results (per-pair XEBResult), pairs.

Return type:

Dict with keys