Skip to content

Kuramoto-XY layout-cost API

scpn_quantum_control.hardware.kuramoto_layout_cost assigns one comparable objective to an injective logical-to-physical qubit placement. It composes post-routing depth, a product-formula error bound, and calibrated mean gate infidelity without introducing a second compiler, error model, or mapper.

Objective and records

For layout l, coupling matrix K, frequencies omega, and target topology, the objective is

w_depth * routed_depth + w_error * trotter_error + w_infidelity * (1 - fidelity).

CostWeights requires finite non-negative weights and rejects the all-zero case. LayoutCost retains the total plus every unweighted value and weighted term; to_dict() produces a JSON-ready mapping without discarding provenance needed to interpret the objective.

Cost construction

kuramoto_layout_cost(...) validates a square coupling matrix, matching frequency vector, distinct non-negative physical indices, fidelity in [0, 1], positive finite evolution time, and positive repetition count. Invalid inputs fail before compilation or routing.

The default routed_layout_depth compiles the existing XY product-formula circuit and routes it with Qiskit against the supplied coupling map and initial layout. Callers may inject a DepthProvider when they already own a measured or cached routing result. Injection changes only the depth source; validation, Trotter error, fidelity pricing, and weighted assembly remain identical.

from qiskit.transpiler import CouplingMap
from scpn_quantum_control.hardware import CostWeights, kuramoto_layout_cost

cost = kuramoto_layout_cost(
    layout=(0, 1, 2, 3),
    K=coupling,
    omega=frequencies,
    coupling_map=CouplingMap([[0, 1], [1, 2], [2, 3]]),
    mean_gate_fidelity=0.99,
    weights=CostWeights(depth=1.0, trotter_error=50.0, infidelity=10.0),
)
print(cost.total, cost.routed_depth)

Reproducibility and evidence boundary

Qiskit routing can be stochastic. routed_layout_depth therefore accepts seed_transpiler; callers constructing a reproducible landscape must bind it. The routed depth is a compiler measurement for the supplied target and seed. The product-formula error is an analytic bound, and the fidelity term is a calibration-priced model. The combined objective is suitable for comparing placements under one fixed contract; it is not hardware success probability or evidence of quantum advantage.

dynq_mean_gate_fidelity(result) extracts the selected execution-region fidelity from a validated QubitMappingResult; it does not recompute or promote the mapper's calibration evidence.

API reference

scpn_quantum_control.hardware.kuramoto_layout_cost

Kuramoto-XY-aware discrete cost model for qubit-layout selection.

A candidate initial layout of the XY-Trotter circuit onto a hardware coupling map is scored by one number,

``C(layout, K, omega, coupling_map)``
    ``= w_depth · post-routing depth``
    ``+ w_error · Trotter error bound``
    ``+ w_infidelity · (1 − DynQ mean gate fidelity)``,

so a discrete optimiser can compare layouts on a single objective. The cost is continuous in the couplings K, frequencies omega, and gate fidelities, and discrete in the layout: only the post-routing depth depends on the integer layout, through the SWAP overhead the coupling map forces on the all-to-all XY interaction.

The three terms reuse existing surfaces rather than reimplementing them:

  • post-routing depth reuses :func:~scpn_quantum_control.phase.xy_compiler.compile_xy_trotter and Qiskit routing (injectable via depth_provider so a caller — or a test — can supply a cheaper or deterministic depth model);
  • the Trotter error reuses :func:~scpn_quantum_control.phase.trotter_error.trotter_error_bound;
  • the DynQ mean gate fidelity is the :class:~scpn_quantum_control.hardware.qubit_mapper.QubitMappingResult region fidelity (see :func:dynq_mean_gate_fidelity).

The cost function is pure and side-effect-free given a depth_provider, so the discrete optimiser can call it in a tight loop.

DepthProvider

Bases: Protocol

Callable returning the post-routing depth of a layout.

Implementations map a candidate layout of the n-qubit XY-Trotter circuit onto coupling_map and return the routed circuit depth. The default is :func:routed_layout_depth; tests and optimisers may inject a cheaper deterministic model.

__call__(layout, K, omega, coupling_map, *, t, reps)

Return the routed depth for layout.

CostWeights dataclass

Non-negative weights combining the three cost terms.

Parameters

depth Weight on the post-routing circuit depth (units: per depth layer). trotter_error Weight on the Trotter error bound. infidelity Weight on 1 − mean gate fidelity.

__post_init__()

Validate the weights.

Raises

ValueError If any weight is non-finite or negative, or if all three are zero.

to_dict()

Return a JSON-serialisable mapping of the weights.

LayoutCost dataclass

Scored cost of one candidate layout with its component breakdown.

to_dict()

Return a JSON-serialisable mapping of the cost and its terms.

dynq_mean_gate_fidelity(result)

Return the DynQ selected-region mean gate fidelity.

Parameters

result A DynQ mapping result from :func:~scpn_quantum_control.hardware.qubit_mapper.dynq_initial_layout.

Returns

float The mean gate fidelity of the selected execution region.

routed_layout_depth(layout, K, omega, coupling_map, *, t, reps, basis_gates=_DEFAULT_BASIS_GATES, optimization_level=1, seed_transpiler=None)

Return the post-routing depth of the XY-Trotter circuit under layout.

Builds the XY-optimised Trotter circuit with :func:~scpn_quantum_control.phase.xy_compiler.compile_xy_trotter, then routes it onto coupling_map with layout as the initial layout and returns the transpiled depth. The SWAP overhead the coupling map forces on the all-to-all XY interaction is exactly what makes the cost discrete in the layout.

Parameters

layout Initial layout: logical qubit i is placed on physical qubit layout[i]. K, omega Coupling matrix and frequency vector for the XY problem. coupling_map A Qiskit CouplingMap (or edge list) describing hardware connectivity. t, reps Evolution time and Trotter repetitions for the compiled circuit. basis_gates Target basis for transpilation. optimization_level Qiskit optimisation level for routing. seed_transpiler Transpiler seed; Qiskit routing is stochastic when unseeded, so pass a seed whenever the depth feeds a reproducible cost landscape (the discrete optimiser and the layout-method comparison do).

Returns

int The routed circuit depth.

kuramoto_layout_cost(layout, K, omega, coupling_map, *, mean_gate_fidelity, weights=None, t=0.1, reps=5, order=1, depth_provider=routed_layout_depth)

Score one candidate layout on the Kuramoto-XY-aware cost.

Parameters

layout Initial layout: logical qubit i on physical qubit layout[i]. K, omega Coupling matrix and frequency vector for the XY problem. coupling_map Hardware connectivity passed through to depth_provider. mean_gate_fidelity DynQ selected-region mean gate fidelity in [0, 1] (see :func:dynq_mean_gate_fidelity). weights Term weights; defaults to unit :class:CostWeights. t, reps, order Evolution time, Trotter repetitions, and product-formula order for the Trotter-error bound and the compiled circuit. depth_provider Callable returning the post-routing depth; defaults to :func:routed_layout_depth.

Returns

LayoutCost The total cost and its three weighted component terms.