QUANTUM ARENA · COURSE

Learn quantum computing by running it

Print this page from your browser (Ctrl/Cmd+P). Each chapter starts on a new page. Run the examples at https://mcp.blueqat.app and submit your run_id to the Arena.

Print

0Setup: connect to the simulator

This course teaches the basics of quantum computing step by step, by actually running circuits on blueqat's quantum simulator. We keep the math to a minimum.

First sign in and issue an API key on your account page (free). That is your key.

There are two ways to work. From an AI agent (MCP): connect Claude or another AI to this server and just ask in plain words -- it builds and runs the circuits. From the REST API: send JSON to https://qapi.blueqat.app.

Every run returns a run_id. That is your record, and anyone can check it at https://mcp.blueqat.app/runs/{run_id}.

Connect an AI (Claude Code)

claude mcp add --transport http blueqat https://mcp.blueqat.app/mcp --header "Authorization: Bearer YOUR_API_KEY"

Other MCP clients: add https://mcp.blueqat.app/mcp as streamable-HTTP with your API key in Authorization: Bearer.

1Qubits and superposition

An ordinary bit is either 0 or 1. A qubit can hold both possibilities until it is measured. This is called superposition.

A qubit starts at 0. The Hadamard gate h turns it into an equal superposition of 0 and 1. Each measurement gives one or the other; over many shots you see half and half.

You can set the probability yourself. ry(θ) rotates the qubit by an angle θ, and the probability of 1 is sin²(θ/2). With θ = π/3 (about 1.047), that is sin²(π/6) = 1/4.

To get 1 with probability p, use θ = 2·arcsin(√p). For p = 1/3, θ ≈ 1.231.

Example (runs as-is)

run_circuit({"n_qubits": 1, "gates": [{"gate": "h", "qubits": [0]}], "shots": 256})

0 and 1 each come out about 128 times.

Exercises (Arena challenges)

  1. A fair quantum coin coin — Measure a 1-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 0, 1 in equal proportions (total variation distance at most 0.1). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
  2. A coin that lands 1 with probability 1/4 coin-1-4 — Measure a 1-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 0 (75%), 1 (25%) (total variation distance at most 0.06). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
  3. A coin that lands 1 with probability 1/3 coin-1-3 — Measure a 1-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 0 (67%), 1 (33%) (total variation distance at most 0.06). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
  4. A coin that lands 1 with probability 1/10 coin-1-10 — Measure a 1-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 0 (90%), 1 (10%) (total variation distance at most 0.06). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
Notes: write down your run_id and result

2Entanglement

When two qubits are entangled, their results always agree even though you measure them separately: if one is 0, so is the other; if one is 1, so is the other.

It takes two gates. Put the first qubit in superposition with h, then copy it onto the second with CNOT cx -- a gate that flips the second qubit only when the first is 1.

This is a Bell state. Measuring it gives only 00 and 11, half and half -- never 01 or 10.

Flip the second qubit with x at the end and you get the always-opposite pair: only 01 and 10.

Example (runs as-is)

run_circuit({"n_qubits": 2, "gates": [{"gate": "h", "qubits": [0]}, {"gate": "cx", "qubits": [0, 1]}], "shots": 256})

The leftmost bit is qubit 0. Only 00 and 11 appear.

Exercises (Arena challenges)

  1. Make a Bell state bell — Measure a 2-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 00, 11 in equal proportions (total variation distance at most 0.1). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
  2. The anti-correlated Bell state bell-psi — Measure a 2-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 01, 10 in equal proportions (total variation distance at most 0.1). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
Notes: write down your run_id and result

3Entangling many qubits

Bell states extend to three or more qubits. After h, chain cx gates and you get a GHZ state: only all-zeros or all-ones.

There is more than one kind of entanglement. A W state is an equal superposition of the strings with exactly one 1, and it behaves differently from GHZ.

Two cx gates can write the parity of two qubits onto a third, so only strings with an even number of ones appear.

In the Arena, whoever makes the same distribution with fewer gates ranks higher. Look for ways to cut gates.

Example (runs as-is)

run_circuit({"n_qubits": 3, "gates": [{"gate": "h", "qubits": [0]}, {"gate": "cx", "qubits": [0, 1]}, {"gate": "cx", "qubits": [1, 2]}], "shots": 256})

Only 000 and 111 appear.

