Full-stack quantum simulation + quantum-safe cryptography: dense state vector (32 qubits), tensor networks, Clifford tableau, topological QC, chemistry / VQE with native autograd, error mitigation, Bell-verified QRNG, and a FIPS 203 post-quantum KEM seeded by that QRNG.

This repository is the public Moonlab Community Edition. It remains a useful MIT-licensed simulator/runtime for local use, research, education, public integrations, and commercial embedding. Commercial Moonlab/QGTL products should build around this public core with hosted execution, private provider overlays, enterprise deployment, billing/audit hooks, support, and certified packages.

See COMMUNITY_EDITION.md for the public/private product boundary.

Open-core extension surfaces. Four runtime registries let private overlays, sibling libraries (QGTL / libirrep / SbNN), and customer applications plug new behavior into a stock moonlab build without touching its source:

Demo examples/extensions/open_core_overlay_demo.c exercises all four surfaces in one executable (ctest-gated). Each registry is bound from Python, Rust, and JS -- see bindings/{python,rust,javascript} for the language-specific signatures. A public-CI hygiene grep rejects any PROPRIETARY: / TSOTCHKE-INTERNAL: markers landing in the public moonlab tree.

Multi-tenant productization (second wave). The control plane now speaks an AUTH <tenant_id>:<hmac> wire form, propagates the tenant identity through to the scheduler completion hook for billing attribution, and exposes a pre-dispatch admission hook that private overlays use for per-tenant quotas, paid-tier gating, and emergency lockouts. Five additional surfaces shipped:

Runnable Python overlay at examples/extensions/python_overlay_demo.py boots an HMAC-secured control plane with a per-tenant TokenBucket-backed admission hook, submits Bell circuits from three tenants + one banned tenant + one over-quota tenant, and prints the resulting billing ledger.

v0.7.0 ships the distributed-scheduler MVP -- the first piece of moonlab's cloud-platform foundation. moonlab_job_t carries a circuit description + shot count + worker fan-out; moonlab_scheduler_run splits the shots across N OpenMP workers in-process today, with the same contract shaped to swap MPI / gRPC / HTTP/2 as the transport in v0.7.1+. 4-worker Bell circuit verified at 1024 shots: 505 / 519 / 0 -- perfect Bell correlation across workers. Schema-versioned JSON job spec (moonlab/job/v0.7.0) enables over-the-wire dispatch.

v0.6.2 extends the CSS-code handle to 6 QEC families behind one opaque type. Surface code, toric, 2D color (Steane + Hamming), IBM bivariate-bicycle qLDPC (the three Bravyi-Nature 627 "Gross" codes), and hypergraph-product CSS codes. Every instance is validated against its published [[n, k, d]] shape. The SurfaceCode JS / Python / Rust bindings shipped in v0.5.12-14 become QEC-zoo dispatchers in v0.6.3 -- one binding, eight code families.

v0.6.1 extends the v0.6.0 bridge with two substantial entry points. First, moonlab_libirrep_heisenberg_sector_e0() runs sector-resolved Heisenberg ground-state ED on the orbit-representative basis: lattice -> space group -> rep table at fixed Sz -> full-reorth Lanczos with irrep_heisenberg_apply_in_sector as the matvec. At N = 24 kagome 4x2 the sector dim is ~337k vs 16 777 216 full Hilbert, making N > 14 ground-state ED a workstation problem instead of an mpo_to_matrix OOM. Second, a CSS-code handle layer (moonlab_libirrep_qec_t) starts wrapping libirrep's 18-module QEC zoo behind one opaque type.

