Metadata-Version: 2.4
Name: dyber
Version: 0.2.1
Summary: Dyber SDK: gate-model circuits, OpenQASM 3 and Qiskit/Cirq interop, and a local statevector simulator with an illustrative H-cat resource model
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

Write gate-model quantum circuits in Python, OpenQASM 3, Qiskit or Cirq, and run them on an
exact local statevector simulator or on any server that speaks the Dyber job protocol. The
resource report and the optional noise come from an illustrative H-cat resource model (see
"What the simulator is (and is not)"). No H-cat hardware exists, and the `hcat_qpu`
backend is not available.

## 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 (not available)

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)                 # model values (illustrative), not a hardware operating point
print(res.noise)                     # illustrative 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. The protocol is 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 model resource report and noise
summary. Jobs can also be submitted as circuit JSON (`{"program": {...}}`, see PROTOCOL.md).
The `hcat_qpu` backend is not available.

## 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` | the illustrative resource model's fault-tolerant, NISQ and above-threshold regimes on the local simulator, with resource and noise reports (model values) |
| `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. Noise
is off unless you pass `loss_per_cycle`; with it, the simulator applies illustrative noise
taken from the SDK's resource report. The resource report (code distance, cats per logical
qubit, hardware modes) is always returned; without `loss_per_cycle` it uses 0.005.

Model value: abstract circuit model with assumed loss heralds. Not a hardware operating
point. The model's thresholds (0.79 percent per cycle by default, 0.898 percent
uncorrected) and distances describe the model only. At or above the model threshold the
report returns the above-threshold regime with a NISQ estimate. No H-cat hardware exists
or has been measured, and the `hcat_qpu` backend is not available.

The native summary in each result is an illustrative count of H-cat operations. In the
H-cat encoding (J. Lee et al., PRX Quantum 5, 030322 (2024)), both logical states carry
even cats. The logical Z value is read from the single photon, the logical X value from
the photon's H/V outcome times the cat photon count mod 4, and cat photon-number parity
only flags photon loss.

## 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 optional illustrative noise |
| Backends | `backend.py` | local simulator, remote (HTTP), and the hcat_qpu placeholder (not available), 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 jobs on the local simulator |
| CLI | `cli.py` | the `dyber` command: run, serve, examples, backends, version |

## Development

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

The native lowering here is illustrative: a count of H-cat operations, not a compiler.
License: Apache-2.0.

## Changelog

### 0.2.1
- Labeling and documentation release, with the output changes listed below.
  Resource-report thresholds, distances and cat counts are labeled as model values
  (abstract circuit model with assumed loss heralds, not a hardware operating point); the
  simulator's optional noise is described as illustrative; the H-cat readout is described
  as in the published encoding; the `hcat_qpu` backend is described as not available.
- The resource report and the noise summary carry a `basis` field with that label. The
  above-threshold `note` now ends its label with "not a hardware operating point".
- Breaking for code that reads `native['parity_measurements']`: use `native['readouts']`.
  The native summary key `parity_measurements` is renamed `readouts` (the op
  `measure_parity` is now `hybrid_readout`).
- The `GET /` descriptor's `backend` field is now `local_simulator`.
- `hcat_qpu` no longer probes the network: `dyber backends` and `Dyber().backends()`
  always report it as not available (no H-cat hardware exists), and running a job on it
  raises `ConnectionError`. An unreachable remote URL now gets a message that does not
  mention `hcat_qpu`.
- No change to circuits, OpenQASM, interop, simulator sampling, the numbers the model
  returns, or the job request format (protocol 1.0).

### 0.2.0
- OpenQASM 3 import and export, Qiskit and Cirq adapters, the `dyber` CLI, a REST API that
  accepts OpenQASM, examples and a test suite.
