NystromNet

Research implementation for characterizing a QFT/Nyström-QSVM iris-recognition pipeline and a server-keyed revocable helper-data scheme. It does not claim quantum advantage, physical QRNG entropy, or formal fuzzy-extractor security. The reference workflow targets the 126 UBIRIS.v2 identities present in both sessions and enforces an honest split: S1 is used for training/validation and S2 is kept untouched until final evaluation.

Pipeline

iris photo -> segmentation -> 64x256 polar band + occlusion mask
           -> fixed 2,048-D sparse Log-Gabor iris code
           -> train-only TruncatedSVD -> standardize/clip -> [-pi, pi]
           -> interleaved angle encoding + QFT fidelity kernel
           -> balanced class-wise medoid landmarks -> Nystrom features
           -> linear SVM

The QFT is interleaved between data-dependent encoding layers. It is not appended as a common final unitary, which would cancel from a fidelity kernel. Training kernels use only their upper triangle, rectangular kernels are evaluated in broadcast batches, and the PennyLane device/QNode is constructed once per kernel engine.

Install and run

py -3.12 -m venv .venv
.venv\Scripts\pip install -e ".[dev]"
.venv\Scripts\nystromnet train `
  --dataset-root F:\tmp\ubirisv2_full\UBIRIS_800_600 `
  --output-dir artifacts\ubiris_q6

Load the final model without serializing a PennyLane device and recognize new photographs with:

.venv\Scripts\nystromnet predict `
  --model artifacts\ubiris_q6\final\nystrom_qsvm.joblib `
  --image F:\path\to\probe.tiff

Protected-template enrollment mixes PennyLane quantum samples with the OS CSPRNG, conditions the result, and authenticates revocable helper data with a server-held key. A simulator is clearly recorded as simulated and is never treated as the security entropy floor. Keep the binding key out of arguments and source control:

$env:NYSTROMNET_BINDING_KEY_HEX = '<at-least-32-random-bytes-as-hex>'
.venv\Scripts\nystromnet token-enroll `
  --model artifacts\ubiris_q6\final\nystrom_qsvm.joblib `
  --image F:\path\enrollment1.tiff F:\path\enrollment2.tiff `
  --token-output artifacts\identity.token.json
.venv\Scripts\nystromnet token-verify `
  --model artifacts\ubiris_q6\final\nystrom_qsvm.joblib `
  --image F:\path\probe.tiff `
  --token artifacts\identity.token.json

The supplied F:\tmp\ubirisv2_full\ubiris2_1.zip is encrypted and the currently extracted ubiris_seg tree contains binary segmentation masks, not iris photographs. NystromNet detects mask-only data and refuses an accuracy run. --allow-mask-only exists solely for pipeline smoke tests; metrics from that mode are explicitly marked invalid for biometric evaluation.

Recommended first run uses 6 qubits, 24 SVD components, one landmark per identity, C in {1, 10}, a 3-sigma angle clip, and no probability calibration during selection. Use --landmarks-per-class 2 before increasing the circuit size. With 24 components on 6 qubits, four encoding/QFT layers are required to use every component; --encoding-layers 2 intentionally uses only the first 12 components and is provided only as a faster ablation.

Artifacts are saved independently beneath the output directory:

• sparse descriptors and sample manifest;
• fitted compressor and compressed arrays;
• landmark indices;
• landmark and sample-to-landmark kernels;
• Nyström-QSVM model, metrics, and run manifest.
• raw probe-by-class scores, genuine/impostor scores, ROC/DET/EER, low-FMR operating points, d-prime, CMC, bootstrap intervals, and Gram diagnostics;
• a full 2,048-D classical linear-SVM control evaluated on the identical split.

Never commit artifacts: even protected biometric templates remain sensitive.

The falsifiable thesis, locked evaluation protocol, required ablations, segmentation study, security limits, governance checklist, and literature positioning are specified in RESEARCH_PROTOCOL.md.

CUST-Iris

CUST-Iris is supported as an eye-class recognition dataset. Its matching PNG masks are used to estimate non-concentric pupil/iris boundaries and exclude invalid polar samples. Captures 1-2 train the model, capture 3 is validation, and capture 4 remains the final test. Each left/right eye is a distinct class.

.venv\Scripts\nystromnet train `
  --dataset-format cust `
  --dataset-root artifacts\cust_iris\raw\images\CUST-Iris `
  --output-dir artifacts\cust_iris\full_q6_f24_l4_m2 `
  --qubits 6 --compressed-features 24 --encoding-layers 4 `
  --landmarks-per-class 2 --c-values 10 `
  --kernel-mode statevector --n-jobs 8

statevector mode is an exact simulator optimization: each QFT feature state is evaluated once and fidelity is calculated from state overlaps. The hardware-compatible projector mode retains the reusable projector QNode. Pass publisher-supplied masks at inference with --mask when benchmarking the mask-assisted CUST protocol.

Tests

.venv\Scripts\pytest

Dense Dynamic QSVM QFT for Biometric Security