Exercises (Arena challenges)

  1. 3-qubit GHZ state ghz3 — Measure a 3-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 000, 111 in equal proportions (total variation distance at most 0.1). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
  2. 4-qubit GHZ state ghz4 — Measure a 4-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 0000, 1111 in equal proportions (total variation distance at most 0.1). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
  3. 5-qubit GHZ state ghz5 — Measure a 5-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 00000, 11111 in equal proportions (total variation distance at most 0.1). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
  4. Even-parity superposition parity3 — Measure a 3-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 000, 011, 101, 110 in equal proportions (total variation distance at most 0.1). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
  5. 3-qubit W state w3 — Measure a 3-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 100, 010, 001 in equal proportions (total variation distance at most 0.1). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
Notes: write down your run_id and result

4Designing superpositions

A row of h gates makes uniform superpositions of 2, 4, 8… outcomes, but not of 3 or any number that is not a power of two.

That is where controlled gates come in. First use ry to make one qubit 1 with probability 1/3, then apply h to another qubit only when the first is 0 (a controlled Hadamard, ch).

ch acts when its control is 1; to act on 0 instead, sandwich it between x gates.

The result is 00, 10 and 01 at exactly 1/3 each. The same idea builds W and Dicke states.

Example (runs as-is)

run_circuit({"n_qubits": 2, "gates": [{"gate": "ry", "qubits": [1], "params": [1.231]}, {"gate": "x", "qubits": [1]}, {"gate": "ch", "qubits": [1, 0]}, {"gate": "x", "qubits": [1]}], "shots": 256})

The ry angle 1.231 is 2·arcsin(√(1/3)). 00, 10 and 01 come out about equally.

Exercises (Arena challenges)

  1. Uniform superposition of 3 uniform3 — Measure a 2-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 00, 10, 01 in equal proportions (total variation distance at most 0.1). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
  2. 4-qubit W state w4 — Measure a 4-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 1000, 0100, 0010, 0001 in equal proportions (total variation distance at most 0.1). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
  3. Uniform superposition of 5 uniform5 — Measure a 3-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 000, 100, 010, 110, 001 in equal proportions (total variation distance at most 0.12). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
  4. Dicke state D(4,2) dicke4-2 — Measure a 4-qubit circuit with run_circuit, at least 100 shots (256 recommended). It passes if the outcome distribution is close to 1100, 1010, 1001, 0110, 0101, 0011 in equal proportions (total variation distance at most 0.12). Fewer gates rank higher. The leftmost bit of a bitstring is qubit 0.
Notes: write down your run_id and result

5Combinatorial optimization and QUBO

Problems that ask "which choice is best?" are combinatorial optimization. As candidates grow, checking them all quickly becomes impossible.

To solve one on a quantum computer, write it as a QUBO: 0/1 variables q, and a sum of coeff × q_i and coeff × q_i × q_j terms to minimize.

Take MaxCut: colour a graph's vertices with two colours so that as many edges as possible join different colours. Adding 2·q_i·q_j − q_i − q_j for each edge (i, j) gives −1 for every cut edge, so minimizing maximizes the cut.

The Arena's optimization challenges fix the QUBO for you. Pass it to run_qaoa as given.

Example: MaxCut: triangle

run_qaoa(qubo=[{"coeff": -2.0, "qubits": [0]}, {"coeff": -2.0, "qubits": [1]}, {"coeff": -2.0, "qubits": [2]}, {"coeff": 2.0, "qubits": [0, 1]}, {"coeff": 2.0, "qubits": [0, 2]}, {"coeff": 2.0, "qubits": [1, 2]}], steps=2, shots=256)

Exercises (Arena challenges)

  1. MaxCut: triangle maxcut-triangle — Pass the QUBO below to run_qaoa exactly as given and solve it with at least 100 shots. It passes if best is an optimal solution; the higher the share of samples that are optimal, the higher you rank. Depth (steps), seed and n_starts can be tuned.
  2. MaxCut: square (4-cycle) maxcut-c4 — Pass the QUBO below to run_qaoa exactly as given and solve it with at least 100 shots. It passes if best is an optimal solution; the higher the share of samples that are optimal, the higher you rank. Depth (steps), seed and n_starts can be tuned.
  3. MaxCut: complete graph K4 maxcut-k4 — Pass the QUBO below to run_qaoa exactly as given and solve it with at least 100 shots. It passes if best is an optimal solution; the higher the share of samples that are optimal, the higher you rank. Depth (steps), seed and n_starts can be tuned.
  4. Number partitioning: 1, 2, 3, 4 partition-1-2-3-4 — Pass the QUBO below to run_qaoa exactly as given and solve it with at least 100 shots. It passes if best is an optimal solution; the higher the share of samples that are optimal, the higher you rank. Depth (steps), seed and n_starts can be tuned.
Notes: write down your run_id and result

6Tuning QAOA

QAOA builds a state that tends to give good answers, while a classical computer tunes the circuit's angles.

