The Qiskit Environment

2.1 Python and Environments

Our experiment starts from \(\ket0\), applies H, and measures, many times. Since \(H\ket0=(\ket0+\ket1)/\sqrt2\), each outcome has probability one half, so we expect a fair coin. Writing this program needs a few Python features beyond the Bell function, and running it elsewhere needs the same software. We take the language first and the software second.

2.1.1 Python through circuit examples

How do we tell the computer to build \(H\ket0\), measure it many times, and count the outcomes? The building part uses only what we already know. We name a one-qubit circuit and append gates with method calls:

circuit = QuantumCircuit(1)
circuit.h(0)
circuit.measure_all()

The method measure_all() measures every qubit. It also adds a classical register, a row of classical bits that holds the results, and names it meas.

Running the circuit is the job of a sampler, an object that runs circuits and returns their measured outcomes. A sampler is built to run many circuits in one request, so it expects a list of circuits, even when we have only one. Square brackets make a list: [circuit] is a list with one item, and [a, b] has two. Inputs can also be given by name, as in shots=4096, which asks for 4096 repetitions.

What comes back is a tally: how many times each bit string appeared. Python stores such a tally as a dictionary, a table that maps each key to a value. A run might return {'1': 2030, '0': 2066}, where the keys are the bit strings and the values are their counts. We look up a value with counts.get("1", 0). The second argument is what we get if the key is missing, which happens when a string never occurred. The expression sum(counts.values()) adds all the counts.

Finally, we turn our prediction into checks with assert, as in the Bell program. The test == asks whether two values are equal, < asks whether one is smaller, and abs gives an absolute value.

2.1.2 Packages, versions, and isolated environments

Suppose the coin program runs on our computer but fails on a friend’s, with an error saying some name does not exist. How can the same text behave differently?

The program is not the only code involved. Its import lines pull in packages, bundles of code written by others and installed separately, such as qiskit. Each package exists in many versions, and between versions names change and behaviour can change. A package also relies on other packages, its dependencies, which have versions of their own. So the friend’s machine runs our text with different code underneath it.

The remedy has two parts. First we record the exact versions we tested. The file requirements.txt lists them as lines such as qiskit==2.6.0, which pins that package to one version. A second file, requirements-lock.txt, records every package that was installed, including the dependencies of dependencies.

Second, we install those versions in a virtual environment, a folder holding its own Python and its own packages, separate from the rest of the computer. Other projects then cannot change our versions, and we cannot change theirs. From the repository root, the first command below creates the environment, and the second switches the terminal to it. The third uses pip, Python’s package installer, to install the pinned versions. The fourth runs the companion program. The accompanying TESTING.md records the Python version and platform on which the companions were tested.

python3 -m venv .venv-quantum
source .venv-quantum/bin/activate
python -m pip install -r education/programming/requirements.txt
python education/programming/examples/chapter_02.py

2.2 The Qiskit Ecosystem

The requirements file installs three Qiskit packages, not one. Why three, and which do we need to flip a simulated coin? Once the software is installed, we must also decide where the program lives: in a script or in a notebook. The packages come first, because they decide what can run locally.

2.2.1 SDK, Aer, and Runtime

Which pieces do we need to run the coin on our own computer, and which only to reach real hardware? Each package answers a different need.

The package qiskit is the SDK itself. It builds circuits and computes quantum-information objects such as Statevector. It contains the compiler that rewrites circuits for a particular device. It also supplies reference primitives: standard interfaces for two basic requests, “sample these circuits” and “estimate these expectation values,” carried out by exact classical simulation. Our coin needs nothing more, because its sampler is one of these primitives.

Exact simulation of an ideal circuit is not always enough. When we later want faster simulators, or simulators that imitate a noisy device, we use the separate package qiskit-aer, called Aer. To send circuits to IBM’s remote devices we use qiskit-ibm-runtime, which needs an account. Importing that package contacts no one: only an explicit submission does. So none of the local examples needs an account or a token.

2.2.2 Notebooks and executable scripts

Suppose we develop the coin in a notebook, where code sits in cells that we run one at a time. We set shots = 100 in one cell and run it. Later we change that cell to shots = 4096, run a different cell, and delete the first one. Can a reader reproduce our result from the notebook they receive?

