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]"

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. There are no qubits and no gates: 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.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.

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.