Core infrastructure for crosstalk-free GST experiment designs

[rileyjmurray]

This PR adds crosstalk-free GST (XFGST) experiment designs. Given a QubitProcessorSpec, a 1Q GST design, and a 2Q GST design, it produces one circuit list that exercises many disjoint 1Q and 2Q GST experiments simultaneously across the device.

The packing of disjoint experiments onto the n-qudit device comes from an edge coloring of the 2Q connectivity graph. Each color class — a patch — is a set of mutually disjoint edges, so all of its 2Q experiments can run together, and any qubit not covered by an edge in that patch runs 1Q GST instead. The coloring algorithms are #848 and the lane-tensoring machinery is #849; this PR is the layer on top of both. It also carries changes to core code outside the feature, including two observable changes to public methods, which have their own section and should be reviewed independently.

The API

New module pygsti/protocols/xfgst_edesign.py, star-imported into pygsti.protocols with __all__ = ['CrosstalkFreeExperimentDesign', 'make_xfgst_design'].

CrosstalkFreeExperimentDesign(GateSetTomographyDesign) takes a processor spec, the two GST designs, and an edge coloring:

Parameter	Default	Meaning
edge_coloring	(required)	{color: [edge, ...]}; one patch per color
circuit_stitcher	assign_the_designs_with_mapping	Pluggable; see the contract below
nested	False	Forwarded to the stitcher as ensure_containment, and separately to GateSetTomographyDesign.__init__ as nested
debug_check	True	Stitcher-agnostic verification of the result
seed	None	Seeds the np.random.default_rng handed to the stitcher
**stitcher_kwargs	—	Forwarded verbatim; takes precedence over the defaults above

make_xfgst_design(nq_pspec, oneq_gstdesign, twoq_gstdesign, seed=0) is the simplified constructor: it computes the connectivity graph and its maximum degree, obtains a coloring from switchboard_find_edge_coloring("auto", ...) — an optimal closed-form coloring for canonical topologies (line, ring, grid, torus, as produced by ProcessorSpec(geometry=...)), a generic (deg + 1)-color algorithm otherwise — and delegates.

The default stitcher

assign_the_designs_with_mapping holds essentially all of the feature's logic. It returns circuit_lists[L] for germ-power index L, and there are four decisions in it worth review.

Patch-major ordering is a contract. Within each germ power, circuits follow the input ordering of color_patches, and downstream verification checks this rather than assuming it.

The two designs must share a germ-power schedule, asserted as len(oneq.circuit_lists) == len(twoq.circuit_lists) with the message "Not implemented.".

List lengths are reconciled per lane slot. random_index_schedule(n, max_len, randgen) always includes 0..n-1, so every circuit in the shorter list appears at least once; the remaining slots are drawn uniformly with repetition and the whole schedule is shuffled. Every circuit in the longer list is used exactly once, either list may be the longer one, and a fresh schedule per lane slot means different edges in a patch get different assignments. This is list-length equalization, distinct from the depth padding batch_tensor applies to shallower sub-circuits.

Same-shape patches share a template. Patches bucket by (num_edges, num_unused_qubits); one tensored circuit is built per group, and the rest obtain theirs via map_state_space_labels through make_line_mapper, which zips lane layouts positionally and raises on arity mismatch, inconsistent duplicates, and non-injective results. This is the stitcher's main optimization and also its main failure mode — copying instead of relabeling silently puts several patches' circuits on the representative's qubits — so MultiplePatchesSameShapeTester targets it directly.

Two other things to know. Idles are always explicit: build_layer_mappers maps the empty layer label Label(()) onto an explicit Gi/Gii idle and rewrites 1Q labels inside the 2Q design into parallel layers, which matters because the tensored circuits are later split back into lanes. And seed reproducibility is tied to the shape-group iteration order, so renaming or reordering patches changes the generated circuits. Passing nested=True (or ensure_containment=True as a stitcher kwarg) makes germ power L+1 contain germ power L exactly, patch-wise; EnsureContainmentTester covers the single-patch, same-shape, and three-germ-power transitivity cases.

