SwiftQiskit — Native Swift Quantum Computing Framework & Circuit Simulator

A pure Swift quantum circuit simulator and linear algebra engine implementing complex Hilbert space state vectors, unitary gate tensor products, quantum entanglement ($|\Phi^+ angle$), and an interactive SwiftUI circuit visualizer.

---

Table of Contents

• Overview
• Architecture & Engine Design
• Quantum Gates & Mathematical Primitives
• Package Targets & Products
• Code Examples
• Tech Stack
• Project Structure
• Getting Started
• Testing
• Author & License

---

Overview

SwiftQiskit brings quantum computing simulations natively to the Apple software ecosystem. Inspired by IBM's Qiskit SDK, SwiftQiskit is engineered in pure, strongly-typed Swift (with zero external C/Python dependencies). It allows iOS and macOS developers to construct quantum circuits, apply single-qubit and multi-qubit quantum gates, compute state vector evolutions in $2^n$-dimensional Hilbert space, and execute probabilistic projective measurements.

Core Capabilities

• High-Performance Complex Linear Algebra: Custom Complex arithmetic and Matrix tensor/Kronecker product engine.
• Unitary Gate Transformations: Exact matrix multiplication for Hadamard ($H$), Pauli-$X$, Pauli-$Z$, and Controlled-NOT ($ ext{CNOT}$).
• SwiftUI Visual Interface: Desktop GUI target for interactive circuit simulation and quantum state inspection.
• Cross-Platform Apple Compatibility: Runs on macOS 13+ (Apple Silicon / Intel) and iOS 16+.

---

Architecture & Engine Design

flowchart TD
    subgraph MathEngine["Linear Algebra & Complex Number Engine"]
        ComplexNum["Complex (Real & Imaginary Arithmetic)"]
        MatrixEngine["Matrix (Kronecker / Tensor Products)"]
    end

    subgraph QuantumCore["Quantum Core (SwiftQiskitCore)"]
        StateVector["StateVector (Normalized Complex Amplitudes)"]
        Gates["Unitary Gates (Hadamard, PauliX, PauliZ, CNOT)"]
        Circuit["QuantumCircuit (Operation Pipeline & Runner)"]
        SimResult["SimulationResult (Measurement Histogram & State)"]
    end

    subgraph Presentation["Application Targets"]
        CLI["SwiftQiskitExamples (CLI Runner)"]
        GUI["SwiftQiskitGUI (SwiftUI Desktop App)"]
    end

    ComplexNum --> MatrixEngine
    MatrixEngine --> Gates & StateVector
    Gates --> Circuit
    StateVector --> Circuit
    Circuit --> SimResult
    SimResult --> CLI & GUI

Loading

---

Quantum Gates & Mathematical Primitives

1. Hadamard Gate ($H$)

Creates equal superposition states from basis states: $$H = rac{1}{\sqrt{2}}�egin{pmatrix} 1 & 1 \ 1 & -1 \end{pmatrix}, \quad H|0 angle = rac{|0 angle + |1 angle}{\sqrt{2}} = |+ angle$$

2. Pauli Gates ($X, Z$)

• Pauli-X (Bit Flip): $$X = �egin{pmatrix} 0 & 1 \ 1 & 0 \end{pmatrix}, \quad X|0 angle = |1 angle$$
• Pauli-Z (Phase Flip): $$Z = �egin{pmatrix} 1 & 0 \ 0 & -1 \end{pmatrix}, \quad Z|+ angle = |- angle$$

3. Controlled-NOT Gate ($ ext{CNOT} / CX$)

Entangles target qubit conditioned on control qubit state: $$ ext{CNOT} = �egin{pmatrix} 1 & 0 & 0 & 0 \ 0 & 1 & 0 & 0 \ 0 & 0 & 0 & 1 \ 0 & 0 & 1 & 0 \end{pmatrix}$$

4. Bell State Creation ($|\Phi^+

angle$) $$|\Phi^+ angle = ext{CNOT}_{0,1} (H_0 \otimes I_1) |00 angle = rac{|00 angle + |11 angle}{\sqrt{2}}$$

