ts-quantum

A comprehensive TypeScript library for quantum mechanics calculations and simulations. Built for both educational purposes and practical quantum computing applications.

🚀 Features

Core Quantum Mechanics

• Quantum State Vectors - Complete state vector operations with complex amplitudes
• Quantum Gates - Standard gates (Pauli, Hadamard, CNOT, Phase, etc.)
• Density Matrices - Mixed state operations and quantum channels
• Quantum Measurements - Projective measurements and Born rule calculations
• Hilbert Space Operations - Tensor products, direct sums, and basis transformations

Advanced Features

• Hamiltonian Evolution - Time evolution with matrix exponentiation
• Angular Momentum Algebra - Complete SU(2) representation theory
• Wigner Symbols - 3j, 6j, and 9j symbols for angular momentum coupling
• Clebsch-Gordan Coefficients - Angular momentum composition
• Quantum Information - Entanglement measures, fidelity, and distances
• Geometric Quantum Mechanics - Fubini-Study metric and quantum distances

Numerical Methods

• Eigendecomposition - Robust eigenvalue/eigenvector computation
• Matrix Functions - Matrix exponentials, logarithms, and arbitrary functions
• Sparse Matrix Support - Efficient operations for large quantum systems
• Optimization - Performance-optimized for multi-qubit systems

📦 Installation

npm install ts-quantum

🎯 Quick Start

import { 
  StateVector,
  PauliX,
  Hadamard,
  CNOT,
  measure,
  DensityMatrix
} from 'ts-quantum';

// Create a qubit in |0⟩ state
const qubit = StateVector.computationalBasis(2, 0);

// Apply Hadamard gate to create superposition
const superposition = Hadamard.apply(qubit);

// Measure the state
const result = measure(superposition);
console.log(`Measured: ${result.value} with probability ${result.probability}`);

// Create Bell state
const twoQubits = StateVector.computationalBasis(4, 0); // |00⟩
const bellState = CNOT.apply(Hadamard.extend(2).apply(twoQubits));

// Work with density matrices
const rho = DensityMatrix.fromStateVector(bellState);
console.log(`Purity: ${rho.purity()}`);
console.log(`Entropy: ${rho.vonNeumannEntropy()}`);

🧮 Requirements

• Node.js >= 14.0.0
• TypeScript >= 4.5.0 (optional, works with JavaScript too)
• mathjs >= 10.0.0 (automatically installed)

📚 Core API

StateVector

// Create and manipulate quantum states
const state = new StateVector(dimension);
const |0⟩ = StateVector.computationalBasis(2, 0);
const |+⟩ = StateVector.superposition(2, [0, 1]);

// State operations
const normalized = state.normalize();
const probability = state.measurementProbability(index);
const overlap = state1.innerProduct(state2);

Quantum Gates

// Single-qubit gates
const X = PauliX;           // NOT gate
const Y = PauliY;           // Y rotation
const Z = PauliZ;           // Phase flip
const H = Hadamard;         // Superposition gate
const S = PhaseGate;        // Phase gate
const T = TGate;           // π/8 gate

// Multi-qubit gates
const cx = CNOT;           // Controlled-X
const cy = ControlledY;    // Controlled-Y
const cz = ControlledZ;    // Controlled-Z

// Apply gates
const result = H.apply(state);
const extended = X.extend(2).apply(twoQubitState);

Measurements

// Computational basis measurement
const outcome = measure(state);

// Projective measurement with custom operator
const projection = projectiveMeasurement(state, operator);

// Measurement probabilities
const probs = state.measurementProbabilities();

Advanced Operations

// Angular momentum
import { createAngularState, clebschGordan, wigner3j } from 'ts-quantum';

const |j,m⟩ = createAngularState(1, 0);  // |1,0⟩ state
const cg = clebschGordan(0.5, 0.5, 0.5, -0.5, 0, 0);  // Singlet coefficient
const w3j = wigner3j(1, 1, 2, 0, 0, 0);  // 3j symbol

// Quantum distances
import { quantumDistance, fidelity } from 'ts-quantum';

const distance = quantumDistance(state1, state2);
const overlap = fidelity(rho1, rho2);

🔬 Examples

Creating Bell States

import { StateVector, Hadamard, CNOT } from 'ts-quantum';

// |Φ⁺⟩ = (|00⟩ + |11⟩)/√2
const phi_plus = CNOT.apply(
  Hadamard.extend(2).apply(
    StateVector.computationalBasis(4, 0)
  )
);

// Verify maximum entanglement
const rho = DensityMatrix.fromStateVector(phi_plus);
console.log(`Entanglement entropy: ${rho.vonNeumannEntropy()}`); // ≈ 0.693

Quantum Random Walk

import { StateVector, hadamardWalk } from 'ts-quantum';

// 1D quantum random walk
const walker = hadamardWalk(position: 0, steps: 10);
const finalState = walker.evolve();

Angular Momentum Coupling

import { createAngularState, coupleAngularMomenta } from 'ts-quantum';

// Couple two spin-1/2 particles
const spin1 = createAngularState(0.5, 0.5);   // |↑⟩
const spin2 = createAngularState(0.5, -0.5);  // |↓⟩

// Create coupled states in both singlet and triplet channels
const { singlet, triplet } = coupleAngularMomenta(spin1, spin2);

📖 Documentation

• API Reference - Complete API documentation
• Examples - Practical usage examples
• Theory Guide - Mathematical background

🧪 Testing

The library includes comprehensive tests with 94% pass rate (422/451 tests passing). All core functionality and examples work correctly.

npm test                 # Run all tests
npm run test:coverage    # Run with coverage report
npm run test:watch       # Watch mode for development

🏗️ Development

# Clone and setup
git clone https://github.com/space-cadet/ts-quantum.git
cd ts-quantum
npm install

# Build
npm run build

# Generate documentation
npm run docs

🎓 Educational Use

This library is designed to be educational while remaining computationally robust. Each operation includes:

• Clear mathematical definitions
• Physical interpretations
• Worked examples
• Performance characteristics

Perfect for:

• Quantum mechanics courses
• Quantum computing education
• Research prototyping
• Algorithm development

⚡ Performance

• Optimized for systems up to ~15 qubits
• Sparse matrix support for larger systems
• Efficient eigendecomposition algorithms
• Memory-conscious implementations

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

• Qiskit - IBM's quantum computing framework
• Cirq - Google's quantum computing library
• PennyLane - Quantum machine learning

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Online Docs

ts-quantum - Bringing quantum mechanics to TypeScript with mathematical rigor and computational efficiency.