Not reliably. A notebook keeps every variable from the cells run so far, in whatever order we ran them. The result can depend on a cell that no longer exists. A script is a plain file that Python runs from top to bottom in a fresh process, so nothing hidden survives from before. If we use a notebook, we restart it and run all cells in order before trusting a result. The tested version of each experiment in this course is a script.

What else must we write down? The versions, the parameters, the number of shots, and the seed. A simulator does not use true randomness. It uses a pseudorandom number generator, a fixed algorithm whose outputs look random and are determined by a starting number called the seed. The same seed with the same implementation gives the same sequence of outcomes. A new version may consume the generator differently, so a seed reproduces a run only within one implementation.

2.3 A First Program

We now have the language, a pinned environment and the packages. We can run the coin. Two questions remain: what exactly does the program get back, and which outputs should we accept as correct? The first is about reading results, and the second about the randomness that every quantum program must allow for.

2.3.1 Build, run, and inspect

What happens between handing the sampler our circuit and holding a dictionary of counts? The program below writes each step on its own line, so that we can name it.

The first two imports let the program report the Python and Qiskit versions it ran with, the record we decided to keep. The next two bring in the circuit class and StatevectorSampler, a reference sampler.

After building the circuit, sampler = StatevectorSampler(seed=7) creates a sampler with a fixed seed. Its method run does not hand back counts directly. It returns a job, a handle to work that may still be in progress. This matters for remote devices, where a job can wait in a queue. Calling job.result() waits until the work is done and fetches the result.

The result holds one entry for each circuit in our list. Square brackets after it select an entry by position, starting from zero, so result[0] is the entry for our only circuit. Inside it, .data.meas is the record of the register meas, and get_counts() turns that record into the dictionary.

"""Runnable companion for Quantum Programming, Chapter 2."""
import sys
from importlib.metadata import version
from qiskit import QuantumCircuit
from qiskit.primitives import StatevectorSampler

circuit = QuantumCircuit(1)
circuit.h(0)
circuit.measure_all()

sampler = StatevectorSampler(seed=7)
job = sampler.run([circuit], shots=4096)
result = job.result()
counts = result[0].data.meas.get_counts()

assert sum(counts.values()) == 4096
assert abs(counts.get("1", 0) / 4096 - 0.5) < 0.05
print("Python", sys.version.split()[0], "Qiskit", version("qiskit"))
print(counts)

Companion script: chapter_02.py.

The sampler computed the amplitudes \((1/\sqrt2,1/\sqrt2)\) internally to generate its samples. What we received, though, is only a classical record of outcomes, the same kind of record a physical device would give.

2.3.2 Predictions and reproducible results

Which counts should our test accept? The obvious attempt demands exactly 2048 ones out of \(R=4096\) shots. Our run gave 2030, and the circuit is correct. So how far from 2048 may a correct run land?

Let \(b_k\) be 1 if shot \(k\) gives one and 0 otherwise, with probability \(p=\tfrac12\) of a one. A single \(b_k\) has mean \(p\). Its variance is \(\mathbb E[b_k^2]-p^2=p-p^2=p(1-p)\), because \(b_k^2=b_k\). The frequency is \(f=(b_1+\dots+b_R)/R\). For independent shots the variances add, and dividing by \(R\) divides the variance by \(R^2\), so \[\operatorname{Var} f=\frac{p(1-p)}{R},\qquad \text{standard deviation}=\sqrt{\frac{p(1-p)}{R}}=\frac1{2\sqrt R}=\frac1{128}.\]

The test accepts any frequency within 0.05 of one half. That is \(0.05\times128=6.4\) standard deviations. For so many shots the frequency is very nearly normally distributed, and a correct circuit lands outside that window with probability about \(2\times10^{-10}\). Our run lies \(18/4096\approx0.0044\) from one half, well inside. A second check confirms that all 4096 shots are present.

What does a pass establish? Only that the outcome distribution looks fair. The circuit that prepares \((\ket0-\ket1)/\sqrt2\) would pass too, and so would a classical coin, so a pass is not evidence that we applied H rather than something else. The fixed seed adds a different kind of value. With the same seed and versions, the program prints the same counts every time, so a change in the output tells us that something in the code or the environment changed. Re-running a fixed program to detect such changes is called regression testing.

Our coin had a single qubit, so each outcome was one character. With two qubits a sampler returns strings such as 01. Which character belongs to qubit 0?

Sources and further study: IBM, SDK primitive simulation.