Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/crates/ruqu-algorithms/README.md

@@ -0,0 +1,127 @@
+# ruqu-algorithms
+
+[![Crates.io](https://img.shields.io/crates/v/ruqu-algorithms.svg)](https://crates.io/crates/ruqu-algorithms)
+[![Documentation](https://docs.rs/ruqu-algorithms/badge.svg)](https://docs.rs/ruqu-algorithms)
+[![License](https://img.shields.io/crates/l/ruqu-algorithms.svg)](https://github.com/ruvnet/ruvector)
+
+**Production-ready quantum algorithms in Rust** — VQE for chemistry, Grover's search, QAOA optimization, and Surface Code error correction.
+
+## Algorithms
+
+| Algorithm | Use Case | Speedup |
+|-----------|----------|---------|
+| **VQE** | Molecular ground states, chemistry | Exponential for certain problems |
+| **Grover** | Unstructured database search | O(√N) vs O(N) |
+| **QAOA** | Combinatorial optimization (MaxCut) | Approximate quantum advantage |
+| **Surface Code** | Quantum error correction | Fault-tolerant computation |
+
+## Installation
+
+```bash
+cargo add ruqu-algorithms
+```
+
+## Variational Quantum Eigensolver (VQE)
+
+Find ground state energies for molecular Hamiltonians:
+
+```rust
+use ruqu_algorithms::vqe::{VQE, Hamiltonian, Ansatz};
+
+// H2 molecule Hamiltonian (simplified)
+let hamiltonian = Hamiltonian::from_pauli_strings(&[
+    ("ZZ", 0.5),
+    ("XX", 0.3),
+    ("YY", 0.3),
+    ("II", -1.0),
+]);
+
+// UCCSD ansatz for chemistry
+let ansatz = Ansatz::uccsd(n_qubits: 4, n_electrons: 2);
+
+let vqe = VQE::new(hamiltonian, ansatz);
+let result = vqe.optimize()?;
+
+println!("Ground state energy: {:.6} Ha", result.energy);
+```
+
+## Grover's Search
+
+Quadratic speedup for unstructured search:
+
+```rust
+use ruqu_algorithms::grover::{Grover, Oracle};
+
+// Search for |101⟩ in 3-qubit space
+let oracle = Oracle::from_target(0b101, 3);
+let grover = Grover::new(oracle);
+
+let result = grover.search()?;
+println!("Found: {:03b}", result);  // 101
+```
+
+**Optimal iterations**: π/4 × √N for N items.
+
+## QAOA MaxCut
+
+Approximate solutions to NP-hard graph problems:
+
+```rust
+use ruqu_algorithms::qaoa::{QAOA, Graph};
+
+// Define graph edges
+let graph = Graph::from_edges(&[
+    (0, 1), (1, 2), (2, 3), (3, 0), (0, 2)
+]);
+
+let qaoa = QAOA::new(graph, depth: 3);
+let result = qaoa.optimize()?;
+
+println!("MaxCut partition: {:?}", result.partition);
+println!("Cut value: {}", result.cut_value);
+```
+
+## Surface Code Error Correction
+
+Topological quantum error correction for fault-tolerant computing:
+
+```rust
+use ruqu_algorithms::surface_code::{SurfaceCode, Decoder};
+
+let code = SurfaceCode::new(distance: 3);  // 3x3 lattice
+let decoder = Decoder::mwpm();              // Minimum-weight perfect matching
+
+// Encode logical qubit
+let logical_state = code.encode_logical_zero();
+
+// Simulate noise and correct
+let noisy = code.apply_noise(logical_state, error_rate: 0.01);
+let syndromes = code.measure_syndromes(&noisy);
+let corrected = decoder.correct(&noisy, &syndromes)?;
+```
+
+## Benchmarks
+
+| Algorithm | Qubits | Time | Hardware |
+|-----------|--------|------|----------|
+| VQE (H2) | 4 | 50ms/iteration | M2 |
+| Grover (N=1024) | 10 | 15ms | M2 |
+| QAOA (depth=3) | 8 | 100ms | M2 |
+| Surface Code (d=3) | 17 | 5ms/round | M2 |
+
+## Related Crates
+
+- [`ruqu-core`](https://crates.io/crates/ruqu-core) — Quantum circuit simulator
+- [`ruqu-exotic`](https://crates.io/crates/ruqu-exotic) — Experimental quantum-classical hybrids
+- [`ruqu-wasm`](https://crates.io/crates/ruqu-wasm) — Run in browsers via WebAssembly
+
+## Documentation
+
+- [VQE Algorithm (ADR-QE-005)](https://github.com/ruvnet/ruvector/blob/main/docs/adr/quantum-engine/ADR-QE-005-vqe-algorithm-support.md)
+- [Grover's Search (ADR-QE-006)](https://github.com/ruvnet/ruvector/blob/main/docs/adr/quantum-engine/ADR-QE-006-grover-search-implementation.md)
+- [QAOA MaxCut (ADR-QE-007)](https://github.com/ruvnet/ruvector/blob/main/docs/adr/quantum-engine/ADR-QE-007-qaoa-maxcut-implementation.md)
+- [Surface Code (ADR-QE-008)](https://github.com/ruvnet/ruvector/blob/main/docs/adr/quantum-engine/ADR-QE-008-surface-code-error-correction.md)
+
+## License
+
+MIT OR Apache-2.0