ruqu — a pretend quantum computer that runs on your laptop

01

“Oh — that’s what it’s for.”

Start here — one concrete, relatable example before anything else

Meet Aisha. She teaches an undergrad “intro to quantum computing” class and is not a quantum physicist herself. She uses Claude Code to prepare her demos. Today she wants to show the famous Bell state: two qubits that become “spookily” linked, so measuring one instantly tells you the other.

First, what’s a “qubit”? A normal bit is either 0 or 1. A qubit (a quantum bit) can be a blend of both at once — until you look. That blend is what gives quantum its power, and what makes it so fragile:

Technical · precise SVG A diagram contrasting a normal bit (0 or 1) with a qubit drawn as an arrow on a Bloch sphere, pointing anywhere between the 0 pole at top and the 1 pole at bottom.

The mechanics. A qubit’s state is an arrow on a Bloch sphere — not just 0 or 1, but any blend, until measured.

A warm illustration: inside a browser window, a teacher gestures to two glowing orbs linked by a magenta thread — a Bell pair — while delighted students watch. Labels 00 and 11 float nearby. — **The feeling.** Aisha shows her class two glowing qubits that are linked — a “Bell pair” — running live in the browser.

Before ruqu: to demo a Bell state live, Aisha would normally have to install a heavy Python quantum toolkit, fight dependency errors on the classroom laptops, or sign her class up for cloud quantum credits that run out. Half the lab period is gone before anything quantum happens — and nothing runs in the students’ own browsers.

After ruqu: she types one command — no install — and a real state-vector simulation runs, printing the outcome (roughly 50% “00” and 50% “11”, the Bell-state signature). For the web lab she drops the @ruvector/ruqu-wasm package into a page; in about ten lines, every student watches the same circuit run in their own browser tab. The whole class is doing quantum in the first five minutes.

# In a terminal — nothing to install:
npx @ruvector/ruqu simulate --qubits 2
# → prints ~50% "00" and ~50% "11" (the Bell signature)

# In a web page — every student runs it themselves:
const circuit = new Circuit(2);
circuit.h(0);          // put qubit 0 into a 50/50 blend
circuit.cnot(0, 1);    // link (entangle) the two qubits
sim.run(circuit);      state.measureAll();  // → "00" or "11"

A before-and-after diagram. Before ruqu: heavy Python installs, dependency errors, cloud credits, and half the lab period gone. After ruqu: one npx command runs a real Bell-state simulation, and every student runs the same circuit in their own browser, getting 00 or 11 with 50/50 odds. — **The whole arc on one canvas.** Heavy setup and lost lab time on the left; one command, a real distribution, and every student’s browser on the right.

The “oh, that’s what it’s for” line: it’s a real quantum computer’s behavior, in a browser tab or one terminal command — so you can actually touch quantum without owning a quantum computer.

02

What ruqu actually is

Past the “quantum execution intelligence engine” pitch — in plain terms

The repo’s own headline calls ruqu “a quantum execution intelligence engine … a layered operating stack that decides how, where, and whether to run quantum workloads.” True — but it means nothing to a normal person. Here’s the down-to-earth version:

A “quantum computer” is a radically different kind of computer that, for certain problems (designing a drug molecule, finding the best route, cracking a search), can try a huge number of possibilities at once. The catch: real ones are rare, cost millions, live in fridges colder than space, and make mistakes constantly.
The problem: almost nobody can get hands-on time on one. So how do you learn quantum, prototype an idea, or check your math? You simulate — run a faithful imitation on an ordinary computer.
ruqu is that faithful imitation, written from scratch in Rust (a fast, safe language) with “no Python, no C++, no heavyweight dependencies.” Because it’s also compiled to WebAssembly, the same simulator runs in three places with zero install: in a web page, from your terminal with one npx command, or inside a Rust program.

It gives you three things:

A diagram: one pure-Rust engine compiles to native and WebAssembly, running in a web page, via npx, or inside Rust. It gives three things: a state-vector simulator (about 25 qubits in browser, 32 in native Rust), ready-made algorithms (VQE, Grover, QAOA, surface-code error correction), and a coherence engine returning PERMIT, DEFER, or DENY. — **One engine, three surfaces, three gifts:** the simulator, the ready-made algorithms, and the coherence engine.

