Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/npm/packages/ruqu-wasm/README.md

@@ -0,0 +1,221 @@
+# ruqu-wasm
+
+[![Crates.io](https://img.shields.io/crates/v/ruqu-wasm.svg)](https://crates.io/crates/ruqu-wasm)
+[![npm](https://img.shields.io/npm/v/@ruvector/ruqu-wasm.svg)](https://www.npmjs.com/package/@ruvector/ruqu-wasm)
+[![License](https://img.shields.io/crates/l/ruqu-wasm.svg)](https://github.com/ruvnet/ruvector)
+
+**Run quantum simulations in the browser** — WebAssembly bindings for ruqu-core and ruqu-algorithms with 25-qubit support.
+
+## Features
+
+- **Browser-Native** — Run quantum circuits directly in JavaScript/TypeScript
+- **5 Simulation Backends** — StateVector, Stabilizer, Clifford+T, TensorNetwork, Hardware
+- **25-Qubit Limit** — Optimized for browser memory constraints (~1GB for 25 qubits)
+- **Full Algorithm Suite** — VQE, Grover, QAOA, Surface Code available
+- **OpenQASM 3.0** — Export circuits to standard quantum assembly format
+- **Zero Dependencies** — Pure WASM, no server required
+- **TypeScript Types** — Full type definitions included
+
+## Installation
+
+### npm
+
+```bash
+npm install @ruvector/ruqu-wasm
+```
+
+### Rust (for building)
+
+```bash
+cargo add ruqu-wasm
+wasm-pack build --target web
+```
+
+## Quick Start (JavaScript)
+
+```javascript
+import init, { Circuit, Simulator } from '@ruvector/ruqu-wasm';
+
+await init();
+
+// Create a Bell state
+const circuit = new Circuit(2);
+circuit.h(0);        // Hadamard on qubit 0
+circuit.cnot(0, 1);  // CNOT: entangle qubits
+
+// Run simulation
+const sim = new Simulator();
+const state = sim.run(circuit);
+
+// Measure
+const result = state.measureAll();
+console.log(`Measured: ${result.toString(2).padStart(2, '0')}`);
+// Output: "00" or "11" with 50% probability each
+```
+
+## React Example
+
+```tsx
+import { useEffect, useState } from 'react';
+import init, { Circuit, Simulator } from '@ruvector/ruqu-wasm';
+
+function QuantumDemo() {
+  const [result, setResult] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function runQuantum() {
+      await init();
+
+      const circuit = new Circuit(3);
+      circuit.h(0);
+      circuit.cnot(0, 1);
+      circuit.cnot(1, 2);  // GHZ state
+
+      const sim = new Simulator();
+      const state = sim.run(circuit);
+      setResult(state.measureAll().toString(2).padStart(3, '0'));
+    }
+    runQuantum();
+  }, []);
+
+  return <div>Quantum result: {result ?? 'Computing...'}</div>;
+}
+```
+
+## API Reference
+
+### Circuit
+
+```typescript
+class Circuit {
+  constructor(nQubits: number);
+
+  // Single-qubit gates
+  h(qubit: number): void;      // Hadamard
+  x(qubit: number): void;      // Pauli-X (NOT)
+  y(qubit: number): void;      // Pauli-Y
+  z(qubit: number): void;      // Pauli-Z
+  rx(qubit: number, theta: number): void;  // X-rotation
+  ry(qubit: number, theta: number): void;  // Y-rotation
+  rz(qubit: number, theta: number): void;  // Z-rotation
+
+  // Two-qubit gates
+  cnot(control: number, target: number): void;
+  cz(control: number, target: number): void;
+  swap(q1: number, q2: number): void;
+
+  // Three-qubit gates
+  toffoli(c1: number, c2: number, target: number): void;
+}
+```
+
+### Simulator
+
+```typescript
+class Simulator {
+  constructor();
+  run(circuit: Circuit): QuantumState;
+}
+```
+
+### QuantumState
+
+```typescript
+class QuantumState {
+  measureAll(): number;
+  measure(qubit: number): number;
+  probability(bitstring: number): number;
+  amplitudes(): Float64Array;  // Complex interleaved [re, im, re, im, ...]
+}
+```
+
+## Algorithms
+
+### Grover's Search
+
+```javascript
+import { Grover } from '@ruvector/ruqu-wasm';
+
+const grover = new Grover(4);  // 4 qubits = search space of 16
+grover.setTarget(0b1010);       // Search for |1010⟩
+
+const result = grover.search();
+console.log(`Found: ${result.toString(2).padStart(4, '0')}`);
+```
+
+### VQE
+
+```javascript
+import { VQE, Hamiltonian } from '@ruvector/ruqu-wasm';
+
+const h = new Hamiltonian();
+h.addTerm("ZZ", 0.5);
+h.addTerm("XX", 0.3);
+
+const vqe = new VQE(h, nQubits: 4);
+const energy = vqe.optimize({ maxIter: 100 });
+console.log(`Ground state energy: ${energy}`);
+```
+
+## Performance
+
+| Qubits | Memory | Init Time | Gate Time |
+|--------|--------|-----------|-----------|
+| 10 | 16 KB | 1ms | 0.01ms |
+| 15 | 512 KB | 5ms | 0.1ms |
+| 20 | 16 MB | 50ms | 5ms |
+| 25 | 512 MB | 500ms | 150ms |
+
+**Note**: 25 qubits requires ~1GB browser memory. Use Web Workers for heavy simulations.
+
+## Web Worker Example
+
+```javascript
+// worker.js
+import init, { Circuit, Simulator } from '@ruvector/ruqu-wasm';
+
+self.onmessage = async (e) => {
+  await init();
+  const { gates, nQubits } = e.data;
+
+  const circuit = new Circuit(nQubits);
+  gates.forEach(g => circuit[g.name](...g.args));
+
+  const sim = new Simulator();
+  const state = sim.run(circuit);
+
+  self.postMessage({ result: state.measureAll() });
+};
+```
+
+## Bundle Size
+
+| Build | Size (gzip) |
+|-------|-------------|
+| Core only | 45 KB |
+| With algorithms | 120 KB |
+| Full bundle | 180 KB |
+
+## Browser Support
+
+- Chrome 89+
+- Firefox 89+
+- Safari 15+
+- Edge 89+
+
+Requires WebAssembly SIMD for optimal performance (available in all modern browsers).
+
+## Related Packages
+
+- [`ruqu-core`](https://crates.io/crates/ruqu-core) — Rust quantum simulator
+- [`ruqu-algorithms`](https://crates.io/crates/ruqu-algorithms) — Algorithm implementations
+- [`ruqu-exotic`](https://crates.io/crates/ruqu-exotic) — Experimental hybrids
+
+## Documentation
+
+- [WASM Strategy (ADR-QE-003)](https://github.com/ruvnet/ruvector/blob/main/docs/adr/quantum-engine/ADR-QE-003-wasm-compilation-strategy.md)
+- [Performance (ADR-QE-004)](https://github.com/ruvnet/ruvector/blob/main/docs/adr/quantum-engine/ADR-QE-004-performance-optimization-benchmarks.md)
+
+## License
+
+MIT OR Apache-2.0