qsim-sdk 0.1.0__tar.gz

qsim_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+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

qsim_sdk-0.1.0/README.md

@@ -0,0 +1,75 @@
+# 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

qsim_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "qsim-sdk"
+version = "0.1.0"
+description = "Run quantum circuits on CPU, GPU, or real hardware with a certified error estimate on every result"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "ZKSF", email = "info@zksf.org" }]
+keywords = ["quantum", "quantum computing", "simulator", "qiskit", "tensor network", "clifford", "QPU"]
+dependencies = ["httpx>=0.24", "qiskit>=1.0"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+
+[project.urls]
+Homepage = "https://zksf.org"
+Documentation = "https://zksf.org/docs"
+Console = "https://app.zksf.org"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["qsim_sdk*"]

qsim_sdk-0.1.0/qsim_sdk/__init__.py

@@ -0,0 +1,88 @@
+"""qsim SDK — three lines to run a circuit:
+
+    import qsim_sdk
+    client = qsim_sdk.Client("http://localhost:8000")
+    result = client.run(qiskit_circuit)
+
+    result["result"]["counts"]        # outcomes
+    result["result"]["error_info"]    # how much to trust them  <- the point
+"""
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+from qiskit import QuantumCircuit, qasm2
+
+
+class JobRejected(RuntimeError):
+    pass
+
+
+class JobFailed(RuntimeError):
+    pass
+
+
+DEFAULT_BASE_URL = "https://api.zksf.org"
+
+
+class Client:
+    def __init__(self, base_url: str = DEFAULT_BASE_URL, token: str | None = None):
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+        self._http = httpx.Client(base_url=base_url, headers=headers, timeout=600.0)
+
+    def estimate(self, circuit: QuantumCircuit, shots: int = 1024) -> dict[str, Any]:
+        """Free pre-run check: engine, predicted runtime and cost, or why not."""
+        resp = self._http.post(
+            "/estimate", json={"qasm2": qasm2.dumps(circuit), "shots": shots}
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def submit(
+        self,
+        circuit: QuantumCircuit,
+        shots: int = 1024,
+        engine: str | None = None,
+        **params: Any,
+    ) -> str:
+        resp = self._http.post(
+            "/jobs",
+            json={
+                "qasm2": qasm2.dumps(circuit),
+                "shots": shots,
+                "engine": engine,
+                "params": params,
+            },
+        )
+        resp.raise_for_status()
+        return resp.json()["id"]
+
+    def job(self, job_id: str) -> dict[str, Any]:
+        resp = self._http.get(f"/jobs/{job_id}")
+        resp.raise_for_status()
+        return resp.json()
+
+    def run(
+        self,
+        circuit: QuantumCircuit,
+        shots: int = 1024,
+        engine: str | None = None,
+        poll_seconds: float = 0.2,
+        timeout: float = 600.0,
+        **params: Any,
+    ) -> dict[str, Any]:
+        """Submit and wait. Raises JobRejected/JobFailed with the honest reason."""
+        job_id = self.submit(circuit, shots=shots, engine=engine, **params)
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            job = self.job(job_id)
+            if job["status"] == "done":
+                return job
+            if job["status"] == "rejected":
+                raise JobRejected(job["reason"])
+            if job["status"] == "error":
+                raise JobFailed(job["error"])
+            time.sleep(poll_seconds)
+        raise TimeoutError(f"job {job_id} still running after {timeout}s")

qsim_sdk-0.1.0/qsim_sdk.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+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

qsim_sdk-0.1.0/qsim_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+qsim_sdk/__init__.py
+qsim_sdk.egg-info/PKG-INFO
+qsim_sdk.egg-info/SOURCES.txt
+qsim_sdk.egg-info/dependency_links.txt
+qsim_sdk.egg-info/requires.txt
+qsim_sdk.egg-info/top_level.txt

qsim_sdk-0.1.0/qsim_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

qsim_sdk-0.1.0/qsim_sdk.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx>=0.24
+qiskit>=1.0

qsim_sdk-0.1.0/qsim_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+qsim_sdk

qsim_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+