The Qubble Booklet

1Hello, qubit

A qubit is the smallest piece of a quantum computer. When you make one, it starts out as a definite 0. plot_state shows its amplitude bars — right now, one tall bar on 0 and nothing on 1.

# Chapter 1 — your first qubit.
q = qubit            # make a qubit; it starts as 0
say "hello, qubit!"  # print a message
plot_state q         # show its bars: all on |0>

2Spin: make a blend

spin is the first truly quantum move. It puts the qubit into a blend of possibilities: part of it points at 0 and part points at 1, at the same strength. The bars show the blend directly — this is the state itself, not a guess.

Careful with words: the qubit is not “both 0 and 1 at once.” It holds a blend of amplitudes — and you can see exactly how much of each.

# Chapter 2 — a fair blend.
q = qubit            # starts as 0
spin q               # now: half strength on 0, half on 1
plot_state q         # two equal bars

3Measure: get one answer

measure asks the qubit a question: “0 or 1?” A blend must give one definite answer, and the tall bars are the likely ones. After measuring, the blend is gone — the qubit really is whatever it answered.

Measurement: a blend goes in, exactly one answer comes out — and the blend is gone.

# Chapter 3 — a quantum coin flip.
q = qubit
spin q               # a fair 50/50 blend
result = measure q   # ask: 0 or 1?
say "the coin says", result

4Run it many times

One run gives one answer. To see the 50/50 hiding inside the blend, run it hundreds of times and count. histogram does exactly that.

# Chapter 4 — see the pattern.
q = qubit
spin q                       # fair blend
histogram q, shots: 200      # run 200 times and count 0s and 1s

5Phase: the hidden dial

Every bar also has a phase — shown as its colour. phase flips the sign of the “1” part of the blend. The heights don’t change, so measuring looks the same… but the phase is about to matter a lot.

# Chapter 5 — flip the hidden dial.
q = qubit
spin q               # fair blend
plot_state q         # look at the bar colours
phase q              # flip the sign of the 1 part
plot_state q         # same heights, different colour!

6Interference: the cancel trick

Here is the heart of quantum computing. When paths agree in phase they add up; when they are opposite they cancel — like waves of light. Spin, flip the phase, spin again: the 0-parts add and the 1-parts erase each other. One bar remains.

This is where any quantum advantage comes from — not from “trying everything at once,” but from arranging the phases so wrong answers cancel and right answers add up. It only helps for some problems.

The cancel trick: matching phases pile up on 0; opposite phases erase the 1.

# Chapter 6 — the cancel trick.
q = qubit
spin q               # blend
phase q              # flip the 1 part's sign
spin q               # paths meet: 0s add, 1s cancel
plot_state q         # one bar standing
say "always:", measure q

7Turn: partial spins

spin is all-or-nothing, but turn lets you choose the angle — a little turn makes a lopsided blend. That is how you make a coin that lands 1 only sometimes.

# Chapter 7 — an unfair coin.
q = qubit
turn q, by: 60               # a partial turn: mostly 0, some 1
plot_state q                 # one tall bar, one short bar
histogram q, shots: 300      # count how often 1 shows up

8Two qubits

Two qubits have four possible answers: 00, 01, 10, 11 — so four bars. Spin both and all four light up equally. Each new qubit doubles the bars; that fast growth is why quantum states are hard for ordinary computers to imitate.

# Chapter 8 — four possibilities.
a = qubit
b = qubit
spin a               # blend the first
spin b               # blend the second
plot_state           # all four bars: 00 01 10 11

9Link: qubits that agree

link ties two qubits together — this is entanglement. After linking, the pair has one shared state: measure them and they agree, every single time, even though each answer alone is random.

Honest note: entangled qubits are correlated, but you cannot use them to send a message. And a linked qubit has no little state of its own — only the pair does. Quave shows the pair’s bars for exactly that reason.

A Bell pair: two random answers, one shared state — agreement every time.

# Chapter 9 — the famous Bell pair.
a = qubit
b = qubit
spin a                       # blend a
link a, b                    # entangle: b follows a
plot_state                   # only 00 and 11 remain
histogram a, b, shots: 200   # they always agree

