qsim-sdk

Official Python client for ZKSF (Zero Kelvin Simulation Foundry): a cloud service that executes quantum circuits on classical simulators, GPU accelerators, or real quantum processors, and attaches a documented accuracy statement to every approximate result.

• Website: https://zksf.org
• Console: https://app.zksf.org
• Documentation: https://zksf.org/docs
• API root: https://api.zksf.org

1. Motivation

Classical simulation of quantum circuits is exact only in a narrow regime. Exact statevector methods terminate near 30 to 32 qubits because state size grows as 2^n. Beyond that, every practical method is approximate: tensor networks truncate the bond dimension, Pauli propagation truncates operator weight, and real hardware substitutes device noise for the ideal distribution.

An approximate result without an error statement is not a measurement, it is an assertion. The purpose of this service, and of the certification protocols documented in docs/CERTIFICATION.md, is to return a quantity alongside each result that states how far it may be from the truth, and to make that quantity independently checkable by a third party.

2. Scope of this repository

This repository contains the client library only. It is a thin HTTP wrapper of roughly 120 lines: authentication, circuit serialisation to OpenQASM 2, four endpoint calls, and a polling loop.

The simulation engines, the router, and the certification computation execute server-side and are not open source. The client is published so that users can read exactly what is transmitted before supplying an API token.

3. Installation

pip install qsim-sdk

Requires Python 3.10 or newer. Dependencies are httpx and qiskit.

To submit circuits written in Cirq, PennyLane, pyQuil, or Amazon Braket, install the optional transpiler extra, which routes them through qBraid into Qiskit:

pip install "qsim-sdk[multiframework]"

To use a quantum program as a differentiable PyTorch layer (qsim_sdk.ml), install the ml extra. torch is not a dependency of the base package, because most users of this client never train anything and it is a large install:

pip install "qsim-sdk[ml]"

Obtain an API token from the console at https://app.zksf.org (sign in, then "Copy API token").

4. Quick start

The notebook above runs in the browser with nothing installed. Its first half needs no account and spends nothing: it reads four real, already-completed certified runs from the public API, covering exact simulation, an approximate run with a measured bound, a 192-qubit Pauli propagation result, and a Bell state executed on IonQ Forte-1 hardware. The second half runs new jobs against your own token.

Six algorithm tutorials follow the same pattern, one per notebook: build the circuit, then read the certificate for the run that produced the published result. See examples/ for all seven, or jump straight in: GHZ and Bell states · Grover · QAOA MaxCut · VQE H2 · Bernstein-Vazirani · Teleportation

import qsim_sdk
from qiskit import QuantumCircuit

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

client = qsim_sdk.Client(token="YOUR_TOKEN")
job = client.run(qc, shots=1000)

print(job["result"]["counts"])      # outcome histogram
print(job["result"]["error_info"])  # accuracy statement for this run

Further examples are in examples/.

5. API surface

Client(base_url="https://api.zksf.org", token=None). The base URL is overridable for self-hosted or staging deployments.

5.0 Neutral-atom sequences

One engine does not take a circuit. Neutral-atom hardware is programmed as a register of atoms and a schedule of laser pulses, which has no gate decomposition, so it takes a Pulser sequence through its own call. Routing does not apply either: there are no circuit features to inspect, so these jobs name their engine.

from pulser import Pulse, Register, Sequence
from pulser.devices import AnalogDevice

reg = Register.square(2, spacing=6.0).with_automatic_layout(AnalogDevice)
seq = Sequence(reg, AnalogDevice)
seq.declare_channel("ising", "rydberg_global")
seq.add(Pulse.ConstantPulse(1000, 6.0, 0.0, 0.0), "ising")

job = client.run_sequence(seq, shots=1000)
print(job["result"]["counts"])      # a bit reads 1 when that atom ended in Rydberg