There are three knobs. Raising steps (depth) adds expressive power. Changing seed changes where tuning starts. Raising n_starts tries several starts and keeps the best.

The result's best is the lowest-value sample. The most frequent state (most_frequent) is not always optimal -- quote best.

In the Arena you rank by the share of samples that are optimal. Turn the knobs to raise it.

Example: MaxCut: 6-vertex graph

run_qaoa(qubo=[{"coeff": -2.0, "qubits": [0]}, {"coeff": -3.0, "qubits": [1]}, {"coeff": -3.0, "qubits": [2]}, {"coeff": -3.0, "qubits": [3]}, {"coeff": -3.0, "qubits": [4]}, {"coeff": -2.0, "qubits": [5]}, {"coeff": 2.0, "qubits": [0, 1]}, {"coeff": 2.0, "qubits": [0, 2]}, {"coeff": 2.0, "qubits": [1, 2]}, {"coeff": 2.0, "qubits": [1, 3]}, {"coeff": 2.0, "qubits": [2, 4]}, {"coeff": 2.0, "qubits": [3, 4]}, {"coeff": 2.0, "qubits": [3, 5]}, {"coeff": 2.0, "qubits": [4, 5]}], steps=2, shots=256)

Exercises (Arena challenges)

  1. MaxCut: 6-vertex graph maxcut-g6 — Pass the QUBO below to run_qaoa exactly as given and solve it with at least 100 shots. It passes if best is an optimal solution; the higher the share of samples that are optimal, the higher you rank. Depth (steps), seed and n_starts can be tuned.
  2. MaxCut: triangular prism maxcut-prism — Pass the QUBO below to run_qaoa exactly as given and solve it with at least 100 shots. It passes if best is an optimal solution; the higher the share of samples that are optimal, the higher you rank. Depth (steps), seed and n_starts can be tuned.
  3. Number partitioning: 4, 5, 6, 7, 8 partition5 — Pass the QUBO below to run_qaoa exactly as given and solve it with at least 100 shots. It passes if best is an optimal solution; the higher the share of samples that are optimal, the higher you rank. Depth (steps), seed and n_starts can be tuned.
  4. Weighted MaxCut: K4 maxcut-k4-weighted — Pass the QUBO below to run_qaoa exactly as given and solve it with at least 100 shots. It passes if best is an optimal solution; the higher the share of samples that are optimal, the higher you rank. Depth (steps), seed and n_starts can be tuned.
Notes: write down your run_id and result

7Constraints as penalties

Constraints such as "choose exactly two" or "never choose neighbours" enter a QUBO as penalty terms that make the value large when broken.

For "exactly k", add A·(Σq − k)². If A is too small, rule-breaking answers win; too large, and QAOA struggles.

Maximum independent set (as many vertices as possible, none adjacent) becomes −1 per chosen vertex and a +2 penalty for choosing two neighbours.

Example: Choose exactly 2: pick 2 of 5 staff for the night shift (lightest load)

run_qaoa(qubo=[{"coeff": -33.0, "qubits": [0]}, {"coeff": -35.0, "qubits": [1]}, {"coeff": -32.0, "qubits": [2]}, {"coeff": -35.0, "qubits": [3]}, {"coeff": -31.0, "qubits": [4]}, {"coeff": 24.0, "qubits": [0, 1]}, {"coeff": 24.0, "qubits": [0, 2]}, {"coeff": 24.0, "qubits": [0, 3]}, {"coeff": 24.0, "qubits": [0, 4]}, {"coeff": 24.0, "qubits": [1, 2]}, {"coeff": 24.0, "qubits": [1, 3]}, {"coeff": 24.0, "qubits": [1, 4]}, {"coeff": 24.0, "qubits": [2, 3]}, {"coeff": 24.0, "qubits": [2, 4]}, {"coeff": 24.0, "qubits": [3, 4]}], steps=2, shots=256)

Exercises (Arena challenges)

  1. Choose exactly 2: pick 2 of 5 staff for the night shift (lightest load) pick5-2-3-1-4-1-5 — Pass the QUBO below to run_qaoa exactly as given and solve it with at least 100 shots. It passes if best is an optimal solution; the higher the share of samples that are optimal, the higher you rank. Depth (steps), seed and n_starts can be tuned. The constraint is a penalty term in the QUBO; think about how its weight affects QAOA.
  2. Maximum independent set: pentagon (5-cycle) mis-c5 — Pass the QUBO below to run_qaoa exactly as given and solve it with at least 100 shots. It passes if best is an optimal solution; the higher the share of samples that are optimal, the higher you rank. Depth (steps), seed and n_starts can be tuned.
  3. Minimum vertex cover: star (hub + 5) cover-star5 — Pass the QUBO below to run_qaoa exactly as given and solve it with at least 100 shots. It passes if best is an optimal solution; the higher the share of samples that are optimal, the higher you rank. Depth (steps), seed and n_starts can be tuned.
  4. Choose exactly 2: run 2 of 4 machines (lowest power bill) pick4-2-5-3-6-2 — Pass the QUBO below to run_qaoa exactly as given and solve it with at least 100 shots. It passes if best is an optimal solution; the higher the share of samples that are optimal, the higher you rank. Depth (steps), seed and n_starts can be tuned. The constraint is a penalty term in the QUBO; think about how its weight affects QAOA.