---

Package Targets & Products

Target Name	Type	Description
SwiftQiskitCore	Library	Core quantum state engine, matrix operations, and gate definitions.
SwiftQiskitGUI	Executable (macOS)	Native SwiftUI interactive circuit visualizer.
SwiftQiskitExamples	Executable (CLI)	Terminal examples demonstrating entanglement and teleportation.
SwiftQiskitCoreTests	Test Target	XCTest suite validating unitary transformations and probabilities.

---

Code Examples

1. Generating a 2-Qubit Bell State

import SwiftQiskitCore

// Initialize a 2-qubit quantum circuit in |00>
let circuit = QuantumCircuit(qubits: 2)

// Apply Hadamard to qubit 0
circuit.h(0)

// Apply CNOT with control=0, target=1
circuit.cx(control: 0, target: 1)

// Execute simulation
let stateVector = circuit.run()

// Output normalized complex amplitudes:
// |00> = 0.7071 + 0.0i (50% probability)
// |11> = 0.7071 + 0.0i (50% probability)
print("State Vector:", stateVector)

2. Performing Shots-Based Measurement

let result = circuit.measure(shots: 1024)
print("Measurement Counts:", result.counts)
// Example output: ["00": 518, "11": 506]

---

Tech Stack

• Language: Swift 5.9+
• Build System: Swift Package Manager (SwiftPM)
• Platforms: macOS 13.0+ (Ventura, Sonoma, Sequoia), iOS 16.0+
• UI Framework: SwiftUI (macOS Target)
• Testing: XCTest (Deterministic Unit & Property Tests)

---

Project Structure

SwiftQiskit/
├── Package.swift                    # SwiftPM Manifest & Target Topology
├── Sources/
│   ├── SwiftQiskitCore/             # Core Quantum Framework
│   │   ├── Circuit/
│   │   │   └── QuantumCircuit.swift # Circuit Pipeline & Gate Dispatcher
│   │   ├── Gates/                   # Quantum Gate Matrix Implementations
│   │   │   ├── Hadamard.swift       # H Gate
│   │   │   ├── PauliX.swift         # X Gate
│   │   │   ├── PauliZ.swift         # Z Gate
│   │   │   └── CNOT.swift           # Controlled-NOT Gate
│   │   ├── Math/                    # Linear Algebra Primitives
│   │   │   ├── Complex.swift        # Complex Number Arithmetic
│   │   │   └── Matrix.swift         # 2^N Matrix Operations & Tensor Products
│   │   ├── Quantum/                 # State Representation
│   │   │   ├── StateVector.swift    # Complex Amplitude Vector
│   │   │   └── SimulationResult.swift # Measurement Histograms
│   │   └── Utils/
│   │       └── String+Padding.swift
│   └── SwiftQiskitGUI/              # SwiftUI Desktop Application
│       ├── ContentView.swift        # Circuit & Measurement UI
│       └── main.swift               # GUI Entry Point
├── Examples/
│   └── main.swift                   # CLI Demonstration
└── Tests/
    └── SwiftQiskitCoreTests/
        └── BellStateTests.swift     # XCTest Verification Suite

---

Getting Started

1. Add as a Swift Package Dependency

In your Package.swift:

dependencies: [
    .package(url: "https://github.com/a360n/SwiftQiskit.git", from: "1.0.0")
]

2. Build and Run via Swift CLI

# Clone the repository
git clone https://github.com/a360n/SwiftQiskit.git
cd SwiftQiskit

# Run tests
swift test

# Run example CLI executable
swift run SwiftQiskitExamples

# Launch SwiftUI Desktop App
swift run SwiftQiskitGUI

---

Testing

swift test --filter BellStateTests

---

Author

Ali Nasser (Ali Al-Khazali)

• Portfolio: www.ali-nasser.dev
• GitHub: @a360n
• LinkedIn: Ali Nasser

---

License

This project is licensed under the MIT License — see the LICENSE file for details.