Documentation

Creates equal superposition from a basis state. Transforms |0⟩ into (|0⟩+|1⟩)/√2 and |1⟩ into (|0⟩−|1⟩)/√2. Fundamental building block for quantum algorithms — used to initialize uniform superposition in Grover's search, QFT, and most variational circuits.

Quantum bit flip — the NOT gate. Rotates the Bloch sphere 180° around the X-axis. Maps |0⟩ ↔ |1⟩. Used in oracle constructions, error correction encoding, and state preparation.

Combined bit and phase flip. Rotates 180° around the Y-axis of the Bloch sphere. Maps |0⟩ → i|1⟩ and |1⟩ → −i|0⟩. Appears in depolarizing noise channels and certain error correction codes.

Phase flip gate. Leaves |0⟩ unchanged, maps |1⟩ → −|1⟩. Rotates 180° around the Z-axis. Core component of phase kickback in Grover oracles and the building block for controlled-phase operations.

90° phase rotation gate. Applies a π/2 phase to the |1⟩ state. S² = Z. Used in the Clifford group and quantum error correction stabilizer codes. Essential for T-gate decompositions in fault-tolerant computation.

45° phase rotation gate. Applies π/4 phase to |1⟩. The T gate completes the universal gate set when combined with Clifford gates (H, S, CNOT). Critical for fault-tolerant quantum computing via magic state distillation.

Continuous rotation around the X-axis by angle θ. Rx(π) = X. Parameterized gate used extensively in variational quantum eigensolvers (VQE) and quantum approximate optimization (QAOA). Gradient-friendly for hybrid quantum-classical optimization.

Continuous rotation around the Y-axis by angle θ. Maps |0⟩ to cos(θ/2)|0⟩ + sin(θ/2)|1⟩. Unique among rotation gates: the matrix is purely real, making it the preferred choice for amplitude encoding of classical data into quantum states.

Continuous rotation around the Z-axis by angle θ. Diagonal gate — does not change measurement probabilities, only modifies relative phase. Rz(π/2) = S, Rz(π/4) = T (up to global phase). Native gate on most superconducting hardware.

Flips the target qubit if and only if the control qubit is |1⟩. The primary entangling gate — transforms |00⟩+|10⟩ into |00⟩+|11⟩ (Bell state when preceded by H on control). Together with single-qubit rotations, forms a universal gate set. Decomposition target for most multi-qubit operations.

Applies a Z gate to the target qubit when the control is |1⟩. Equivalently, flips the phase of the |11⟩ state: |11⟩ → −|11⟩. Symmetric — control and target are interchangeable. Native gate on many ion-trap and superconducting architectures. Preferred for lattice-surgery in surface codes.

Exchanges the quantum states of two qubits: |ψ⟩⊗|φ⟩ → |φ⟩⊗|ψ⟩. Decomposes into three CNOT gates. Essential for routing on hardware with limited qubit connectivity. The √SWAP gate is a natural entangling gate on some semiconductor qubit platforms.

ρ → (1−p)ρ + (p/3)(XρX + YρY + ZρZ)

The most common noise model. With probability p, applies a random Pauli operator (X, Y, or Z) uniformly. At p = 3/4, the qubit is fully depolarized to the maximally mixed state I/2. Models worst-case incoherent noise. Used as a benchmark channel in quantum error correction threshold calculations.

K₀ = [[1,0],[0,√(1−γ)]], K₁ = [[0,√γ],[0,0]]

Models energy relaxation (T₁ decay). Drives the excited state |1⟩ toward the ground state |0⟩ with probability γ. At γ = 1, any state collapses to |0⟩. This is a non-unital channel — it does not preserve the maximally mixed state, reflecting the thermodynamic arrow.

K₀ = [[1,0],[0,√(1−λ)]], K₁ = [[0,0],[0,√λ]]

Models pure dephasing (T₂ decay) without energy loss. Destroys off-diagonal coherence in the density matrix: ρ₀₁ → √(1−λ)·ρ₀₁. At λ = 1, all phase information is lost and the state becomes classical. This is a unital channel — it preserves I/2.

Statevector Representation

Struct-of-arrays layout using two Float64Array buffers (real and imaginary parts). All gate operations are applied in-place for zero-allocation simulation. Dimension is always 2ⁿ for n qubits.

Qubit Limits

1 to 10 qubits supported (2 to 1024 basis states). Memory scales exponentially — 10 qubits requires 16 KB for the statevector. The engine validates bounds before execution.

Circuit Constraints

Maximum 200 steps per circuit. Each step can contain multiple parallel gate operations on non-overlapping qubits. Steps are executed sequentially left-to-right.

Measurement Engine

Up to 100,000 shots per simulation run. Uses cumulative distribution sampling from the Born rule probabilities. Results are returned as a frequency dictionary keyed by bitstring.

Pseudorandom Number Generator

mulberry32 — a 32-bit seedable PRNG providing deterministic, reproducible results. The same seed + circuit always produces identical measurement distributions. Used for both noise simulation and shot sampling.

Input Validation

All circuit definitions are validated against Zod schemas before execution. This catches invalid gate names, out-of-range qubit indices, malformed angles, and constraint violations at the boundary, not at simulation time.