Skip to main content

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 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.
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)

Source distribution for qio 0.2.11
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)

Table of built distributions (wheels) for qio 0.2.11
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.2.11 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page