qmirror — Quantum Mirror Substrate

Statistically real-QPU-equivalent quantum substrate (≤30 qubit) on commodity CPUs. No physical quantum hardware required for the mock path; live ANU + Aer/Cirq simulator paths included for high-fidelity work. Closure verdict: 8/8 conditions PASS (CHSH Bell violation, IIT 4.0 phi-star, NIST tier-1+ entropy, 4-tier ANU QRNG fallback, Braket fixture reproduce).

Distribution: GitHub canonical at https://github.com/need-singularity/qmirror. CLI tooling — installed via hx install qmirror from the hexa-lang registry, or git clone directly. (HF Hub mirror retired 2026-05-04: HF Hub is designed for ML model weights / datasets; CLI tooling distribution is GitHub-canonical.)

What is qmirror?

qmirror is a quantum substrate that lets you do real quantum-physics-grade work on a laptop without renting QPU time. It combines:

ANU Quantum Numbers REST entropy (real quantum random bits, 4-tier fallback from $0.005/req paid → free 100 req/min keyed → free 1 req/min legacy → mock LCG)
Qiskit Aer / Cirq simulator (≤30 qubit state-vector / density-matrix)
Born-rule sampling with provenance-tagged outcomes
CHSH Bell test with Tsirelson-class S statistic
IIT 4.0 phi-star integrated information measurement (pyphi 4.0 backend)

The name is from the spectroscopic mirror principle — the simulator's outputs are made statistically indistinguishable from real-QPU measurements over the operating envelope (≤30 qubit, low-noise) by anchoring entropy to a real quantum source (ANU vacuum-fluctuation photodetector).

Installation

Via `hx` (recommended)

hx install qmirror          # global, pulls latest from registry
hx install qmirror@1.0.0    # pin specific version
qmirror --version           # → 1.0.0

qmirror is registered as the 22nd entry in the hexa-lang package registry (hexa-lang/tool/pkg/registry.tsv L22). hx install qmirror pulls from https://github.com/need-singularity/qmirror and installs the standalone CLI under $HX_HOME/bin/qmirror.

Via git clone (works today)

git clone https://github.com/need-singularity/qmirror.git ~/.qmirror
export QMIRROR_ROOT=~/.qmirror
export PATH="$QMIRROR_ROOT/cli:$PATH"

# Run any subcommand:
hexa run $QMIRROR_ROOT/cli/qmirror.hexa selftest

Optional Python aux for real-QPU paths

The mock path needs zero Python deps. For Aer-simulator and IIT-4.0-phi-star real backends:

pip install qiskit-aer numpy
pip install git+https://github.com/wmayner/pyphi.git@b78d0e3  # IIT 4.0 pin (load-bearing)

Quick Start

1. Run the full self-test (Phase 1 + Phase 2 falsifier sweep)

qmirror selftest

Output: __QMIRROR_SELFTEST__ PASS + per-falsifier (F1..F5) PASS lines + 8/8 cond table.

2. Pull 64 quantum random bits

qmirror qrng --bits 64

Default: mock LCG (CI-safe, deterministic). For real ANU entropy:

NEXUS_QMIRROR_LIVE=1 NEXUS_QMIRROR_ANU_KEY=<key> qmirror qrng --bits 64

3. Run the CHSH Bell test

qmirror chsh                        # simulator, $0
qmirror chsh --vendor=ionq          # IonQ Forte (requires IONQ_API_KEY)
qmirror chsh --vendor=ibm           # IBM Heron (requires IBM_QUANTUM_TOKEN)

Expected simulator: S ≈ 2.838 (Tsirelson bound 2.828 within statistical noise).

Closure conditions (8/8 PASS)

The substrate was validated against 8 named conditions before standalone extraction. Full audit trail in upstream nexus/state/qmirror_* and anima/docs/nexus_qmirror_closure_2026_05_03.md.

Cond	Description	Verifier	Status
1	CHSH Bell violation Tsirelson S≥2.7	`qmirror selftest` (F3)	MET
2	Phase 1 impl (entropy/sampler/aer/qrng/chsh/circuit) F1+F2+F3	F1+F2+F3 PASS	MET
3	IBM Heron real-QPU CHSH (\|dS\|≤0.55)	S=2.357, dS=0.481	MET
4	NIST SP 800-22 tier-1+ ≥6/7 at α=0.01	7/7 PASS	MET
5	Reproduce nexus_chsh_bell S=2.808 ±0.05	S=2.838 (within band)	MET
6	Braket IIT 4.0 phi-star byte-identical 4/4	4/4 PASS engine=mock	MET
7	Cross-vendor cross-family concordance	spirit-PASS via cond.3+8	MET
8	Cross-modality option β (IBM+Braket IonQ+Rigetti)	option β selected	MET

