GitHub - qumulator/qumulator-sdk: Python client SDK for the Qumulator quantum computing API
Pangram verdict · v3.3
We believe that this document is primarily human-written, with some AI-generated content detected
AI likelihood · overall
MixedArticle text · 1,138 words · 7 segments analyzed
Simulate 1,000-qubit quantum circuits on classical hardware. Exact results. No GPU. No quantum hardware required.
What is this? Qumulator is a cloud API — and this is its Python client — for simulating quantum circuits, spin systems, photonic amplitudes, and molecular properties on standard classical hardware. It does not require a quantum computer, a GPU, or any special hardware. It runs in the cloud (Google Cloud Run, 4 vCPU, 16 GB RAM) and returns results over HTTP. The key numbers: a 1,000-qubit circuit at depth 3 runs in under 1 second using 1 MB of memory — where the equivalent statevector would require $2^{1000}$ bytes (more atoms than exist in the observable universe). A 105-qubit Willow-layout circuit at depth 5 completes in under 0.5 s. Results are exact within the stated truncation error, not statistical estimates. The simulation engine is built on the KLT Engine, a proprietary classical simulation framework that routes each problem to the most efficient representation — tensor network, cluster-exact, Gaussian covariance matrix, nexus graph, or full statevector — based on the entanglement structure of the specific circuit. Callers select a mode with a single parameter; the engine handles routing automatically.
Benchmarks Measured on a standard cloud CPU (4 vCPU, no GPU). "Exact" means output agrees with full statevector simulation to double-precision floating point (< 10⁻¹⁴ L² error on the amplitude vector).
Problem Size Result Reference Error Time
CHSH Bell violation N=2 S = 2.828427 2√2 = 2.828427 < 0.0001% < 1 ms
H₁₂ Heisenberg chain 12 sites −11.000 −11.000 (exact diag.)
0.00% ~0.27 s
Photonic hafnian (GBS) 8×8 matrix 0.2598−0.0078i exact DP < 2×10⁻¹⁵ 39 ms
Photonic hafnian (GBS) 12×12 matrix 0.0239+0.9947i exact DP < 5×10⁻¹⁵ 43 ms
RCS circuit (exact) 12 q, depth 20 XEB = 1.014 exact statevector 0.00% 15–23 ms
RCS circuit (exact) 20 q, depth 20 XEB = 1.024 exact statevector 0.00% 8.5–9.6 s
MBL discrete time crystal 8 q, 24 Floquet autocorr = 0.827 Google Sycamore 2021 Consistent ~1 s
Holographic wormhole 2×6 SYK sites fidelity 94.89% Google Sycamore 2022 — ~5 s
Non-Abelian anyon braiding Fibonacci anyons ‖[σ₁,σ₂]‖ = 1.272 SU(2)₃ exact < 0.001% < 1 ms
Kitaev chain BdG L=1000 sites W=−1, gap=2.000 analytic (exact) < 10⁻¹² 0.84 s
QUBO dense optimisation N=100 matches SA optimum simulated annealing
0% ~3 s
Kuramoto BEC (large-scale) N=500 oscillators, 2 MB r=0.114 (Mott-like) statevector: 2⁵⁰⁰ bytes (impossible) — 3.22 s
Circuit depth limits (approximation modes) Bond dimension $\chi = 2^\text{depth}$; all tiers keep peak memory under 400 MB.
Tier Qubit range Max entangling depth χ Peak memory Notes
1 1 – 20 20 1024 335 MB Exact for structured circuits
2 21 – 54 9 512 226 MB Exact (2⁹ = 512)
3 55 – 105 8 256 110 MB Exact (2⁸ = 256)
4 106 – 1,000 7 128 262 MB Exact (2⁷ = 128)
Depth is counted in entangling layers only — single-qubit gates (H, Rz, T, etc.) do not count toward the depth limit and are not restricted. Requests exceeding the tier depth limit return HTTP 422 with a self-documenting error message. Statevector mode: max 20 qubits at any depth.
Install pip install qumulator-sdk Optional extras: pip install "qumulator-sdk[qiskit]" # Qiskit drop-in backend pip install "qumulator-sdk[cirq]" # Cirq drop-in simulator pip install "qumulator-sdk[all]" # everything
Get a free API key Mac / Linux curl -s -X POST https://api.qumulator.com/keys \
-H "Content-Type: application/json" \ -d '{"name": "my-key"}' Windows (PowerShell) Invoke-WebRequest ` -Uri "https://api.qumulator.com/keys" ` -Method POST ` -ContentType "application/json" ` -Body '{"name":"my-key"}' ` -UseBasicParsing Or via the CLI (after install): qumulator key
Quick start — 1,000-qubit circuit in 30 seconds import os from qumulator import QumulatorClient
client = QumulatorClient( api_url="https://api.qumulator.com", api_key=os.environ["QUMULATOR_API_KEY"], )
# 500 parallel Bell pairs across 1,000 qubits (depth 1) eng = client.circuit.engine(n_qubits=1000) for i in range(0, 1000, 2): eng.apply("h", i) # Hadamard on even qubits (parallel) for i in range(0, 1000, 2): eng.apply("cx", [i, i + 1]) # entangle each pair (parallel)
result = eng.sample(shots=10) print(result.counts) # e.g. {'0101100110...': 1, '1010011001...': 1, ...} print(result.most_probable) # Exact result. No quantum hardware. No GPU. Standard cloud CPU. Run the built-in demo against the live API: qumulator demo # 1000-qubit GHZ qumulator demo --willow # 105-qubit Willow-layout RCS
OpenQASM 2/3 result = client.circuit.run_qasm("""
OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0], q[1]; measure q -> c; """, shots=1024)
print(result.counts) # {'00': ~512, '11': ~512} print(result.entropy_map) # [0.999, 0.999] — entanglement per qubit
Drop into Qiskit — two lines of code from qumulator.backends.qiskit_backend import QumulatorBackend from qiskit import transpile
backend = QumulatorBackend(client) # replaces AerSimulator() job = backend.run(transpile(qc, backend), shots=1024) counts = job.result().get_counts() Everything else in your Qiskit workflow is unchanged.
Drop into Cirq — two lines of code from qumulator.backends.cirq_simulator import QumulatorSimulator
sim = QumulatorSimulator(client) # replaces cirq.Simulator() result = sim.run(circuit, repetitions=1024)
Simulation modes Pass mode= to any run() call. The server selects auto by default.
User-facing mode Internal mode Max qubits Best for
auto (server-routed) 1,000 General circuits; server auto-routes
exact (statevector) 20 Unconditionally correct; small N
compressed (tensor network) 1,000 VQE, QAOA, chemistry ansätze
tensor (MPS) 1,000 1D-structured, low-entanglement circuits
hamiltonian (operator algebra) 1,000 Hamiltonian simulation without gate decomposition
gaussian (covariance matrix) unlimited Clifford circuits; returns Wigner negativity certificate
Other computation types # Molecular HOMO/LUMO frontier orbital energies (SMILES input) homo = client.homo.run("Oc1ccc(/C=C/c2cc(O)cc(O)c2)cc1") print(homo.homo_E_eV,
homo.lumo_E_eV, homo.gap_eV)
# Ground-state energy of a spin Hamiltonian (Ising / Heisenberg / general) import numpy as np J = np.random.randn(8, 8); J = (J + J.T) / 2 result = client.klt.run(J.tolist()) print(result.energy)
# Hafnian / GBS photonic amplitude A = np.random.randn(8, 8); A = (A + A.T) / 2 h = client.hafnian.run(A.tolist()) print(h.value)
Free tier limits
Limit Value
Compute Units / month 500 CU (1 CU = 1 CPU-second of engine time)
Max qubits (statevector mode) 20
Max qubits (MPS mode) 1,000 (all tiers)
Rate limit 1 request / minute
Daily limit 100 requests / day
Free tier availability Beta only — may be discontinued at any time
Paid plans start at $99/month (10,000 CU). See qumulator.com/#pricing.
Demo notebooks Click to open in Google Colab — no install required, just add your API key:
Notebook Description
Willow RCS — 105-qubit exact simulation, Willow-layout
Holographic wormhole — traversable wormhole, matches Google 2022
Anyon braiding — Fibonacci anyons, matches Microsoft topological target
Discrete time crystal — MBL Floquet, matches Google Sycamore 2021
QUBO optimisation — 100-variable dense combinatorial optimisation
CLI The qumulator command ships with the SDK: qumulator demo # 1000-qubit GHZ demo vs. the public API qumulator demo --willow # 105-qubit Willow-layout benchmark qumulator demo --wormhole # holographic wormhole qumulator demo --anyon # anyon braiding qumulator key # instructions to get a free API key qumulator run circuit.qasm # submit a QASM file and print the result
Set QUMULATOR_API_KEY in your environment, or pass --key YOUR_KEY.
Documentation Full API reference and examples: qumulator.com
License MIT — see LICENSE.