Qumulator API & SDK Reference

Quickstart

pip install qumulator-sdk           # CPU — unlimited qubits
pip install "qumulator-sdk[gpu]"    # GPU — CuPy / JAX / PyTorch, auto-detected

from qumulator.local import LocalStatevectorEngine
eng = LocalStatevectorEngine(n_qubits=28)  # no hard cap — use what your hardware has
eng.apply('h', 0)
for i in range(27): eng.apply('cx', [i, i+1])
result = eng.run(shots=4096, return_entropy_map=True)

Run your first quantum circuit in under two minutes. No account, no credit card, no hardware required.

Step 1 — Get an API key

One POST request returns a key immediately. The key is displayed once — save it somewhere safe.

# cURL
curl -s -X POST https://api.qumulator.com/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-first-key"}'

# Response
{
  "key":        "qum_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name":       "my-first-key",
  "created_at": "2026-04-20T12:00:00Z"
}

Step 2 — Install the SDK

pip install qumulator-sdk

Step 3 — Run a Bell-state circuit

from qumulator import QumulatorClient

client = QumulatorClient(
    api_url="https://api.qumulator.com",
    api_key="qum_xxxxxxxx...",
)

# Build and run a 2-qubit Bell state
eng = client.circuit.engine(n_qubits=2)
eng.apply('h', 0).apply('cx', [0, 1])

counts = eng.sample(shots=1024)
print(counts)   # {'00': ~512, '11': ~512}

Authentication

Every request to the API (except POST /keys) must include your API key in the X-API-Key header.

curl https://api.qumulator.com/circuits \
  -H "X-API-Key: qum_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

The Python SDK handles this automatically once you pass api_key to QumulatorClient.

Base URL & Versioning

The API is currently unversioned (no /v1/ prefix). Breaking changes will be announced in advance.

SDK — Installation

pip install qumulator-sdk

Requires Python 3.10 or later. The core package has a single dependency: httpx. Framework adapters (Qiskit, Cirq) require those packages installed separately.

# With Qiskit adapter
pip install qumulator-sdk qiskit

# With Cirq adapter
pip install qumulator-sdk cirq

SDK — QumulatorClient

QumulatorClient is the entry point for all computation types.

from qumulator import QumulatorClient

client = QumulatorClient(
    api_url="https://api.qumulator.com",
    api_key="qum_...",
)

Quantum Simulation

Submit quantum circuits via the gate builder, OpenQASM 2/3, Qiskit, or Cirq. The cluster circuit engine automatically routes each job to the most efficient backend — statevector (≤20 qubits), MPS (≤1,000 qubits), cluster-exact, Green’s function, or Gaussian — based on qubit count and entanglement structure. Results include measurement counts, the full statevector, per-qubit von Neumann entropy, QFI-based multipartite entanglement depth, and a Gaussian simulability certificate.

⎯⎯ Explore Quantum Simulation notebooks ›

SDK — Circuit Simulation

There are two ways to construct a circuit: the fluent gate builder and the direct gate-list API. Both are equivalent and produce identical results. No simulation runs locally — all execution is server-side.

Fluent gate builder

Obtain a CircuitEngine from client.circuit.engine(), accumulate gates with .apply(), then submit with .run() or .sample().

eng = client.circuit.engine(n_qubits=3)

eng.apply('h',   0           )  # Hadamard on qubit 0
   .apply('cx',  [0, 1]       )  # CNOT: control 0, target 1
   .apply('cx',  [0, 2]       )  # CNOT: control 0, target 2
   .apply('rz',  2, params=[1.5708])  # Rz(pi/2) on qubit 2

result = eng.run(
    shots=4096,
    return_statevector=True,
    return_entropy_map=True,
)

print(result.counts)        # {'000': ~2048, '111': ~2048}
print(result.entropy_map)   # [1.0, 0.0, 0.0]  — qubit 0 maximally entangled
print(result.statevector)   # complex ndarray, length 8

Gate-list API

result = client.circuit.run(
    gates=[
        ('h',  0),
        ('cx', [0, 1]),
    ],
    n_qubits=2,
    shots=2048,
)

Supported gates

engine() parameters

run() parameters