Writing an alternative stitcher

circuit_stitcher(oneq_gstdesign, twoq_gstdesign, vertices, color_patches,
                 randgen=..., ensure_containment=..., **stitcher_kwargs)
    -> List[List[Circuit]]

CrosstalkFreeExperimentDesign supplies randgen and ensure_containment and merges **stitcher_kwargs over them, so an alternative can take its own options without a signature change anywhere; the built-in accepts and ignores **kwargs to stay compatible, and sets aux_info = {} unconditionally since it produces none. _layer_mappers_override is a private testing hook.

Validation is external by design. assert_circuit_lists_match_color_patches, run from __init__ when debug_check=True, re-derives the patch layout and checks even patch-major chunking, absence of implicit idles, and that each circuit's line labels are exactly its patch's qubits and every multi-qubit op sits on one of that patch's own edges. Comparing only the set of line labels does not catch a mis-relabeled template, since {0,1,2} == {0,1,2} holds even when the gates are on the wrong lines. Because the check runs against whatever was returned, it still applies to a swapped-in stitcher — which relying on the stitcher's own debug_check parameter did not. One known non-behavior: patches are not deduplicated, so [(0,1),(2,3)] and [(1,0),(3,2)] both generate.

Behavior changes outside XFGST

Circuit.serialize preserves CircuitLabel layers. With expand_subcircuits=False, a CircuitLabel layer is appended as-is rather than expanded into its components. This matches the existing docstring ("If False, the circuit may contain CircuitLabel layers") but is an observable change to a core public method.

EffectRepComputational.probability no longer densifies. It calls the new matrixtools.zvals_int64_probability instead of building a dense length-4**nfactors effect vector and taking a full dot product, so the work is O(2**n) rather than O(4**n), mirroring the compiled evotypes' C++ path. We make no representations about whether this change matters in the workflows where pyGSTi is used.

compute_2Q_connectivity and compute_clifford_2Q_connectivity no longer crash on {idle}. gate_num_qubits('{idle}') equals the device size, so on a two-qubit spec the global idle clears the == 2 arity guard — but its availability is [None], so both methods reach qubit_labels.index(sslbls[0]) and raise TypeError: 'NoneType' object is not subscriptable. The Clifford method's except (KeyError, TypeError, ValueError) does not save it: clifford_symplectic_rep_of(Label('{idle}', None)) succeeds, so the crash lands after the guard. The idle is now special-cased and treated as available on every qubit.

A regression test for per-site Clifford validation. nonstd_gate_symplecticreps can register a symplectic rep against a specific Label — one embedding — rather than against a gate name, so compute_clifford_2Q_connectivity has to validate each availability site individually. Trusting the name alone yields phantom edges that disagree with compute_clifford_ops_on_qubits and crash create_random_germ (pygsti/algorithms/randomcircuit.py:1736) with ValueError: low >= high when one is sampled. The guard itself is unchanged relative to develop — it was dropped and reinstated within this branch — so what lands here is test_compute_clifford_2Q_connectivity_only_counts_validated_sites and an explanatory comment, not a fix. It is a randomized-benchmarking concern with no connection to XFGST.

New LocalNoiseModel.__getitem__, dispatching by substring: 'rho' → prep_blks['layers'], 'Mdefault' → povm_blks['layers'], ':' → split into a tuple, otherwise operation_blks['gates'] falling back to operation_blks['layers'].

objectivefns is now imported eagerly (pygsti/__init__.py, pygsti/objectivefns/__init__.py), so pygsti.objectivefns.objectivefns.X resolves without a separate import — the intent stated in commit c4d3fb89e. Small import-time cost, no known circularity.

test/unit/objects/test_processorspec.py moved to test/unit/processors/, with about thirteen new tests for previously untested QubitProcessorSpec methods (resolved_availability, subset, map_qudit_labels, the connectivity methods, and others). Hardcoded paths to the old location will break.

Reviewer attention

