Metadata-Version: 2.4
Name: qio
Version: 0.2.9
Summary: Common quantum computing objects description and conversion library
License: Apache-2.0
Project-URL: Repository, https://github.com/QuantumCommons/qio
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: dataclasses-json
Requires-Dist: openqasm3[parser]>=0.4.0
Requires-Dist: pyqasm<1.1.0,>=0.5.0
Dynamic: license-file

<p align="center"><img width="50%" src="docs/logo.png" /></p>

# qio
`qio` is a python package to smoothly manipulate quantum computing objects between client and server.

It handle all the conversion boilerplate to focus your dev on your quantum SDK and backend on real matters.

## Installation

We encourage installing `qio` via the pip tool (a Python package manager):

```bash
pip install qio
```

## Getting started

To leverage `qio` and get quick interoperability between your frontend and your backend, you simply need to use qio wrappers system.

Here a snippet code for `cirq` and `qsim`:

```python
import cirq

from cirq.circuits import Circuit
from qsimcirq import QSimSimulator

from qio.core import (
    QuantumComputationModel,
    QuantumComputationParameters,
    QuantumProgramResult,
    QuantumProgram,
)

#############
# Client side

qc = _random_cirq_circuit(10)
shots = 100

program = QuantumProgram.from_cirq_circuit(qc)

model_json = QuantumComputationModel(
    programs=[program],
).to_json_str()

parameters_json = QuantumComputationParameters(
    shots=shots,
).to_json_str()

# Send this to server side

###########################
# Server / Computation side

model = QuantumComputationModel.from_json_str(model_json)
params = QuantumComputationParameters.from_json_str(parameters_json)

circuit = model.programs[0].to_cirq_circuit()

qsim_simulator = QSimSimulator()

qsim_result = qsim_simulator.run(circuit, repetitions=params.shots)

program_result = QuantumProgramResult.from_cirq_result(qsim_result).to_json_str()

# Send this to back to client side

#####################
# Back to client side

client_result = QuantumProgramResult.from_json_str(program_result)

cirq_result = client_result.to_cirq_result()

qiskit_result = client_result.to_qiskit_result()
```

## Conversion losses & unsupported features

[`LOSS_REPORT.md`](LOSS_REPORT.md) details every conversion loss across all SDK
edges (per edge: expected value, actual value, explanation), the unsupported
conversions that must raise, feature coverage, and result conventions. It is
generated from the conversion test batteries (`make -C tests report`, or
`report-observed` to include per-run observed/expected values) and is
auto-refreshed in CI on every merge to `main`.

## qio circuit conversion mapping

Map of the SDKs integrated in `qio` and the conversion links between them
(**circuits** branch / `QuantumProgram` — *results* conversions are not
represented here).

- **Conversion flow**: an SDK node is translated into a serialization format
  (OpenQASM, QIR, Cirq JSON), then reloaded by another SDK.
- The converters are located in `qio/utils/conversion/program/`.
- `Perceval JSON` and `Pulser Sequence JSON` are **closed self-round-trips**:
  their converters only map the native SDK <-> the format (no other SDK reads
  them).
