q5m.js

A complete type-safe TypeScript library for quantum computing simulations with comprehensive algorithm support, and seamless multi-framework integration.

✨ Features

• 📝 TypeScript First - Complete type safety with strict mode, 90%+ test coverage
• 🔬 Advanced Quantum Simulation - Complete quantum computing primitives with state-of-the-art optimization
• 🔧 Flexible APIs - Multiple entry points and API styles for different use cases
• ⚡ Modern Tooling - Built with Vite, esbuild, Jest, and Cypress for optimal DX
• 🧪 Well Tested - 2000+ comprehensive tests across unit, integration, and E2E scenarios
• 🌐 Multi-Framework - Native support for React, Vue, Angular, and vanilla JavaScript
• 🎲 Algorithm Library - Built-in quantum algorithms with optimized implementations
• 📊 Rich Visualization - Circuit diagrams, state visualization, and export capabilities
• 🔌 Extensible Architecture - Plugin system for custom extensions and integrations
• 🚀 High Performance - Hybrid sparse/dense quantum states with CSR format, up to 45% performance improvement
• 🎯 Memory Optimized - Intelligent state representation switching, 28% memory reduction for large systems

📦 Installation

npm install q5m

🚀 Quick Start

Basic Quantum Circuit

import { Circuit } from 'q5m';

// Create a 2-qubit Bell state
const circuit = new Circuit(2);
circuit.h(0).cnot(0, 1);

const result = circuit.execute();
console.log('Bell state probabilities:', result.state.probabilities());

Advanced Usage with Custom Initial State

import { Circuit, QubitState, complex } from 'q5m';

// Create custom initial state
const customState = new QubitState(2, [
  complex(0.5, 0),   // |00⟩
  complex(0, 0.5),   // |01⟩  
  complex(0.5, 0),   // |10⟩
  complex(0, -0.5)   // |11⟩
]);

const circuit = new Circuit(2);
circuit.h(0).measure(0);
const result = circuit.run(customState);

if( result.hasMeasurements ) {
    for ( const m of result.measurements ){
        console.log('Measurement results: [', m.measureIndex,'] ', m.outcome, '[', m.probability , '%]');
        console.log('After state vector:', m.collapsedState.stateVector);
    }
} else {
    console.log('After state vector:', result.state.stateVector);
}

📚 Package Structure & Entry Points

q5m.js provides optimized entry points for different use cases:

🎯 Core Package (Lightweight)

Minimal bundle (~65KB) - Essential quantum computing primitives

import { Circuit, QubitState } from 'q5m/core';
// Only core quantum circuit and state functionality

📦 Standard Import (Full Features)

Complete library (~195KB) - All features including algorithms

import { 
  Circuit, 
  groverSearch, 
  quantumFourierTransform,
  exportToQiskit 
} from 'q5m';

🌐 Browser/CDN

UMD build for direct browser usage

<script src="https://unpkg.com/q5m/dist/q5m.min.js"></script>
<script>
  const circuit = new Q5M.Circuit(3);
  circuit.h(0).cnot(0, 1).cnot(1, 2);
  console.log(circuit.execute().state.probabilities());
</script>

📱 Framework-Specific Usage

React Integration

import React, { useState } from 'react';
import { Circuit, CircuitRenderer } from 'q5m';

function QuantumApp() {
  const [circuit] = useState(() => {
    const c = new Circuit(2);
    return c.h(0).cnot(0, 1);
  });

  return (
    <div>
      <h1>Bell State Circuit</h1>
      <pre>{circuit.toString()}</pre>
      <p>Probabilities: {JSON.stringify(circuit.execute().state.probabilities())}</p>
    </div>
  );
}

🔬 Core Concepts

Quantum Circuits

Central abstraction for building and executing quantum computations:

import { Circuit } from 'q5m';

// Create circuit with specified number of qubits
const circuit = new Circuit(3);

// Fluent API for gate composition
circuit
  .h(0)                    // Hadamard gate on qubit 0
  .cnot(0, 1)             // CNOT from qubit 0 to 1
  .rz(Math.PI / 4, 2)     // Z rotation on qubit 2
  .measure([0, 1, 2]);    // Measure all qubits

// Execute and get results
const result = circuit.execute();
console.log('Final state:', result.amplitudes());
console.log('Measurements:', result.measurements);

Quantum States

Advanced state representation with automatic optimization:

import { QubitState, complex } from 'q5m';

// Automatic sparse/dense optimization
const state = new QubitState(10); // 10-qubit state
console.log('Memory usage:', state.memoryUsage(), 'bytes');

// Access individual amplitudes efficiently
const amplitude = state.amplitude(0b1010101010);
console.log('Amplitude for |1010101010⟩:', amplitude.toString());

// State operations
const prob = state.probability(0b0000000000);
console.log('Probability of |0000000000⟩:', prob);

🎲 Built-in Quantum Algorithms

Grover's Search Algorithm

import { groverSearch, groverSearchForItem } from 'q5m';

// Search for specific bit pattern
const result = groverSearchForItem(4, '1010'); // 4 qubits, search for |1010⟩
console.log('Found item with probability:', result.probability(0b1010));

// Custom oracle search
const oracle = (bitString: string) => bitString === '1100';
const searchResult = groverSearch(4, oracle);

Quantum Fourier Transform

import { quantumFourierTransform, qftEncode } from 'q5m';

// Apply QFT to encode classical data
const data = [1, 2, 3, 4];
const qftCircuit = qftEncode(data);
const result = qftCircuit.execute();

console.log('QFT encoded state:', result.amplitudes());

Quantum Phase Estimation

