qsimulator
A quantum circuit simulator in Rust. It holds the full 2^n state vector of an
n-qubit register, applies gates, measures and resets mid-circuit, branches on
the result, and simulates noise — by quantum trajectories on the state vector,
or exactly on a density matrix. It reads OpenQASM 2 and 3 and writes OpenQASM 2.
The priority is being correct and readable, not fast.
Every result is cross-validated against Qiskit on each CI run: state vectors and density matrices entrywise, and sampled distributions against Qiskit Aer for the circuits that collapse or decohere.
Example
use Circuit;
let mut c = new;
c.h.cnot; // prepare a Bell state
print!;
// q0: -H-*-
// q1: ---X-
let counts = c.sample; // seeded; only 00 and 11 ever appear
The same circuits can be written as a small text program or as OpenQASM and run from the command line:
Worked examples live in examples/ and each verify their own
output:
What's here
- State-vector simulation up to ~25 qubits on a laptop; amplitudes take
16·2^nbytes, which is the practical limit. - Gates — X, Y, Z, H, S, T and their daggers, the phase gate P(λ), the general single-qubit U2/U3, Rx/Ry/Rz, SWAP, CNOT, CY, CZ, CH, controlled rotations, controlled-U3, Toffoli, Fredkin (CSWAP), and arbitrary (multi-)controlled unitaries.
- Measurement — single-qubit and full-register collapse plus Born-rule sampling, driven by a seedable, dependency-free RNG so runs reproduce.
- Three front ends — a Rust builder API, a line-based text format, and OpenQASM 2.0 import and export.
- ASCII circuit diagrams via
Circuit::diagram()/Display.
The core depends only on num-complex.
Testing
Every quantity has an independent oracle rather than a hand-copied expected value:
- Gate matrices are checked against their algebraic identities —
Rx(π)equals X up to global phase,S·S† = I,p(π/2) = S, and so on. - The OpenQASM importer is validated by running an imported circuit and comparing its amplitudes to the equivalent builder circuit; export is checked by round-tripping back through the importer.
- Measurement is checked statistically: a Bell state only ever collapses to 00 or 11, measuring one half of a pair fixes the other, and the same seed reproduces the same histogram.
Beyond the in-tree tests, crossval/ checks qsimulator against
Qiskit: it runs hundreds of random circuits over the shared gate set through
both engines (via OpenQASM) and confirms the state vectors match to
floating-point precision. See crossval/README.md.
The parsers are fuzzed with cargo fuzz (targets under fuzz/), with
a stable-toolchain random-input smoke test in tests/robustness.rs for
continuous coverage.
cargo test runs 120+ unit and integration tests (including a CLI driven
end-to-end). CI runs the full suite on Linux and macOS, enforces
cargo fmt --check, cargo clippy -D warnings, and a warning-clean
cargo doc, executes the examples, runs the Qiskit cross-validation, fuzzes
the parsers, audits dependencies with cargo audit, and gates line coverage
(~97%) at 90% via cargo llvm-cov.
Benchmarks
cargo bench measures gate-application throughput (the simulator's inner
loop). The harness and a note on the kernel's structure — a bounds-check-free
walk over the target bit's |0>/|1> halves — are in
benches/README.md. Numbers are machine-dependent, so
regenerate them on the target machine rather than trusting a checked-in figure.
An optional parallel feature runs the single-qubit kernel across threads
(via rayon); it is off by default so the core has no dependency beyond
num-complex. Enable it with cargo build --features parallel.
Project layout
qsimulator/
├── src/
│ ├── lib.rs # crate root, re-exports
│ ├── state.rs # state vector and gate application
│ ├── gates.rs # gate matrices
│ ├── circuit.rs # circuit builder, execution, diagrams, QASM export
│ ├── program.rs # text program parser
│ ├── qasm.rs # OpenQASM 2.0 importer
│ ├── rng.rs # seedable xorshift64 RNG
│ └── main.rs # CLI
├── programs/ # example programs (.qsim and .qasm)
├── tests/ # integration tests
├── docs/design.md # design notes and status
└── .github/ # CI
Text program format
One instruction per line; # starts a comment. The first line sets the
register size.
qubits 3
h 0
cnot 0 1
cnot 1 2 # GHZ state
sample 1000 42
Instructions: qubits N; id|h|x|y|z|s|t|sdg|tdg|sx|sxdg Q; rx|ry|rz|p THETA Q
(THETA is an arithmetic expression over numbers and pi, like pi/2, -pi/4,
2pi, or (pi/4+0.1)*2 — one unspaced token, since instructions split on
whitespace);
u2 PHI LAMBDA Q; u3 THETA PHI LAMBDA Q; cnot|cy|cz|ch C T;
crz|cp THETA C T; cu3 THETA PHI LAMBDA C T; swap A B; cswap C A B;
toffoli C1 C2 T; measure Q; reset Q; if VALUE INSTRUCTION;
depolarizing|bit_flip|phase_flip|amplitude_damping|phase_damping P Q; the open-ended mcx C... T and
mcu3 THETA PHI LAMBDA C... T; and an optional sample SHOTS SEED.
Sampling flags work on any program, including OpenQASM files, which have no
way to carry a sample directive:
--shots overrides the program's own sample directive; --seed on its own
re-seeds it. Sampling is a pure function of the seed, so a run repeats exactly.
OpenQASM 2.0 and 3
A file ending in .qasm, or one starting with an OPENQASM header, is parsed
as OpenQASM — the version in the header picks 2 or 3. The supported subset is
enough for hand-written textbook circuits and for what Qiskit exports:
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
h q[0];
cx q[0],q[1];
Supported gates: id x y z h s t sdg tdg sx sxdg, rx/ry/rz(theta), u1(lambda)
(alias p), u2(phi,lambda), u3(theta,phi,lambda), cx, cy, cz, ch,
crz(theta), cu1(lambda) (alias cp), cu3(theta,phi,lambda), swap,
ccx, cswap, and the primitives U, CX; plus gate declarations, which
are expanded at each call site (so files Qiskit exports for composite gates
import), and the rest of qelib1.inc (u, u0, crx, cry, csx, cu,
rxx, rzz, rccx, rc3x, c3x, c3sqrtx, c4x) implemented natively,
since include is ignored rather than honoured.
Multiple qregs map into one flat qubit space in declaration order;
creg and barrier are accepted and ignored; anything outside
the subset is reported rather than silently mis-simulated.
Circuit::to_qasm() (and qsimulator --emit-qasm <FILE>) writes a circuit
back out as OpenQASM 2.0, and every gate in the builder round-trips exactly
through the importer. Gates with no OpenQASM 2 equivalent are decomposed into
ones that have one: an arbitrary controlled-U into a control phase plus cu3,
and a multi-controlled gate of any width into Toffolis and single-qubit
rotations.
Status
The core is complete and covered by tests: simulation, the gate set above, measurement and sampling, the three front ends, ASCII diagrams, cross-validation against Qiskit, a throughput benchmark harness, and an optional parallel gate kernel.
Planned:
cu3import and export, to round-trip arbitrary controlled-U gates.
Design notes and a detailed status table live in docs/design.md.
Contributing
See CONTRIBUTING.md. In short: keep new gates and primitives
covered by tests, and run cargo fmt and cargo clippy before opening a pull
request.
License
MIT.