File size: 3,688 Bytes
eef9104 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 | <!--
Copyright (c) 2026 Ahmad Ali Parr and others.
SPDX-License-Identifier: LicenseRef-CPSC-ESCL-1.0 OR AGPL-3.0-only
-->
# Mercury — Ruby quantum circuit frontend for CPSC-QFT
A dependency-free Ruby quantum circuit library and full statevector
simulator, with a browser console (Ruby/WASM) for building circuits,
running them, and checking CPSC conservation laws at compile time.
## Layout
```
frontend/
lib/mercury.rb entry point (require this)
lib/mercury/version.rb
lib/mercury/gates.rb gate matrices: H X Y Z S T Rx Ry Rz U,
CNOT CZ CP SWAP RZZ XX, Toffoli
lib/mercury/circuit.rb circuit DSL + Unicode diagram
lib/mercury/simulator.rb full statevector simulator
lib/mercury/mini_json.rb dependency-free JSON (WASM-safe)
lib/mercury/cpsc.rb CPSC bridge: symmetry analyzer, Trotter
scattering evolution, leakage, <H>
test/test_mercury.rb 25 tests, 556 assertions (minitest, stdlib only)
web/index.html console template (= qsim.html after build)
web/app.rb WASM bridge (handle_request)
web/build.sh builds mercury_bundle.rb + qsim.html
web/qsim.html the console (generated)
web/mercury_bundle.rb concatenated Ruby (generated, fetched at boot)
```
## Quickstart (Ruby)
```ruby
require_relative "lib/mercury"
# Bell pair
c = Mercury::Circuit.new(2) do |c|
c.h 0
c.cnot 0, 1
end
puts c.to_s
res = Mercury::Simulator.new.run(c, shots: 1000, seed: 42)
p res.counts # {"00"=>..., "11"=>...}
# CPSC conservation check (mirrors src/cpsc/analyzer.py)
p Mercury::CPSC.analyze(c)
# => {:admitted=>false, :rejections=>[{:gate=>"H[0]", ...}, ...]}
# H and CNOT do not preserve the Z2 parity sector — rejected, as designed.
# Trotterized scattering: H = -J ΣZ_i Z_{i+1} + λ ΣX_i (periodic)
trotter = Mercury::CPSC.trotter_circuit(4, j: 1.0, lam: 0.0, time: 0.4, steps: 8)
psi = Mercury::Simulator.new.run(trotter, initial: "0011").statevector
p Mercury::CPSC.leakage(psi, 4, Mercury::CPSC.parity_of(0b0011, 4)) # => 0.0
```
Run the tests:
```bash
cd frontend && ruby -Ilib test/test_mercury.rb
```
## Web console
Build, then serve the `web/` directory over HTTP (WASM requires it):
```bash
cd frontend/web && ./build.sh
ruby -run -e httpd -- . -p 8123
# open http://localhost:8123/qsim.html
```
The console boots Ruby 3.2 (ruby.wasm, CDN) and evaluates the verbatim
`mercury_bundle.rb`. Features:
- circuit script editor (one op per line) + gate palette + presets
(Bell, GHZ-3, QFT-3, Trotter scattering, adversarial X)
- Unicode circuit diagram, measurement histogram, statevector and
probability tables
- CPSC panel: compile-time admission verdict, parity leakage,
energy expectation — the analyzer rejects illegal gates before
simulation, never post-selects after
To publish on GitHub Pages, copy `qsim.html` and `mercury_bundle.rb`
side-by-side into `docs/`.
## Notes
- Little-endian: qubit `q` is bit `q` of the basis index, matching the
Python prototype's convention.
- At λ=0 the Trotter terms commute, so the Trotter circuit is exact:
verified bit-identical against `cpsc.channel.evolve_in_sector`
(max |Δ| = 0.0, n=4, t=0.4).
- At λ≠0 the transverse field genuinely mixes parity sectors; the
console reports the honest leakage instead of projecting it away.
- `Mercury::CPSC.prepare` was removed in favor of `initial:` basis
strings so state preparation never smuggles X gates past the analyzer.
## License
Dual strict copyleft: `LicenseRef-CPSC-ESCL-1.0` OR `AGPL-3.0-only`.
See the repository root `LICENSE`, `NOTICE`, `LICENSES/`.
|