Metadata-Version: 2.4
Name: qsim-sdk
Version: 0.1.0
Summary: Run quantum circuits on CPU, GPU, or real hardware with a certified error estimate on every result
Author-email: ZKSF <info@zksf.org>
License: MIT
Project-URL: Homepage, https://zksf.org
Project-URL: Documentation, https://zksf.org/docs
Project-URL: Console, https://app.zksf.org
Keywords: quantum,quantum computing,simulator,qiskit,tensor network,clifford,QPU
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24
Requires-Dist: qiskit>=1.0

# qsim-sdk

Python SDK for [ZKSF](https://zksf.org) (Zero Kelvin Simulation Foundry): run quantum
circuits on CPU, GPU, or real quantum hardware, and get a certified error estimate on
every approximate result.

```bash
pip install qsim-sdk
```

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

## Three lines to run a circuit

```python
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"])       # the outcome histogram
print(job["result"]["error_info"])   # how much to trust it
```

## Estimate before you spend

```python
est = client.estimate(qc, shots=1000)
# {'engine': 'clifford', 'predicted_seconds': 0.05,
#  'predicted_cost_usd': 0.000001, 'reason': '...'}
```

`estimate()` is free and instant: it tells you which engine will run the circuit,
roughly how long it will take, and what it will cost, before anything is charged.

## Choose an engine explicitly

By default the router picks the cheapest adequate simulator (`clifford` for Clifford
circuits, `exact.cpu` for small ones, `mps.quimb.cpu` for structured larger ones).
GPU and real hardware are opt-in:

```python
client.run(qc, engine="exact.gpu")     # CUDA statevector
client.run(qc, engine="qpu.rigetti")   # real Rigetti hardware (billed at provider cost)
```

Hardware jobs may sit in the device queue for minutes to hours; `run()` polls until the
result attaches. Use `submit()` + `job()` for a non-blocking flow:

```python
job_id = client.submit(qc, shots=1000, engine="qpu.rigetti")
job = client.job(job_id)               # poll whenever you like
```

## Error handling

`run()` raises instead of returning a bad result silently:

- `qsim_sdk.JobRejected` — the circuit is intractable or infeasible for the request
  (the message says why, and what would make it work)
- `qsim_sdk.JobFailed` — an engine or hardware-provider error

## Links

- Docs: <https://zksf.org/docs>
- Console: <https://app.zksf.org>
- Contact: info@zksf.org
