Quantum simulator lab: qubits, gates and measurement in JupyterLab

This lab gives each student a JupyterLab of their own with a small quantum simulator, qsim.py, written in about 70 lines of NumPy that a student can read from top to bottom. The work folder also holds a starter notebook and short scripts that make a qubit, apply gates, measure, build a Bell state and show interference.

It is a simulator running on an ordinary computer. It is not a quantum computer, and it cannot show that a quantum computer is faster: it keeps every amplitude in memory, so each extra qubit doubles the work. What it shows is the rules. It is not an attack lab: every copy has no route to the internet and none to any other student.

What students learn

That a qubit is described by amplitudes and that the chance of an answer is the amplitude squared. That a gate changes the amplitudes: X flips 0 to 1 and H makes an equal mix. That a measurement gives one answer by chance, so 1000 shots of an equal mix give close to 500 of each and never exactly that. That a Bell state ties two qubits so they always agree, and that amplitudes can cancel, which is interference. Last, one step that steers four items toward the marked one. It suits a first look at quantum computing for students who know some Python; check your own awarding body’s unit for the exact wording, none is quoted here.

Run it in your browser

The lab starts one service, jupyter, which writes the simulator, the notebook and the short scripts into its work folder. JupyterLab asks for no token, because the platform’s own door already knows who is opening it. The terminal beside the lab has no Python of its own, so it reaches the lab’s with docker exec jupyter, followed by the command to run inside.

  1. Open the Container page. Open Build on the bar and choose Run a container. Anybody may open it, and the Git lab and the SQL lab start with no account. Every other lab needs a free account: create one, sign in, then press Start.
  2. Find the lab. The Sample labs card lists every sample. Find JupyterLab: a quantum simulator.
  3. Press Start. Start runs it as it is, in one press. Edit the file first opens the compose file so you can change it before you start.
  4. Open it. On the lab’s page, the lab bar has a link called JupyterLab: press it to open JupyterLab in your browser and double-click start.ipynb. Then press Open terminal and type docker exec jupyter python3 steps/qubit.py to see a qubit in the state |0>.

What to ask students to hand in

A notebook of their own that uses qsim.py, for example a three-qubit state made with H on each qubit, or what a different gate does to |0>, downloaded from JupyterLab with File, Download. Then a sentence or two in their own words on what they saw, and on what a simulator cannot show. Nothing is marked automatically: the sentence shows whether it was understood. For stronger work ask them to predict the counts before they run a cell.

A basic lesson on this lab

Quantum Simulator Basics is a small lesson worked in this lab. In it a student lists the work folder, makes a qubit, applies X and H, measures with a fixed seed, builds a Bell state, sees amplitudes cancel, and steers four items toward the marked one.

It is deliberately small: it shows a teacher what a lesson worked in a lab is, and the lab does the rest. Copy it into a module of your own to change it.

The code on GitHub

The compose file has no Dockerfile: it runs one stock public image, the Jupyter Docker Stacks’ own scipy-notebook, pinned to a dated tag, as its own unprivileged account with 512 MB of memory. The image is licensed BSD-3-Clause and is not distributed by us. The file writes qsim.py and the scripts when it starts and downloads nothing, and every script prints the same each time. The limits are honest ones: it is a simulator and shows no speed, it holds every amplitude so it suits a few qubits only, and nothing can be installed from the internet. Nothing is kept when the lab stops, so a student downloads their notebook first.

Set it as work

Say in the task what to hand in.

  1. Make the lab. In your module add a task and choose the Container lab card, then In a GitHub repository. Give https://github.com/mitsurutech/lab-quantum-sim with the branch main. The compose file is the default, compose.yaml. Fork the repository first if you want to change it, for example to add a gate of your own.
  2. Publish and try it. Publish pins the commit you were shown, so a later change in the repository does not alter a lab you have already set. Start your own copy first.
  3. Hand it out. Assign it like any task, with a due date if you want one, and say in the task what to do and what to hand in.
  4. Mark what is handed in. Open a student’s copy and the work they handed in, mark it, and send it back with a reason if it needs more.

Try this lab, and what it costs

A free personal account can work through the basic lessons in this lab, with enough free credit each month to follow most lessons and no card. For a class, a school or college has its first 365 days free for up to 50 students, then pays per student a year, with every lab included and staff free.

Questions people ask

Is this a real quantum computer?
No. It is a simulator: an ordinary program that follows the rules of qubits using NumPy. It is good for learning the rules, and it cannot show whether a quantum computer is faster, because it works by storing every amplitude.
Why does a run print the same counts every time?
The measuring takes a seed, and the same seed gives the same draws. Change the seed and the counts change a little, as chance does. The scripts fix the seed so the lesson and your screen agree.
Why does the terminal use docker exec jupyter?
The lab’s terminal carries curl, psql and a few other clients, and no Python. docker exec jupyter runs a command inside the lab’s own container, which has Python and NumPy. JupyterLab also has a terminal of its own, under File, New, Terminal.