Topology-Aware Quantum Kernel¶

BL-88 provides a bounded local product for asking one precise question: does an edge-aligned XY feature map retain the inductive bias of a declared coupling graph strongly enough to reproduce labels generated by that same kernel?

The public facade is scpn_quantum_control.topology_kernel_product. It builds exact local statevectors, fidelity Gram and cross-kernel matrices, a regularised kernel-ridge classifier, graph and classical controls, deterministic evidence, and byte-checkable custody artefacts. It performs no provider call or hardware execution.

Claim boundary first¶

The committed experiment is deliberately teacher-aligned: labels are generated from similarity to two frozen prototypes under the same ring-topology kernel later evaluated as the primary method. Its 100% held-out score is therefore evidence that the implemented classifier represents its declared topology-aware feature map. It is not independent generalisation evidence.

BL-88 does not establish:

quantum or computational advantage;
performance on independently sourced labels;
tokamak, EEG, power-grid, biological, or other domain fitness;
provider compatibility, QPU execution, noise robustness, or hardware value;
superiority of ring graphs in general; or
that a large Hilbert space automatically yields a useful kernel.

Feature-map definition¶

For n graph nodes, features are aligned with the canonical upper-triangle edge order

\[ E_n=((0,1),(0,2),\ldots,(n-2,n-1)). \]

canonical_edge_pairs(n) is the single source of truth for this ordering. The feature dimension is n * (n - 1) // 2. Given a symmetric, zero-diagonal coupling matrix K, feature x[k] modulates only the matching edge:

\[ \widetilde K_{ij}(x)=K_{ij}x_{k(i,j)}. \]

The local circuit prepares |+>**n and applies a Lie–Trotter synthesis of the XY Hamiltonian

\[ H_K(x)=-\sum_{i<j}\widetilde K_{ij}(x)(X_iX_j+Y_iY_j), \qquad |\phi_K(x)\rangle=e^{-itH_K(x)}|+\rangle^{\otimes n}. \]

Unlike the older compatibility encoder in applications.quantum_kernel, this path adds no local RZ feature rotations and never cycles a shorter feature vector across edges. A zero coupling is an explicit topology mask: its aligned feature cannot affect the state.

The fidelity kernel is

\[ k_K(x,y)=|\langle\phi_K(x)|\phi_K(y)\rangle|^2. \]

All values come from dense exact qiskit.quantum_info.Statevector objects. The default policy caps the product at four qubits and 64 samples per kernel axis; the public configuration refuses more than eight qubits or 256 samples.

Minimal classifier workflow¶

import numpy as np

from scpn_quantum_control.topology_kernel_product import (
    TopologyKernelConfig,
    evaluate_kernel_ridge,
    fidelity_kernel_matrix,
    fit_kernel_ridge,
    ring_topology,
)

config = TopologyKernelConfig(n_qubits=3, max_samples=4)
features = np.array(
    [
        [0.1, 0.2, 0.3],
        [-0.1, -0.2, -0.3],
    ]
)
labels = np.array([1, -1])
ids = ("positive", "negative")

gram = fidelity_kernel_matrix(
    features,
    features,
    ring_topology(3),
    config,
    row_ids=ids,
    column_ids=ids,
)
model = fit_kernel_ridge(gram, labels, alpha=config.ridge)
result = evaluate_kernel_ridge("ring", model, gram, labels)

assert result.accuracy == 1.0
assert not gram.values.flags.writeable

Identifiers are part of the numerical contract. A training matrix must be square with identical row and column identifiers. A prediction matrix must be test-by-train, must use the model's exact training identifiers on its columns, and must carry the same topology digest. Mismatches raise instead of silently reordering coefficients.

Shapes, budgets, and failure modes¶

Surface	Required input	Returned object	Main refusal conditions
`TopologyKernelConfig`	`n_qubits` in `[2,8]`, positive time/ridge, Trotter reps in `[1,16]`	Frozen policy	Invalid type, range, or non-finite value
`validate_topology`	Symmetric finite `(n,n)`, zero diagonal	Read-only defensive copy	Shape, diagonal, symmetry, finiteness
`validate_feature_matrix`	Finite `(samples,n(n-1)/2)`	Read-only defensive copy	Feature width or sample budget
`fidelity_kernel_matrix`	Two feature axes, topology, exact IDs	`TopologyKernelMatrix`	Invalid axes, IDs, topology, or allocation budget
`rbf_kernel_matrix`	Two feature axes and positive gamma	`TopologyKernelMatrix`	Invalid gamma, axes, or IDs
`fit_kernel_ridge`	Square aligned kernel and binary labels	`KernelRidgeClassifier`	Misaligned IDs, non-binary labels, invalid ridge
`predict_kernel_ridge`	Test-by-train kernel	Read-only `{-1,+1}` vector	Training IDs or topology digest differ
`build_teacher_aligned_dataset`	Frozen policy and seed	`TopologyKernelDataset`	Unbalanced split, unsafe pool, insufficient class tails