A friendly illustration of a glowing quantum orb floating above an open laptop with circuit ribbons — a quantum computer's behavior on a normal machine. — **The picture to hold onto:** a real quantum machine’s behavior, living inside your ordinary laptop.

A state-vector simulator — the imitation quantum computer itself (up to ~25 qubits in a browser/terminal, up to 32 in native Rust).
Ready-made quantum algorithms you can just call — VQE (chemistry / find a molecule’s lowest energy), Grover (fast search), QAOA (optimization), and surface-code error correction.
A novel “coherence engine” — a classical nervous system that watches a quantum machine’s error pattern in real time and says PERMIT / DEFER / DENY before each operation: “is it still safe to act, or is this thing about to fall apart?”

03

Why this matters — and why now

The stakes: what it does, why you care, why you need it

What does it actually do? It pretends to be a quantum computer on your normal machine, accurately — so you can run quantum programs, test quantum algorithms, and study quantum error correction without owning (or renting) real quantum hardware.

Why do you care? Because real quantum machines are scarce, costly, and noisy. A faithful free simulator lets you learn, prototype, and validate today — and catch your bugs before you burn money on actual hardware time.

Why do you need it? The popular alternatives are heavy Python stacks (Qiskit, Cirq) that pull in big dependency trees and don’t run cleanly in a browser or as a one-line terminal command. ruqu is pure Rust → WebAssembly: tiny, fast, embeddable, and runnable with no Python install and no setup.

Why is it important? It also ships ruv’s original idea — the coherence engine — a real-time “is it safe to act?” monitor that turns a quantum computer “from a fragile experiment into a self-aware machine,” the missing piece for running long, trustworthy quantum jobs.

A diagram: real quantum computers are rare, cost millions, live colder than space, and make mistakes constantly — so almost nobody gets hands-on time. The fix: run a faithful imitation on an ordinary computer, which lets you learn, prototype, validate, and catch bugs before paying. ruqu is that imitation. — **Why simulation, not hardware.** Four reasons real machines are out of reach — and why a faithful imitation is the practical answer today.

A playful comparison: a heavy crate with a tangled python snake (heavy Python stack) versus a tiny glowing Rust gear spinning happily in a browser tab (lightweight Rust-in-browser). — **The trade in one glance:** a heavy Python stack versus a tiny Rust engine that runs right in a browser tab.

04

How it works

From the gates you write to a measured outcome — the real pipeline

You describe a circuit as qubits and gates. ruqu builds a state vector — one number (an “amplitude”) for every possible outcome, so it tracks every state at once. Each gate is applied as a matrix operation (pure linear algebra, exact). Then you measure, which collapses that vector into one real bitstring with the right probabilities. A SHA-256 witness log records each step, so the run is reproducible — not hallucinated.

This is also where the 25/32-qubit ceiling comes from: every qubit you add doubles the size of the state vector. Two qubits need 4 amplitudes; ten need 1,024; twenty-five need over 33 million. That doubling is the real, honest limit.

A six-step diagram of how a circuit runs inside ruqu, using the Bell-state circuit: (1) you describe a circuit with an H gate on qubit 0 and a CNOT from 0 to 1; (2) ruqu builds a state vector with amplitudes on the 00 and 11 outcomes; (3) each gate is applied as a matrix; (4) optionally the coherence engine checks PERMIT, DEFER, or DENY; (5) measurement collapses the state to a real bitstring, 00 or 11 at about 50/50; (6) a SHA-256 witness log records every step. — **Accurate to the engine.** The exact path a Bell-state circuit takes — superpose, entangle, build the state vector, (optionally) gate-check, measure, and witness-log.

A friendly illustration of a traffic-light-style health gauge (green, amber, red) acting as a guardian over a glowing quantum chip with a bloch-sphere orb, with a small heartbeat line. — **Step 4, made friendly:** a little guardian watching the machine’s health and giving it a green, amber, or red light before each move.

05

What a “solved” state looks like

From “I’ve read about this” to “I just ran it”

When ruqu is working for you, quantum stops being theoretical. A terminal prints a real Bell-state distribution. Every student’s browser runs the same circuit. A Rust program hands you a molecule’s ground-state energy. And a health gauge flags trouble a median of four cycles before failure. Quantum ideas you could only read about become things you run.

