OpenQASM Quantum Circuits

This course is not a glossary of quantum mechanics. You will learn a quantum circuit as a procedure: prepare an input, operate on it, and read a 0 or 1 at the end. Rather than memorizing abstract words, the goal is to predict what happens when you run the same circuit many times.

The overall learning order

The single path through Chapters 13–18

The six-step template used throughout

• •See the result: what you measure and how many 0s and 1s appear.
• •Name it: attach new vocabulary only to an observed result or a calculation step.
• •Follow the numbers: update the state's numbers one line at a time.
• •Follow the circuit: trace the same operation from left to right.
• •Follow the OpenQASM: trace the same operation from top to bottom.
• •Predict: answer the result before running, then confirm it.

0.1 Start with an ordinary bit

A bit in an ordinary computer is either 0 or 1 the instant you read it. A representative implementation reads low voltage as 0 and high voltage as 1. Here we ignore the physical method and use only 'an answer that is a single 0-or-1 digit'.

0.2 A quantum circuit also returns 0 or 1 at the end

A qubit can hold more states than a classical bit along the way. But when you measure it the usual way at the end, a single run yields just one answer, 0 or 1. The first key point is not to confuse the intermediate state with the answer you can finally read.

0.3 A circuit diagram is a timetable of operations

One horizontal line is the flow of time for one qubit. The left is the start, the right is the end. A box on the line is an instruction that changes the state at that point. You read 0/1 at the position of the measurement symbol.

0.4 OpenQASM writes the same procedure as text

OPENQASM 3.1;
include "stdgates.inc";
qubit q;
bit result;
reset q;
result = measure q;

0.5 The first experiment

1.1 First, just look at the result

Apply X once

1.2 Applying X twice

|0> → X → |1> → X → |0>. Because it returns to the start, X is its own inverse.

OPENQASM 3.1;
include "stdgates.inc";
qubit q;
bit result;
reset q;
x q;
result = measure q;

2.1 One result alone cannot tell you the ratio

To learn whether a given preparation tends to give 0 or 1, run the same program from the start many times. Each run is an independent experiment that prepares a fresh qubit.

2.2 Separate the roles of OpenQASM and the execution service

OpenQASM describes 'what one program does'. Setting up a 1000-shot run, choosing the target simulator or hardware, and building the tally chart are usually the job of the SDK or execution service.

3.1 The state card [a, b]

We record the pre-measurement state of one qubit with two numbers, [a, b]. The left value a is the 0-side number; the right value b is the 1-side number. In this course we use real numbers only, at first.

3.2 Don't fear √2

√2 is 'the positive number that squares to 2', about 1.414. 1/√2 is about 0.707, and squares to 1/2. So [1/√2, 1/√2] is a state card that gives 0 and 1 with 50% each.

3.3 A negative amplitude still gives a positive probability

For [1/√2, -1/√2] too, squaring gives 1/2 on both the 0-side and the 1-side. If you measure right away, plus versus minus is invisible in the count distribution. But later gates add and subtract amplitudes, so a difference in sign can turn into a different measurement result.

4.1 The H rule has two parts

The H gate makes two new amplitudes from the input's 0-side amplitude a and 1-side amplitude b. The new 0-side is (a+b)/√2, and the new 1-side is (a−b)/√2. At first, just plug numbers into these formulas.

4.2 Apply H to |0>

The state card of |0> is [1,0]. The 0-side is (1+0)/√2 = 1/√2, and the 1-side is (1−0)/√2 = 1/√2. So H|0> = [1/√2, 1/√2]. Measuring gives 0 and 1 with 50% each.

4.3 Apply H to |1>

|1> is [0,1]. The 0-side is (0+1)/√2 = 1/√2, and the 1-side is (0−1)/√2 = −1/√2. So H|1> = [1/√2, −1/√2]. A standard measurement right after is still 50:50, but the sign differs.

OPENQASM 3.1;
include "stdgates.inc";
qubit q;
bit result;
reset q;
h q;
result = measure q;

4.4 Apply H twice

Apply H again to |+> = [1/√2, 1/√2]. The new 0-side is (1/√2 + 1/√2)/√2 = 1, and the new 1-side is (1/√2 − 1/√2)/√2 = 0. The result is [1,0] = |0>. H is also its own inverse.

