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.