- **QIR**: `cirq` / `qiskit` / `cudaq` (and the `qasm3_to_qir` converter) emit QIR
  LLVM IR *text*; `qir_to_cudaq` reads it back into a CUDA-Q kernel (the `QIR_V1`
  reader, exposed through `QuantumProgram.to_cudaq_kernel()`). The reader covers
  the *straight-line* subset of both the thin profile (`cirq`/`qiskit`/`qasm3`
  producers' constant-pointer operands) and the CUDA-Q profile
  (`qubit_allocate_array` + SSA loads + `generalizedInvoke` controlled gates);
  richer QIR (computed SSA angles, multi-control gates, mid-circuit control
  flow) raises `QirToCudaqError`.
- **OpenQASM version normalization**: `qasm2_to_qasm3` / `qasm3_to_qasm2`
  re-express a QASM program in the other version; `QuantumProgram` exposes it
  through `to_qasm2_circuit()` (down-converts a QASM3 program) and
  `to_qasm3_circuit()` (up-converts a QASM2 program). It also backs two more
  SDK legs: CUDA-Q writes OpenQASM 3 via `cudaq_to_qasm3` (its QASM2 output
  up-normalized) and MIMIQ reads OpenQASM 3 **text** via `qasm3_to_mimiq`
  (down-normalized to QASM2, then `qasm2_to_mimiq`). The normalization only
  covers **straight-line** programs and does not decompose gates beyond the
  `u1`/`cu1` ↔ `p`/`cp` rename: classical control flow
  (`if`/`for`/`while`/`switch` blocks) is not handled, `gphase` is silently
  dropped on the QASM3→QASM2 leg, and other stdlib gates
  (`u2`/`u3`/`cu`/`cu2`/`cu3`) are not mapped. The circuit-conversion test
  battery surfaces these inherent limits as declared loss categories
  (`qasm_control_flow`, `qasm_gphase`, `qasm_stdlib_gate`) in its
  [loss report](LOSS_REPORT.md).

```mermaid

flowchart LR

    subgraph IN["Input SDKs (write to format)"]
        direction TB
        CIRQ_IN["Cirq<br/>(cirq.Circuit)"]
        QISKIT_IN["Qiskit<br/>(qiskit.QuantumCircuit)"]
        CUDAQ_IN["CUDA Quantum<br/>(cudaq.Kernel)"]
        MIMIQ_IN["MIMIQ<br/>(mimiqcircuits.Circuit)"]
        PULSER_IN["Pulser<br/>(pulser.Sequence)"]
        PERCEVAL_IN["Perceval<br/>(perceval.Circuit / perceval.Experiment)"]
    end

    subgraph SER["Serialization format"]
        direction TB
        QASM1["OpenQASM 1"]
        QASM2["OpenQASM 2"]
        QASM3["OpenQASM 3"]
        QIR["QIR"]
        CIRQJSON["Cirq JSON"]
        PULSERJSON["Pulser JSON"]
        PERCEVALJSON["Perceval JSON"]
    end

    subgraph OUT["Output SDKs (read from format)"]
        direction TB
        CIRQ_OUT["Cirq<br/>(cirq.Circuit)"]
        QISKIT_OUT["Qiskit<br/>(qiskit.QuantumCircuit)"]
        CUDAQ_OUT["CUDA Quantum<br/>(cudaq.Kernel)"]
        MIMIQ_OUT["MIMIQ<br/>(mimiqcircuits.Circuit)"]
        PULSER_OUT["PULSER<br/>(pulser.Sequence)"]
        PERCEVAL_OUT["Perceval<br/>(perceval.Circuit / perceval.Experiment)"]
    end

    CIRQ_IN -->|cirq_to_cirqjson| CIRQJSON
    CIRQ_IN -->|cirq_to_qasm2| QASM2
    CIRQ_IN -->|cirq_to_qasm3| QASM3
    CIRQ_IN -->|cirq_to_qir| QIR
    QISKIT_IN -->|qiskit_to_qasm2| QASM2
    QISKIT_IN -->|qiskit_to_qasm3| QASM3
    QISKIT_IN -->|qiskit_to_qir| QIR
    CUDAQ_IN -->|cudaq_to_qasm2| QASM2
    CUDAQ_IN -->|"cudaq_to_qasm3 (via qasm2_to_qasm3)"| QASM3
    CUDAQ_IN -->|cudaq_to_qir| QIR
    MIMIQ_IN -->|mimiq_to_qasm2| QASM2
    PULSER_IN -->|pulser_to_pulserjson| PULSERJSON
    PERCEVAL_IN -->|perceval_to_percevaljson| PERCEVALJSON

    CIRQJSON -->|cirqjson_to_cirq| CIRQ_OUT
    PULSERJSON -->|pulserjson_to_pulser| PULSER_OUT
    PERCEVALJSON -->|percevaljson_to_perceval| PERCEVAL_OUT
    QASM1 -->|qasm1_to_cirq| CIRQ_OUT
    QASM2 -->|qasm2_to_cirq| CIRQ_OUT
    QASM3 -->|qasm3_to_cirq| CIRQ_OUT
    QASM1 -->|qasm1_to_qiskit| QISKIT_OUT
    QASM2 -->|qasm2_to_qiskit| QISKIT_OUT
    QASM3 -->|qasm3_to_qiskit| QISKIT_OUT
    QASM2 -->|qasm2_to_cudaq - via qasm3_to_cudaq| CUDAQ_OUT
    QASM3 -->|qasm3_to_cudaq| CUDAQ_OUT
    QIR -->|qir_to_cudaq| CUDAQ_OUT
    QASM2 -->|qasm2_to_mimiq| MIMIQ_OUT
    QASM3 -->|"qasm3_to_mimiq (via qasm3_to_qasm2)"| MIMIQ_OUT

    QASM2 -.->|qasm2_to_qasm3| QASM3
    QASM3 -.->|qasm3_to_qasm2| QASM2



    classDef sdk fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#00344f,font-weight:bold,rx:20px,ry:20px;
    classDef fmt fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#062b07,font-weight:bold,rx:20px,ry:20px;
    classDef decl fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,stroke-dasharray: 5 5,color:#2a0a4a,font-weight:bold,rx:20px,ry:20px;

    class CIRQ_IN,QISKIT_IN,CUDAQ_IN,PULSER_IN,MIMIQ_IN,PERCEVAL_IN,CIRQ_OUT,QISKIT_OUT,CUDAQ_OUT,MIMIQ_OUT,PULSER_OUT,PERCEVAL_OUT sdk;
    class QASM1,QASM2,QASM3,QIR,CIRQJSON,PULSERJSON,PERCEVALJSON fmt;
```

### Entrypoints in `qio`

| Source SDK | Write method | Supported output formats |
|---|---|---|
| Cirq | `QuantumProgram.from_cirq_circuit` | Cirq JSON, OpenQASM 2, OpenQASM 3, QIR |
| Qiskit | `QuantumProgram.from_qiskit_circuit` | OpenQASM 2, OpenQASM 3, QIR |
| CUDA Quantum | `QuantumProgram.from_cudaq_kernel` | OpenQASM 2, OpenQASM 3, QIR |
| MIMIQ | `QuantumProgram.from_mimiq_circuit` | OpenQASM 2 |
| Pulser | `QuantumProgram.from_pulser_sequence` | Pulser JSON |
| Perceval | `QuantumProgram.from_perceval_circuit` | Perceval JSON |
| Perceval | `QuantumProgram.from_perceval_experiment` | Perceval Experiment JSON |

| Target SDK | Read method | Supported input formats |
|---|---|---|
| Cirq | `QuantumProgram.to_cirq_circuit` | OpenQASM 1/2/3, Cirq JSON |
| Qiskit | `QuantumProgram.to_qiskit_circuit` | OpenQASM 1/2/3 |
| CUDA Quantum | `QuantumProgram.to_cudaq_kernel` | OpenQASM 2/3, QIR |
| MIMIQ | `QuantumProgram.to_mimiq_circuit` | OpenQASM 2, OpenQASM 3 |
| Pulser | `QuantumProgram.to_pulser_sequence` | Pulser JSON |
| Perceval | `QuantumProgram.to_perceval_circuit` | Perceval JSON |
| Perceval | `QuantumProgram.to_perceval_experiment` | Perceval Experiment JSON |

## qio result conversion mapping

Map of the SDKs integrated in `qio` and the conversion links between them
(**results** branch / `QuantumProgramResult`).

- **Conversion flow**: an SDK result is serialized into a dedicated JSON format
  (`*_RESULT_JSON_V1`), then reloaded by an SDK (its own or another one).
- Unlike circuits, there is **no shared format** (no QASM): each SDK has its own
  JSON format, and cross conversions directly link one JSON format to another
  SDK.
- The converters are located in `qio/utils/conversion/program_result/`.

```mermaid

flowchart LR

    subgraph IN["Input SDKs (write to format)"]
        direction TB
        CIRQ_IN["Cirq<br/>(cirq.Result)"]
        QISKIT_IN["Qiskit<br/>(qiskit.result.Result)"]
        CUDAQ_IN["CUDA Quantum<br/>(cudaq.SampleResult)"]
        MIMIQ_IN["MIMIQ<br/>(mimiqcircuits.QCSResults)"]
        PULSER_IN["Pulser<br/>(pulser.backend.Results)"]
        PERCEVAL_IN["Perceval<br/>(pcvl.SVDistribution / pcvl.BSCount </br> pcvl.BSDistribution / pcvl.BSSamples)"]
    end

    subgraph SER["Result serialization format"]
        direction TB
        CIRQJSON["Cirq result JSON<br/>(CIRQ_RESULT_JSON_V1)"]
        QISKITJSON["Qiskit result JSON<br/>(QISKIT_RESULT_JSON_V1)"]
        CUDAQJSON["CUDA Quantum sample JSON<br/>(CUDAQ_SAMPLE_RESULT_JSON_V1)"]
        MIMIQJSON["MIMIQ QCSR JSON<br/>(MIMIQ_QCSR_JSON_V1)"]
        PULSERJSON["Pulser Result JSON<br/>(PULSER_RESULT_JSON_V1)"]
        PERCEVALJSON["Perceval Result JSON<br/>(PERCEVAL_RESULT_JSON_V1)"]
    end

    subgraph OUT["Output SDKs (read from format)"]
        direction TB
        CIRQ_OUT["Cirq<br/>(cirq.Result)"]
        QISKIT_OUT["Qiskit<br/>(qiskit.result.Result)"]
        CUDAQ_OUT["CUDA Quantum<br/>(cudaq.SampleResult)"]
        MIMIQ_OUT["MIMIQ<br/>(mimiqcircuits.QCSResults)"]
        PULSER_OUT["Pulser<br/>(pulser.backend.Results)"]
        PERCEVAL_OUT["Perceval<br/>(pcvl.SVDistribution / pcvl.BSCount </br> pcvl.BSDistribution / pcvl.BSSamples)"]
    end

    CIRQ_IN -->|cirq_to_dict| CIRQJSON
    QISKIT_IN -->|qiskit_to_dict| QISKITJSON
    CUDAQ_IN -->|cudaq_sample_to_dict| CUDAQJSON
    MIMIQ_IN -->|mimiq_to_dict| MIMIQJSON
    PULSER_IN -->|pulser_to_dict| PULSERJSON
    PERCEVAL_IN -->|perceval_to_dict| PERCEVALJSON

    CIRQJSON -->|dict_to_cirq| CIRQ_OUT
    QISKITJSON -->|dict_to_qiskit| QISKIT_OUT
    CUDAQJSON -->|dict_to_cudaq_sample| CUDAQ_OUT
    MIMIQJSON -->|dict_to_mimiq| MIMIQ_OUT
    PULSERJSON -->|dict_to_pulser| PULSER_OUT
    PERCEVALJSON -->|dict_to_perceval| PERCEVAL_OUT

    CIRQJSON -->|cirq_to_qiskit| QISKIT_OUT
    CIRQJSON -->|cirq_to_mimiq| MIMIQ_OUT
    QISKITJSON -->|qiskit_to_cirq| CIRQ_OUT
    QISKITJSON -->|qiskit_to_mimiq| MIMIQ_OUT
    CUDAQJSON -->|cudaq_sample_to_qiskit| QISKIT_OUT
    MIMIQJSON -->|mimiq_to_qiskit| QISKIT_OUT
    MIMIQJSON -->|mimiq_to_cirq| CIRQ_OUT

    classDef sdk fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#00344f,font-weight:bold,rx:20px,ry:20px;
    classDef fmt fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#062b07,font-weight:bold,rx:20px,ry:20px;

    class CIRQ_IN,QISKIT_IN,CUDAQ_IN,MIMIQ_IN,PULSER_IN,PERCEVAL_IN,CIRQ_OUT,QISKIT_OUT,CUDAQ_OUT,MIMIQ_OUT,PULSER_OUT,PERCEVAL_OUT sdk;
    class CIRQJSON,QISKITJSON,CUDAQJSON,MIMIQJSON,PULSERJSON,PERCEVALJSON fmt;
```

### Entrypoints in `qio`

| Source SDK | Write method | Output format |
|---|---|---|
| Cirq | `QuantumProgramResult.from_cirq_result` | `CIRQ_RESULT_JSON_V1` |
| Qiskit | `QuantumProgramResult.from_qiskit_result` | `QISKIT_RESULT_JSON_V1` |
| CUDA Quantum | `QuantumProgramResult.from_cudaq_sample_result` | `CUDAQ_SAMPLE_RESULT_JSON_V1` |
| MIMIQ | `QuantumProgramResult.from_mimiq_qcsr` | `MIMIQ_QCSR_JSON_V1` |
| PULSER | `QuantumProgramResult.from_pulser_result` | `PULSER_RESULT_JSON_V1` |
| PERCEVAL | `QuantumProgramResult.from_perceval_result` | `PERCEVAL_RESULT_JSON_V1` |

| Target SDK | Read method | Supported input formats |
|---|---|---|
| Cirq | `QuantumProgramResult.to_cirq_result` | `CIRQ_RESULT_JSON_V1`, `QISKIT_RESULT_JSON_V1`, `MIMIQ_QCSR_JSON_V1` |
| Qiskit | `QuantumProgramResult.to_qiskit_result` | `QISKIT_RESULT_JSON_V1`, `CIRQ_RESULT_JSON_V1`, `CUDAQ_SAMPLE_RESULT_JSON_V1`, `MIMIQ_QCSR_JSON_V1` |
| CUDA Quantum | `QuantumProgramResult.to_cudaq_sample_result` | `CUDAQ_SAMPLE_RESULT_JSON_V1` |
| MIMIQ | `QuantumProgramResult.to_mimiq_qcsr` | `MIMIQ_QCSR_JSON_V1`, `CIRQ_RESULT_JSON_V1`, `QISKIT_RESULT_JSON_V1` |
| PULSER | `QuantumProgramResult.to_pulser_result` | `PULSER_RESULT_JSON_V1` |
| PERCEVAL | `QuantumProgramResult.to_perceval_result` | `PERCEVAL_RESULT_JSON_V1` |
