SwiftQiskitApp

SwiftQiskitApp contains a large set of introductory documents (see INTRODUCTION.md) which are illustrated in an iOS/iPadOS/macOS based SwiftQiskitApp and supplemented by a set of Xcode playgrounds contained in SwiftQiskitPlaygrounds.

SwiftQiskitApp is a SwiftUI app for building quantum circuits by tapping gates onto a grid (circuit) instead of writing code.

Place gates, watch the state vector update live, then measure with as many shots as you like and see a histogram of the outcomes. Display the Bloch sphere(s) (final, after each step or in 3D) and a tensor network representation.

It is intended as a "get familiar" tool for playing around with quantum circuits.

SwiftQiskitPlaygrounds lets you go further by writing Swift code.

At some point you might want to switch to e.g. Julia's Yao (see reference 5), or Qiskit, Cirq or PennyLane (see references 7 to 9), and potentially run the code on a quantum computer (see Chapter 0).

This app is a thin front end. All quantum simulation — state vectors, gates, measurement — is implemented by the SwiftQiskit package; this repo contributes only the UI and a small model that replays placed gates onto a QuantumCircuit.

---

Requirements

• Xcode 27, macOS 27 / iOS 27.
• No local setup beyond that — Xcode resolves the SwiftQiskit package dependency from GitHub automatically. A checkout of SwiftQiskitPlaygrounds is only needed if you want to browse its playground pages (see Docs/Introduction/01-Setup.md).

Getting started

1. Open SwiftQiskitApp.xcodeproj in Xcode.
2. Pick a run destination — My Mac, or an iOS device/simulator.
3. Run (⌘R). The app opens on an empty 2-qubit circuit.

See Docs/Tutorial.md for a full walkthrough that builds and measures a Bell state.

---

Features

• Gate palette — Hadamard/Pauli (H X Y Z), phase (S S† T T†), rotations (P RX RY RZ, each with a θ parameter), the two-qubit CX (CNOT), CY, CZ and SWAP, and the two-qubit rotations RZZ RXX RYY (each with a θ parameter).
• Tap-to-place — arm a gate in the palette, then tap a wire to place it. Multi-qubit gates need multiple taps in the same column: CX and CY distinguish control from target, while CZ, SWAP and RZZ/RXX/RYY treat the two taps the same way. The popover on a control dot adds or removes extra controls (multi-controlled CX, CY and CZ).
• Live state vector — recomputed on every change, no explicit "run" step.
• Measure — choose a shot count (1–10,000) and see a bar-chart histogram of the results.
• 1–8 qubits, adjustable with a stepper; shrinking the count drops gates that no longer fit.
• θ editor — tap a placed parameterized gate to open a popover with a 0–2π slider.
• Bloch sphere display — a Display button opens a Bloch-sphere view: every qubit's final state at once, one chosen qubit's state after each column, a tensor-network diagram of the circuit, or a rotatable 3D sphere you orbit by dragging.

Layouts

Layout	Platforms	Description
Regular	macOS, iPad	Three-pane: gate palette, circuit grid, and live results side by side (the results pane hides below 672 pt wide, e.g. in iPad Split View)
Compact	iPhone	Full-bleed circuit grid with a horizontal gate strip below; results open in a sheet

Project structure

SwiftQiskitApp/
├── SwiftQiskitApp/
│   ├── CircuitModel.swift
│   ├── CircuitLayout.swift
│   ├── CircuitWiresView.swift
│   ├── CircuitGridView.swift
│   ├── GateTileView.swift
│   ├── GatePaletteView.swift
│   ├── ParameterPopover.swift
│   ├── ResultsView.swift
│   ├── MeasurementView.swift
│   ├── HistogramView.swift
│   ├── BlochSphereView.swift
│   ├── Bloch3DSphereView.swift
│   ├── BlochDisplayView.swift
│   ├── CircuitBuilderView.swift
│   ├── CompactBuilderView.swift
│   ├── ContentView.swift
│   └── SwiftQiskitAppApp.swift
├── SwiftQiskitAppTests/
│   ├── CircuitBuilderTests.swift
│   ├── CircuitLayoutTests.swift
│   ├── BlochVectorTests.swift
│   └── Bloch3DProjectionTests.swift
├── Docs/
│   ├── Introduction/
│   ├── Tutorial.md
│   ├── Help.md
│   ├── Todo.md
│   ├── TemplatesPlan.md
│   └── SwiftQiskit as an external SPM.md
├── Templates/
├── INTRODUCTION.md
├── README.md
└── CLAUDE.md

Testing

Run via ⌘U or the RunAllTests MCP tool under the SwiftQiskitApp scheme — 41 tests total, using the Swift Testing framework (not XCTest).

---

Documentation

• INTRODUCTION.md — a 27-chapter, book-length introduction to quantum computing (plus a Chapter 0 opener) taught through this app and the SwiftQiskit playgrounds, chapter by chapter, from qubits and gates through the named algorithms (Deutsch, Grover, the QFT, Shor, teleportation, error correction, the CHSH inequality, ...) and on to noise, tomography, and VQE.
• Docs/Introduction/ — contains Chapter 0 and the 27 numbered chapters.
• Docs/Tutorial.md — how to use the app, step by step.
• Docs/Help.md — implementation reference, extension guide, troubleshooting.
• Docs/Todo.md — status and roadmap.
• Docs/TemplatesPlan.md — design of the Xcode project template.
• Docs/SwiftQiskit as an external SPM.md — record of moving from a local package path to a version-tagged remote dependency.
• Templates/README.md — an Xcode project template for starting a new quantum-algorithm demo app, prefilled with a worked example.
• CLAUDE.md — guidance for Claude Code working in this repo.

For everything about the simulator itself — the gate set, Dirac notation, tensor products, see the SwiftQiskit package. The playground pages that teach quantum computing algorithm by algorithm are in SwiftQiskitPlaygrounds (neither checkout is required to build this app).

Status

v1 scope: no persistence, no undo, no drag-and-drop. See Docs/Todo.md for the full roadmap.

---

References

1. Ali Nasser - The parent repository for SwiftQiskit.
2. Quantum Computing for everyone - Good starting book.
3. Medium - Short introductions, part 1 to 4.
4. Quantum Mechanics - Leonard Susskind's lectures at Stanford, many years ago, triggered my interest.
5. Yao - For me, a Julia supporter, a great next step.
6. Quantum Computing made simple - Another good introductory book.
7. Qiskit - The Python library SwiftQiskit is modelled on; it also runs on IBM's quantum hardware.
8. Cirq - Google Quantum AI's Python framework, close to the hardware, with explicit qubit layouts and noise models.
9. PennyLane - A Python framework for differentiable circuits, suited to variational algorithms such as VQE.