5.1 The Z rule

The Z gate changes the state card [a,b] to [a,−b]. It leaves the 0-side unchanged and flips the sign of the 1-side amplitude only.

5.2 Why [0,−1] also measures as 1

Because P(0) = 0² = 0 and P(1) = (−1)² = 1. [0,−1] and [0,1], which differ by the same overall −, cannot be told apart by any measurement. On the other hand, [1/√2,1/√2] and [1/√2,−1/√2] differ in the sign relation between the two components, and a later H can tell them apart.

5.3 Compute H-Z-H line by line

5.4 Now, for the first time, we call it 'interference'

In the last H, to make the new 0-side amplitude we added 1/√2 and −1/√2. The result is 0. On the 1-side we subtracted −1/√2 from 1/√2, so the result is 1. When several amplitudes enter the amplitude calculation of the same output and grow or cancel to 0 through addition or subtraction, we call it interference.

OPENQASM 3.1;
include "stdgates.inc";
qubit q;
bit result;
reset q;
h q;
z q;
h q;
result = measure q;

6.1 A measuring device needs answer labels

A standard measure returns whether the state reads as |0> or |1>. But if you want to tell |+> from |->, place an H just before the standard measurement, because H|+> = |0> and H|-> = |1>.

// Prepare |-> and measure in the X basis
x q;
h q;
// X-basis measurement
h q;
result = measure q;

7.1 Two classical bits have four cases

Line up two bits and there are four cases: 00, 01, 10, 11. A two-qubit measurement result, in one shot, is also one of these four. With three qubits there are 2³ = 8 cases, from 000 to 111.

7.2 The two-qubit state card

For two qubits we line up four amplitudes, one for each candidate 00, 01, 10, 11. This book writes them in the order [q[0]q[1]], so the state card is [a00, a01, a10, a11].

7.3 Index order and display order are separate issues

This book writes bit strings in the order q[0]q[1]. However, an SDK or execution service may display the result string in the order q[1]q[0]. Don't guess the meaning; confirm the display rule with a minimal test that places a single X.

OPENQASM 3.1;
include "stdgates.inc";
qubit[2] q;
bit[2] c;
reset q;
x q[0];
c = measure q;

8.1 The rule is 'if the control is 1, apply X to the target'

8.2 Apply the same rule across the whole state card

When a state has amplitudes on multiple candidates, apply the four-row table to each candidate. For example, [1/√2,0,1/√2,0] is 00 and 10 at 50:50. Applying CX q[0],q[1] moves 00 to 00 and 10 to 11, giving [1/√2,0,0,1/√2].

OPENQASM 3.1;
include "stdgates.inc";
qubit[2] q;
bit[2] c;
reset q;
x q[0];
cx q[0], q[1];
c = measure q;

8.3 Swapping the arguments is a different circuit

For the same input |10>, cx q[1],q[0] does nothing because the control q[1] is 0, leaving |10>. The control and target lines cannot be exchanged.

9.1 After H, apply CX

9.2 Look at 'each qubit alone' and it's 50:50

Since 00 and 11 are half each, q[0] alone is 0/1 at 50:50, and q[1] alone is 0/1 at 50:50. But looking at the two together, 01 and 10 never appear and the values always match. The individual ratios alone cannot express the overall relationship.

9.3 CX is not a copier of an unknown state

When the control is |0> or |1>, CX seems to align the target to the same Z-basis value. But if the control is |+>, the output is a Bell state, not 'control |+>, target |+>'. It has not made two copies of the same single-qubit state.

OPENQASM 3.1;
include "stdgates.inc";
qubit[2] q;
bit[2] c;
reset q;
h q[0];
cx q[0], q[1];
c = measure q;

10.1 One line is, in principle, one statement

10.2 Indices start from 0

For qubit[3] q; the usable indices are 0, 1, 2. q[3] means the fourth element, which is out of range. Distinguish the count 3 from the maximum index 2.

10.3 Comments are explanations that are not executed

// Everything to the right on this line is a line comment
x q[0];  // flip q[0]
/* A multi-line
   comment */

10.4 A complete Bell program