v0.6.0 opens the libirrep-integration arc. libirrep is a production-grade C library covering 18 QEC codes (toric, surface, color, bivariate bicycle, hypergraph + lifted product, honeycomb + CSS Floquet, 3D toric, X-cube fracton, HaPPY, single-shot, Bacon-Shor, Steane * Steane, BdG-skyrmion), rep-theory primitives (SO(3) / SU(2) / O(3) / SE(3)), and a verified spin-1/2 Heisenberg sector-ED stack. Moonlab has been treating it as a paper reference (the LIBIRREP_KAGOME12_E0 = -5.44487522 constant in the kagome tests is a number copied out of libirrep's PHYSICS_RESULTS.md); this release wires in the first real link.

Build with -DQSIM_ENABLE_LIBIRREP=ON; detection tries find_package(libirrep CONFIG), then pkg-config libirrep, then -DQSIM_LIBIRREP_ROOT=<path> / $LIBIRREP_ROOT env-var pointing at a source tree with build/lib/liblibirrep.{a,dylib,so}. When detected, tests/unit/test_kagome_ed re-derives the libirrep reference at runtime (live irrep_lanczos_eigvals_reorth on the irrep_heisenberg_t built from irrep_lattice_build(KAGOME, 2, 2)) and confirms agreement to machine precision (3.553e-15 disagreement with moonlab's MPO + zheev path). Default is OFF; when off the bridge compiles to stubs returning MOONLAB_LIBIRREP_NOT_BUILT and the test prints (skipped).

Next phases: v0.6.1 routes moonlab_surface_code_clifford_* through irrep_surface_* + irrep_css_code_t, picking up the other 17 codes for free behind the same JS / Python / Rust binding surface that v0.5.12-14 shipped. v0.6.2 expands to wrappers for the toric / color / BB / X-cube / Floquet / HaPPY family. v0.6.3+ exposes Clebsch-Gordan + reduction tables to the existing QGT / DMRG paths.

The v0.5 cycle is a production-quality push across all three language bindings: every algorithm class that exists in Python now has a working Rust analog and a working JavaScript / WebAssembly wrapper, with end-to-end integration tests gated by CI.

• WASM build resurrection (v0.5.0) — a silent _Static_assert break that landed in v0.2.4 had been quietly failing the emscripten build for ~12 days. MOONLAB_MAX_QUBITS is now adaptive (30 on wasm32, 32 on native 64-bit hosts); the ABI-export module is split into a qrng-free lean half that the WASM build can include, surfacing moonlab_qwz_chern + moonlab_abi_version + DMRG / CA-MPS / Z2-LGT shims to JS.

• JS binding parity (v0.5.4 - v0.5.6) — Bell tests / Grover / VQE / QAOA / topology are all callable from @moonlab/quantum- core now. Hardware entropy backed by crypto.getRandomValues() via a WASM-only hardware_entropy_wasm.c shim unblocks every shot-noise-sampling C entry point. Eight topological-invariant helpers in topology.ts cover QWZ Chern (3 integrators), SSH winding, Kitaev BdG Z_2, Kane-Mele / BHZ Z_2, Hofstadter sub-band Chern.

• JS integration test gate (v0.5.1 + v0.5.3) — 141 vitest integration tests cover every TS wrapper that previously had zero coverage; CI now runs them after every WASM rebuild, so the kind of silent symbol-export break that bit v0.5.0 cannot recur.

• Rust examples coverage (v0.5.7 + v0.5.8) — 3/14 -> 14/14 modules have a runnable cargo run --example demo with textbook-correct output: CHSH = 2.82 on the Bell pair, H2 exact ground at -1.142 Ha, Mermin-Klyshko hits the GHZ ideal 2^((n-1)/2) at every n in 2..5, triangle MaxCut at p=3 converges to 100% approximation ratio, etc.

• Kane-Mele Rashba silent-correctness fix (v0.5.9) — the C-side qgt_model_kane_mele had been silently dropping the lambda_r parameter, returning the S_z-conserving Z_2 invariant when the caller passed non-zero Rashba. Now rejects lambda_r != 0.0 rather than emitting wrong physics; the full Pfaffian-based Rashba Z_2 stays on the v0.3.1 milestone list.

• Rust build hygiene (v0.5.2) — 326 unused-unsafe warnings collapsed to 0 by setting the crate-level unsafe_code lint to allow (matching moonlab-sys; the FFI surface is unsafe by construction).

Full version-by-version notes in CHANGELOG.md.

• Matrix-product density operator (MPDO) noise simulator — polynomial- cost simulation of noisy circuits with named single-qubit channels (depolarising, amplitude damping, phase damping, bit/phase/bit-phase flip). Up to ~100 qubits at single-qubit error rates of 1e-3 in quasi-1D layouts. See src/quantum/noise_mpdo.{c,h}.

• n-band quantum geometric tensor (QGT) module — opaque-handle multi-band Bloch-Hamiltonian primitives + three Berry-grid Chern integrators (eigvec FHS, parallel-transport, projector-trace, rigorously gauge-free). Z_2 invariant for 4-band TR-symmetric and 1D BdG systems. Cross-checked against the existing real-space Bianco-Resta chern_marker on QWZ.

• New topological-band-structure model primitives: Kane-Mele (4-band honeycomb QSH), BHZ (4-band square-lattice TI), Kitaev p-wave chain (1D BdG topological superconductor), Harper-Hofstadter (q-band magnetic-flux lattice). Every model reproduces its analytical phase boundary exactly. Hofstadter sub-band Chern numbers match the canonical TKNN values.

• Critical Haldane fix — the existing 2-band Haldane Hamiltonian's NNN antisymmetric sum vanished at the Dirac points in this primitive-coord convention; restored to the canonical form, which reproduces the textbook |M| < 3*sqrt(3)*|t2*sin(phi)| boundary.

See CHANGELOG.md for the full breakdown.

Moonlab v0.2.0 was the first release with an honest end-to-end "quantum-source to quantum-safe" pipeline in one library: the Bell-verified quantum RNG generates 32-byte seeds that feed directly into NIST-standard ML-KEM-512 / 768 / 1024 key generation via a single stable-ABI call. Alongside the cryptography work, 0.2 closes the Phase 1/2 "completeness" items from the release plan — error mitigation (ZNE + PEC), POVM measurement, weak measurement, Mermin / Mermin-Klyshko Bell inequalities, quantum mutual information, composite and correlated noise channels, DI-QRNG primitives — and extends the native reverse-mode autograd with controlled rotations and integrates it directly into the VQE driver. See CHANGELOG.md for the per-subsystem state.

v0.2.x note: hermitian_eigen_decomposition in src/utils/matrix_math.c now correctly handles both real-symmetric and complex-Hermitian inputs (residual ||H v − λv|| < 1e-14 on the 2×2 smoke; consumed by the dense-ED path in vqe_exact_ground_state_energy). The earlier real-Givens limitation was fixed in v0.2.0; the README warning is retained here as a deprecation note for downstream code that may have copied the old workaround.

• Quick Start
• State Vector Simulation
• Tensor Network Methods
• Quantum Algorithms
• Topological Quantum Computing
• Skyrmion Braiding
• Quantum Chemistry
• Many-Body Localization
• Post-Quantum Cryptography
• Error Mitigation
• Language Bindings
• Performance
• Building
• Documentation
• Citation

# Build (CMake, the canonical path on 0.1.2+)
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j

# Run the full test suite (~20s, long_evolution adds ~7min and is opt-in)
ctest --test-dir build -E long_evolution --output-on-failure

# Try an example
./build/bell_test_demo

Warnings-as-errors CI build (clean on macOS arm64):

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DQSIM_WERROR=ON
cmake --build build -j

Sanitized build (AddressSanitizer + UndefinedBehaviorSanitizer):

cmake -S . -B build-asan -DCMAKE_BUILD_TYPE=Debug -DQSIM_ENABLE_SANITIZERS=ON
cmake --build build-asan -j
ASAN_OPTIONS="detect_leaks=0:halt_on_error=1" \
UBSAN_OPTIONS="print_stacktrace=1:halt_on_error=1" \
  ctest --test-dir build-asan -E "long_evolution|python_bindings|rust_bindings|webgpu_unified" \
        --output-on-failure --timeout 300

Distributed (MPI) build:

brew install open-mpi          # macOS; apt-get install -y libopenmpi-dev on Ubuntu
cmake -S . -B build-mpi -DQSIM_ENABLE_MPI=ON
cmake --build build-mpi -j
ctest --test-dir build-mpi -E long_evolution     # mpirun -np 4 distributed_gates

The legacy Makefile path (make all / make test) still works for a subset of targets, but the CMake build is the source of truth for CI, warnings discipline, sanitizer builds, install, and all new language bindings.

#include "quantum/state.h"
#include "quantum/gates.h"

int main(void) {
    // Create Bell state |Φ+⟩ = (|00⟩ + |11⟩)/√2
    quantum_state_t state;
    quantum_state_init(&state, 2);

    gate_hadamard(&state, 0);
    gate_cnot(&state, 0, 1);

    // Verify entanglement
    double entropy = quantum_entanglement_entropy(&state, 0);
    printf("Entanglement entropy: %.4f (max 1.0)\n", entropy);

    quantum_state_free(&state);
    return 0;
}

Full state vector representation for exact quantum simulation.

• 32 Qubits: 4.3 billion amplitude state space (68 GB on high-memory systems)
• Universal Gates: Pauli, Hadamard, Phase, Rotation, CNOT, Toffoli, QFT
• Entanglement Metrics: Von Neumann entropy, purity, fidelity, partial trace
• Secure Measurements: Cryptographic entropy from hardware RNG

Polynomial-scaling simulation for systems beyond state vector limits.

#include "algorithms/tensor_network/tn_state.h"
#include "algorithms/tensor_network/tn_gates.h"

// Create 100-qubit MPS with bond dimension 64
tn_mps_t* mps = tn_mps_create(100, 64);

// Apply gates (automatic SVD truncation)
tn_mps_apply_single(mps, 0, GATE_H);
tn_mps_apply_two(mps, 0, 1, GATE_CNOT);

// Measure expectation values
double magnetization = tn_mps_expectation_z(mps, 50);

#include "algorithms/tensor_network/dmrg.h"

// Heisenberg chain Hamiltonian
dmrg_params_t params = {
    .num_sites = 100,
    .max_bond_dim = 128,
    .num_sweeps = 20,
    .tolerance = 1e-10
};

dmrg_result_t result = dmrg_ground_state(&hamiltonian, &params);
printf("Ground state energy: %.10f\n", result.energy);

#include "algorithms/tensor_network/tdvp.h"

// Real-time dynamics
tdvp_evolve(mps, hamiltonian, dt, num_steps, TDVP_TWO_SITE);

#include "algorithms/tensor_network/lattice_2d.h"
#include "algorithms/tensor_network/mpo_2d.h"

// Create 10x10 lattice
lattice_2d_t* lattice = lattice_2d_create(10, 10, LATTICE_SQUARE);

// Apply 2D MPO Hamiltonian
mpo_2d_t* H = mpo_2d_heisenberg(lattice, J_coupling);

Hybrid representation |psi> = C |phi> where C is a Clifford unitary tracked by the Aaronson-Gottesman tableau and |phi> is an MPS. Clifford gates update only the tableau (O(n) bit ops); non-Clifford gates push Pauli-string rotations into the MPS factor. For stabilizer-state-like circuits CA-MPS uses a bond dimension of 1 regardless of qubit count, giving up to 64x bond-dim advantage + 13884x speedup over plain MPS at n=12 (see tests/performance/bench_ca_mps.c).

#include "algorithms/tensor_network/ca_mps.h"

// 12-qubit CA-MPS with max MPS bond dim 32
moonlab_ca_mps_t* s = moonlab_ca_mps_create(12, 32);

// Clifford gates: tableau-only, no MPS cost
for (uint32_t q = 0; q < 12; q++) moonlab_ca_mps_h(s, q);
moonlab_ca_mps_cnot(s, 0, 1);

// Non-Clifford: pushed into MPS factor via Pauli-string rotation MPO
moonlab_ca_mps_rz(s, 3, 0.7);

// Imaginary-time ground-state search (non-unitary primitive)
moonlab_ca_mps_imag_pauli_rotation(s, (uint8_t[]){3,3,0,0,0,0,0,0,0,0,0,0}, 0.01);
moonlab_ca_mps_normalize(s);

// Expectation value of an observable Pauli string
double _Complex e;
uint8_t p[12] = {3,0,0,0,0,0,0,0,0,0,0,0};  // Z_0
moonlab_ca_mps_expect_pauli(s, p, &e);

See docs/research/ca_mps.md for the full theory, gate-application rules, and benchmark methodology.

CA-MPS is also a ground-state-search representation: |psi_GS> ~ D|phi> where D is a Clifford basis transform chosen to absorb the stabilizer-rich entanglement of the target Hamiltonian, leaving |phi> as a low-entanglement MPS. moonlab_ca_mps_optimize_var_d_alternating implements the alternating optimisation: greedy local-Clifford D-update

• imag-time |phi> evolution.

#include "algorithms/tensor_network/ca_mps_var_d.h"

ca_mps_var_d_alt_config_t cfg = ca_mps_var_d_alt_config_default();
cfg.warmstart                 = CA_MPS_WARMSTART_DUAL_TFIM;  // H_all + CNOT chain
cfg.max_outer_iters           = 25;
cfg.imag_time_steps_per_outer = 4;
cfg.clifford_passes_per_outer = 8;
cfg.composite_2gate           = 1;  // 2-gate composite moves to escape local minima

ca_mps_var_d_alt_result_t res = {0};
moonlab_ca_mps_optimize_var_d_alternating(
    state, paulis, coeffs, num_terms, &cfg, &res);
// res.final_energy, res.final_phi_entropy, res.total_gates_added, ...

Warmstart options bias the greedy search toward known-productive Clifford basins:

• IDENTITY -- D starts at I.
• H_ALL -- product of H on every qubit.
• DUAL_TFIM -- H_all then CNOT chain (Kramers-Wannier dual basis).
• FERRO_TFIM -- H + CNOT chain (cat-state encoder).
• STABILIZER_SUBGROUP -- gauge-aware: see below.

Validated workloads (in examples/tensor_network/): 1D TFIM, 1D XXZ Heisenberg (ca_mps_var_d_heisenberg.c), kagome 12-site frustrated AFM (ca_mps_var_d_kagome12.c), comparison vs plain DMRG (ca_mps_var_d_vs_plain_dmrg.c).

For Hamiltonians whose physical sector is the +1 eigenspace of a commuting set of Pauli generators (lattice gauge theory Gauss-law operators, surface/toric/repetition-code stabilizers, any abelian symmetry projector), the warmstart Clifford D_S can be built exactly via Aaronson-Gottesman symplectic Gauss-Jordan. D_S|0^n> is then in the simultaneous +1 eigenspace of every generator and the var-D loop only has to capture the residual non-stabilizer dynamics on top.

#include "algorithms/tensor_network/ca_mps_var_d_stab_warmstart.h"

// Generators g_0, ..., g_{k-1} as (k, n) row-major Pauli bytes
// (0=I, 1=X, 2=Y, 3=Z), pairwise commuting and independent.
moonlab_ca_mps_apply_stab_subgroup_warmstart(state, generators, k);
// state->D now stabilises the +1 eigenspace of every g_i.

First HEP application: 1+1D Z2 lattice gauge theory. src/applications/hep/lattice_z2_1d.{c,h} builds the matter + gauge-link Pauli sum; examples/hep/z2_gauge_var_d.c runs the full var-D pipeline with the gauge-aware warmstart. Math write-up: docs/research/var_d_lattice_gauge_theory.md.

src/algorithms/tensor_network/ca_peps.{c,h} ships the 2D extension of CA-MPS via a row-major-MPS embedding over Lx * Ly qubits. Clifford gates (H, S, Sdag, X, Y, Z, CNOT, CZ) update the tableau in-place; non-Clifford rotations and the T family push into the inner MPS factor the same way CA-MPS does. Validation lives in tests/unit/test_ca_peps.c: runs a mixed Clifford + rotation circuit on a 3x3 lattice through both moonlab_ca_peps_* and the equivalent CA-MPS linear index, and checks every Pauli-string expectation agrees to <1e-10. Wired into ctest as unit_ca_peps.

grover_result_t result = grover_search(&state, marked_state, num_qubits);
// O(√N) queries vs classical O(N)

#include "algorithms/vqe.h"

vqe_config_t config = {
    .ansatz = VQE_ANSATZ_UCCSD,
    .optimizer = VQE_OPT_BFGS,
    .max_iterations = 100
};

vqe_result_t result = vqe_minimize(&hamiltonian, &config);
printf("Ground state energy: %.8f Ha\n", result.energy);

#include "algorithms/qaoa.h"

// MaxCut problem
qaoa_result_t result = qaoa_maxcut(&graph, num_layers);
printf("Best cut: %zu edges\n", result.best_cut);

#include "algorithms/qpe.h"

double phase = qpe_estimate(&unitary, precision_qubits, &state);

#include "algorithms/bell_tests.h"

/* CHSH on a Bell pair */
bell_test_result_t r = bell_test_chsh(&state, 0, 1, 10000, NULL, entropy);
printf("CHSH: %.4f (classical <= 2, quantum <= 2.828)\n", r.chsh_value);

/* Mermin polynomial on |GHZ_3>: classical <= 2, quantum max 4 */
bell_test_result_t m = bell_test_mermin_ghz(&ghz3, 0, 1, 2, 0, entropy);
printf("Mermin |M|: %.4f\n", m.chsh_value);

/* Mermin-Klyshko M_N on |GHZ_N>, normalised so classical <= 1,
   quantum max 2^((N-1)/2). */
double mk = bell_test_mermin_klyshko(&ghz_n, N, 0, NULL);

Fault-tolerant quantum computation using anyonic systems.

#include "algorithms/topological/topological.h"

// Create Fibonacci anyon system
anyon_system_t* sys = anyon_system_fibonacci(num_anyons);

// Braid anyons (topological gate)
braid_anyons(sys, i, j, BRAID_COUNTERCLOCKWISE);

// Compute resulting unitary
complex_t* U = fusion_tree_to_unitary(sys->fusion_tree);

// Create distance-5 surface code
surface_code_t* code = surface_code_create(5, 5, BOUNDARY_PLANAR);

// Measure stabilizers
surface_code_measure_stabilizers(code);

// Decode and correct errors
int success = surface_code_decode_mwpm(code);

// Create toric code on 6x6 lattice
toric_code_t* toric = toric_code_create(6, 6);

// Measure plaquette and star operators
toric_code_measure_plaquettes(toric);
toric_code_measure_stars(toric);

// Apply logical X on first logical qubit
toric_code_logical_x(toric, 0);

// Compute topological entanglement entropy
double gamma = topological_entanglement_entropy(&state, &region);
// γ = log(D) where D is total quantum dimension

Magnetic skyrmion-based topological qubits using real-time dynamics.

Skyrmions are topologically protected magnetic structures that can encode quantum information through their braiding. This implementation follows [Psaroudaki & Panagopoulos, Phys. Rev. Lett. 127, 067201 (2021)].

#include "algorithms/tensor_network/skyrmion_braiding.h"

// Initialize two skyrmions
skyrmion_t sk1 = { .x = 0.0, .y = 0.0, .charge = 1 };
skyrmion_t sk2 = { .x = 2.0, .y = 0.0, .charge = 1 };

// Define circular braiding path
braid_path_t* path = braid_path_circular(sk1, sk2, num_steps);

// Perform braiding with TDVP time evolution
topo_qubit_t* qubit = topo_qubit_create(mps, sk1, sk2);
braid_result_t result = skyrmion_braid(qubit, path, &params);

// Extract Berry phase
printf("Berry phase: %.6f\n", result.berry_phase);
printf("Fidelity: %.6f\n", result.fidelity);

// Apply topological gates via skyrmion exchange
topo_gate_apply(qubit, TOPO_GATE_EXCHANGE);  // π rotation
topo_gate_apply(qubit, TOPO_GATE_BRAID);     // Braiding unitary

Molecular simulation with fermionic mappings.

#include "algorithms/chemistry/chemistry.h"

// Create fermionic operator a†_p a_q
fermion_op_t op = fermion_op_hopping(p, q);

// Transform to qubit Hamiltonian
jw_operator_t* jw = jordan_wigner_transform(&op);

// Get Pauli string representation
pauli_string_t* paulis = jw_to_pauli_strings(jw);

// Build UCCSD circuit for molecular simulation
uccsd_params_t params = {
    .num_electrons = 2,
    .num_orbitals = 4,
    .singles = true,
    .doubles = true
};

circuit_t* ansatz = uccsd_circuit(&params);

// H2 molecule in minimal basis
molecular_hamiltonian_t* H = molecular_hamiltonian_h2(bond_length);

// Run VQE
vqe_result_t result = vqe_minimize(H, &vqe_config);
printf("H2 energy: %.6f Ha\n", result.energy);

Disordered quantum systems and thermalization dynamics.

#include "algorithms/mbl/mbl.h"

// Create XXZ Hamiltonian with disorder
xxz_params_t params = {
    .num_sites = 16,
    .Jxy = 1.0,
    .Jz = 1.0,
    .disorder_strength = 5.0,  // Strong disorder (MBL phase)
    .seed = 42
};

xxz_hamiltonian_t* H = xxz_hamiltonian_create(&params);

// Level statistics (Poisson vs GOE)
double r = level_spacing_ratio(eigenvalues, num_eigenvalues);
// r ≈ 0.39 (Poisson, MBL) vs r ≈ 0.53 (GOE, thermal)

// Entanglement entropy dynamics
double S = entanglement_entropy_half_chain(state, num_sites);

Moonlab v0.2 ships a reference implementation of FIPS 202 (SHA-3, SHAKE) and FIPS 203 (ML-KEM — the NIST-standardised module-lattice-based KEM), seeded by the same Bell-verified quantum RNG that exports moonlab_qrng_bytes. Three parameter sets are available: ML-KEM-512 (NIST Category 1), ML-KEM-768 (recommended default), and ML-KEM-1024 (Category 5).

#include <moonlab/moonlab_export.h>

uint8_t ek[MOONLAB_MLKEM768_PUBLICKEYBYTES];
uint8_t dk[MOONLAB_MLKEM768_SECRETKEYBYTES];
uint8_t ct[MOONLAB_MLKEM768_CIPHERTEXTBYTES];
uint8_t K_alice[32], K_bob[32];

// Entropy is drawn from moonlab_qrng_bytes internally.
moonlab_mlkem768_keygen_qrng(ek, dk);
moonlab_mlkem768_encaps_qrng(ct, K_bob, ek);
moonlab_mlkem768_decaps(K_alice, ct, dk);
// K_alice == K_bob

Python:

from moonlab.crypto import mlkem
ek, dk   = mlkem.keygen768_qrng()
ct, K_a  = mlkem.encaps768_qrng(ek)
K_b      = mlkem.decaps768(ct, dk)
assert K_a == K_b

All NIST FIPS 202 known-answer vectors pass byte-for-byte (SHA-3 224 / 256 / 384 / 512, SHAKE128, SHAKE256 including split-squeeze). ML-KEM conformance is validated at two tiers: a self-regression KAT (12 SHA3-256 fingerprints of every artifact at fixed (d, z, m) seeds, across all three parameter sets) and a NIST-seeded KAT that drives our in-tree AES-256 SP 800-90A CTR_DRBG from the published NIST count=0 seed through KeyGen + Encaps. A FIPS 203 reviewer can hash the official PQCkemKAT .rsp artifacts with SHA3-256 and compare to the pinned fingerprints -- match establishes conformance.

Security posture: this is a reference implementation -- constant-time on non-exotic CPUs, not FIPS-140-certified, and not hardened for adversarial side-channel environments. It is suitable for learning, for integrating the QRNG source into a PQC workflow, and for research on quantum-safe primitives. For FIPS-certified production crypto, integrate with BoringSSL or OpenSSL EVP; the QRNG seed path still applies.

See examples/applications/pqc_qrng_demo.c for a ~100-line end-to-end demo and docs/security/pqc.md for the threat model.

A new src/mitigation/ subsystem with the two workhorse techniques for current-generation NISQ hardware:

#include <moonlab/mitigation/zne.h>

// Suppose fn(lambda, ctx) runs the circuit with noise scaled by lambda
// and returns the measured <O>.
double scales[] = { 1.0, 1.5, 2.0, 3.0 };
double sd = 0.0;
double E_mitigated = zne_mitigate(fn, ctx, scales, 4,
                                   ZNE_EXPONENTIAL, &sd);

Three estimators: linear (OLS intercept fit), Richardson (exact Lagrange interpolation at lambda = 0 -- zero residual on polynomials of degree <= n-1), and exponential (fit E = a + b exp(-c lambda), recovers depolarised <Z> to 1e-13 in the integration test).

Probabilistic error cancellation primitives (pec_one_norm_cost, pec_sample_index, pec_aggregate) provide the Monte-Carlo machinery for caller-supplied quasi-probability decompositions of inverse noise channels.

import moonlab as ml
import torch

# Create quantum state
state = ml.QuantumState(4)
state.h(0).cnot(0, 1).cnot(1, 2).cnot(2, 3)

# PyTorch hybrid layer
class QuantumLayer(torch.nn.Module):
    def __init__(self, num_qubits):
        super().__init__()
        self.circuit = ml.ParameterizedCircuit(num_qubits)
        self.params = torch.nn.Parameter(torch.randn(num_qubits * 3))

    def forward(self, x):
        return self.circuit.run(x, self.params)

# Train with backpropagation
model = QuantumLayer(4)
optimizer = torch.optim.Adam(model.parameters())

from moonlab.algorithms import VQE

vqe = VQE(
    hamiltonian=H_molecular,
    ansatz='uccsd',
    optimizer='BFGS'
)
result = vqe.minimize()
print(f"Energy: {result.energy:.8f} Ha")

use moonlab::{QuantumState, Gate};

fn main() {
    let mut state = QuantumState::new(4);
    state.apply(Gate::H, 0);
    state.apply(Gate::CNOT, (0, 1));

    let entropy = state.entanglement_entropy(0);
    println!("Entropy: {:.4}", entropy);
}

import { useQuantumState, BlochSphere } from '@moonlab/quantum-react';

function QuantumVisualizer() {
    const [state, dispatch] = useQuantumState(1);

    return (
        <div>
            <BlochSphere state={state} />
            <button onClick={() => dispatch({ type: 'H', qubit: 0 })}>
                Hadamard
            </button>
        </div>
    );
}

<template>
    <circuit-diagram :circuit="circuit" />
</template>

<script setup>
import { useQuantumState } from '@moonlab/quantum-vue';
const { state, circuit } = useQuantumState(2);
</script>

Read this before judging the repo against its headline claims. The adversarial audit that produced this list lives in docs/audits/adversarial-review-2026-04-19.md.

• Chern mosaic: the full Bianco-Resta local marker C(r) = -4 pi * Im Sum_orb <r, orb| P X Q Y P |r, orb> now runs end-to-end via the MPO pipeline on a real QWZ 2D Chern insulator at L = 4 and reproduces the dense Schulz reference to machine precision (|MPO - dense| = 0.0000 at a bulk site). Position operators are the quantics-bit-weighted diagonal-sum MPOs. The sparse-stencil renderer scales to L = 300 single-core. Adaptive QTCI for non-monomial modulations is still future work; the linear-in-coordinate case (what the Bianco-Resta formula actually uses) is shipped.
• CHSH / "Bell-verified" QRNG: prior to 0.2.0 the bell_test_chsh function silently overwrote the input state with |Phi+> before measuring, so every CHSH reading was 2.828 by fiat. Fixed this release. The moonlab_qrng_bytes BELL_VERIFIED mode now runs its health check on a fresh |Phi+> temporary rather than on the QRNG's own evolving scratch state; treat the resulting CHSH number as a plumbing sanity check, not a proof of quantum advantage in the emitted bytes.
• MPI: the distributed_gates ctest runs at mpirun -np 4 and exercises H, CNOT, SWAP, Toffoli, and a full GHZ chain across the partition boundary (norm preservation + specific amplitude checks to 1e-10). What is not tested yet: multi-node (>1 physical host) scaling, wall-clock comparisons against single-host baselines, and any MPI backend other than OpenMPI.
• GPU backends other than Metal + Eshkol: OpenCL and Vulkan now compile cleanly and pass a "compile + discovery smoke" CI tier on Linux (apt's ocl-icd-loader + PoCL for OpenCL; vulkan-loader + lavapipe for Vulkan) but are not exercised against a real GPU in CI -- the smoke test just verifies backend selection and fallback. CUDA and cuQuantum have 1000+ LOC implementations but no CI runner has NVIDIA hardware; treat them as compile-only.
• WebGPU / JS: CI has a dedicated WASM / WebGPU smoke tier that builds the TS @moonlab/quantum-core package and runs the unified smoke end-to-end. The default C-only ctest on a fresh clone without -DQSIM_BUILD_JS_DIST=ON produces no WebGPU coverage -- that is the trade-off for not requiring a JS toolchain just to build the library.
• Platforms: Linux x86_64, Linux aarch64, macOS arm64, and macOS x86_64 all have CI tiers that build the full tree and run ctest -E long_evolution; macOS arm64 additionally runs Release, Debug, -Werror, ASAN+UBSAN, and MPI-enabled variants. Windows is unsupported.
• Performance numbers: every headline multiplier was measured once on one host. No stddev, no cross-platform reproduction. Use the benches below to measure your own hardware; do not quote the repository's numbers as portable.

The numbers historically quoted here (GPU speedups, MPI scaling, DMRG wall-clocks) pre-date any reproducible harness that exercises the full pipeline on a single host configuration, so they have been retired pending the 0.2 benchmark work (Quantum Volume + CLOPS + XEB + direct RB as described in docs/release/ / MOONLAB_RELEASE_ROADMAP.md).

Runnable micro-benchmarks ship today:

./build/bench_state_operations          # dense SV gate throughput
./build/bench_tensor_networks           # MPS / DMRG micro-probes
./build/grover_parallel_benchmark       # Grover scaling across cores
./build/phase3_phase4_benchmark         # Metal kernel sanity

Use those to measure your own hardware. A comparative regression harness against Qiskit-Aer / Qulacs / cuStateVec is tracked for 0.2.

State-vector sharding across MPI ranks is wired end-to-end in src/distributed/: dist_gate_1q, dist_hadamard, dist_pauli_*, dist_cnot, etc. handle both local-partition and cross-partition gates with the necessary MPI_Sendrecv exchange. The tests/integration/test_distributed_* harnesses validate Bell + GHZ round-trips on mpirun -np 2..4. Cross-rank scaling above N = 32 qubits (which exercises the dist_* buffer-size path fixed in v0.8.0) runs on dev hosts but has not yet been published with a peer-host reproducible scaling table -- that's tracked as part of the post-v1.0 scaling-honesty pass.

• macOS: 10.15+ (Apple Silicon recommended)
• Linux: GCC 9+ with OpenMP
• Memory: 8 GB minimum, 32 GB+ for large simulations

CMake is the canonical build system (0.1.2+). Useful options:

Legacy make all / make test still work for a subset of the surface.

Required:

• C compiler (GCC/Clang)
• POSIX threads

Optional:

• OpenMP (multi-core)
• Accelerate framework (macOS AMX)
• Metal (GPU, macOS)
• MPI (distributed)

Full documentation is available in the docs/ directory:

• Getting Started
• Concepts
• Tutorials
• API Reference
• Algorithm Deep Dives
• Performance Guide

moonlab/
├── src/
│   ├── quantum/              # State vector engine
│   ├── algorithms/
│   │   ├── grover.c          # Grover's search
│   │   ├── vqe.c             # Variational eigensolver
│   │   ├── qaoa.c            # Quantum optimization
│   │   ├── qpe.c             # Phase estimation
│   │   ├── tensor_network/   # MPS, DMRG, TDVP, skyrmions
│   │   ├── topological/      # Anyons, surface codes
│   │   ├── chemistry/        # Jordan-Wigner, UCCSD
│   │   └── mbl/              # Many-body localization
│   ├── optimization/         # SIMD, Metal GPU, parallel
│   └── distributed/          # MPI communication
├── bindings/
│   ├── python/               # Python + PyTorch
│   ├── rust/                 # Rust FFI + TUI
│   └── javascript/           # React, Vue, WASM
├── examples/
│   ├── basic/                # Hello quantum, Bell states
│   ├── algorithms/           # VQE, QAOA, Grover
│   ├── tensor_network/       # Spin chains, DMRG
│   └── applications/         # Portfolio, QRNG
├── tests/                    # Test suite
└── docs/                     # Documentation

If you use Moonlab in your research, please cite:

@software{tsotchke_moonlab_2026,
    author       = {tsotchke},
    title        = {{Moonlab}: A Quantum Computing Simulation Framework},
    year         = {2026},
    version      = {v1.0.2},
    url          = {https://github.com/tsotchke/moonlab},
    license      = {MIT},
    keywords     = {quantum computing, simulation, tensor networks,
                    Clifford-Assisted MPS, variational-D, lattice gauge
                    theory, Z2 LGT, gauge-aware warmstart,
                    topological quantum computing, DMRG, VQE, QAOA,
                    Chern insulators, quantum geometric tensor}
}

Foundational Textbooks and Reviews:

• Nielsen, M.A. & Chuang, I.L. (2010). Quantum Computation and Quantum Information. Cambridge University Press.
• Preskill, J. (2018). Quantum computing in the NISQ era and beyond. Quantum, 2, 79.

Quantum Algorithms:

• Shor, P.W. (1994). Algorithms for quantum computation: discrete logarithms and factoring. Proc. 35th FOCS, 124-134.
• Grover, L.K. (1996). A fast quantum mechanical algorithm for database search. Proc. 28th STOC, 212-219.
• Peruzzo, A. et al. (2014). A variational eigenvalue solver on a photonic quantum processor. Nat. Commun. 5, 4213.
• Farhi, E., Goldstone, J., & Gutmann, S. (2014). A quantum approximate optimization algorithm. arXiv:1411.4028.
• Kitaev, A.Y. (1995). Quantum measurements and the Abelian stabilizer problem. arXiv:quant-ph/9511026.

Tensor Networks:

• White, S.R. (1992). Density matrix formulation for quantum renormalization groups. Phys. Rev. Lett. 69, 2863.
• Schollwöck, U. (2011). The density-matrix renormalization group in the age of matrix product states. Ann. Phys. 326, 96-192.
• Orús, R. (2014). A practical introduction to tensor networks. Ann. Phys. 349, 117-158.
• Vidal, G. (2003). Efficient classical simulation of slightly entangled quantum computations. Phys. Rev. Lett. 91, 147902.
• Haegeman, J. et al. (2016). Unifying time evolution and optimization with matrix product states. Phys. Rev. B 94, 165116.

Topological Quantum Computing:

• Kitaev, A. (2003). Fault-tolerant quantum computation by anyons. Ann. Phys. 303, 2-30.
• Nayak, C., Simon, S.H., Stern, A., Freedman, M., & Das Sarma, S. (2008). Non-Abelian anyons and topological quantum computation. Rev. Mod. Phys. 80, 1083.
• Fowler, A.G., Mariantoni, M., Martinis, J.M., & Cleland, A.N. (2012). Surface codes: Towards practical large-scale quantum computation. Phys. Rev. A 86, 032324.

Skyrmion Physics:

• Psaroudaki, C. & Panagopoulos, C. (2021). Skyrmion qubits: A new class of quantum logic elements. Phys. Rev. Lett. 127, 067201.

Quantum Chemistry:

• Jordan, P. & Wigner, E. (1928). Über das Paulische Äquivalenzverbot. Z. Physik 47, 631-651.
• McArdle, S., Endo, S., Aspuru-Guzik, A., Benjamin, S.C., & Yuan, X. (2020). Quantum computational chemistry. Rev. Mod. Phys. 92, 015003.

Many-Body Localization:

• Nandkishore, R. & Huse, D.A. (2015). Many-body localization and thermalization in quantum statistical mechanics. Annu. Rev. Condens. Matter Phys. 6, 15-38.
• Abanin, D.A., Altman, E., Bloch, I., & Serbyn, M. (2019). Colloquium: Many-body localization, thermalization, and entanglement. Rev. Mod. Phys. 91, 021001.

Bell Tests and Foundations:

• Bell, J.S. (1964). On the Einstein Podolsky Rosen paradox. Physics Physique Физика 1, 195-200.
• Clauser, J.F., Horne, M.A., Shimony, A., & Holt, R.A. (1969). Proposed experiment to test local hidden-variable theories. Phys. Rev. Lett. 23, 880.

High-Performance Quantum Simulation:

• Häner, T. & Steiger, D.S. (2017). 0.5 petabyte simulation of a 45-qubit quantum circuit. Proc. SC17, Article 33.

MIT License. See LICENSE for details.

Moonlab - From qubits to anyons, from state vectors to tensor networks.

Built for researchers. Optimized for discovery.