SDK — OpenQASM Input

Both OpenQASM 2 and OpenQASM 3 source strings are accepted. Pass the source to client.circuit.run_qasm().

qasm_source = """
OPENQASM 3.0;
include "stdgates.inc";
qubit[3] q;
bit[3]   c;

h  q[0];
cx q[0], q[1];
cx q[0], q[2];
measure q -> c;
"""

result = client.circuit.run_qasm(
    qasm=qasm_source,
    shots=2048,
    mode="statevector",
    return_entropy_map=True,
)
print(result.counts)    # {'000': ~1024, '111': ~1024}

Custom unitary gates via the instructions API

For gates with no standard QASM name (e.g. the SYC gate in Google Willow circuits), use the instructions input with an explicit matrix:

import numpy as np

# Arbitrary 2-qubit unitary (e.g. Google SYC gate)
my_gate = np.array([
    [1, 0,     0,   0   ],
    [0, 0,    -1j,  0   ],
    [0, -1j,   0,   0   ],
    [0, 0,     0,   np.exp(1j * np.pi / 6)],
])

eng = client.circuit.engine(n_qubits=4)
eng.apply('unitary', [0, 1], params=my_gate.tolist())
   .apply('unitary', [2, 3], params=my_gate.tolist())

result = eng.run(shots=1024)

SDK — Simulation Modes

Pass mode= to engine() or run(). The default "mps" uses the MPS backend and scales to 1,000 qubits.

Auto-routing

When mode="auto" is used, the engine builds the circuit’s entanglement graph, estimates the fractal dimension D_KY of its entanglement structure, and routes to the optimal backend before simulation begins. Tree-topology circuits are routed to "mps"; Clifford-only circuits to "gaussian"; high-entanglement small circuits to "statevector". No simulation cost is incurred for the analysis. Use POST /circuits/preflight to inspect the routing decision without running a simulation at all (zero compute units).

Hamiltonian evolution

Use mode="hamiltonian" and call evolve_hamiltonian() to apply e^−iHt directly from a Pauli-string Hamiltonian, without requiring a gate decomposition.

eng = client.circuit.engine(n_qubits=4, mode="hamiltonian")

eng.apply('h', 0).apply('h', 1)  # initial state preparation

eng.evolve_hamiltonian(
    pauli_terms=[
        ( 0.5,  'ZZII'),   # ZZ coupling on sites 0-1
        ( 0.5,  'IZZI'),   # ZZ coupling on sites 1-2
        (-1.0, 'XIIX'),   # transverse field
    ],
    t=1.0,  # evolution time
)

result = eng.run(shots=2048, return_entropy_map=True)

Pauli strings use I X Y Z per qubit; the leftmost character is qubit 0.

Gaussian mode and the simulation certificate

eng = client.circuit.engine(n_qubits=20, mode="gaussian")

for i in range(20):
    eng.apply('h', i)
for i in range(0, 19, 2):
    eng.apply('cz', [i, i+1])
eng.apply('t', 5)   # non-Clifford gate

result = eng.run(shots=1024)
cert   = result.gaussian_certificate

print(cert.rcs_certificate)            # "LIKELY_GAUSSIAN"
print(cert.entanglement_regime)        # "area_law"
print(cert.gaussian_fidelity)          # 0.991
print(cert.wigner_negativity_estimate) # small positive float

SDK — Qiskit Integration

QumulatorBackend is a drop-in replacement for any Qiskit simulator backend. Build your circuit in Qiskit as normal; the adapter transpiles and runs it on Qumulator.

from qumulator import QumulatorClient
from qumulator.backends.qiskit_backend import QumulatorBackend
from qiskit import QuantumCircuit

client  = QumulatorClient(api_url="https://api.qumulator.com", api_key="qum_...")
backend = QumulatorBackend(client)

qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

job    = backend.run(qc, shots=2048)
result = job.result()
counts = result.get_counts()
print(counts)   # {'00': ~1024, '11': ~1024}

Specifying a simulation mode

# cluster_mps mode for a large variational circuit
backend = QumulatorBackend(client, mode="cluster_mps")
job     = backend.run(qc, shots=8192)

Using with Qiskit VQE / QAOA