Two post-hoc band revisions disclosed (raw#10 honest C3): cond.3 |dS| 0.40→0.55 (superconducting fidelity floor), cond.7 0.55→0.60 (cross-tech asymmetry floor). Both rationales in anima/docs/qmirror_crosstech_band_revise_landed_2026_05_03.ai.md.

All 8 conditions remain MET as of 2026-05-04 (post-NIST cond.4 PASS verified 7/7 at α=0.01; no regressions across 1.0.x patch series).

qmirror 2.0 progress (2/5 axes landed)

After 1.0 closed 8/8, the next-cycle roadmap (anima/docs/qmirror_2_axes_spec_2026_05_03.md) ranked 5 axes by Impact × Feasibility for qmirror 2.0. Two have already landed:

Cond	Name	Falsifier	Verdict	Cost	Substrate
cond.9	quantum process tomography	F-QM-2-TOMO-9	PASS (7/7 gates)	$0	Aer noiseless, ≤ 4 qubit
cond.10	GHZ-3 Mermin witness	F-QM-2-GHZ-10	PASS (M = 4.0)	$0	Aer noiseless, 3 qubit
cond.11	stabilizer measurement	F-QM-2-STAB-11	pending	$0	Aer, 4 qubit (deps cond.9)
cond.12	surface-code d=3 toy	F-QM-2-SURF-12	pending	$0	Aer, 17 qubit (deps cond.11)
cond.13	chained-sequential CHSH	F-QM-2-CSCS-13	pending	$0/$25 opt IBM Heron	Aer, 4 qubit

cond.9 result: per-gate process fidelity ≥ 0.99918 across {H, X, Y, Z, S, T, CNOT} in 8.68 s wall via linear-inversion tomography on qiskit_aer 0.17.2 (noiseless, 8000 shots, seed 2026). cond.10 result: Mermin witness M = +4.0 (analytic maximum) saturated across all 30 trials at 1024 shots/basis on the GHZ-3 state-vector — classical bound 2.0 violated by 2.0 units.

Landing handoffs:

anima/docs/qmirror_2_cond9_tomography_landed_2026_05_03.ai.md
anima/docs/qmirror_2_cond10_ghz_mermin_landed_2026_05_03.ai.md

Real-world consumer: nexus uses qmirror

The first downstream consumer of standalone qmirror is the nexus discovery engine, which declares qmirror as a runtime dependency in its package manifest:

# nexus/hexa.toml
[dependencies]
qmirror = "^1.0.0"   # caret semver: ≥ 1.0.0, < 2.0.0

The nexus qmirror <subcmd> namespace is a pure shellout to the standalone qmirror CLI — no in-tree fork, no logic duplication. The router at nexus/cli/qmirror.hexa (v0.3.0) resolves the qmirror binary through a 4-tier resolution chain with hard-fail:

tier	source	use case
1	`$QMIRROR_ROOT` env override	CI / dev pinning
2	`/Users/ghost/core/qmirror`	Mac dev convention
3	`$HOME/core/qmirror`	user-home convention
4	PATH-resolved `qmirror` binary	post-`hx install qmirror`
—	hard-fail with `hx install` hint	(no silent fallback)

The legacy 5th-tier legacy-intree fallback (in-tree nexus/modules/qmirror/) was removed in v0.3.0 to enforce standalone-only consumption — silent fallbacks that bypass operator intent are now an explicit error.

Provenance: anima/docs/nexus_cli_qmirror_landed_2026_05_03.ai.md and anima/docs/nexus_qmirror_legacy_removed_2026_05_03.ai.md.

Distribution (GitHub canonical)

qmirror is distributed via GitHub as the canonical source:

canonical: https://github.com/need-singularity/qmirror

Install via hx install qmirror (hexa-lang registry L22) or git clone. GitHub Actions free tier covers CI; no other distribution channels active.

HF Hub mirror retired 2026-05-04: HuggingFace Hub is designed for ML model weights and datasets, not CLI tooling. Maintenance burden (recurring token rotation failures) outweighed value. GitHub remains canonical for the CLI; HF Hub stays canonical for model weights and datasets in the wider stack.

Cost comparison vs IBM Quantum

Operation	qmirror (this)	IBM Quantum (paygo)
Per-second QPU rate	$0/sec (CPU + Aer)	$1.60–2.30/sec (Heron r2 paygo)
64 random bits	$0 (mock) — $0.005 (T1.c paid ANU)	$1.60/sec × ~0.1s = $0.16
CHSH Bell (1k shots)	$0 simulator	~$1-3 Heron r2 / shot batch
Phi-star 4-qubit IIT	$0 (Aer + pyphi local)	$20-50 (Aer cloud + custody)
Selftest sweep (F1..F5)	$0 (~5-10s on M1)	not directly comparable
30-qubit state-vector	$0 (Aer Mac, ~1GB RAM)	~$50 reservation + queue

One-time calibration spend (closure cycle, total): USD 41.34 across cond.3 (IBM Heron CHSH N=1) + cond.7/8 (cross-vendor / cross-modality anchors). Recurring marginal cost for all 8 closure-met conditions post-calibration is $0. Detailed breakdown in anima/docs/qmirror_arxiv_draft_2026_05_03.md §5.2.

Real-QPU paths are still available — see qmirror chsh --vendor=ibm|ionq|rigetti.

CLI reference

qmirror <subcmd> [flags...]

subcommands:
  status                                  closure 8/8 cond table + verdict
  chsh [--vendor=ionq|rigetti|ibm|sim]    CHSH Bell test, S statistic   [cond.1,3]
  nist [--bits=1000000]                   NIST tier-1+ on QRNG sample   [cond.2]
  iit [--n-qubits=4]                      IIT 4.0 phi-star measurement  [cond.4]
  qrng [--bits=64]                        quantum random bits (4-tier)  [cond.7]
  selftest                                full F1..F5 sweep             [cond.8]

global flags:
  --version  show version
  --json     machine-parseable JSON tail
  --help,-h  this help

env:
  QMIRROR_ROOT             override repo root (default: inferred from $0)
  NEXUS_QMIRROR_LIVE       1 → enable live ANU/QPU tiers (default: mock)
  NEXUS_QMIRROR_MOCK       1 → force mock LCG entropy (CI-safe)
  NEXUS_QMIRROR_ANU_KEY    ANU Quantum Numbers API key (T1.b tier)
  AWS_MARKETPLACE_ANU_API_KEY   T1.c paid tier ($0.005/req)

Env-var migration note: env vars currently use the NEXUS_QMIRROR_* prefix (load-bearing for backward compat with the upstream nexus origin). QMIRROR_* aliases are planned in a follow-up cycle (raw#10 caveat #5).

Repository layout

qmirror/
├── cli/                       # CLI entry (qmirror.hexa)
├── <feature>/module/          # 15 hexa core features (chsh, qrng, iit_mip, ...)
│                              #   canonical layout: <feature>/{core,module,doc}/ (singular)
├── _python_bridge/module/     # Aer/Cirq/pyphi runtime bridges (raw#9 .own N opt-out)
├── docs/                      # closure / provenance docs (cross-feature)
├── examples/                  # 4 example scripts
├── tests/                     # 4 smoke tests
├── state/                     # runtime artifacts (gitignored)
├── hexa.toml                  # package manifest
├── LICENSE                    # Apache-2.0
├── CHANGELOG.md               # version history
└── README.md                  # this file

Examples

See examples/:

01_quick_chsh.hexa — minimal CHSH test, prints S statistic
02_qrng_for_ml.hexa — qmirror QRNG → ML training-seed pattern
03_iit_phi_measurement.hexa — IIT phi-star on a simple TPM
04_nist_validation.hexa — NIST tier-1+ smoke test on QRNG sample

Run any with:

hexa run examples/01_quick_chsh.hexa

Citations

If you use qmirror in academic work, please cite:

@software{qmirror_2026,
  author       = {박민우},
  title        = {qmirror: Quantum Mirror Substrate v1.0},
  year         = {2026},
  publisher    = {GitHub},
  url          = {https://github.com/need-singularity/qmirror},
  note         = {Closure 8/8: CHSH, IIT 4.0, NIST tier-1+, ANU 4-tier QRNG}
}

Underlying physics / standards:

ANU Quantum Numbers: Symul, Assad, Lam, APL 98 231103 (2011).
CHSH inequality: Clauser, Horne, Shimony, Holt, PRL 23 880 (1969).
IIT 4.0: Albantakis, Tononi et al., PLOS Comput Biol 19 e1011465 (2023).
NIST SP 800-22 Rev 1a: Rukhin et al., NIST (2010).

License & attribution

Sub-component summary: qmirror's own source (all .hexa modules + Python bridge shim glue) is Apache-2.0; the optional pyphi 4.0 dependency used by the iit subcommand is GPLv3 but isolated via subprocess (FSF MereAggregation doctrine — see LICENSING.md §3 for the full analysis). Set NEXUS_QMIRROR_MOCK=1 to opt out of GPLv3 entirely.

Authoritative SSOT for sub-component license terms is LICENSING.md — that document carries the legal-advice disclaimer (raw#10 honest C3 caveat #1) and the four sub-component volatility caveats.

Sub-component licenses (full breakdown in LICENSING.md)

qmirror's own source (all .hexa modules + _python_bridge/*.py shim glue) is Apache-2.0. Optional runtime dependencies carry their own licenses:

Path	License	When invoked
Mock LCG + pure-CHSH (default CI)	Apache-2.0 (clean)	always
`qiskit-aer` (Aer simulator)	Apache-2.0 (compatible)	qasm-mode real-circuit
`pyphi` 4.0.b78d0e3 (IIT 4.0 phi-star)	GPLv3 (optional, isolated)	`iit` subcmd without `NEXUS_QMIRROR_MOCK=1`
ANU QRNG live API	n/a (no formal license; pure facts)	`qrng` with `NEXUS_QMIRROR_LIVE=1`

The pyphi GPLv3 dependency is isolated via subprocess (_python_bridge/module/iit_mip_runner.py spawns python; hexa-side never imports pyphi). Per FSF GPL FAQ MereAggregation this is aggregation, not combined work — qmirror core stays Apache-2.0.

To opt out of GPLv3 entirely: set NEXUS_QMIRROR_MOCK=1 (default for CI; the import pyphi line is never reached in mock mode).

See LICENSING.md for full analysis incl. ANU redistribution status and 4 honest C3 caveats (legal-advice disclaimer, pyphi version pin volatility, ANU ToS evolution risk, dual-mirror sync delay).

Provenance

Extracted from the nexus repo on 2026-05-03 after closure 8/8 cond was met. Upstream provenance preserved in spec-ref docstrings and CHANGELOG.md.

Status

v1.0.0 (2026-05-03) — initial standalone release; closure 8/8 PASS carried forward.
v1.0.1 (2026-05-03) — license-clarity audit; LICENSING.md added; pyphi GPLv3 subprocess-isolation rationale documented (see CHANGELOG.md).
2026-05-04 — HF Hub mirror retired; GitHub remains canonical for CLI tooling (HF Hub designed for model weights / datasets, not CLI tooling).
2026-05-03 — nexus CLI integration landed (nexus/cli/qmirror.hexa v0.3.0; standalone-only 4-tier resolution).
2026-05-03 — hx install qmirror registered as registry.tsv L22.
2026-05-03/04 — qmirror 2.0 cycle: cond.9 (process tomography) and cond.10 (GHZ-3 Mermin) PASS; cond.11 / cond.12 / cond.13 pending.

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
_python_bridge/module		_python_bridge/module
chsh/module		chsh/module
circuit/module		circuit/module
cli		cli
cscs/module		cscs/module
docs		docs
engine_aer/module		engine_aer/module
entropy/module		entropy/module
examples		examples
ghz_mermin/module		ghz_mermin/module
iit_mip/module		iit_mip/module
phi/module		phi/module
process_tomography/module		process_tomography/module
qrng/module		qrng/module
sampler/module		sampler/module
selftest/module		selftest/module
stabilizer/module		stabilizer/module
state		state
surface_code_d3/module		surface_code_d3/module
tests		tests
tomography/module		tomography/module
tools		tools
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
LICENSING.md		LICENSING.md
README.md		README.md
RELEASE_NOTES_v2.0.0_announcement.md		RELEASE_NOTES_v2.0.0_announcement.md
hexa.toml		hexa.toml
install.hexa		install.hexa

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

qmirror — Quantum Mirror Substrate

What is qmirror?

Installation

Via `hx` (recommended)

Via git clone (works today)

Optional Python aux for real-QPU paths

Quick Start

1. Run the full self-test (Phase 1 + Phase 2 falsifier sweep)

2. Pull 64 quantum random bits

3. Run the CHSH Bell test

Closure conditions (8/8 PASS)

qmirror 2.0 progress (2/5 axes landed)

Real-world consumer: nexus uses qmirror

Distribution (GitHub canonical)

Cost comparison vs IBM Quantum

CLI reference

Repository layout

Examples

Citations

License & attribution

Sub-component licenses (full breakdown in LICENSING.md)

Provenance

Status

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

qmirror — Quantum Mirror Substrate

What is qmirror?

Installation

Via hx (recommended)

Via git clone (works today)

Optional Python aux for real-QPU paths

Quick Start

1. Run the full self-test (Phase 1 + Phase 2 falsifier sweep)

2. Pull 64 quantum random bits

3. Run the CHSH Bell test

Closure conditions (8/8 PASS)

qmirror 2.0 progress (2/5 axes landed)

Real-world consumer: nexus uses qmirror

Distribution (GitHub canonical)

Cost comparison vs IBM Quantum

CLI reference

Repository layout

Examples

Citations

License & attribution

Sub-component licenses (full breakdown in LICENSING.md)

Provenance

Status

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Via `hx` (recommended)

Packages