quantum-math-lab/README.md

Quantum Math Lab

Pure-Python quantum circuit simulator with a companion catalog of unsolved problems in mathematics.

Simulator

The QuantumCircuit class implements a state-vector simulator that stores the full 2^n complex amplitude vector and applies gates as matrix operations. No external quantum framework required — just NumPy.

Supported Gates

Gate	Method	Matrix
Hadamard	hadamard(q)	(1/sqrt(2)) 1,1],[1,-1
Pauli-X	pauli_x(q)	0,1],[1,0
CNOT	cnot(c, t)	4x4 controlled-NOT
Custom	apply_custom(U, qubits)	Any unitary matrix

Quick Start

pip install numpy

from quantum_simulator import QuantumCircuit
import numpy as np

# Create a Bell state: (|00> + |11>) / sqrt(2)
circuit = QuantumCircuit(2)
circuit.hadamard(0)
circuit.cnot(0, 1)

print(circuit.probabilities())
# {'00': 0.5, '01': 0.0, '10': 0.0, '11': 0.5}

result = circuit.measure(shots=1000, rng=np.random.default_rng(42))
print(result.counts)
# {'00': 494, '01': 0, '10': 0, '11': 506}

3-Qubit GHZ State

circuit = QuantumCircuit(3)
circuit.hadamard(0)
circuit.cnot(0, 1)
circuit.cnot(0, 2)
# |000> + |111> with equal probability, all other states zero

Custom Unitaries

# Pauli-Z gate
Z = np.array([[1, 0], [0, -1]], dtype=complex)
circuit = QuantumCircuit(1)
circuit.apply_custom(Z, [0])

# SWAP gate
SWAP = np.array([[1,0,0,0],[0,0,1,0],[0,1,0,0],[0,0,0,1]], dtype=complex)
circuit = QuantumCircuit(2)
circuit.apply_custom(SWAP, [0, 1])

Architecture

QuantumCircuit(n)
  |
  |-- _state: np.ndarray[complex128]   # 2^n amplitude vector
  |-- hadamard(q) / pauli_x(q)         # Single-qubit gates
  |-- cnot(c, t)                        # Two-qubit gate
  |-- apply_custom(U, qubits)           # Arbitrary unitary
  |-- probabilities(qubits?)            # |amplitude|^2 distribution
  |-- measure(qubits?, shots, rng)      # Sample + collapse
       |
       +-- MeasurementResult
             |-- counts: {bitstring: int}
             |-- most_likely() -> str
             |-- total_shots() -> int

State is stored as a dense vector reshaped into a tensor for gate application via permutation and matrix multiplication. Measurement collapses the state vector by projecting onto the observed subspace and renormalizing.

Unsolved Problems

problems.md covers ten influential open problems:

1. Riemann Hypothesis
2. P vs NP
3. Navier-Stokes regularity
4. Hodge Conjecture
5. Yang-Mills mass gap
6. Birch and Swinnerton-Dyer
7. Goldbach's Conjecture
8. Twin Prime Conjecture
9. Collatz Conjecture
10. abc Conjecture

Each entry includes a problem statement, known progress, and references.

Development

# Install
pip install -r requirements.txt

# Run tests (35+ tests)
make test

# Lint
make lint

# Coverage report
make coverage

License

Proprietary — BlackRoad OS, Inc. See LICENSE.