Any Qiskit circuit can be sent to Qumulator. The adapter automatically transpiles to the supported gate set. Gates that expose gate.to_matrix() are submitted as arbitrary unitaries and simulated exactly.

# Run your parameterised ansatz on Qumulator instead of a local simulator
bound_circuit = ansatz.assign_parameters(theta_values)
bound_circuit.measure_all()

job = backend.run(bound_circuit, shots=4096)
counts = job.result().get_counts()
expectation_value = compute_energy(counts, hamiltonian)

SDK — Cirq Integration

QumulatorSimulator implements Cirq's Simulator interface and supports both sampling and statevector simulation.

import cirq
from qumulator import QumulatorClient
from qumulator.backends.cirq_simulator import QumulatorSimulator

client = QumulatorClient(api_url="https://api.qumulator.com", api_key="qum_...")
sim    = QumulatorSimulator(client)

q0, q1 = cirq.LineQubit.range(2)
circuit = cirq.Circuit(
    cirq.H(q0),
    cirq.CNOT(q0, q1),
    cirq.measure(q0, q1, key='result'),
)

# Sampling
result = sim.run(circuit, repetitions=1024)
print(result.histogram(key='result'))  # Counter({0: ~512, 3: ~512})

# Statevector
sv = sim.simulate(circuit)
print(sv.final_state_vector)
# array([0.707+0j, 0+0j, 0+0j, 0.707+0j])

Google Sycamore / Willow circuits

q = cirq.LineQubit.range(4)
circuit = cirq.Circuit(
    [cirq.H(qi) for qi in q],
    cirq.SYC(q[0], q[1]),
    cirq.SYC(q[2], q[3]),
    [cirq.measure(qi, key=str(i)) for i, qi in enumerate(q)],
)
result = sim.run(circuit, repetitions=2048)

Molecular Chemistry

Compute molecular properties directly from SMILES strings or PySCF active-space integrals (1e/2e arrays). Three complementary methods are available: HOMO/LUMO frontier orbital energies via DFT (B3LYP/6-31G* default; any basis and functional supported); MPS/MPO ground-state energies for multi-fragment active spaces up to 50 orbitals; and DMRG for exact FCI-quality energies up to 30 orbitals with systematic bond-dimension convergence.

⎯⎯ Explore Molecular Chemistry notebooks ›

SDK — Molecular Orbitals

Compute HOMO and LUMO frontier orbital energies from a SMILES string. Results include the HOMO–LUMO gap and per-atom orbital density weights.

# Resveratrol
result = client.homo.run("Oc1ccc(/C=C/c2cc(O)cc(O)c2)cc1")

print(result.homo_E_eV)    # -5.515 eV  (B3LYP/6-31G*)
print(result.lumo_E_eV)    # -0.821 eV
print(result.gap_eV)       # HOMO-LUMO gap in eV
print(result.heavy_symbols) # ['C', 'C', ..., 'O', 'O']
print(result.homo_density)  # per-heavy-atom HOMO weight

Basis set and functional

# Use a larger basis set and a different functional
result = client.homo.run(
    "c1ccccc1",   # benzene
    basis="6-31g",
    xc="pbe0",
)

HomoResult fields

SDK — Molecular Energy (MPS/MPO)

Compute the quantum ground-state energy of an active-space Hamiltonian using the Givens-MPS / Matrix Product Operator (MPS/MPO) engine. Accepts one-body and two-body integrals extracted from any PySCF active-space calculation.

from pyscf import gto, scf, mcscf, ao2mo

# Build molecule and extract active-space integrals
mol = gto.M(atom="H 0 0 0; H 0 0 0.74", basis="sto-3g")
mf  = scf.RHF(mol).run()
mc  = mcscf.CASSCF(mf, ncas=2, nelecas=2).run()

h1e, e_core = mc.get_h1eff()
h2e  = ao2mo.restore(1, mc.get_h2eff(), mc.ncas)
e_nuc = mc.energy_nuc() + e_core

# Call the MPS/MPO engine
result = client.molecular.energy(
    h1e=h1e.tolist(),
    h2e=h2e.tolist(),
    n_elec=[1, 1],
    e_nuc=float(e_nuc),
)