Four solved-state tiles: a terminal printing a real Bell distribution (00 about 0.498, 11 about 0.501); a browser running the same circuit and getting 00 or 11 at 50/50 with no server; a Rust program returning result.energy of about -1.137 Hartree; and a health gauge with a sparkline and PERMIT/DEFER/DENY flagging trouble a median of four cycles before failure at 85.7 percent recall. — **Real artifacts, not promises:** a printed distribution, a browser result, a returned energy, and an early-warning signal.

A friendly illustration of a small molecule made of glowing orbs above a cyan energy curve that dips to a starred lowest point labeled ground state. — **One result, made friendly:** a molecule settling into its lowest-energy “ground state” — the core question behind drug and materials design.

Honest note on the numbers: the coherence-engine figures (median 4-cycle early warning, 85.7% recall, 468 ns P99, 3.8M decisions/sec) are vendor-measured on an Apple M2 under specified conditions — indicative, not independently audited.

06

How you’d implement it

Three doors into the same engine — pick the one that fits your job

There’s no “setup” ceremony. Pick the surface that fits what you’re doing — all three drive the same pure-Rust state-vector engine.

A diagram of three ways to use ruqu, all converging on the same pure-Rust state-vector engine. Terminal CLI: npx @ruvector/ruqu with simulate, grover, or qaoa subcommands (v0.2.0). Web page WASM: npm install @ruvector/ruqu-wasm, build a Circuit, run it, measureAll (v2.0.5, 180KB gzip). Rust crate: build a Hamiltonian, pick an ansatz, call VQE optimize, or use SurfaceCode, process_cycle, plan_execution (workspace v2.2.3). — **Real code paths.** The actual commands and calls for each surface — CLI, in-browser WASM, and the Rust crate — all hitting one engine.

A friendly illustration of a glowing magnifying glass over a haystack with one spotlighted glowing needle — quantum search. — **What “just call it” feels like:** one command (`grover`) finds the needle — you don’t build the algorithm, you call it.

# Terminal — fastest, nothing installed:
npx @ruvector/ruqu grover --qubits 3 --target 5

# Web page — an in-browser widget, no server:
npm i @ruvector/ruqu-wasm
const c = new Circuit(3); /* … */ sim.run(c); state.measureAll();

# Rust — full power (chemistry, error correction, coherence):
let h = Hamiltonian::from_pauli_strings([/* … */]);
let result = VQE::new(h, Ansatz::uccsd(/* … */)).optimize();

07

How to start — in 60 seconds

No install. One command. You’re doing quantum in the first minute.

Technical · the 3 steps A three-step start diagram. Step 1: open a terminal and run npx @ruvector/ruqu simulate --qubits 2 — npx fetches it on the fly, no install. Step 2: watch the Bell-state distribution print, about 50 percent 00 and 50 percent 11. Step 3: to put it in a web page, npm install @ruvector/ruqu-wasm and drop in an in-browser widget.

The literal path. Open a terminal, run one command, watch quantum happen — then optionally drop it into a web page.

1

Run one command

Open a terminal: npx @ruvector/ruqu simulate --qubits 2. npx fetches it on the fly — nothing to install first.

2

Watch quantum happen

It prints the Bell-state distribution — roughly 50% “00” and 50% “11”. That’s a real simulation, for real.

3

Put it in a page

Want it in a website or teaching app? npm i @ruvector/ruqu-wasm and drop in an in-browser widget your visitors run.

From here, explore the use-case gallery below — search (Grover), optimization (QAOA), chemistry (VQE), error correction, and the coherence engine — each with its own command and its own picture.

08

Use-case gallery

Seven real things you can do — each opens to its own visual, concept, and command

Each card is a full scenario: the situation, the exact command, what it does, and what you get — with its own diagram. Open any of them.

1 Quantum search in the terminal CLI · Grover

Situation: You want to show how a quantum computer finds a “needle in a haystack” faster than checking items one by one.
Command: npx @ruvector/ruqu grover --qubits 3 --target 5
What it does: Runs Grover’s algorithm (amplitude amplification) on the WASM state-vector simulator to home in on the target in about √N steps instead of N.
What you get: The found bitstring and the probability it landed on the right answer — Grover’s quadratic speedup, made visible.