10Repeat: loops

repeat runs some lines several times. Handy for spinning many qubits, or for gates that build up an angle bit by bit.

# Chapter 10 — three small turns make one big one.
q = qubit
repeat 3
  turn q, by: 30     # 3 turns of 30 = one turn of 90
end
plot_state q         # a fair blend, built in steps

11Registers: many qubits at once

A register is a row of qubits with one name. reg[0] is the first, reg[1] the next, and so on. Three qubits means eight bars.

# Chapter 11 — a row of qubits.
reg = qubits 3       # three qubits: reg[0], reg[1], reg[2]
spin reg[0]          # blend the first
link reg[0], reg[1]  # tie the second to it
link reg[1], reg[2]  # ...and the third
plot_state           # a 3-qubit "all agree" state: 000 and 111

12Share your demo

Built something you like? In the Studio, press Deploy to publish it to the Gallery. Anyone can press play, watch your amplitudes, and read every line — Quave demos have no secrets. Titles and descriptions are checked by our safety rules before they appear.

Accounts are just a username and password — no email needed, and never a real name. Learning never requires an account at all.

13Case study: the rig-proof drawthink like a pro

The real-life problem. Your class holds a prize draw with eight numbered tickets, 0 to 7. Last time, someone claimed the computer picking the winner was rigged — and here is the uncomfortable truth: an ordinary computer cannot make a truly random number. It can only follow instructions, so its "random" numbers come from a recipe, and a recipe can be predicted or rigged. How do you run a draw nobody can rig?

The rig-proof draw: fairness you can verify in the bars before you measure.

How a quantum pro thinks it through:

1. Name what you need. Not a clever calculation — genuine unpredictability. That is a physics resource, not a math one.
2. Find the quantum resource. Measuring a fair blend gives an answer that is random by the laws of physics (chapter 3) — no recipe underneath, nothing to predict.
3. Size the state. Eight tickets need eight possibilities. Each qubit doubles the bars (chapter 8), so 3 qubits give exactly 2 × 2 × 2 = 8.
4. Make it fair. Spin each of the 3 qubits: every one of the eight bars gets the same amplitude — every ticket exactly as likely.
5. Measure once — the blend produces one definite ticket, and even the machine did not know it in advance.

The solution, in code — each line is one of the steps above:

# Chapter 13 — a draw nobody can rig.
draw = qubits 3      # step 3: three qubits = eight tickets, 000..111
spin draw[0]         # step 4: blend the first digit...
spin draw[1]         # ...the second...
spin draw[2]         # ...the third: all 8 bars now equal
plot_state           # check fairness with your own eyes
d0 = measure draw[0] # step 5: the blend gives one definite digit
d1 = measure draw[1]
d2 = measure draw[2]
say "winning ticket:", d0, d1, d2

14Case study: one question, not twothink like a pro

The real-life problem. You are handed a mystery machine: feed it a 0 or a 1, and it answers 0 or 1. You must find out whether it is boring (answers the same for both inputs) or fair (answers differently for 0 than for 1). With an ordinary computer there is no way around it: ask about 0, ask about 1, compare — two questions, always. Can quantum do it in one?

Deutsch's puzzle: ask in a blend, let interference keep only the verdict.

How a quantum pro thinks it through:

1. Spot the trap. You do not actually need the two answers — only whether they differ. An ordinary computer must learn both answers anyway; that is wasted work a pro tries to cancel away.
2. Ask in a blend. Put the question qubit in a superposition, so one pass through the machine touches the 0-path and the 1-path together (chapter 2).
3. Turn answers into phases. Prepare the answer qubit (flip, then spin) so the machine does not write its answer as a 0 or 1, but as a hidden phase on each path (chapter 5). This trick is called phase kickback.
4. Let the paths interfere. Spin the question qubit again so the two paths meet (chapter 6). Same answers → phases match → paths add up to 0. Different answers → phases opposite → paths cancel into 1.
5. Measure once. The verdict — not the answers — comes out, deterministically.

The solution, in code. Our mystery machine is link a, b — it flips the answer when the question is 1, so it treats 0 and 1 differently (it is "fair"):