Notes: write down your run_id and result

8Finding energies with VQE

Physics and chemistry often need the lowest energy of a system, its ground-state energy, written as a Hamiltonian.

A Hamiltonian is a sum of products of Pauli operators (X, Y, Z). For example −Z0 Z1 rewards aligned neighbours and −X0 is a transverse field.

VQE tunes a circuit's angles to push the energy down. By the variational principle, the result is never below the true ground-state energy.

More layers in run_vqe usually get closer. In the Arena, the smaller your gap to the exact value, the higher you rank.

Example: Transverse-field Ising chain: 2 qubits, h=1.0 (critical)

run_vqe(n_qubits=2, hamiltonian=[{"coeff": -1.0, "paulis": [{"op": "Z", "qubit": 0}, {"op": "Z", "qubit": 1}]}, {"coeff": -1.0, "paulis": [{"op": "X", "qubit": 0}]}, {"coeff": -1.0, "paulis": [{"op": "X", "qubit": 1}]}], layers=2)

Exercises (Arena challenges)

  1. Transverse-field Ising chain: 2 qubits, h=1.0 (critical) tfim2-h10 — Pass the Hamiltonian below to run_vqe exactly as given (n_qubits=2). It passes if energy is within 0.0671 of the exact ground-state energy; the smaller the gap, the higher you rank. More layers help.
  2. Transverse-field Ising chain: 3 qubits, h=1.0 (critical) tfim3-h10 — Pass the Hamiltonian below to run_vqe exactly as given (n_qubits=3). It passes if energy is within 0.1048 of the exact ground-state energy; the smaller the gap, the higher you rank. More layers help.
  3. Transverse-field Ising chain: 4 qubits, h=0.5 (ordered) tfim4-h05 — Pass the Hamiltonian below to run_vqe exactly as given (n_qubits=4). It passes if energy is within 0.1028 of the exact ground-state energy; the smaller the gap, the higher you rank. More layers help.
  4. Transverse-field Ising chain: 5 qubits, h=2.0 (paramagnetic) tfim5-h20 — Pass the Hamiltonian below to run_vqe exactly as given (n_qubits=5). It passes if energy is within 0.3151 of the exact ground-state energy; the smaller the gap, the higher you rank. More layers help.
Notes: write down your run_id and result

9Reproducing papers

In research it matters a great deal whether a published number can be reproduced by someone else.

Farhi et al. (2014) showed that depth-1 QAOA on MaxCut of a ring cuts 3/4 of the edges on average (the approximation ratio). Check it on a 6-cycle.

O'Malley et al. (2016) computed the ground-state energy of H₂ on a quantum computer. Solving the same Hamiltonian with VQE gives about −1.137 hartree.

Paper challenges rank you by how close your run comes to the published value.

Exercises (Arena challenges)

  1. Reproduce QAOA's 3/4 approximation ratio farhi-ring6 — Solve MaxCut on the 6-cycle (QUBO below) with run_qaoa at steps=1 and at least 100 shots. The approximation ratio is the mean cut (from mean_value) divided by the maximum cut, 6. Within 0.03 of 0.75 counts as reproduced; closer ranks higher.
  2. Ground-state energy of H₂ h2-omalley — Pass the Hamiltonian below to run_vqe exactly as given (n_qubits=2). It passes if energy is within 0.0241 of the exact ground-state energy; the smaller the gap, the higher you rank. More layers help. Add back the constant −1.0524 that was left out and the nuclear repulsion 0.7200 to get the paper's −1.137 Ha.
Notes: write down your run_id and result

10Next steps

You have now worked through superposition, entanglement, QUBO and QAOA, VQE, and reproducing papers.

The Arena has many more benchmark challenges across circuits, optimization, physics and paper reproduction. Results are kept as run records, and every leaderboard entry traces back to one.

Over MCP, an AI agent can read the improvement hints in each result and keep running and submitting. It also suits internal evaluation and training.

Evaluation on real quantum hardware is on the way.