1. build_layer_mappers is both unexercised and over-specialized. No test runs it: every test passes _layer_mappers_override=, and test/integration/test_xfgst.py injects its own near-duplicate _get_layer_mappers helper. It also asserts tgt in [0, 1] and hardcodes 'Gi' / 'Gii', assuming the 2Q design's qubit labels are literally 0 and 1 and that both idle names exist in the model. Neither is checked against the processor spec, and make_xfgst_design gives no way to override them.
2. The {idle} branch sets avail = [qubit_labels] and then indexes sslbls[0] / sslbls[1], which is correct only for a two-qubit spec. It is safe today, because the idle's arity equals the device size and the gate_num_qubits(gn) == 2 guard therefore confines the branch to two-qubit devices. The residual exposure is a user-registered two-qubit gate literally named {idle} on a larger spec, which would connect only the first two qubits. An assertion would make that reasoning local rather than implicit.
3. LocalNoiseModel.__getitem__ has no in-tree caller. Has a loose hueristic'rho' in key matches any label containing "rho" anywhere, the annotation admits Label as well as str (where in means something else), and no key produces a clean KeyError.
4. Minor: Circuit.serialize now ends with tmp = Circuit._fastinit(...); return tmp — a leftover temporary.
5. test/integration/test_xfgst.py tests GLND HSCA models, but not CPTPLND models.

Incidental changes

• jupyter_notebooks/Examples/xfgst.ipynb (new): three code cells that build a 3-qubit XYIECR design and run the pipeline end to end. No markdown narrative yet.
• pygsti/tools/matrixtools.py: type annotations across roughly sixty signatures. Substantively, zvals_int64_probability (the sparse inner product used above), a rewritten zvals_int64_to_dense, the bit-manipulation helpers _zvals_int64_indices_and_signs / _spread_bits / _reverse_bits_scalar, and a module-level cache. Separately, minweight_match now fills its weight matrix by broadcasting rather than looping, with guarded fast paths that fall back to the original loop whenever bit-identical results cannot be guaranteed.
• pygsti/models/explicitmodel.py: Union[X, Y] → X | Y on the default_gauge_group setter, an unused import dropped.
• Sandia license headers added to pygsti/circuits/split_circuits_into_lanes.py, test/unit/circuits/test_circuit_splitting.py, and test/unit/tools/test_graphcoloring.py.
• test/unit/objects/test_localnoisemodel.py reformatted, bare assert → self.assertX.
• .github/workflows/reuseable-main.yml: drops the stale pygsti/tools/graphcoloring.py path from the graph-coloring change detector, since Feature graphcoloring #848 turned that module into a subpackage.

Testing

test/unit/protocols/test_xfgst_edesign.py (new) covers the stitcher against stub designs: AssignDesignsLengthPairingTester (length reconciliation in both directions, plus idle padding of shallower sub-circuits), MultiplePatchesSameShapeTester, and EnsureContainmentTester (including three-germ-power transitivity).

test/integration/test_xfgst.py (new) runs design construction, data simulation, and GST on a 3-qubit line under four Lindblad noise configurations — H, S, H+S, and H+S+C+A, the last under GLND not CPTPLND, asserting a 2*deltaLogL bound for each. It is reduced-scale by construction and finishes in well under a minute.

test_circuit.py gains serialize/parallelize round-tripping alongside set_line_labels, set_occurrence, and QUIL string helper coverage; test_processorspec.py gains the connectivity tests described above; test_localnoisemodel.py gains test_getitem.

[rileyjmurray]

It's occurring to me that much of PR's complexity can be attributed to the concept of "lanes" within a circuit. I recommend we move all of that functionality to a second PR.

[rileyjmurray]

A label whose string representation starts with a I is assumed to be an Instrument. I'm not sure if we have a truly standard way of referring to an idle gate. Gi is the most common, but that's not universal. This seems like a deeply messy issue.

[rileyjmurray]

On a separate but related note, I don't like the depth of the nesting here. We've got a for, then if, then if, then for, then if. That's very hard to follow.

[rileyjmurray]

It's extremely misleading for this function to suggest that efficiency here matters. It does not. I take it that this comment block was written by a robot. That's fine, but I expect you to remove these kinds of things.