OPENQASM 3.1;
include "stdgates.inc";
qubit[2] q;
bit[2] c;
reset q;
h q[0];
cx q[0], q[1];
c = measure q;

11.1 Measurement is not only at the end

You can measure a qubit mid-circuit and save the result into a bit. Depending on whether that bit is 0 or 1, some systems let you change the later gates.

11.2 reset re-prepares to |0>

reset q[0];

11.3 Check a classical bit with if

bit m;
m = measure q[0];
if (m == 1) {
  x q[1];
}

11.4 Once measured, the original superposition does not remain

For example, measuring |+> gives 0 or 1. If the result is 0 the post-measurement state is |0>; if 1, it is |1>. Measuring the same qubit again with a standard measurement gives, ideally, the same value.

12.1 A type decides how a value is used

12.2 input receives a value from outside the circuit

OPENQASM 3.1;
include "stdgates.inc";
input bit flip;
output bit result;
qubit q;
reset q;
if (flip == 1) {
  x q;
}
result = measure q;

12.3 for is a repetition with a fixed count

qubit[4] q;
for int i in [0:3] {
  h q[i];
}

i changes as 0, 1, 2, 3, applying H once to each of the four qubits. [0:3] includes the endpoint 3.

12.4 while repeats while the condition is true

qubit q;
bit success = 0;
while (success == 0) {
  reset q;
  h q;
  success = measure q;
}

13.1 Two maps for reading rotations

So far we treated amplitudes as real numbers and used only + and −. If you think of + as the 0° direction and − as the 180° direction, the sign is two special cases of phase. General quantum circuits also use intermediate directions such as 45° or 90°.

13.2 RY moves continuously from 0 to 1

Applying RY(θ) to |0> gives cos(θ/2)|0> + sin(θ/2)|1>. θ=0 gives |0>, θ=π/2 gives 0/1 at 50:50, and θ=π gives |1>. π is 180°, so π/2 is 90°.

OPENQASM 3.1;
include "stdgates.inc";
input angle theta;
output bit result;
qubit q;
reset q;
ry(theta) q;
result = measure q;

13.3 Read RZ's invisible difference with H

OPENQASM 3.1;
include "stdgates.inc";
output bit result;
qubit q;
reset q;
h q;
rz(pi) q;
h q;
result = measure q;

13.4 Apply phase to a two-qubit relation with CX-RZ-CX

The first CX flips b only when a is 1. Listing all four cases shows that the temporary b after CX is 0 when a and b match and 1 when they differ. In other words, b becomes a temporary one-bit note that records ‘same or different’.

13.5 gate names a sequence of quantum operations

gate zz_phase(theta) a, b {
  cx a, b;
  rz(theta) b;
  cx a, b;
}
qubit[2] q;
zz_phase(pi / 2) q[0], q[1];

def parity(bit[4] x) -> bit {
  bit p = 0;
  for int i in [0:3] {
    p ^= x[i];
  }
  return p;
}

14.1 Start with the Bell circuit that expresses our intent

Throughout this chapter we follow the same example: a Bell state made with H and CX. The q[0] and q[1] we write are not yet component numbers on a device. At first they express only the logic: apply H, then CX, and aim to obtain 00 or 11.

OPENQASM 3.1;
include "stdgates.inc";
output bit[2] result;
qubit[2] q;
reset q;
h q[0];
cx q[0], q[1];
result = measure q;

Why not connect physical 0 directly to physical 2? On real hardware, a two-qubit operation such as CX is allowed only for pairs with a physical coupling (a direct link). If the device is 0–1–2, 0 and 2 cannot talk by jumping over 1. This is not like broadcasting a classical signal over a longer wire: the two-qubit gate itself is supported only on adjacent pairs. The compiler can choose another layout, move a state with SWAPs, or use another decomposition. We use SWAP here because it makes the routing idea visible.

14.2 Separate barrier, delay, and pulse on the timeline

h q[0];
barrier q;
cx q[0], q[1];

delay[100ns] q[0];

14.3 Tell shot fluctuation from noise by which candidates appear

An ideal Bell state has only the candidates 00 and 11. With 100 shots their ratio may fluctuate to 46 versus 54, but an ideal run still never produces 01 or 10. If 01 and 10 repeatedly appear on hardware, finite shots alone cannot explain them, so investigate gate and readout errors.

