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