iqm.benchmarks.entanglement.ghz_optimal.rank_ghz_trees

iqm.benchmarks.entanglement.ghz_optimal.rank_ghz_trees(qubit_layout: Sequence[int], backend: IQMBackendBase, metrics: Mapping[str, Mapping[int | tuple[int, int], float]], num_qubits: int | None = None, options: TreeSearchOptions | None = None) → list[TreeCandidate]

Score one spanning tree per possible root qubit and return them best first.

Subset and tree are chosen together: which num_qubits qubits are cheapest depends on the shape of the tree that will connect them, so scoring the two separately picks an elongated set and then pays for it in depth.

Only the best candidate of each root is kept. The search generates many trees per root that differ by a single edge, and keeping them would fill the ranking with near-duplicates – one per root is what makes rank n a genuinely different starting node rather than a rounding difference.

Candidates whose costs agree to _COST_TIE_DECIMALS are ordered by CZ layer count, so that where the objective cannot tell two trees apart the shallower one ranks first.

Parameters:

• qubit_layout (Sequence[int]) – The subset of system-qubits used in the protocol, indexed from 0.

• backend (IQMBackendBase) – The backend whose coupling map defines the connectivity.

• metrics (Mapping[str, Mapping[int | tuple[int, int], float]]) – The metrics dictionary from extract_fidelities_unified(), whose keys are physical qubit indices.

• num_qubits (int | None) – Size of the GHZ state; None uses every qubit of the layout.

• options (TreeSearchOptions | None) – What the search minimizes; defaults to TreeSearchOptions.

Returns:

when no connected set of the requested size exists it holds a single linear-chain fallback.

Return type:

The candidates sorted by non-decreasing cost, one per root, never empty

Raises:

ValueError – If options.objective is not one of TREE_OBJECTIVES.