There are two things to track in this chapter: the candidate labels and the direction of each amplitude. H prepares the four candidates, the Oracle changes only 10 from +1/2 to −1/2, and we do not measure yet. The Oracle is therefore not an operation that displays the answer; it writes a mark that a later amplification step can use.

15.1 First separate what you solve from how you run it

In this chapter, we search the candidates 00, 01, 10, and 11 for one that matches a condition. The condition is ‘the left bit is 1 and the right bit is 0.’ Instead of storing the answer 10 directly in a box, we build a predicate rule that can be applied equally to every candidate.

15.2 Fix the predicate f(x) with four rows

15.3 Mark only 10 with X–CZ–X

CZ flips only the amplitude of 11. To mark 10, first apply X to q[1] so that 10 temporarily moves to 11, use CZ to flip its sign, and apply X again to restore the candidate label to 10. The other candidates are also temporarily exchanged, but only the original 10 reaches the location affected by CZ.

OPENQASM 3.1;
include "stdgates.inc";
output bit[2] result;
qubit[2] q;
reset q;
h q;
x q[1];
cz q[0], q[1];
x q[1];
result = measure q;

16.1 Connect every line from reset to measure

Here we follow the code without gaps from the first reset to the final measure, explaining both what happens on each line and why it happens. Keep the candidate order fixed as [00,01,10,11], and use that same order for every amplitude list.

OPENQASM 3.1;
include "stdgates.inc";

output bit[2] result;
qubit[2] q;

reset q;

// Equalization
h q;

// Oracle: mark 10
x q[1];
cz q[0], q[1];
x q[1];

// Diffusion
h q;
x q;
cz q[0], q[1];
x q;
h q;

result = measure q;

16.2 Check the same diffusion using the 'mean as a mirror' view

The mean after the Oracle is m=(1/2+1/2−1/2+1/2)/4=1/4. 'About the mean' means moving a value the same distance from one side of the mean to the other. A value below the mean moves the same distance above it. The representative formula is new amplitude = 2m−old amplitude.

16.3 Too many repetitions lower the success rate

In general, for N candidates and M correct answers, the Oracle and diffusion are repeated on the order of √(N/M) times. But the successful amplitude does not rise forever; overshooting makes it fall again. For this N=4, M=1 example, one iteration is optimal.

QAOA is not the name of one gate. It is a framework that repeats a pattern: prepare all candidates, use Cost to change the directions of good and bad candidates, use Mixer to mix candidates, and measure. A classical program outside the quantum circuit chooses new γ and β values after looking at the measurement scores.

17.1 Act 1: Give every candidate a score

Consider the smallest MaxCut: divide two people into different groups. x0 and x1 are each 0 or 1, with 0 meaning group A and 1 meaning group B. Different groups score 1; the same group scores 0. The two optimal candidates are 01 and 10.

17.2 The QUBO formula preserves all four scores

The score can be written as C(x)=x0+x1−2x0x1. Do not memorize it as an opaque formula; substitute all four candidates and verify that it matches the table above.

17.4 Act 2: Use a Mixer to turn Cost phases into probabilities

OPENQASM 3.1;
include "stdgates.inc";
input angle gamma;
input angle beta;
output bit[2] result;
qubit[2] q;
reset q;
h q;
// U_C(gamma): e^{-i gamma C}
cx q[0], q[1];
rz(-gamma) q[1];
cx q[0], q[1];
// U_B(beta)
rx(2 * beta) q;
result = measure q;

17.5 Angles are updated outside the circuit

In this chapter, ‘correct’ has four layers: the text can be read, the quantum-state calculation matches the intention, the circuit fits the device constraints, and the hardware result is within an acceptable range. If an earlier layer has not passed, checking a later layer cannot reveal the real cause.

18.1 Read the same Bell circuit through two versions

Migration is not a global word replacement. First determine the state and ideal distribution produced by the old code, then express the same meaning with the new declarations and measurement syntax. We use the same Bell circuit, where H and CX produce 00 and 11.

OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0], q[1];
measure q -> c;

OPENQASM 3.1;
include "stdgates.inc";
output bit[2] result;
qubit[2] q;
reset q;
h q[0];
cx q[0], q[1];
result = measure q;