Metadata-Version: 2.4
Name: dyber
Version: 0.2.0
Summary: Dyber SDK: interact with the H-cat photonic quantum computer (simulator now, QPU later)
Author: Dyber, Inc.
License: Apache-2.0
Project-URL: Homepage, https://quantaforge.dyber.org
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Provides-Extra: physics
Requires-Dist: dyberforge; extra == "physics"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Dyber SDK

Interact with the H-cat photonic quantum computer. Write a circuit once and run it on the
local simulator today and on the H-cat QPU later, with no change to your code. This is the
control interface, designed so that when the hardware exists, only the backend transport
changes.

## 30-second quickstart

```bash
pip install dyber
```

```python
from dyber import Dyber, Circuit
c = Circuit(2, "bell")
c.h(0); c.cx(0, 1); c.measure_all()
job = Dyber().backend("local_simulator").run(c, shots=1000)
print(job.result().counts())        # {'00': ~500, '11': ~500}
```

Five lines, a Bell state. Qubit 0 is the leftmost bit in result strings.

## Three access modes

Same circuits, same job protocol, pick the surface that fits your workflow.

### 1. Python SDK

```python
from dyber import Dyber, Circuit

dy = Dyber()
print(dy.backends())                 # local_simulator (online), hcat_qpu (offline)

c = Circuit(2, "bell")
c.h(0); c.cx(0, 1); c.measure_all()

res = dy.backend("local_simulator").run(c, shots=1000, loss_per_cycle=0.005).result()
print(res.counts())                  # measurement counts
print(res.resources)                 # code distance, cats per logical, hw modes per logical
print(res.noise)                     # physics-informed noise summary
```

### 2. Command line

The `dyber` command ships with the package (or use `python -m dyber.cli`):

```bash
dyber run bell.qasm --shots 1000     # run an OpenQASM file on the simulator
dyber run bell.qasm --json           # machine-readable output for scripts
dyber backends                       # list backends and their status
dyber examples                       # bundled example circuits to get started
dyber serve                          # start the reference control plane (REST API)
dyber version
```

### 3. REST API

Start the reference control plane and submit jobs over HTTP. This is the exact protocol
the hardware control system will implement, documented in [PROTOCOL.md](PROTOCOL.md).

```bash
dyber serve      # listens on http://127.0.0.1:8787
```

```bash
curl -s -X POST http://127.0.0.1:8787/jobs \
  -H "Content-Type: application/json" \
  -d '{"qasm": "OPENQASM 3.0; qubit[2] q; h q[0]; cx q[0], q[1];", "shots": 1000}'
```

Then `GET /jobs/{id}/result` returns counts plus the resource and noise reports. Jobs can
also be submitted as circuit JSON (`{"program": {...}}`, see PROTOCOL.md). The `hcat_qpu`
backend speaks this same protocol to the production control plane; the moment the hardware
is online, `dy.backend("hcat_qpu").run(c)` runs on silicon.

## Bring your own language

Dyber deliberately has no proprietary circuit language. Circuits come in and out through
open formats and the tools you already use:

- **OpenQASM 3 import and export**: `dyber.qasm.loads(text)` and `dyber.qasm.dumps(circuit)`.
  OpenQASM 2 programs are accepted on import.
- **Qiskit adapter**: `dyber.interop.from_qiskit(qc)` and `to_qiskit(circuit)` convert
  to and from a Qiskit `QuantumCircuit`.
- **Cirq adapter**: `dyber.interop.from_cirq(circuit)` and `to_cirq(circuit)` convert
  to and from a Cirq `Circuit`.

If your circuit already exists somewhere, it runs here. The adapters are duck-typed:
neither Qiskit nor Cirq is a dependency of this package.

## Examples

| Example | What it shows |
|---|---|
| `examples/run_local.py` | fault-tolerant vs NISQ runs on the local simulator, resource and noise reports |
| `examples/run_remote.py` | the same circuit over the network via the reference control plane |
| `dyber examples` | bundled circuits runnable straight from the command line |

## What the simulator is (and is not)

The `local_simulator` backend is an exact statevector simulator for up to 14 qubits, with
physics-informed noise calibrated by the published H-cat resource model (June 2026
circuit-level validation: corrected loss threshold 0.79 percent per cycle, spec operating
point 0.5 percent per cycle). Noise is a planning-grade estimate, applied as logical error
rates and heralded-erasure fractions from that model; it is not a full physical simulation
of the hardware. At or above the loss threshold the resource report honestly returns the
above-threshold regime (no fault-tolerant distance) with a NISQ fallback estimate. The
`hcat_qpu` backend points at the production control plane and is not yet available;
until then, everything you write against the simulator carries over unchanged.

## How it is layered

| Layer | Module | Role |
|---|---|---|
| Circuit | `circuit.py` | gate-model program you write |
| Formats | `qasm.py`, `interop.py` | OpenQASM 3 in/out, Qiskit and Cirq adapters |
| Simulator | `simulator.py` | exact statevector run plus physics-informed noise |
| Backends | `backend.py` | local simulator, remote (HTTP), and hcat_qpu, one interface |
| Protocol | `protocol.py` | the JSON job format shared by SDK and control plane, see [PROTOCOL.md](PROTOCOL.md) |
| Control plane | `server.py` | reference server: runs the simulator today, fronts the hardware control system later |
| CLI | `cli.py` | the `dyber` command: run, serve, examples, backends, version |

## Development

```bash
pip install -e .[dev]        # from sdk/
python -m pytest tests -q
```

Proprietary components (the OpenForge compiler passes and calibration) are not part of
this SDK; the native lowering here is illustrative. License: Apache-2.0.