All matrix, feature, label, prototype, coefficient, and prediction arrays in public records are defensive copies marked read-only. SHA-256 digests bind topology bytes, axis identifiers, matrix bytes, fitted coefficients, and the frozen dataset/evidence payloads.

Simultaneous graph relabeling¶

permute_topology and permute_edge_features use the same convention: permutation[new_node] is the original node represented at the new position. Applying both transformations together must preserve every fidelity. The committed four-node cyclic relabeling changes the primary probe Gram matrix by at most 4.441e-16.

Relabeling only the topology or only the edge features is a different experiment and is not required to preserve the kernel.

Frozen synthetic task¶

The evidence builder fixes:

Field	Value
Seed	880
Qubits/nodes	4
Canonical edge features	6
Candidate pool	256
Training samples	32, balanced
Test samples	16, balanced
Evolution time	0.8
Trotter repetitions	2
Ridge regularisation	0.001
Classical RBF gamma	0.2

The generator draws two prototypes and 256 candidates uniformly from [-pi, pi]. It scores each candidate by

\[ k_{ring}(x,p_+) - k_{ring}(x,p_-), \]

selects equal numbers from the positive and negative tails, interleaves them, and takes the first 32 for training and the final 16 for testing. Train and test IDs remain disjoint source-candidate IDs. The minimum selected absolute teacher margin is 0.22085677522668157.

Controls and committed result¶

Every quantum control fits a fresh kernel-ridge model on the same features and labels. Only the coupling topology changes. The classical RBF control uses the same features, split, ridge regularisation, and evaluation labels.

Kernel	Correct	Total	Accuracy
Ring teacher topology	16	16	1.0000
Path topology	4	16	0.2500
Complete topology	9	16	0.5625
Zero-coupling topology	8	16	0.5000
Classical RBF, gamma 0.2	8	16	0.5000

The primary Gram matrix is symmetric to machine precision, has maximum diagonal error 1.998e-15, and has minimum symmetrised eigenvalue 0.0015427469852438568. These checks support correct finite-kernel construction; they do not promote the comparison into an advantage claim.

Evidence content digest: a960ec0386d892518548c0d00cb8bc765301768ef52c4b29a6922050eb1d2c22.

Regenerate or byte-check both committed artefacts:

PYTHONPATH=src:oscillatools/src python scripts/run_topology_kernel_product_evidence.py
PYTHONPATH=src:oscillatools/src python scripts/run_topology_kernel_product_evidence.py --check

The canonical payload and rendered companion live in data/topology_kernel_product/.

Notebook 52_topology_aware_quantum_kernel.ipynb uses only the public facade and local statevectors. It stores no executed outputs.

Work-package decisions¶

S88.1 supported: one feature is aligned to every canonical undirected edge and modulates only that XY coupling.
S88.2 supported: exact Gram/cross matrices, identifier custody, and regularised binary kernel classification are implemented.
S88.3 descoped: BL-63 has no implemented domain kit or typed consumer, so no tokamak, EEG, grid, or other domain bridge is invented.
S88.4 supported: path, complete, zero-coupling, RBF, PSD, diagonal, symmetry, and simultaneous-relabeling controls are committed.

Scientific basis¶

Havlíček et al. define quantum-enhanced feature spaces and fidelity-style quantum kernels, Nature 567, 209–212 (2019), DOI 10.1038/s41586-019-0980-2.
Huang et al. analyse power and limitations of quantum kernels, including positive-semidefinite Gram matrices and engineered-label experiments, Nature Communications 12, 2631 (2021), DOI 10.1038/s41467-021-22539-9.
Kübler, Buchholz, and Schölkopf show why access to a large quantum feature space alone does not guarantee a useful learning advantage, arXiv:2106.03747.
Rieck et al. demonstrate topology-aware graph kernels in a classical setting; this motivates careful graph relabeling and controls without implying that their persistent Weisfeiler–Lehman construction is implemented here, PMLR 97.

These sources constrain terminology and experimental design. They do not validate this repository's synthetic thresholds, labels, domain relevance, or hardware performance.

Public API map¶

Responsibility	Public symbols
Policy and records	`TopologyKernelConfig`, `TopologyKernelMatrix`, `TopologyKernelDataset`, `KernelEvaluation`, `TOPOLOGY_KERNEL_CLAIM_BOUNDARY`
Kernel construction	`validate_topology`, `validate_feature_matrix`, `topology_digest`, `fidelity_kernel_matrix`, `rbf_kernel_matrix`
Relabeling	`permute_topology`, `permute_edge_features`
Classification	`KernelRidgeClassifier`, `fit_kernel_ridge`, `predict_kernel_ridge`, `evaluate_kernel_ridge`
Synthetic controls	`ring_topology`, `path_topology`, `complete_topology`, `zero_topology`, `build_teacher_aligned_dataset`
Evidence	`KernelSupportRow`, `TopologyKernelEvidence`, `build_topology_kernel_evidence`, `render_topology_kernel_markdown`, `write_topology_kernel_evidence`

See the complete API reference for every public symbol's parameters, returns, exceptions, shapes, and claim boundaries.