Pulser is not a dependency of this package. If you do not have it installed, pass the sequence's abstract representation as a JSON string instead. There is no estimate() counterpart: the cost model reads gate-circuit features that a pulse schedule lacks.

5.0.1 Photonic linear optics

Nor does photonic hardware take a circuit in the gate sense. Quandela sells Belenos as a 12-qubit machine (MosaiQ 12), and dual-rail encoding does spend two of its 24 modes on each qubit, but the interface exposed here is the optics underneath: there are no gates, and photons enter chosen modes, interfere through beamsplitters and phase shifters, and the answer is which modes they leave by. A program is therefore two things, a Perceval circuit and the input photons, because unlike a gate circuit it does not carry its own initial state. Both are hashed, so two runs that differ only in where the photons entered cannot share a certificate.

import perceval as pcvl
from perceval.components import BS, PERM

# Hong-Ou-Mandel: two photons meet on a balanced beamsplitter
circuit = pcvl.Circuit(3) // (1, PERM([1, 0])) // (0, BS.H())

job = client.run_photonic(circuit, [1, 0, 1], shots=1000)
print(job["result"]["counts"])      # {'|2,0,0>': 492, '|0,2,0>': 508}

Indistinguishable photons must bunch: both leave by the same mode, and the coincidence term |1,0,1> is zero. That makes the coincidence fraction a direct fidelity measure, which is what a photonic certificate reports.

The input state accepts an occupation list as above, a perceval.BasicState, or either one already serialised. Perceval is not a dependency of this package, and the list form needs it only for the circuit. Pass engine="qpu.quandela.belenos" to run on real hardware, which accepts photons only on its connected input modes and refuses anything else before submission rather than after you have paid. As with sequences there is no estimate() counterpart yet.

5.0.2 Parameter sweeps and training loops

A single submission is rarely the workload. A variational solver, a quantum kernel or a photonic generative model is one parameterised program evaluated hundreds or thousands of times while an optimiser walks its parameters. Sent one job at a time that is thousands of round trips and thousands of queue entries, so the whole step goes as one job instead.

Gate circuits send one bound circuit per point, because OpenQASM 2 cannot express a free parameter. Pulser sequences and Perceval circuits can, so they send the program once and a list of bindings, applied server-side. Each bound point hashes to its own value, so a certificate still identifies exactly which parameters produced it.

import numpy, perceval as pcvl

circuit = pcvl.Circuit(2) // (0, pcvl.BS(theta=pcvl.P("theta")))
job = client.run_parametric_sweep(
    circuit,
    [{"theta": t} for t in numpy.linspace(0, numpy.pi, 40)],
    input_state=[1, 1],
    engine="photonic.slos.cpu",
)
job["results"][7]["result"]["counts"]      # the run for bindings[7]

The same call takes a Pulser sequence, whose variables come from seq.declare_variable(...). Sweeps run on simulation engines: each provider task is queued and billed individually, so batching to a QPU would hide the per-task cost behind one job id rather than save anything. Settle the sweep in simulation, then send the surviving point to the machine.

As a torch layer. qsim_sdk.ml wraps either kind as an nn.Module, so a quantum program becomes a differentiable layer in an ordinary PyTorch model. The forward pass is one job; the backward pass is one job carrying two points per parameter.

from qsim_sdk.ml import PhotonicLayer          # pip install qsim-sdk[ml]

layer = PhotonicLayer(client, circuit, [1, 1], shots=4000)
opt = torch.optim.SGD(layer.parameters(), lr=0.3)
for step in range(200):
    opt.zero_grad()
    criterion(layer(), target).backward()      # layer() = probability per outcome
    opt.step()

Gradients are central differences, not the parameter-shift rule: the shift rule is exact only where an output is a sinusoid of the parameter, which is true of a Pauli rotation and false of a beamsplitter angle or a pulse amplitude. Shot noise sets the floor on how small a gradient you can resolve, so an optimiser that stalls at low shot counts is usually reading noise rather than a flat landscape.