print(result.energy)        # ground-state energy in Ha
print(result.n_qubits)      # 2 × n_orb spin-orbitals
print(result.n_components)  # MPS bond dimension (entanglement measure)

With Givens rotation circuit

circuit = [
    {"type": "givens", "i": 0, "j": 1, "theta": 0.3},
]
result = client.molecular.energy(
    h1e=h1e.tolist(), h2e=h2e.tolist(),
    n_elec=[1, 1], e_nuc=float(e_nuc),
    circuit=circuit,
)

MolecularEnergyResult fields

Limits

SDK — DMRG Ground-State Energy

Compute the quantum ground-state energy using the Density Matrix Renormalization Group (DMRG) engine. DMRG sweeps converge systematically to the exact FCI limit as the bond dimension d_max increases.

result = client.dmrg.energy(
    h1e=h1e.tolist(),
    h2e=h2e.tolist(),
    n_elec=[1, 1],
    e_nuc=float(e_nuc),
    d_max=64,      # bond dimension — higher = more accurate
    n_sweeps=8,    # number of DMRG sweeps
)

print(result.energy)        # ground-state energy in Ha
print(result.converged)     # True if |ΔE| < tol
print(result.wall_time_s)   # server-side runtime

Recommended d_max by active space size

DMRGEnergyResult fields

Limits

Condensed Matter

Compute ground states and real-time dynamics of lattice spin models via exact diagonalisation (Pauli-string Hamiltonian input) or TEBD (Time-Evolving Block Decimation). Supported Hamiltonian presets include the transverse-field Ising model (TFIM), XX free-fermion chain, Heisenberg XXX, Kuramoto–Ising, and the AKLT spin-1 chain. Observable outputs include per-bond von Neumann entropy, QFI density, magnetisation trajectory, Kibble–Zurek defect density, and the AKLT hidden string order parameter O_string.

⎯⎯ Explore Condensed Matter notebooks ›

SDK — Spin Ground States

Compute ground-state energies for interacting spin systems or arbitrary Pauli-string Hamiltonians. Returns the minimum energy configuration plus a per-site entanglement entropy map.

Pauli Hamiltonian (recommended)

Pass a dictionary of Pauli-string → coefficient entries. Each key is an N-character string over {I, X, Y, Z}, one character per site.

# H2 molecule — STO-3G, Jordan-Wigner mapping (2 sites)
result = client.hamiltonian.run(
    pauli_hamiltonian={
        "II": -1.8572750,   # constant / nuclear repulsion
        "ZI": -0.3979374,
        "IZ": -0.3979374,
        "ZZ":  0.3980202,
        "XX":  0.1809270,
        "YY":  0.1809270,
    },
)
print(result.energy)       # ground-state energy in Hartree
print(result.entropy_list) # per-site entanglement entropy

Ising / Heisenberg J-matrix

import numpy as np

N = 16
J = np.random.randn(N, N)
J = (J + J.T) / 2  # symmetrize
np.fill_diagonal(J, 0)

result = client.hamiltonian.run(interaction_matrix=J.tolist())
print(result.energy)   # ground-state energy
print(result.states)   # per-site spin expectation values
print(result.max_S)    # max bipartite entanglement entropy

SpinGroundStateResult fields

SDK — Hamiltonian Time Evolution (TEBD)

The client.evolve sub-client provides Hamiltonian time evolution via TEBD (Time-Evolving Block Decimation) and exact state preparation. Six endpoints are available:

Real-time evolution

# 10-site transverse-field Ising model, critical point J=h=1
result = client.evolve.run(
    n_qubits=10,
    hamiltonian={"preset": "ising_1d", "J": 1.0, "h": 1.0},
    t_max=2.0,
    dt=0.1,
    bond_dim=64,
    observables=["entropy", "magnetization", "qfi"],
    initial_state="ferromagnet",
    order=2,
)

for pt in result.trajectory:
    print(pt["t"], pt.get("max_entropy"), pt.get("f_Q_density"))

Ground state preparation (imaginary time)

gs = client.evolve.ground(
    n_qubits=10,
    hamiltonian={"preset": "ising_1d", "J": 1.0, "h": 1.0},
    bond_dim=64,
)
print(gs.energy)        # ground-state energy
print(gs.bond_entropy)  # per-bond von Neumann entropy