import { quantumPhaseEstimation, estimateEigenstatePhase } from 'q5m';

// Estimate phase of a unitary operator
const unitary = [
  [complex(Math.cos(0.3), 0), complex(-Math.sin(0.3), 0)],
  [complex(Math.sin(0.3), 0), complex(Math.cos(0.3), 0)]
];

const phase = estimateEigenstatePhase(unitary, [complex(1, 0), complex(0, 0)], 4);
console.log('Estimated phase:', phase);

🔄 Export & Integration

Export to Other Quantum Frameworks

import { exportToQiskit, exportToOpenQASM, exportToCirq } from 'q5m';

const circuit = new Circuit(2);
circuit.h(0).cnot(0, 1);

// Export to various formats
const qiskitCode = exportToQiskit(circuit);
const qasmCode = exportToOpenQASM(circuit);
const cirqCode = exportToCirq(circuit);

console.log('Qiskit:\n', qiskitCode);
console.log('OpenQASM:\n', qasmCode);
console.log('Cirq:\n', cirqCode);

📊 Performance Features

Memory Optimization

import { Circuit, QubitState } from 'q5m';

// Automatic sparse optimization for large systems
const largeCircuit = new Circuit(20); // 20 qubits
largeCircuit.h(0); // Most amplitudes remain zero

const state = largeCircuit.execute();
console.log('Representation:', state.isDense ? 'Dense' : 'Sparse');
console.log('Memory usage:', state.memoryUsage(), 'bytes');

Performance Monitoring

import { Circuit } from 'q5m';

// Built-in performance tracking
const startTime = performance.now();
const circuit = new Circuit(15);

// Build complex circuit
for (let i = 0; i < 10; i++) {
  circuit.h(i % 15).cnot(i % 15, (i + 1) % 15);
}

const result = circuit.execute();
const endTime = performance.now();

console.log(`Execution time: ${endTime - startTime}ms`);
console.log('Final state sparsity:', result.sparsity);

🎨 Visualization

Circuit Visualization

import { Circuit, CircuitRenderer } from 'q5m';

const circuit = new Circuit(3);
circuit.h(0).cnot(0, 1).cnot(1, 2);

// ASCII representation
console.log(circuit.toString());

// Rich visualization (if available)
if (typeof window !== 'undefined') {
  const renderer = new CircuitRenderer(circuit);
  document.body.appendChild(renderer.toSVG());
}

📖 API Reference

Core Classes

• Circuit - Main quantum circuit builder and executor
• QubitState - Quantum state with automatic optimization
• Q5mState - Base quantum state abstraction
• Gate Classes - Individual quantum gate implementations

Algorithms Module

• groverSearch - Grover's quantum search algorithm
• quantumFourierTransform - QFT implementation
• quantumPhaseEstimation - Phase estimation algorithm
• amplitudeAmplification - Generalized amplitude amplification

Math Utilities

• complex - Complex number operations
• createUnitary - Unitary matrix construction
• matXvec - Optimized matrix-vector multiplication

Export Functions

• exportToQiskit - Generate Qiskit Python code
• exportToOpenQASM - Generate OpenQASM 2.0 code
• exportToCirq - Generate Google Cirq code

🔧 Configuration

TypeScript Configuration

q5m.js is built with strict TypeScript for maximum type safety:

{
  "compilerOptions": {
    "strict": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true
  }
}

Build Targets

• ES2022 - Modern JavaScript features
• Node.js 18+ - Server-side compatibility
• Modern browsers - Chrome 91+, Firefox 90+, Safari 14+

🧪 Development & Testing

Running Tests

# Unit tests
npm test

# Integration tests  
npm run test:integration

# E2E tests across frameworks
npm run test:e2e

# Coverage report
npm run test:coverage

Performance Benchmarks

# Basic performance tests
npm run benchmark

# Detailed performance analysis
npm run profile

# Memory usage analysis
npm run test:memory

📈 Performance Characteristics

Benchmark Results

• Small circuits (2-5 qubits): ~0.1ms execution time
• Medium circuits (10-15 qubits): ~10ms execution time
• Large sparse circuits (20+ qubits): ~100ms execution time
• Memory usage: 40-60% reduction vs dense representation for sparse states

Optimization Features

• Automatic sparse/dense state switching
• CSR (Compressed Sparse Row) format for very sparse states
• Optimized complex number operations
• TypedArray usage for memory efficiency
• SIMD-friendly algorithms where possible

🤝 Contributing

We welcome contributions! This project follows strict code quality standards and comprehensive testing practices.

Quick Start for Contributors

git clone https://github.com/openql-org/q5mjs.git
cd q5mjs
npm install
npm run dev

Code Quality Standards

• TypeScript: Strict mode enabled with zero any types
• Testing: Jest with 90%+ coverage requirement (2000+ tests)
• Linting: ESLint + Prettier with zero warnings policy
• CI/CD: GitHub Actions with multi-platform testing

For complete contributing guidelines, see CONTRIBUTING.md which covers:

• Development setup and workflow
• Coding standards and type safety requirements
• Testing guidelines and coverage requirements
• Commit message format and pull request process
• Documentation standards and API guidelines

📄 License

MIT License - see LICENSE for details.

📚 Documentation

• Getting Started - Quick start guide and tutorials
• API Documentation - Complete API reference
• Contributing Guidelines - Development workflow and standards
• GitHub Repository - Source code and issues
• npm Package - Package on npm registry

🙏 Acknowledgments

Built with inspiration from the quantum computing community and leveraging modern web technologies for optimal performance and developer experience.

q5m.js - Making quantum computing accessible through elegant TypeScript APIs