A diagram of Grover's algorithm: a flat list of equal items goes through amplify rounds that raise the target item's probability, until measurement spikes on the target after about the square root of N rounds. — Flat list → “amplify the answer” rounds → a probability spike on the target.

2 Optimization toy problem (MaxCut), no math PhD CLI · QAOA

Situation: You have a network and want the best way to split it into two groups — a classic NP-hard problem.
Command: npx @ruvector/ruqu qaoa --nodes 4
What it does: Runs QAOA (a quantum approximate optimizer) on a 4-node ring to find a good split.
What you get: A partition and its cut value — a hands-on feel for “quantum approximate advantage” on combinatorial problems.

A diagram: a 4-node ring graph goes through QAOA cost and mixer layers and returns a two-group coloring (magenta vs cyan) with the cut edges highlighted, plus the cut value. — Ring graph → QAOA cost/mixer layers → a colored two-group split.

3 A quantum chemistry prototype in Rust Rust · VQE

Situation: You want a molecule’s lowest-energy (“ground”) state — the core question behind drug and materials design — but have no quantum hardware.
Command (Rust): Build a Hamiltonian::from_pauli_strings([…]), pick the Ansatz::uccsd(…), then VQE::new(…).optimize().
What it does: Runs the Variational Quantum Eigensolver, the standard near-term quantum-chemistry algorithm, entirely on the simulator.
What you get: An estimated ground-state energy in Hartrees (result.energy) — a working chemistry prototype with zero hardware.

A diagram: a molecule is encoded as a Hamiltonian, fed into a parameterized circuit (ansatz) with tunable angles, and an optimizer lowers the energy step by step until it settles to a minimum — returning result.energy in Hartrees. — Molecule → parameterized circuit → energy curve settling to its minimum.

4 How quantum survives its own mistakes Rust · error correction

Situation: You’re learning why quantum machines need error correction and how a “surface code” fixes errors.
Command (Rust): SurfaceCode::new(distance: 3), inject noise with apply_noise(…, error_rate: 0.01), then Decoder::mwpm().correct(…).
What it does: Encodes a logical qubit, scatters realistic errors, measures the tell-tale “syndromes,” and corrects them with minimum-weight perfect matching.
What you get: A before/after you can inspect — corrupted state → detected syndromes → recovered state.

A diagram of surface-code error correction: a clean distance-3 lattice, then noise injects red error dots and amber syndrome flags, then minimum-weight perfect matching pairs the syndromes and corrects them, recovering a clean lattice. — Clean lattice → red error dots + syndromes → matched-and-corrected lattice.

5 A real-time “is it safe to act?” health monitor Rust · coherence engine

Situation: You’re running a long quantum job and want to catch a structural breakdown before it wipes out your progress.
Command (Rust): Feed each cycle’s syndrome_data into fabric.process_cycle(…); read back Permit / Defer / Deny.
What it does: ruv’s original coherence engine runs a real-time min-cut on the error pattern and decides whether the machine is healthy, borderline, or collapsing.
What you get: An early-warning signal — in tests it flagged trouble a median of 4 cycles before failure with 85.7% recall — so healthy regions keep running while a bad region is quarantined.

A diagram of the coherence engine: each cycle's syndrome stream is fed into a real-time min-cut over the error pattern, which returns PERMIT (healthy, keep running), DEFER (borderline, wait), or DENY (collapsing, quarantine) before the next operation. Measured stats: median 4 cycles early warning, 85.7 percent recall, 468 nanosecond P99 latency, 3.8 million decisions per second. — Syndrome stream → real-time min-cut → PERMIT / DEFER / DENY, with the vendor-measured numbers.

Why this is the headline. No mainstream toolkit ships a real-time safety gate like this — it’s ruv’s original contribution and the piece that makes ruqu more than “just another simulator.”

6 Pick the right engine automatically for a bigger circuit Rust · planner

Situation: Your circuit is too big for the obvious “track every possibility” method, but you don’t know which technique to use.
Command (Rust): plan_execution(&circuit, &PlannerConfig::default()) — or decompose(&circ, 25) to split it.
What it does: A cost-model planner predicts memory/runtime/fidelity and routes the circuit to the best of five backends (StateVector, Stabilizer for Clifford-only circuits with millions of qubits, TensorNetwork, Clifford+T, or hardware profiles).
What you get: A feasible run where a naive simulator would have run out of memory.