# Chapter 14 — test the machine with ONE question.
a = qubit            # the question qubit
b = qubit            # the answer qubit
flip b               # step 3: prepare the answer qubit...
spin b               # ...so answers land as phases, not digits
spin a               # step 2: ask about 0 and 1 in one blend
link a, b            # THE MYSTERY MACHINE gets asked — once
spin a               # step 4: paths meet and interfere
say "verdict:", measure a   # step 5: 1 = fair, 0 = boring

15Case study: the shared secretthink like a pro

The real-life problem. You and a friend want a secret key — a string of random bits only you two know — to lock your messages. If you send the key over the internet, a spy can copy it in transit and you would never know: copying ordinary data leaves no trace. Banks and hospitals face exactly this problem every day. How do you share a key that cannot be secretly copied?

Quantum key sharing: physics itself is the burglar alarm.

How a quantum pro thinks it through:

1. Turn the weakness around. The enemy is invisible copying — so build the key from things physics refuses to let anyone copy: quantum states (unknown ones cannot be cloned) and measurements (which disturb the blend, chapter 3).
2. Do not send the key — grow it. Never transmit finished bits. Share entangled pairs instead (chapter 9): each of you keeps one qubit of a Bell pair.
3. Harvest matching randomness. Each of you measures your own qubit. Each result is random — but the two of you always match. One pair, one shared secret bit that never travelled anywhere.
4. Set the spy trap. A spy who touches a qubit in transit must measure it, and measuring disturbs the shared state — the perfect agreement breaks. Sacrifice a few pairs, compare them openly: all matching means no spy; mismatches mean throw the key away.
5. Repeat for as many pairs as your key needs bits.

The solution, in code — one shared bit being born:

# Chapter 15 — one bit of an un-copyable key.
a = qubit            # your qubit
b = qubit            # your friend's qubit
spin a               # step 2: open the blend...
link a, b            # ...and entangle: ONE shared state
mine = measure a     # step 3: your bit — random
theirs = measure b   # your friend's bit — always matches
say "my key bit:   ", mine
say "friend's bit: ", theirs

16The grand challenges — and your small-scale versionszoom out

Here is a secret most adults do not know: the "impossible" problems in the quantum headlines and the little programs you just wrote are the same moves, on different sized stages. The grand versions need machines that do not fully exist yet. Your versions run today, in this browser — and yours are the only ones where the whole state can still be seen.

1. Simulating impossible molecules. Writing down a big molecule's exact quantum state takes more numbers than every hard drive on Earth — supercomputers must approximate, and drug and battery designers pay the price. A quantum computer holds the blend natively. Your small-scale version: every plot_state you run holds a real quantum state, exactly — just a small one.
2. Breaking the internet's math locks. Factoring a modern key: longer than the age of the universe for the best supercomputers; roughly a day for a large future quantum machine, by published estimates — because interference makes wrong factors cancel. Your small-scale version: the cancel trick (chapter 6) and the one-question machine (chapter 14) — the same wrong-answers-erase-themselves choreography Shor's algorithm scales up.
3. Un-copyable secret keys. Working today between banks and via satellite. Your small-scale version: chapter 15 — you already ran the honest core of it.

Why Quave stops at 12 qubits — and why that is the honest place to learn: your computer must store every amplitude, and each qubit doubles the list. 12 qubits is 4,096 amplitudes (easy). 50 would be about a million billion (no supercomputer holds it comfortably). Around 280, more amplitudes than atoms in the visible universe. The exact point where simulators like Quave give up is the point where real quantum machines become interesting.

Stand on the biggest stage Quave has:

# Chapter 16 — 12 qubits: 4,096 possibilities in one blend.
stage = qubits 12    # the maximum — a laptop can still hold this
spin stage[0]        # each spin DOUBLES the bars in the blend...
spin stage[1]        # 4...
spin stage[2]        # 8...
spin stage[3]        # 16...
spin stage[4]        # 32...
spin stage[5]        # 64 equal possibilities so far
plot_state           # see the blend grow — imagine 50 qubits