Kuramoto layout-relaxation API

scpn_quantum_control.hardware.kuramoto_layout_relaxation studies whether an annealed Sinkhorn relaxation can improve on the repository's discrete layout search at a matched budget of true-cost evaluations. The surface remains research-labelled: its committed comparison found no consistent gain, so the discrete optimiser remains the recommended route.

Relaxation and rounding

sinkhorn_normalise(logits, n_iterations) alternates row and column normalisation in log space and returns a numerically doubly-stochastic matrix. swap_distance_surrogate(P, K, distances) then prices expected coupling-graph distance under the relaxed placement. The optimiser differentiates that surrogate, applies the gradient to placement logits, and rounds each annealing step with a Hungarian assignment.

Rounded candidates are evaluated by kuramoto_layout_cost, not by the surrogate. Consequently the comparison retains routed depth, product-formula error, calibrated fidelity, and the configured weights of the discrete-search objective.

Configuration and result

SinkhornRelaxationConfig binds the temperature endpoints, annealing and gradient step counts, learning rate, Sinkhorn iterations, true-cost budget, seed, cost weights, evolution time, repetitions, and formula order. Invalid temperatures, non-positive counts or rates, and malformed cost controls fail before search execution.

RelaxationSearchResult records the best rounded layout and its complete LayoutCost, the number of distinct true-cost evaluations, the surrogate trajectory, and the research label. Both records provide JSON-ready mappings.

from scpn_quantum_control.hardware import (
    SinkhornRelaxationConfig,
    relax_kuramoto_layout,
)

result = relax_kuramoto_layout(
    coupling,
    frequencies,
    coupling_map,
    physical_qubits=(0, 1, 2, 3, 4),
    mean_gate_fidelity=0.99,
    config=SinkhornRelaxationConfig(
        seed=7,
        n_anneal_steps=8,
        max_true_cost_evaluations=8,
    ),
)
print(result.best_layout, result.best_cost.total)

Evidence boundary

The surrogate is a differentiable search guide, not a hardware measurement or the comparison metric. A fixed seed makes the current NumPy search deterministic, while custom depth providers may carry their own provenance and reproducibility requirements. The result does not establish quantum advantage, hardware success, or promotion readiness; those require separate approved evidence.

The preregistration and measured no-gain outcome are recorded in layout_relaxation_preregistration.md. The surrounding mapper and discrete-search contract is documented in dynq_qubit_mapping.md.

API reference

scpn_quantum_control.hardware.kuramoto_layout_relaxation

RESEARCH: Sinkhorn continuous relaxation of the Kuramoto layout search.

Research label. This module implements the continuous-relaxation question preregistered in docs/layout_relaxation_preregistration.md: does an annealed Sinkhorn relaxation over placement logits beat the discrete optimiser (:func:~scpn_quantum_control.hardware.kuramoto_layout_optimiser.optimise_kuramoto_layout) on the true seeded layout cost at a matched evaluation budget? The honest outcome may be "modest or no gain"; nothing here is promoted beyond a research result without owner-approved isolated-host confirmation.

Method (Mena et al., arXiv:1802.08665; Jang et al., arXiv:1611.01144; Maddison et al., arXiv:1611.00712 — verified in the design doc):

1. relax the injective placement of n logical onto m candidate physical qubits into a doubly-stochastic matrix P = Sinkhorn(logits / τ) (dummy rows pad n < m);
2. descend a differentiable SWAP-distance surrogate S(P) = Σ_{i<j} K_ij · (P D Pᵀ)_{ij} (D = coupling-graph distances between candidates) with the closed-form gradient ∇_P S = K P D, applied straight-through to the logits (the Jang et al. estimator);
3. anneal τ downward; after each temperature, round with the Hungarian assignment and score the rounded layout with the true seeded layout cost — the surrogate never enters the comparison;
4. stop at the preregistered true-cost evaluation budget.

The comparison protocol, seeds, and the baseline reference numbers live in the design doc and in dynq_qubit_mapping.md §7.6/§8.5.

SinkhornRelaxationConfig dataclass