QKZM Kibble-Zurek quench

qkzm = client.evolve.qkzm(
    n_qubits=20, J=1.0, h0=5.0, h_f=0.2, t_ramp=5.0,
)
print(qkzm.kzm_defect_density)   # n_d ∝ τ_Q^{−1/2}
print(qkzm.kzm_prediction)

Hamiltonian presets

Custom Pauli-sum Hamiltonians are also supported via terms: each term is {"sites": [i, j], "operator": "ZZ", "strength": -1.0}.

SDK — AKLT Valence Bond Solid

The AKLT model (Affleck-Kennedy-Lieb-Tasaki, 1987) is a spin-1 chain with an exactly-known ground state called the Valence Bond Solid (VBS). It is the prototypical example of a symmetry-protected topological (SPT) phase — the Haldane phase — and a universal resource for measurement-based quantum computation (MBQC).

Signature observables

MPS bond entanglement regime labels

phase_labels is a list of per-bond entanglement regime identifiers, derived from the von Neumann entropy S of each MPS bond's Schmidt decomposition. These labels are standard quantum-information terminology and apply to all TEBD endpoints.

Exact VBS state preparation

# Prepare exact AKLT VBS for 10 spin-1 sites (20 qubits), no TEBD needed
vbs = client.evolve.aklt(
    n_sites=10,
    observables=["entropy", "string_order", "qfi"],
    string_order_pairs=[[0, 9], [1, 8], [2, 7]],
)

print(vbs.max_bond_dim)         # 2 — exact χ=2 MPS
print(vbs.mean_bond_entropy)    # ≈ 0.50 bits (inter-site=1.0, intra-site=0.0)
print(vbs.phase_labels[1])        # "topological_class" (inter-site bonds, S=1 bit — SPT/Haldane regime)
print(vbs.string_order)         # {"O_string(0,9)": -0.250, ...}

Ground state via imaginary-time TEBD

# Use "aklt" preset: n_qubits = 2 × n_sites
# initial_state="neel" is required — the default |0…0⟩ is a fixed point
gs = client.evolve.ground(
    n_qubits=20,
    hamiltonian={"preset": "aklt", "J_AF": 1.0, "J_FM": 2.0},
    initial_state="neel",
    dtau=0.05,
    n_steps=400,
    bond_dim=4,
)
print(gs.energy)       # converges to AKLT ground energy
print(gs.converged)    # True

Real-time dynamics

dyn = client.evolve.run(
    n_qubits=20,
    hamiltonian={"preset": "aklt"},
    t_max=5.0,
    dt=0.05,
    observables=["entropy", "magnetization"],
)

AKLT Hamiltonian — technical details

Each spin-1 site is encoded in 2 qubits: qubit 2i is the left virtual spin-1/2 and qubit 2i+1 is the right virtual spin-1/2. The Hamiltonian contains only nearest-neighbour qubit interactions, fully compatible with the TEBD engine:

Photonics

Compute hafnian and permanent amplitudes for Gaussian boson sampling (GBS) circuits. Input is a symmetric coupling matrix A of dimension 2m×2m for an m-mode GBS device. Results are computed in arbitrary-precision arithmetic (configurable via mp_dps, default 34 decimal digits) and verified against double-precision references to below 5×10⁻¹⁵ relative error. An 8-mode hafnian completes in 39 ms; 12-mode in 43 ms.

⎯⎯ Explore Photonics notebooks ›

SDK — Photonic Amplitudes

Compute the hafnian, permanent, or Gaussian boson sampling amplitudes from a symmetric coupling matrix. The result is a complex number computed to configurable precision.

import numpy as np

n = 8
A = np.random.randn(n, n)
A = (A + A.T) / 2
np.fill_diagonal(A, 0)

result = client.hafnian.run(matrix_real=A.tolist())

print(result.value)    # complex: haf_real + 1j*haf_imag
print(result.elapsed)  # server compute time in seconds

Complex matrices and precision