Technical · the routing decision A diagram: a circuit too big for the naive method is handed to a cost-model planner that predicts memory, runtime, and fidelity, then routes to the cheapest of five backends — StateVector (chosen for small exact jobs), Stabilizer (Clifford-only, millions of qubits), TensorNetwork, Clifford+T, or a hardware profile. Honest note: Clifford+T is not in the auto-router yet.

One circuit → planner predicts cost → the cheapest viable backend is chosen.

7 In-page quantum for a website or teaching app JS · WASM widget

Situation: You want a live quantum demo embedded in a web page with no backend server.
Command (JS): npm install @ruvector/ruqu-wasm, then new Circuit(3) … sim.run(circuit) … state.measureAll().
What it does: Runs genuine state-vector simulation client-side via WebAssembly (up to ~25 qubits; ~1 GB browser memory at 25).
What you get: An interactive quantum widget your visitors run themselves, zero server cost.

A diagram: a browser tab loads the @ruvector/ruqu-wasm WebAssembly module — the pure-Rust state-vector engine compiled to wasm32 — which runs genuine simulation client-side up to about 25 qubits and returns a live measurement readout, with zero server cost. — Browser tab → WASM module → a live measurement readout, no server.

⚛

“I already have X — why ruqu too?”

Qiskit/Cirq? Claude Code? Another simulator? Here’s the honest difference.

vs Python quantum stacks (Qiskit / Cirq): powerful but heavy — a Python runtime plus a large dependency tree, awkward to embed and impossible to drop straight into a browser. ruqu is pure Rust with no FFI that compiles to native and wasm32: a 180 KB-gzip WASM bundle that runs in a web page or as npx @ruvector/ruqu. Same physics, far less weight, runs where Python can’t.
vs “just use Claude Code”: Claude Code is a brilliant generalist, but it can’t run a quantum circuit or check whether your VQE energy is right — it would guess. ruqu is the actual engine it can call: real state-vector math, real algorithms, and a cryptographic witness log (SHA-256 hash chain) so results are reproducible and auditable, not hallucinated. The repo even ships ruqu as a Claude-Code agent harness so your assistant can drive it directly.
vs other simulators generally: the differentiator is the coherence engine — “ruQu is not a simulator… it decides how, where, and whether to run quantum workloads.” The real-time PERMIT/DEFER/DENY safety gate (468 ns P99, 3.8M decisions/sec — measured) is ruv’s original contribution and exists in no mainstream toolkit.

A comparison table of Qiskit/Cirq, Claude Code, other simulators, and ruqu across weight and portability, whether they can actually run the math, and the unique piece. ruqu is pure Rust, native and wasm32, 180KB gzip, with a SHA-256 witness log and the coherence engine. Footer: before ruqu, quantum ideas stay theoretical; after, you prototype, test, and even monitor quantum workloads from a terminal, browser, or Rust app, today, free. — **The head-to-head, plus your own before→after.** What changes when ruqu is in your toolbox — lighter, runnable everywhere, reproducible, and uniquely able to monitor a quantum machine’s health.

09

The drop-in kit

One download, two halves — one for you, one for your AI assistant

Want your AI assistant (in Claude Code or Cursor) to answer questions about ruqu from the real source instead of guessing? Grab the drop-in kit. It’s one folder with two clearly-labeled halves: a plain-English primer for you, and a queryable knowledge base for your AI.

An annotated file tree of the ruqu-dropin.zip download. Root: ruqu-dropin, unzip into your project as kb. for-humans half: ruqu-primer.md (the whole tool in plain English) and a highlighted studio folder holding ruqu-audio.m4a (a NotebookLM audio overview to play first), ruqu-report.md (the written briefing), and the prompt that made them. for-ai half: ruqu-kb.rvf (the single 384-dim bge-small brain), ruqu-kb.passages.jsonl (every doc and all source, full text), ruqu-kb.ids.json (the id index), ask-kb.mjs (ask it from the command line), kb-mcp-server.mjs (wire it into Claude Code or Cursor), kb.config.mjs and package.json. Plus a README and manifest with the build's provenance. — **Exactly what’s inside.** Every file, with a plain-English “what this is” — the real contents, not an abstract picture. Note the highlighted **studio/**: a 🎧 audio overview (play first) and a 📄 report ride *inside the zip*.

