File: quantum_ml_workshop/20260814/lab_02/AAREADME.txt Tool: The NEDC QML Workshop, Lab 02: Quantum Kernels and Variational Circuits Version: 1.0.0 ------------------------------------------------------------------------------- Change Log: 20260813 (AM): initial version ------------------------------------------------------------------------------- SUMMARY Lab 02 is the hands-on companion to Session 3. It builds both of the paths described in the lecture, on the same data, so you can feel the difference between them: Path A a quantum kernel feeding a classical support vector machine. The quantum computer is a fixed ruler and the learning stays classical. Path B a variational circuit. The circuit itself is the model and there is no separate classical learner. The lab answers one question throughout: how similar are these systems, and what are the significant differences? Every segment computes the same thing, and only the ruler changes. The notebook is organized into six segments. Each one teaches an idea, runs the code, gives you an exercise, and then shows the solution. Segment 1 a classical SVM, and seeing that a kernel is a similarity table Segment 2 the quantum kernel written in three lines of numpy, then broken on purpose to show what controls whether it works Segment 3 the same kernel measured from shots on a simulator, then with a device noise model Segment 4 a kernel measured on ibm_kingston, a real 156-qubit processor, and what that costs Segment 5 Path B: training a variational circuit, and data re-uploading Segment 6 the dataset where a quantum kernel wins outright, and why The single most useful result in the lab is in Segment 2. The same circuit on the same data scores near chance or near perfect depending only on which scaler you use. The encoding decides everything. A. WHAT'S NEW Version 1.0.0: + initial release B. INSTALLATION REQUIREMENTS See section B of the AAREADME.txt in the parent directory. In short, either select the nedc_03.11 kernel, which already has everything installed and tested, or build your own environment from requirements.txt. This lab also uses scikit-learn, which Lab 01 does not. C. USER'S GUIDE The lab directory contains: lab_02/ AAREADME.txt this file l02_v00.ipynb the lab notebook run_experiment.py command line tool for your own experiments qmllab/ the helper package used by the notebook data/ seven two-dimensional datasets in IMLD csv format configs/ saved experiment settings you can reuse results/ cached hardware results and the job script C.1. RUNNING THE NOTEBOOK 1. open l02_v00.ipynb in VS Code or Jupyter 2. select the nedc_03.11 kernel, or your own environment 3. run the version check cell at the top 4. work through the notebook from top to bottom The whole notebook runs in about six minutes. Run the cells in order; later cells use variables defined earlier. Try each exercise before opening the solution below it. C.2. USING YOUR OWN DATA Datasets are stored in the IMLD csv format: a header where every line begins with a '#', then one row per sample as "label, x1, x2" with six decimal places. The label is column 0. # filename: ./data/imld_two_moons.csv # classes: [0,1] # colors: [#1f77b4,#ff7f0e] # limits: [-1.0,1.0,-1.0,1.0] # 0, 0.229829, 0.436207 Seven datasets ship with the lab: two_moons, two_spirals, checkerboard, yin_yang, noisy_xor, toroidal, and circles. Segment 1 of the notebook has a DATASET_PATH variable. Point it at any IMLD file and the entire lab runs on your data instead. C.3. RUNNING YOUR OWN EXPERIMENTS Everything in the notebook can also be run from the command line: python run_experiment.py --compare --output out/moons runs a classical SVM and a quantum kernel SVM on the same split, prints a comparison table with a verdict, and writes the results, a summary and a decision boundary into the output directory python run_experiment.py --scaler-study runs every scaler and shows why the encoding decides the outcome python run_experiment.py --dataset-path data/my_train.csv \ --eval-path data/my_eval.csv --compare uses your own training and evaluation files. When an evaluation file is given there is no train/test split: the whole dataset trains and that file does the scoring. python run_experiment.py --help lists every option, with more examples C.4. RUNNING ON REAL QUANTUM HARDWARE Segment 4 of the notebook replays a job that was measured ahead of time on ibm_kingston, so the lab never waits on a queue. No account is needed to run the lab. If you do want to run on a real processor, Segment 4.5 makes it easy. There are no files to create and nothing to configure: 1. get a free API key at https://quantum.cloud.ibm.com 2. paste it between the quotes in the IBM_API_KEY cell 3. run the cells That is the whole setup. The notebook finds your instance CRN, connects, picks the processor with the shortest queue, and can measure a small 10x10 kernel on real hardware for about 14 seconds of quantum time. Three notes on that: (1) Treat your API key like a password, and clear the cell before sharing the notebook with anyone. (2) The instance CRN is handled for you. It matters because an IBM Cloud account usually owns several services, and attaching to the wrong one fails with an error that looks like a network problem but is not. backends.connect() looks up the right one automatically. (3) Quantum processor time is scarce. The free Open plan gives about ten minutes per month. A 10x10 kernel costs about 14 seconds and a 20x20 about one minute. Both the notebook and results/hw_kernel_job.py print an estimate before spending anything. ------------------------------------------------------------------------------- If you have any additional comments or questions about this lab, please direct them to help@nedcdata.org. We will do our best to answer them. Best regards, Joe Picone Sadia Afrin Purba Abdullah Al Mamun Copyright (c) 2026 Dr. Joseph Picone and the Neural Engineering Data Consortium (NEDC), Temple University. All rights reserved.