5.1 Cost control

estimate() is free, instant, and returns the engine that would be selected, the predicted wall-clock seconds, the predicted cost in USD, and the reason for that selection. Calling it before run() is the recommended pattern for any circuit whose cost is not already known.

5.2 Failure semantics

The client raises rather than returning a result that cannot be trusted:

Rejection is deliberate. A circuit that would return an inconclusive answer is refused with a diagnostic rather than executed and reported with a meaningless error bar.

5.3 Non-blocking submission

Hardware jobs may wait in a provider queue for minutes to hours. run() polls until the result attaches. For long-running hardware work, separate the two phases:

job_id = client.submit(qc, shots=1000, engine="qpu.rigetti")
job = client.job(job_id)  # poll at your convenience

6. Engines

A rule-based router selects the cheapest engine adequate for the submitted circuit. No language model or learned policy participates in engine selection or in simulation. Selection can be overridden with the engine argument.

Two MPS implementations are maintained deliberately. Agreement between independent implementations of the same approximation is evidence that neither carries an implementation-specific error, which is a different question from whether the approximation itself is tight.

Refer to https://zksf.org/docs for current qubit ceilings, which are deployment configuration rather than properties of the methods.

7. Certification

Two protocols are defined. Both are described in full, with worked figures, in docs/CERTIFICATION.md.

ZCC-v0.1 covers exact.cpu, exact.gpu, clifford, mps.quimb.cpu, mps.aer.cpu, and pauli.cpu. It does not cover noisy.cpu, for the reason given in section 8.

Every job may be exported as a signed certificate carrying a stable identifier. The certificate is retrievable without authentication, so a reader who was not party to the original run can check it:

GET https://api.zksf.org/certify/<cert_id>       # HTML verification page
GET https://api.zksf.org/certify/<cert_id>/pdf   # PDF

8. Limitations

Stated explicitly, because a certification claim is only as credible as its declared boundaries:

1. A ZCC-v0.1 bound quantifies the error introduced by the approximation used in that specific run. It does not bound error arising from an incorrectly specified circuit, nor from finite sampling, which is reported separately as shot noise.
2. Rigorous single-run bounds are available on the quimb MPS engine. Other engines report a convergence-based accuracy statement, which is diagnostic rather than a proof.
3. Noise-preview runs are not certifiable. The noisy.cpu engine simulates a device noise model, so its output deliberately approximates a noisy machine rather than the ideal distribution. There is no ideal reference for a bound to be taken against, and no certificate is issued for these runs.
4. A ZHF-v0.1 fidelity is a measurement of one hardware run against a reference distribution. It characterises that execution on that device at that time. It does not predict the fidelity of a subsequent run.
5. Direct verification requires an obtainable reference distribution, which constrains the circuit sizes for which ZHF-v0.1 can be evaluated in its direct mode.
6. Protocol versions are pinned in the identifier (v0.1). Version numbers below 1.0 indicate that the specifications are not yet frozen.
7. Parameter sweeps run on simulation engines only. Hardware is refused rather than silently fanned out: each provider task is queued and billed individually, so a "batch" to a QPU would hide the per-task cost behind one job id. Training loops against real hardware are driven from your own code, one submission per evaluation.
8. qsim_sdk.ml gradients are central differences, not the parameter-shift rule. The shift rule is exact only where an output is a sinusoid of the parameter, which holds for a Pauli rotation and not for a beamsplitter angle or a pulse amplitude. The estimate therefore carries a step-size error as well as shot noise.

9. Citation

If this service or its certification protocols contribute to published work, please cite the protocol note. Machine-readable metadata is in CITATION.cff.

10. Contributing and security

• Contribution guidance: CONTRIBUTING.md
• Vulnerability disclosure: SECURITY.md. Please do not open a public issue for a security report.

11. License

MIT. See LICENSE.