A friendly illustration of a glowing download box splitting into two halves: a 'for you' half with a person icon and a 'for your AI' half with a robot icon. — **The idea in one picture:** one tidy download that opens into a half for you and a half for your AI.

1

Unzip into your project

Drop the folder in as kb/. You now have for-humans/ and for-ai/ side by side.

2

Add the 2-line `.mcp.json`

In for-ai/ run npm i (two deps, Node 18+), then point a 2-line .mcp.json at the bundled kb-mcp-server.mjs so your assistant can query the single ruqu-kb.rvf brain.

3

Paste the `CLAUDE.md` gate

Tell your AI to answer ruqu questions from the KB. Confirm it works with a real query — e.g. “How does the coherence engine decide PERMIT vs DENY?”

Download the drop-in kit

ruqu-dropin.zip — single 384-dim brain + the 🎧 studio audio overview & 📄 report inside — Gate A: 99.3 tuned / 100 held-out — ready now

Ready

Generated with Google NotebookLM · grounded in the same source repo

A full NotebookLM studio for ruqu

Audio overview, an explainer video, a slide deck, an infographic and a written report — all in one place, all built for a curious newcomer with no quantum hardware. No account, no setup: just open it and explore.

▶ Open the public NotebookLM studio — audio, video, slides & more ↗

🎧 Audio overview
🎬 Explainer video
📊 Slide deck
📈 Infographic
📄 Written report

🎧 Audio overview — a warm, jargon-free deep-dive on ruqu (NotebookLM). Play it right here, or find it in the zip at for-humans/studio/.

Prefer reading? 📄 the written report (themes · quotes · honest limits).

🎬 Explainer video — the before→after of a curious dev with no quantum hardware, in ~a minute.

📊 Slide deck — what ruqu is, why it matters, how to start.

Open the slide deck (PDF) ↗

The ruqu explainer infographic: the before-and-after of running quantum circuits without quantum hardware, on one landscape page. — 📈 **Infographic** — the whole idea on one landscape page (before→after).

Listen first. Inside the zip, for-humans/studio/ holds the 🎧 NotebookLM audio overview above (play it first — a warm, jargon-free deep-dive) and a 📄 written report. The for-ai/ half is one runnable folder: a single ruqu-kb.rvf brain (384-dim bge-small), the full passages, the CLI, and the MCP server — it cleared its answer-quality gate (tuned 99.3 / held-out 100, both ≥95) before shipping.

⚠

Honest limits

What ruqu does not do, stated plainly

It is a simulator, not a quantum computer. Validation is simulation-only; “hardware behavior may differ.” The hardware adapters (IBM/IonQ/Rigetti/Braket) are profiles with local-simulation fallback, not a finished end-to-end pipeline (roadmap v0.5, “Planned”).
Qubit ceilings are real. Exact state-vector simulation tops out around 25 qubits in browser/Node (≈1 GB memory at 25) and 32 in native Rust — cost doubles with every qubit. The Stabilizer backend reaches “millions” of qubits only for restricted (Clifford-only) circuits.
Versions are early / mixed. The coherence engine is at roadmap v0.3–0.4 (“v1.0 production-ready with hardware validation” still Planned); the CLI is @ruvector/ruqu v0.2.0; @ruvector/ruqu-wasm is v2.0.5; the Rust workspace is v2.2.3 — read the version that matches what you install.
Some pieces aren’t wired together yet. The repo openly lists gaps: “no end-to-end pipeline” (modules run independently), Clifford+T not yet in the auto-router, greedy (not optimal) min-cut partitioning, and no fidelity-aware stitching at partition boundaries.
ruqu-exotic is explicitly experimental. Its quantum-inspired AI hybrids (memory decay, interference search, reasoning error correction) are research, not production guarantees.
The benchmark numbers are vendor-measured (Apple M2 / specified conditions), not independently audited — treat them as indicative.

Bottom line: ruqu is a genuinely useful, faithful simulator with a unique real-time safety engine — and an early-stage, partly-unwired project. Both are true. Use it for learning, prototyping, and validation today; don’t mistake it for finished hardware tooling.

A quantum computeron your normal laptop.