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

``bash
npm install q5m
`

🚀 Quick Start

$3

`typescript
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());
`

$3

`typescript
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:

$3

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

$3

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

$3

`html


`

$3

#### React Integration
`tsx
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 (


{circuit.toString()}

`typescript
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);
`

$3

`typescript
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

$3

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

$3

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

$3

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

🔄 Export & Integration

$3

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

📊 Performance Features

$3

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

$3

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

🎨 Visualization

$3

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

📖 API Reference

$3

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

$3

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