Configuration of the annealed Sinkhorn relaxation search.

Parameters

tau_initial, tau_final Initial and final Sinkhorn temperatures (annealed geometrically). n_anneal_steps Number of temperatures in the schedule; each proposes one rounded layout for true-cost scoring. n_gradient_steps Surrogate gradient-descent steps per temperature. learning_rate Step size on the placement logits. n_sinkhorn_iterations Row/column normalisation sweeps per Sinkhorn projection. max_true_cost_evaluations Budget of distinct rounded layouts scored with the true cost; None allows one per anneal step. This is the preregistered budget-match knob against the discrete-search baseline. seed Seed for the logit initialisation. weights True-cost term weights; None selects the unit defaults. t, reps, order Evolution time, Trotter repetitions, and product-formula order forwarded to the true cost.

__post_init__()

Validate the configuration.

Raises

ValueError If the temperatures are not positive and ordered, or any count or the learning rate is not positive, or the budget is not positive when set.

temperatures()

Return the geometric annealing schedule from initial to final τ.

to_dict()

Return a JSON-serialisable mapping of the configuration.

RelaxationSearchResult dataclass

Outcome of the relaxed-then-rounded layout search (research result).

to_dict()

Return a JSON-serialisable mapping of the search outcome.

sinkhorn_normalise(logits, n_iterations)

Project logits to a doubly-stochastic matrix in log space.

Alternating row and column log-sum-exp normalisation (the Sinkhorn operator of Mena et al., arXiv:1802.08665).

Parameters

logits Square real matrix. n_iterations Number of alternating normalisation sweeps.

Returns

numpy.ndarray A (numerically) doubly-stochastic matrix of the same shape.

coupling_graph_distances(coupling_map, physical_qubits)

Return pairwise shortest-path distances between candidate qubits.

Breadth-first search over the undirected coupling graph restricted to the full device (paths may leave the candidate set), evaluated between every pair of candidates.

Parameters

coupling_map A Qiskit CouplingMap (anything exposing get_edges()) or an iterable of directed edge pairs. physical_qubits Candidate physical qubits.

Returns

numpy.ndarray (m, m) matrix of hop distances between candidates.

Raises

ValueError If any pair of candidates is disconnected in the coupling graph — the surrogate is undefined there (fail-closed).

swap_distance_surrogate(P, K, distances)

Return the expected SWAP-distance load of a relaxed placement.

S(P) = Σ_{i<j} K_ij · (P D Pᵀ)_{ij} — continuous in P, correlating with the SWAP overhead routing must pay for distant strongly coupled pairs. Only the first n rows of P (the real logical qubits) contribute, because K is zero on the dummy padding.

Parameters

P Doubly-stochastic placement matrix (m × m; rows n..m are dummy padding when n < m). K Coupling matrix zero-padded to m × m. distances Candidate-pair distance matrix D.

Returns

float The surrogate value.

relax_kuramoto_layout(K, omega, coupling_map, physical_qubits, *, mean_gate_fidelity, config=None, initial_layout=None, depth_provider=routed_layout_depth)

Run the annealed Sinkhorn relaxation and score rounded layouts truly.

Parameters

K, omega Coupling matrix and frequency vector; K fixes the logical count. coupling_map Hardware connectivity (distances for the surrogate; forwarded to the true cost's depth_provider). physical_qubits Candidate physical qubits (distinct, non-negative, at least n). mean_gate_fidelity DynQ selected-region mean gate fidelity in [0, 1]. config Relaxation configuration; None selects the defaults. initial_layout Optional warm-start layout: its placements receive a positive logit bias so the relaxation starts near the (e.g. DynQ) seed. depth_provider Depth callable for the true cost; defaults to :func:~scpn_quantum_control.hardware.kuramoto_layout_cost.routed_layout_depth.

Returns

RelaxationSearchResult The best rounded layout by true cost, the number of distinct true-cost evaluations spent, and the surrogate trajectory (reported for diagnostics only — never used for the comparison).

Raises

ValueError If the search space, seed layout, or cost inputs are malformed, or the candidates are disconnected in the coupling graph.