Quickstart

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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

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_...",
)

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="exact",
    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 "auto" lets the server select the optimal backend for your circuit.

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

# compressed mode for a large variational circuit
backend = QumulatorBackend(client, mode="compressed")
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)

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.klt.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.klt.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

KLTResult fields

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 — 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)    # e.g. -5.88 eV
print(result.lumo_E_eV)    # e.g. -1.40 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 — 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)

REST API — API Keys

Create a key

No authentication required.

# Response 201
{
  "key":        "qum_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "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",
  "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 6.
  Tiers: T1(1-20q,d≤20) T2(21-54q,d≤6) T3(55-105q,d≤5) T4(106-1000q,d≤3)"
}