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):
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:
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 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 JSONandPulser Sequence JSONare closed self-round-trips: their converters only map the native SDK <-> the format (no other SDK reads them).- QIR:
cirq/qiskit/cudaq(and theqasm3_to_qirconverter) emit QIR LLVM IR text;qir_to_cudaqreads it back into a CUDA-Q kernel (theQIR_V1reader, exposed throughQuantumProgram.to_cudaq_kernel()). The reader covers the straight-line subset of both the thin profile (cirq/qiskit/qasm3producers' constant-pointer operands) and the CUDA-Q profile (qubit_allocate_array+ SSA loads +generalizedInvokecontrolled gates); richer QIR (computed SSA angles, multi-control gates, mid-circuit control flow) raisesQirToCudaqError. - OpenQASM version normalization:
qasm2_to_qasm3/qasm3_to_qasm2re-express a QASM program in the other version;QuantumProgramexposes it throughto_qasm2_circuit()(down-converts a QASM3 program) andto_qasm3_circuit()(up-converts a QASM2 program). It also backs two more SDK legs: CUDA-Q writes OpenQASM 3 viacudaq_to_qasm3(its QASM2 output up-normalized) and MIMIQ reads OpenQASM 3 text viaqasm3_to_mimiq(down-normalized to QASM2, thenqasm2_to_mimiq). The normalization only covers straight-line programs and does not decompose gates beyond theu1/cu1↔p/cprename: classical control flow (if/for/while/switchblocks) is not handled,gphaseis 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.
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/.
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 |
Metadata
Release files for qio 0.2.11
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| qio-0.2.11.tar.gz | 57.3 kB | Without provenance | Details for qio-0.2.11.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| qio-0.2.11-py3-none-any.whl | Python 3 | none | any | Details for qio-0.2.11-py3-none-any.whl |
Total release size: 156.5 kB
Release files / qio-0.2.11.tar.gz
| Download URL | qio-0.2.11.tar.gz |
|---|---|
| Size | 57.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
84743de2df583d5fb91d06d6e548a0196b0edfd06ad493a5e67bd1205f8bb1fa
|
|
BLAKE2b-256 checksum How to use checksums |
fe40eab0def850b8164b456ed1f0a244add992452909c285e04d141bed0fa5ae
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Release files / qio-0.2.11-py3-none-any.whl
| Download URL | qio-0.2.11-py3-none-any.whl |
|---|---|
| Size | 99.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a3ffedf468fa1f540261ddf6db02ac3f1512a29dc42d5194038a48e3e3a8fc18
|
|
BLAKE2b-256 checksum How to use checksums |
2ac0d57799a7ccf619b4e27711581d662d0dd9adf9a418fc31ac155ef76c9834
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.25
|
Security for qio 0.2.11
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.