SwiftQiskit is a lightweight quantum computing simulator written entirely in Swift.
It brings a Qiskit-like experience to the Apple ecosystem, with a strong focus on clarity, correctness, and future GUI integration.
This project is experimental and educational, but grounded in real quantum mechanics principles
Differences between this forked repository ("fork") and its parent:
- The usage of Xcode playgrounds.
- Showing of Bloch spheres (in live playgrounds).
- Using Swift Testing.
- ✅ Complex number arithmetic
- ✅ Matrix operations (including Kronecker products)
- ✅ Tensor products:
tensor(_:)/⊗onMatrixandStateVector - ✅ Dirac (bra–ket) notation:
Ket/Bra, postfix†(dagger), inner & outer products - ✅ State vector simulation
- ✅ Quantum gates (see the gate tables below):
- Hadamard (H)
- Pauli-X (X)
- Pauli-Y (Y)
- Pauli-Z (Z)
- Phase gates: S, S†, T, T†, and the general P(θ)
- Rotations: RX(θ), RY(θ), RZ(θ)
- CNOT (Controlled-NOT)
- ✅ Single-qubit gate embedding
- ✅ Quantum circuit abstraction
- ✅ Measurement & state collapse
- ✅ Bell State (Entanglement) example
Named single-qubit basis kets, defined as Ket (= StateVector) constants in
Sources/SwiftQiskitCore/Quantum/Dirac.swift:
| Constant | State | Definition | Bloch sphere |
|---|---|---|---|
.zero |
|0⟩ | (1, 0) | +z (north pole) |
.one |
|1⟩ | (0, 1) | −z (south pole) |
.plus |
|+⟩ | (|0⟩ + |1⟩)/√2 | +x |
.minus |
|−⟩ | (|0⟩ − |1⟩)/√2 | −x |
.plusI |
|i⟩ | (|0⟩ + i|1⟩)/√2 | +y |
.minusI |
|−i⟩ | (|0⟩ − i|1⟩)/√2 | −y |
Multi-qubit basis kets come from the binary-label initializer, e.g. Ket("01") = |01⟩
(qubit 0 is the most-significant bit), with Bra("01") as the matching bra.
Built-in gates — each is a public enum in Sources/SwiftQiskitCore/Gates/ exposing
static let matrix: Matrix (parameterized gates expose static func matrix(theta:)),
with a matching convenience method on QuantumCircuit:
| Gate | Circuit API | Type | Used in |
|---|---|---|---|
| Hadamard (H) | h(qubit) |
HadamardGate |
Bell example; all five test suites; playground pages 01, 02, 05–16 |
| Pauli-X (X) | x(qubit) |
PauliXGate |
TensorProductTests, AdditionalGatesTests; pages 02, 05, 09–14, 17, 18 |
| Pauli-Y (Y) | y(qubit) |
PauliYGate |
AdditionalGatesTests; pages 05 (y(0)), 08 (Y† == Y, ⟨ψ|Y|ψ⟩); page 18 (PauliYGate.matrix as a raw Hamiltonian term, not via y(qubit)) |
| Pauli-Z (Z) | z(qubit) |
PauliZGate |
DiracNotationTests, AdditionalGatesTests; pages 01, 02, 05, 08, 13, 14; page 18 (PauliZGate.matrix as a raw Hamiltonian term) |
| S / S† | s(qubit) / sdg(qubit) |
SGate / SDaggerGate |
AdditionalGatesTests; pages 02 (the |±i⟩ states), 05 |
| T / T† | t(qubit) / tdg(qubit) |
TGate / TDaggerGate |
AdditionalGatesTests; page 05 (t applied twice, T² == S — tdg isn't used on any page) |
| Phase P(θ) | p(theta, qubit) |
PhaseGate |
AdditionalGatesTests; pages 01, 05; page 16 (the building block of the hand-built controlled-phase CP(θ), five gates deep) |
| RX/RY/RZ (θ) | rx/ry/rz(theta, qubit) |
RXGate / RYGate / RZGate |
AdditionalGatesTests; page 05; page 13 (ry/rz prepare the teleported payload); page 14 (rx(θ) as a partial bit-flip error); page 15 (ry(-θ) rotates into a tilted measurement basis); page 18 (ry(θ) is the VQE ansatz's only parameter) |
| CNOT (CX) | cx(control, target) — any distinct pair |
CNOTGate (also matrix(qubits:control:target:)) |
Bell example; BellStateTests, CNOTTests; pages 05, 07–11, 13–18 |
Hand-built gates — constructed in tests/playgrounds from raw Matrix values or gate
compositions and applied with circuit.apply(_:); not (yet) part of Core:
| Gate | Built from | Where |
|---|---|---|
| Pauli-Y (Y) | raw 2×2 Matrix |
DiracNotationTests (adjoint of a non-symmetric matrix — the test predates PauliYGate) |
| CZ | h(1); cx(0,1); h(1) |
page 11 (phase oracles and diffusion operator); page 13 (h(2); cx(0,2); h(2) — the deferred Z^a correction) |
| Bell-basis projector | (Ket("ab") * Bra("ab")) ⊗ Matrix.identity(size: 2) |
page 13 (recovering one measurement branch without measure()) |
| 3-qubit code correction | 32×32 permutation decoding two syndrome bits and flipping the accused data qubit | page 14 (syndrome-driven error correction via apply(_:)) |
| Tilted observable A(θ) | cos θ·Z + sin θ·X, built entrywise |
page 15 (CHSH correlators; measured via ry(-θ)) |
| CCZ | Matrix.identity(size: 8) with the |111⟩ entry set to −1 |
page 11 (3-qubit Grover finale) |
| Modular multiplication U_a (mod 15) | 16×16 / 128×128 basis-state permutations — one .one per column; the controlled versions key on a counting bit |
page 12 (Shor order finding) |
| QFT† (3-qubit inverse Fourier) | 8×8 inverse-DFT matrix built entrywise from cos/sin, embedded as qftDagger ⊗ I₁₆ |
page 12 (phase-estimation readout) |
| Controlled phase CP(θ) | p(θ/2, c); cx(c,t); p(-θ/2, t); cx(c,t); p(θ/2, t) |
page 16 (the QFT ladder and standalone phase estimation; reduces to CZ at θ=π) |
| H₂ Hamiltonian (Jordan–Wigner, 2 qubits) | six Pauli terms (I⊗I, Z⊗I, I⊗Z, Z⊗Z, Y⊗Y, X⊗X) combined entrywise | page 18 (VQE's energy operator) |
Custom operators on the quantum types (Ket = StateVector): the postfix dagger † is
declared in Sources/SwiftQiskitCore/Quantum/Dirac.swift, and the infix tensor product ⊗
(at MultiplicationPrecedence) in Sources/SwiftQiskitCore/Math/Matrix.swift:
| Operator | Expression | Result | Meaning | Defined in |
|---|---|---|---|---|
† |
Ket† |
Bra |
⟨ψ| = (|ψ⟩)† | Quantum/Dirac.swift |
† |
Bra† |
Ket |
|ψ⟩ = (⟨ψ|)† | Quantum/Dirac.swift |
† |
Matrix† |
Matrix |
adjoint U† (also Matrix.adjoint) |
Quantum/Dirac.swift |
⊗ |
Matrix ⊗ Matrix |
Matrix |
Kronecker product A ⊗ B (also tensor(_:)) |
Math/Matrix.swift |
⊗ |
Ket ⊗ Ket |
Ket |
|a⟩ ⊗ |b⟩ — combines registers, lhs in the high-order bits (also tensor(_:)) |
Quantum/StateVector.swift |
⊗ |
Bra ⊗ Bra |
Bra |
⟨a| ⊗ ⟨b| (also tensor(_:)) |
Quantum/Dirac.swift |
⊗ |
Ket ⊗ Bra |
Matrix |
mixed product = the outer product |a⟩⟨b| | Quantum/Dirac.swift |
⊗ |
Bra ⊗ Ket |
Matrix |
mixed product ⟨a| ⊗ |b⟩ = |b⟩⟨a| | Quantum/Dirac.swift |
* |
Bra * Ket |
Complex |
inner product ⟨φ|ψ⟩ | Quantum/Dirac.swift |
* |
Ket * Bra |
Matrix |
outer product |ψ⟩⟨φ| | Quantum/Dirac.swift |
* |
Bra * Matrix |
Bra |
⟨ψ|U — enables expectation values ψ† * U * ψ |
Quantum/Dirac.swift |
* |
Matrix * Matrix |
Matrix |
matrix product AB | Math/Matrix.swift |
Scalar Complex arithmetic (+ - * / and Double scaling) lives in Math/Complex.swift
and is not listed here — it acts on numbers, not on qubit states or gates.
- No hidden magic — everything is explicit and readable
- Mathematical correctness over shortcuts
- Modular architecture (Core / Examples / GUI-ready)
- Designed for learning, experimentation, and extension
SwiftQiskit is not just a simulator — it’s an attempt to make quantum computing accessible, visual, and native on Apple platforms.
Enjoy exploring the quantum world
SwiftQiskit/
├── Sources/
│ └── SwiftQiskitCore/
│ │ ├── Math/
│ │ │ ├── Complex.swift
│ │ │ └── Matrix.swift
│ │ ├── Quantum/
│ │ │ ├── StateVector.swift
│ │ │ ├── Dirac.swift
│ │ │ └── SimulationResult.swift
│ │ ├── Gates/
│ │ │ ├── Hadamard.swift
│ │ │ ├── PauliX.swift
│ │ │ ├── PauliY.swift
│ │ │ ├── PauliZ.swift
│ │ │ ├── Phase.swift
│ │ │ ├── Rotation.swift
│ │ │ └── CNOT.swift
│ │ ├── Circuit/
│ │ │ └── QuantumCircuit.swift
│ │ ├── Utils/
│ │ │ └── String+Padding.swift
│ │ └── SwiftQiskitCore.swift
├── Examples/
│ └── main.swift
├── SwiftQiskitGUI/
│ └── Sources/
│ ├── main.swift
│ └── ContentView.swift
├── Tests/
│ └── SwiftQiskitCoreTests/
│ ├── BellStateTests.swift
│ ├── TensorProductTests.swift
│ ├── DiracNotationTests.swift
│ ├── CNOTTests.swift
│ └── AdditionalGatesTests.swift
├── Docs/
│ ├── LIVEVIEWHELP.md (not page-numbered — the shared-code/live-view guide)
│ ├── 01QUBITSHELP.md
│ ├── 02BLOCH2DHELP.md
│ ├── 03BLOCH2DPROJECTIONHELP.md
│ ├── 04BLOCH3DHELP.md
│ ├── 05GATESHELP.md
│ ├── 06SUPERPOSITIONHELP.md
│ ├── 07ENTANGLEMENTHELP.md
│ ├── 08DIRACHELP.md
│ ├── 09TENSORPLAN.md
│ ├── 09TENSORHELP.md
│ ├── 10DEUTSCHPLAN.md
│ ├── 10DEUTSCHHELP.md
│ ├── 11GROVERPLAN.md
│ ├── 11GROVERHELP.md
│ ├── 12SHORPLAN.md
│ └── 12SHORHELP.md
├── Playgrounds.playground/
│ ├── Sources/ (code shared by all pages — see PLAYGROUNDSUPPORT.md)
│ └── Pages/
│ ├── 00TOC
│ ├── 01Qubits
│ ├── 02Bloch2d
│ ├── 03Bloch2dProjection
│ ├── 04Bloch3d
│ ├── 05Gates
│ ├── 06Superposition
│ ├── 07Entanglement
│ ├── 08Dirac
│ ├── 09Tensor
│ ├── 10DeutschExample
│ ├── 11GroverExample
│ ├── 12ShorExample
│ ├── 13Teleportation
│ ├── 14ErrorCorrection
│ ├── 15CHSH
│ ├── 16QFT
│ ├── 17DeutschJozsa
│ └── 18VQE
├── Package.swift
└── References (tbd)
The package itself (Package.swift) declares swift-tools-version: 5.9 and targets
macOS 13+ / iOS 16+.
This fork's playground pages, however, are developed and tested against Xcode 27.0 beta and macOS 27 beta — some SwiftUI live-view pages need the beta-specific workarounds in PLAYGROUNDSUPPORT.md on Xcode 27 betas (confirmed still needed on beta 5, 27A5237l).
Open Xcode, go to Integrate and clone "https://github.com/SwiftProjectOrganization/SwiftQiskit".
swift run SwiftQiskitExamplesThe Bell state |Φ⁺⟩ is defined as:
|Φ⁺⟩ = (|00⟩ + |11⟩) / √2
import SwiftQiskitCore
let circuit = QuantumCircuit(qubits: 2)
circuit.h(0)
circuit.cx(0, 1)
let finalState = circuit.run()
print(finalState)
let result = circuit.measure(shots: 1000)
for (state, count) in result.sortedCounts {
let probability = Double(count) / Double(1000)
print("\(state): \(count) (\(String(format: "%.2f", probability)))")
}Note: The core module is currently imported as
SwiftQiskitCore. This is the same code asExamples/main.swift, run viaswift run SwiftQiskitExamples.
00: 498 (0.50)
11: 502 (0.50)
States 01 and 10 never appear — this confirms quantum entanglement. Measurement outputs are probabilistic and may vary per run.
Playgrounds.playground (at the repo root, macOS target) contains interactive, lecture-style
explorations of the library. Open it in Xcode — pages build against the SwiftQiskit scheme
and are linked sequentially with Previous/Next markers.
Code shared by multiple pages (the Bloch-sphere types and views) lives in the playground's
Sources/ folder — see Docs/LIVEVIEWHELP.md for a user-facing
guide to that shared code and to putting a live view on a page, and
PLAYGROUNDSUPPORT.md for the terse implementation reference.
Clickable table of contents (markdown only): links to every page with a one-line
description, plus pointers to the guides in Docs/.
First look at qubit states through the Dirac API, shown in the results sidebar (no
console output): building Kets from amplitudes, the dagger †, inner and outer
products, probabilities, and tensoring a ket with itself. Content provisional.
User guide in Docs/01QUBITSHELP.md.
Visualizes single-qubit states on the Bloch sphere using a SwiftUI Canvas live view.
- Bloch vector math — maps a state |ψ⟩ = α|0⟩ + β|1⟩ to sphere coordinates
(x = 2·Re(ᾱβ), y = 2·Im(ᾱβ), z = |α|² − |β|²) plus the spherical angles θ and φ,
reusing the
Complexarithmetic fromSwiftQiskitCore. - Rendering — a 2D orthographic projection of the sphere with axes, drawn by the
shared
BlochSphereView, each sphere accompanied by a numeric readout. - Gallery — six canonical states built with real circuits and shown side by side: |0⟩ (north pole), |1⟩ via Pauli-X (south pole), |+⟩ via Hadamard (+x axis), |−⟩ via Hadamard + Pauli-Z (−x axis), |+i⟩ via Hadamard + S (+y axis), and |−i⟩ via Hadamard + S† (−y axis). The same vectors are also printed to the console.
User guide in Docs/02BLOCH2DHELP.md; the general recipe for putting a SwiftUI live
view on a playground page is in Docs/LIVEVIEWHELP.md.
A general single-qubit state, tilted off the equator of the Bloch sphere (45° from x, 60° from y and z), explored in depth.
- Ket definition — derives |ψ⟩ = cos(θ/2)|0⟩ + e^{iφ}·sin(θ/2)|1⟩ from direction
cosines and builds the state directly from its amplitudes with
StateVector. - Console readout — amplitudes, magnitudes, probabilities, and a round-trip check recovering the Bloch vector from the amplitudes.
- Live view — the state on a large Bloch sphere plus two plane projections
(x–y seen from +z, z–y seen from +x) drawn by the shared
BlochProjectionView.
User guide in Docs/03BLOCH2DPROJECTIONHELP.md.
An interactive 3D Bloch sphere: a rotatable wireframe rendered with a pure SwiftUI
Canvas (no SceneKit/RealityKit), plus live sliders for the spherical angles.
- 3D rendering — latitude/longitude circles are perspective-projected through an orbit camera; drag the canvas to rotate. The far hemisphere is drawn dimmer as a depth cue, and dashed drop lines connect the state vector to the equator plane.
- θ/φ sliders — rebuild |ψ⟩ = cos(θ/2)|0⟩ + e^{iφ}·sin(θ/2)|1⟩ on every change. The two sliders are independent because the parametrization keeps |α|² + |β|² = cos²(θ/2) + sin²(θ/2) = 1 identically — every slider position is a valid normalized state, shown live in the numeric readout.
- Xcode 27 beta note — running SwiftUI playground pages on the Xcode 27 beta
currently needs two workarounds, described in
PLAYGROUNDSUPPORT.md: a shim
libcups.dylibin DerivedData, and keeping@State-based views in the playground'sSources/folder (which is why the slider viewBlochExplorerViewlives there). Both are confirmed still present on beta 5 (27A5237l).
User guide: Docs/04BLOCH3DHELP.md.
A gentle, gate-by-gate tour of the built-in gate set in the results sidebar (no live
view, no prints): x, h, z (with the interference reveal that makes its phase flip
visible), y, s/sdg, t (applied twice to show T² == S), the general phase gate
p(theta:), and the rotations rx/ry/rz, each shown individually on a 1-qubit
QuantumCircuit, plus a one-line h+cx Bell-state teaser pointing to 07Entanglement.
User guide: Docs/05GATESHELP.md.
A 4-qubit console walkthrough: every qubit put into superposition via h, inspecting the
resulting 16-state amplitudes/probabilities and a 1600-shot measurement, plus a
partial-superposition (2-qubit) contrast. User guide:
Docs/06SUPERPOSITIONHELP.md.
Annotated walkthrough of the Bell state |Φ⁺⟩: builds the circuit (h + cx), inspects the
resulting state vector and its amplitudes/probabilities, and runs a 1000-shot measurement.
A GHZ section extends the recipe to 3 qubits — cx(0, 2) spans non-adjacent qubits — and
the page closes by rebuilding the Bell state via apply(CNOTGate.matrix) to show the
matrix form agrees with the fluent cx API.
User guide in Docs/07ENTANGLEMENTHELP.md.
Dirac-notation walkthrough of Quantum/Dirac.swift:
- Bras and kets — basis kets via
Ket("01")and the named states.zero/.one/.plus/.minus/.plusI/.minusI; the postfix dagger†turns aKetinto aBra(and givesMatrix.adjoint). - Products — inner products
Bra * Ket(orthonormality checks) and outer productsKet * Bra(projectors, completeness). - Expectation values — recovers the page-04 initial qubit's Bloch coordinates
as the Pauli expectation values ⟨ψ|X|ψ⟩, ⟨ψ|Y|ψ⟩, ⟨ψ|Z|ψ⟩, shown on a static
Bloch3DView.
User guide in Docs/08DIRACHELP.md.
Tensor-product walkthrough (console only), mirroring
Tests/SwiftQiskitCoreTests/TensorProductTests.swift section by section:
tensor(_:)/⊗onMatrixandStateVector, and the mixed-product identity (A ⊗ B)(C ⊗ D) = (AC) ⊗ (BD).- Gate embedding — building H ⊗ I by hand and checking it matches what
circuit.h(0)applies across a 2-qubit register. - Entanglement — why the Bell state cannot be factored as a tensor product of single-qubit states.
Design notes in Docs/09TENSORPLAN.md; user guide in Docs/09TENSORHELP.md.
Deutsch's algorithm (console only) — deciding whether a black-box function f: {0,1} → {0,1} is constant or balanced with a single oracle query:
- The four oracles — every 1-bit function's oracle U_f built from gates the
library already has: identity,
x(1),cx(0,1), andcx(0,1)+x(1). - Phase kickback — a stage-by-stage state-vector walkthrough showing how the |−⟩ ancilla turns the oracle into a phase (−1)^f(x) on the input qubit.
- Deterministic verdict — the final Hadamard maps the phase to qubit 0, so one measurement reads off constant (0) vs balanced (1) with certainty, confirmed for all four oracles and backed by shot statistics.
Design notes in Docs/10DEUTSCHPLAN.md; user guide in Docs/10DEUTSCHHELP.md.
Grover's search (console only) — finding a marked basis state with quadratically fewer oracle queries:
- CZ from existing gates — the controlled-Z built as
h(1); cx(0,1); h(1), then conjugated by X gates to make a phase oracle for any marked state |w⟩. - Inversion about the mean — an amplitude-by-amplitude walkthrough of one Grover iteration, with exact 1-iteration success on 2 qubits and what happens when you over-rotate by iterating further.
- The diffusion operator in Dirac notation — 2|s⟩⟨s| − I assembled directly from
the outer product in
Quantum/Dirac.swiftand checked against the gate construction. - 3-qubit finale — Grover on 8 states using a hand-built CCZ matrix applied via
apply(_:), with the theoretical success probability after each iteration.
Design notes in Docs/11GROVERPLAN.md; user guide in Docs/11GROVERHELP.md.
Compiled Shor's algorithm (console only) — factoring 15 by quantum order finding, with a 3-qubit counting register and a 4-qubit work register:
- Factoring reduces to order finding — the classical gcd reduction, plus the "lucky guess" cases where no quantum computer is needed at all.
- Modular multiplication as permutation matrices — U_a |w⟩ = |a·w mod 15⟩ and its
controlled powers hand-built (one
.oneper column) and applied viaapply(_:), with the orbit |1⟩ → |7⟩ → |4⟩ → |13⟩ → |1⟩ exposing the order geometrically. - A hand-built QFT† — the 8×8 inverse DFT constructed entrywise on the register's integer index (no bit-reversal bookkeeping), checked against Hadamard and unitarity.
- Phase estimation stage by stage — superposed counts, the entangled orbit, then
exact peaks at y = 8·s/r; shot statistics sampled from one
run()(with a note on whymeasure(shots:)is too slow at dimension 128). - Classical post-processing — measured phase → lowest terms → verified order → gcd factors, then a sweep of every coprime base including the instructive a = 14 failure (a^(r/2) ≡ −1).
Design notes in Docs/12SHORPLAN.md; user guide in Docs/12SHORHELP.md.
Quantum teleportation and its dual, superdense coding — entanglement used as a communication resource, with a Bloch-sphere live view:
- Teleportation on 3 qubits — Alice's payload, a shared Bell pair, her Bell-basis
rotation (
cx(0,1); h(0)), and Bob's X^b Z^a correction. - Measurement branches without measuring — the four outcomes recovered with Dirac projectors (|ab⟩⟨ab|) ⊗ I₂, showing P(ab) = ¼ regardless of |ψ⟩ (no signalling) and fidelity 1 once each branch gets its own correction.
- Deferred measurement — classical feedback replaced by
cx(1,2)and CZ(0,2), after which the register factors exactly as |+⟩ ⊗ |+⟩ ⊗ |ψ⟩ (~8e-17). - No cloning, concretely — Bob's marginal reproduces |ψ|² while Alice's qubit is left in |+⟩: the state moved rather than copied.
- Superdense coding — two classical bits carried by one qubit, decoded with certainty, with the Bell basis's Gram matrix printed as the identity to show why.
Design notes in Docs/13TELEPORTATIONPLAN.md; user guide in Docs/13TELEPORTATIONHELP.md.
The 3-qubit bit-flip/phase-flip repetition code — how a quantum computer protects one fragile qubit without ever looking at it directly, with a Bloch-sphere live view:
- Encode and extract a syndrome —
cx-based encoding and two ancilla parities that name the flipped qubit (or "none") without touching α or β. - A hand-built correction — a 32×32 permutation (Core has no Toffoli) that flips
whichever qubit the syndrome accuses, applied via
apply(_:). - Continuous errors, digitized exactly — an
rx(θ)sweep shows the coherent correction restoring fidelity 1.0000 at every θ, while the syndrome ancillas alone carry the cos²(θ/2)/sin²(θ/2) branch weights. - Where distance 3 breaks — two simultaneous errors alias to the wrong syndrome, producing a silent, fully "corrected" logical X; the exact logical error rate p_L = 3p² − 2p³ is confirmed by enumeration.
- Phase flips for free — Hadamard-conjugating the same code (H Z H = X) turns a Z error into the X error the rest of the page already fixes.
Design notes in Docs/14ERRORCORRECTIONPLAN.md; user guide in Docs/14ERRORCORRECTIONHELP.md.
The CHSH inequality — whether a Bell pair's correlations could ever come from a shared classical instruction list — with a live chart of the violation:
- The classical bound, exhaustively — all 16 deterministic ±1 strategies checked by brute force (max |S| = 2), plus a shared-direction hidden-variable model that saturates the bound and doubles as the chart's classical comparison curve.
- A pinned measurement convention — the tilted observable A(θ) = cos θ·Z + sin θ·X,
built entrywise, measured via
ry(-θ), with the sign checked against the exact expectation value (and against page 04/08's ⟨Z⟩/⟨X⟩ for the same qubit) before it's trusted. - Correlators two ways — exact via
psi† * (A(a) ⊗ A(b)) * psiand sampled viameasure(shots:), agreeing with cos(a−b). - The violation and its limits — a Bell pair's S = 2√2 against a product-state control (S = √2) and a fine angle sweep confirming the Tsirelson ceiling of 2√2, never higher.
- A live chart —
CHSHChartView(new sharedSources/type) plots the exact cos θ curve, sampled points, and the classical line together.
Design notes in Docs/15CHSHPLAN.md; user guide in Docs/15CHSHHELP.md.
The quantum Fourier transform as a gate circuit (console only) — closing the gap page 12 left open when it built the QFT as a single entrywise matrix:
- The missing gate — controlled phase CP(θ) derived from
p+cxalone (p(θ/2,c); cx(c,t); p(-θ/2,t); cx(c,t); p(θ/2,t)), checked against CZ at θ = π. - The QFT ladder — Hadamards and CP's per qubit, plus a swap network, checked against page 12's entrywise DFT to ~1e-15 on every basis state.
- Why the swaps — dropping them reproduces the exact bit-reversal of the correct output.
- The inverse QFT and unitarity — QFT then QFT† returns every basis state to itself.
- Standalone phase estimation — exact recovery of dyadic phases, a spread for phases that aren't, and a precision comparison at 3 vs. 6 counting qubits.
Design notes in Docs/16QFTPLAN.md; user guide in Docs/16QFTHELP.md.
Deutsch–Jozsa and Bernstein–Vazirani (console only) — page 10's algorithm generalized from 1 bit to n:
- The n-qubit circuit — page 10's shape widened to n input qubits + 1 ancilla.
- Oracles from
cx— constant and balanced functions built the same way page 10 did. - The verdict — P(all-zero input) is exactly 1 or 0, from a single query, for any n.
- A shot-sampling gotcha — the ancilla's bit is a free coin flip; only the input bits are
deterministic in
measure(shots:)output. - Bernstein–Vazirani — the identical circuit recovers an entire hidden n-bit string in one query.
- The query-count gap — quantum stays at 1 while classical Deutsch–Jozsa's worst case grows exponentially and classical Bernstein–Vazirani grows linearly.
Design notes in Docs/17DEUTSCHJOZSAPLAN.md; user guide in Docs/17DEUTSCHJOZSAHELP.md.
The variational quantum eigensolver — the one page where the circuit isn't fixed in advance, with a live chart of the optimization:
- The Hamiltonian — the qubit Hamiltonian for H₂ (Jordan–Wigner, minimal basis), assembled entrywise from six Pauli terms.
- A one-parameter ansatz —
x(0); ry(θ,1); cx(1,0), provably confined to the {|01⟩,|10⟩} subspace. - The energy —
psi† * H * psi, page 08's Dirac expectation-value idiom. - The exact answer — a closed-form 2×2 eigenvalue, used only to grade the optimizer.
- Parameter-shift gradients — exact, not approximate, for a single-rotation ansatz; pinned against a finite difference.
- Gradient descent — converges to the exact ground energy (error 0.00e+00) in ~10 steps.
- A live chart — the E(θ) landscape and the optimizer's own visited points, on the shared
CHSHChartView.
Design notes in Docs/18VQEPLAN.md; user guide in Docs/18VQEHELP.md.
The Bloch types and views (BlochVector, BlochSphereView, BlochProjectionView,
Bloch3DView, BlochExplorerView) and the shared 2D chart (CHSHChartView, used by pages 15
and 18) are shared between these pages via the playground's Sources/ folder (not part of
Core) — see Docs/LIVEVIEWHELP.md for a user guide to each type and
PLAYGROUNDSUPPORT.md for the implementation reference.
Contributions, ideas, and discussions are welcome. This project is built step by step and open for exploration.
Project status, what works in v0.1, and the roadmap live in STATUSandTODO.md, together with this fork's working TODO list.
MIT License © 2025 Ali Nasser