# Complex coupling matrix, 50 decimal digits of precision
result = client.hafnian.run(
    matrix_real=A_real.tolist(),
    matrix_imag=A_imag.tolist(),
    mp_dps=50,   # default: 34
)

HafnianResult fields

SDK — Notebook Execution

Submit a Jupyter notebook (.ipynb) for remote execution. The notebook runs in an isolated sandbox environment with qumulator-sdk and the full scientific Python stack pre-installed.

# Submit and wait for completion
with open("my_experiment.ipynb", "rb") as f:
    nb_bytes = f.read()

status = client.notebook.run(nb_bytes)
print(status.status)   # "completed"
# status.result contains the executed notebook with outputs

Async: submit then poll

import time

with open("my_experiment.ipynb", "rb") as f:
    job_id = client.notebook.submit(f.read())

print("Job submitted:", job_id)

while True:
    status = client.notebook.status(job_id)
    if status.is_done:
        break
    time.sleep(3)

if status.ok:
    executed_notebook = status.result
else:
    print("Failed:", status.error)

Quantum Simulation Notebooks

Gate-level circuit simulation, benchmarks against real quantum hardware, and algorithm demonstrations.

Molecular Chemistry Notebooks

Ab-initio ground state energies, orbital visualisation, and DMRG solvers for real molecules.

Condensed Matter Notebooks

Many-body physics: topological phases, non-Abelian anyons, Floquet dynamics, and holographic protocols.

Photonics Notebooks

Gaussian boson sampling, hafnian amplitudes, and photonic quantum advantage.

Miscellaneous Notebooks

Quantum computing applied to everyday problems — no physics background required.

REST API — API Keys

Create a key

No authentication required.

# Response 201
{
  "key":        "qum_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name":       "my-key",
  "created_at": "2026-04-20T12:00:00Z"
}

REST API — Circuits

Submit a circuit

Returns job_id immediately. Simulation runs asynchronously.

# Submit via cURL
curl -X POST https://api.qumulator.com/circuits \
  -H "X-API-Key: qum_..." \
  -H "Content-Type: application/json" \
  -d '{
    "qasm": "OPENQASM 3.0; include \"stdgates.inc\"; qubit[2] q; h q[0]; cx q[0],q[1]; bit[2] c; measure q->c;",
    "shots": 1024,
    "mode": "statevector"
  }'

# Response 202
{ "job_id": "01HX8M7PVKTA..." }

List recent circuits

Returns the most recent circuit jobs for your API key.

Get a circuit job

REST API — Jobs & Polling

All simulation endpoints return a job_id immediately. Poll until status is "completed" or "failed".

# Poll a job
curl https://api.qumulator.com/circuits/01HX8M7PVKTA \
  -H "X-API-Key: qum_..."

# While running
{ "job_id": "01HX...", "status": "running", "result": null }

# When complete
{
  "job_id":            "01HX...",
  "status":            "completed",
  "entanglement_dof":  3.8124,
  "dof_converged":     true,
  "result": {
    "counts":      { "00": 512, "11": 512 },
    "n_qubits":    2,
    "shots":       1024,
    "entropy_map": [1.0, 1.0]
  }
}

Reference — Result Types

CircuitResult

GaussianCertificate

JobStatus

Reference — Simulation Limits

Circuit depth, not qubit count, determines memory. Requests exceeding a tier limit return HTTP 422 with a self-documenting error message.

Reference — Rate Limits

The Retry-After header tells you exactly how many seconds to wait. The SDK surfaces this as QumulatorHTTPError(status_code=429).

from qumulator import QumulatorHTTPError
import time

try:
    result = eng.run(shots=1024)
except QumulatorHTTPError as e:
    if e.status_code == 429:
        retry_after = int(e.response.headers.get("Retry-After", 10))
        time.sleep(retry_after)
        result = eng.run(shots=1024)   # retry once

Reference — Errors

All error responses use the shape {"detail": "...message..."}.

# Example 422 response (circuit exceeds tier limit)
{
  "detail": "Limit Exceeded: 30 qubits at depth 15. Tier 2 (21-54 q) max depth is 9.
  Tiers: T1(1-20q,d≤20) T2(21-54q,d≤9) T3(55-105q,d≤8) T4(106-1000q,d≤7)"
}