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.