NumPyQuantum

A beginner-friendly, lightweight quantum circuit simulator built entirely from scratch using NumPy.

This repository contains a quantum simulation library in quantum_core/, along with example scripts demonstrating core quantum concepts like entanglement, superdense coding, and teleportation.

✨ Supported Quantum Gates

• Single Qubit Gates: Identity (I), Pauli-X (X), Pauli-Y (Y), Pauli-Z (Z), Hadamard (H), Phase (S), T
• Two Qubit Gates: CNOT, CZ
• Parametric Gates: phase_gate(theta), rotation_y_gate(theta)

📂 Repository structure

• quantum_core/
  • state.py — state vector creation, validation, normalization, and measurement utilities.
  • gates.py — predefined gates, gate validation, and parametric gates.
  • circuit.py — applying gates to state vectors.
  • measurement.py — partial measurement and state collapse logic.
• example scripts in the repository root
  • 01_entanglement.py — builds and measures a Bell pair.
  • 02_quantum_communication.py — demonstrates basis encoding and decoding.
  • 03_superdense_coding.py — encodes and decodes classical bits with quantum states.
  • 04_teleportation.py — implements quantum teleportation.
• DOCUMENTATION.md — detailed API usage for each function.

⚙️ Requirements

• Python 3.8+
• NumPy

Install dependencies with:

pip install numpy

🚀 Quick start

Run one of the example scripts from the repository root:

python 01_entanglement.py

💻 Example usage

import numpy as np
from quantum_core.state import make_zero_state, make_one_qubit_state, normalize_state
from quantum_core.gates import H, CNOT, X, Z
from quantum_core.circuit import apply_gate
from quantum_core.measurement import get_probabilities, measure

# Create a 2-qubit zero state
state = make_zero_state(2)

# Apply Hadamard to the first qubit and CNOT to create entanglement
state = apply_gate(state, H, [0])
state = apply_gate(state, CNOT, [0, 1])

# Show probabilities and measure qubit 0
print(get_probabilities(state))
measured_bit, collapsed_state = measure(state, [0])
print(measured_bit)
print(get_probabilities(collapsed_state))

📖 Documentation

Detailed API documentation explaining every public function, variable, and error handling is available in DOCUMENTATION.md.