Topology Kernel Product API¶
scpn_quantum_control.topology_kernel_product is the public BL-88 facade for
bounded topology-aware fidelity kernels, custody-checked kernel ridge
classification, deterministic graph controls, and frozen synthetic evidence.
All quantum values use exact local statevectors. Public records hold defensive, read-only arrays and SHA-256 custody. Identifier, topology, shape, finiteness, and resource mismatches raise rather than being silently coerced. No API on this page submits a provider job or claims hardware execution, quantum advantage, independent generalisation, or application-domain fitness.
For equations, a complete workflow, frozen metrics, scientific sources, and non-claims, read Topology-Aware Quantum Kernel.
Configuration and immutable records¶
scpn_quantum_control.topology_kernel_product.schema
¶
Immutable contracts for the bounded BL-88 quantum-kernel product.
TopologyKernelConfig
dataclass
¶
Resource and numerical policy for topology-aware kernel evaluation.
Parameters¶
n_qubits:
Number of graph nodes/qubits. Dense simulation is restricted to
[2, 8].
evolution_time:
Positive finite XY evolution time.
trotter_reps:
Lie–Trotter repetition count in [1, 16].
max_samples:
Maximum rows or columns accepted by a single kernel call.
ridge:
Positive diagonal regularisation for kernel ridge classification.
feature_dim
property
¶
Return the number of canonical undirected graph edges.
TopologyKernelMatrix
dataclass
¶
A custody-bound fidelity-kernel matrix.
Parameters¶
values:
Finite two-dimensional fidelity values in [0, 1] up to numerical
tolerance. A defensive, read-only copy is stored.
row_ids, column_ids:
Unique sample identifiers matching the matrix axes.
topology_digest:
SHA-256 of the exact validated coupling matrix.
content_digest:
SHA-256 binding values, identifiers, and topology digest.
claim_boundary:
Explicit interpretation limit propagated with the result.
TopologyKernelDataset
dataclass
¶
Frozen balanced train/test split for teacher-aligned evidence.
The labels are derived from two frozen prototype similarities under the primary ring kernel. Consequently this dataset tests whether the product can reproduce its own declared inductive bias; it is not an independently labelled scientific or application benchmark.
Parameters¶
train_features, test_features:
Finite edge-feature matrices with equal feature width.
train_labels, test_labels:
Balanced binary labels encoded as -1 and +1.
train_ids, test_ids:
Unique, mutually disjoint sample identifiers.
teacher_prototypes:
Two edge-feature rows defining positive and negative teacher anchors.
teacher_topology_digest:
SHA-256 of the ring topology used to generate labels.
content_digest:
SHA-256 binding all dataset contents and identifiers.
KernelEvaluation
dataclass
¶
Predictions and exact accuracy for one named kernel control.
Parameters¶
name: Stable, non-empty control name. predictions, labels: Read-only binary arrays of equal non-zero length. correct, total, accuracy: Internally consistent classification counts and ratio. kernel_digest: SHA-256 of the evaluated cross-kernel matrix.
Fidelity and classical kernels¶
scpn_quantum_control.topology_kernel_product.kernels
¶
Validated exact-statevector and classical-control kernel construction.
validate_topology(topology, config)
¶
Return a read-only validated coupling topology.
Parameters¶
topology:
Finite symmetric (n_qubits, n_qubits) matrix with zero diagonal.
Signed, weighted off-diagonal couplings are accepted.
config:
Kernel configuration fixing n_qubits.
Returns¶
numpy.ndarray
Defensive read-only float64 copy.
Raises¶
ValueError If the matrix violates shape, finiteness, symmetry, or diagonal requirements.
topology_digest(topology, config)
¶
Return SHA-256 custody for an exact validated topology matrix.
The digest binds row-major little-endian float64 bytes and the qubit
count. Numerically equal matrices with different input dtypes therefore
receive the same digest after validation.
validate_feature_matrix(features, config, *, name='features')
¶
Return a finite read-only edge-feature matrix within sample budgets.
Each row must contain exactly config.feature_dim values, ordered as
:func:scpn_quantum_control.applications.canonical_edge_pairs.
fidelity_kernel_matrix(row_features, column_features, topology, config, *, row_ids, column_ids)
¶
Evaluate a topology-aware exact-statevector fidelity kernel.
Parameters¶
row_features, column_features:
Edge-feature matrices in canonical upper-triangle order. Each axis is
independently bounded by config.max_samples.
topology:
Validated graph coupling matrix. A zero off-diagonal entry suppresses
its aligned feature.
config:
Qubit, simulation, and resource policy.
row_ids, column_ids:
Unique identifiers matching the two feature axes.
Returns¶
TopologyKernelMatrix
Matrix with entries |<phi(x_i)|phi(y_j)>|**2 plus topology and
content digests.
Notes¶
This routine performs dense local statevector simulation. It neither submits jobs nor infers performance on a quantum processor.
rbf_kernel_matrix(row_features, column_features, config, *, gamma, row_ids, column_ids)
¶
Evaluate a classical radial-basis-function comparison kernel.
gamma must be finite and positive. The returned topology_digest is
a stable digest of the literal control label classical-rbf and gamma;
it must not be interpreted as graph custody.
permute_topology(topology, permutation, config)
¶
Relabel graph nodes and return the corresponding read-only topology.
permutation[new_node] names the original node represented at each new
position. It must be a complete permutation of range(n_qubits).
permute_edge_features(features, permutation, config)
¶
Relabel canonical edge features consistently with graph nodes.
For every new pair (i, j), the returned feature is read from the old
canonical pair joining permutation[i] and permutation[j]. Applying
this together with :func:permute_topology should preserve fidelities.
Kernel ridge classification¶
scpn_quantum_control.topology_kernel_product.classifier
¶
Custody-checked binary kernel ridge fitting and evaluation.
KernelRidgeClassifier
dataclass
¶
Immutable binary classifier fitted from a precomputed kernel.
Parameters¶
train_ids:
Ordered identifiers for coefficient alignment at prediction time.
coefficients:
Solution of (K + alpha I) coefficients = labels.
alpha:
Positive diagonal regularisation used during fitting.
topology_digest:
Kernel/topology family digest required on every prediction matrix.
training_kernel_digest:
Content digest of the exact square training kernel.
content_digest:
SHA-256 binding identifiers, coefficients, alpha, and kernel custody.
fit_kernel_ridge(kernel, labels, *, alpha)
¶
Fit a binary ridge classifier from a square training kernel.
Parameters¶
kernel:
Square, identifier-aligned training kernel.
labels:
One -1 or +1 label per training row.
alpha:
Positive finite diagonal regularisation.
Returns¶
KernelRidgeClassifier Immutable coefficient vector with exact kernel custody.
Raises¶
ValueError If identifiers are misaligned, labels are not binary, regularisation is invalid, or the solve produces non-finite coefficients.
predict_kernel_ridge(model, cross_kernel)
¶
Predict binary labels from a test-by-train cross-kernel matrix.
The cross-kernel columns must exactly match the fitted train_ids and
its topology/control digest must match the fitted kernel family. Scores at
exactly zero deterministically map to +1.
evaluate_kernel_ridge(name, model, cross_kernel, labels)
¶
Predict and return a self-consistent named accuracy record.
Parameters¶
name:
Stable label such as ring or classical_rbf.
model:
Previously fitted kernel ridge classifier.
cross_kernel:
Test-by-train kernel with matching custody and training identifiers.
labels:
Expected binary test labels, one per cross-kernel row.
Synthetic task and graph controls¶
scpn_quantum_control.topology_kernel_product.synthetic
¶
Deterministic graph controls and teacher-aligned synthetic data.
ring_topology(n_qubits)
¶
Return an unweighted undirected cycle adjacency matrix.
For two nodes the simple cycle collapses to their single undirected edge; no parallel-edge weight is introduced.
path_topology(n_qubits)
¶
Return an unweighted undirected path adjacency matrix.
complete_topology(n_qubits)
¶
Return an unweighted complete-graph adjacency matrix.
zero_topology(n_qubits)
¶
Return the all-zero topology used as a no-coupling control.
build_teacher_aligned_dataset(config, *, seed=880, candidate_count=256, train_count=32, test_count=16)
¶
Build the frozen balanced BL-88 representability task.
Two prototype vectors and a candidate pool are drawn uniformly from
[-pi, pi]. Candidates are ranked by the difference between their ring
kernel similarities to the positive and negative prototype. Equal counts
from the two tails are interleaved, then split without shuffling.
Parameters¶
config:
Kernel configuration. train_count and test_count must each fit
its sample budget.
seed:
Non-negative NumPy generator seed. BL-88 evidence fixes this at 880.
candidate_count:
Candidate pool size in [train_count + test_count, 256].
train_count, test_count:
Positive even split sizes. Each split is exactly balanced.
Returns¶
TopologyKernelDataset Immutable features, labels, source candidate identifiers, prototypes, and SHA-256 custody.
Notes¶
Because labels and evaluation share the ring-kernel family, good accuracy is circular representability evidence rather than independent predictive validation.
Evidence contracts and rendering¶
scpn_quantum_control.topology_kernel_product.evidence
¶
Deterministic evidence and claim-boundary rendering for BL-88.
KernelSupportRow
dataclass
¶
One explicit implementation or descoping decision.
Parameters¶
capability:
Stable work-package capability name.
status:
supported by this product slice or deliberately descoped.
evidence:
Exact implementation or verification fact.
boundary:
Interpretation the row does not establish.
to_dict()
¶
Return deterministic JSON-compatible support fields.
TopologyKernelEvidence
dataclass
¶
Frozen BL-88 synthetic result, numerical checks, and controls.
Parameters¶
schema_version, generated_on: Versioned evidence format and fixed generation date. seed, n_qubits, feature_dim, train_count, test_count: Frozen synthetic task dimensions. dataset_digest, ring_gram_digest: SHA-256 custody for the exact dataset and primary training Gram matrix. ring, path, complete, zero, classical_rbf: Test-set predictions and accuracies from independently fitted kernel ridge models. The first four differ only in graph coupling topology. minimum_teacher_margin: Smallest absolute prototype-similarity difference in selected data. gram_symmetry_max_abs_error, gram_diagonal_max_abs_error: Numerical primary-Gram invariants. gram_minimum_eigenvalue: Smallest eigenvalue of the symmetrised primary Gram matrix. permutation_max_abs_error: Fidelity change after simultaneous node and edge-feature relabeling. support: Ordered implementation and descoping ledger. claim_boundary: Mandatory limit on scientific and operational interpretation. content_digest: SHA-256 of every preceding canonical evidence field.
build_topology_kernel_evidence(*, config=None, seed=880)
¶
Build deterministic BL-88 evidence with four topology controls.
The frozen defaults use four qubits, six canonical edge features, 32 train samples, 16 test samples, seed 880, and RBF gamma 0.2. The ring kernel is the label-generating teacher; path, complete, zero-coupling, and RBF evaluations are explicit controls. All quantum values are exact local statevector fidelities.
Returns¶
TopologyKernelEvidence Custody-bound metrics, predictions, invariants, and support ledger.
render_topology_kernel_markdown(evidence)
¶
Render a concise human-readable companion to canonical JSON evidence.
write_topology_kernel_evidence(evidence, json_path, markdown_path, *, check=False)
¶
Write or byte-check canonical JSON and Markdown evidence.
Parameters¶
evidence: Frozen record to serialise. json_path, markdown_path: Distinct explicit output targets. check: When true, require both existing files to exactly equal regenerated bytes and raise without writing on any difference. When false, parent directories are created and only the two exact targets are replaced.
Returns¶
tuple[pathlib.Path, pathlib.Path] JSON and Markdown paths in argument order.
Raises¶
ValueError If evidence is the wrong type or paths are equal. RuntimeError In check mode when a file is absent or its bytes differ.