Quantum circuit portability is less about finding one universal file format and more about choosing the right exchange boundary. This guide gives you a reusable checklist for saving, sharing, and moving circuits between Qiskit, Cirq, PennyLane, simulators, and hardware workflows while preserving the behavior and metadata that matter.
Overview
A quantum circuit contains more than a list of gates. Its meaning can depend on qubit and classical-bit layout, parameter expressions, measurement placement, custom definitions, execution options, and the target backend. A circuit that imports successfully may still produce different results if one of those details is lost or interpreted differently.
Use OpenQASM when you need a text-based interchange format and the circuit uses operations supported by the chosen OpenQASM version and importer. Use QPY when you need a compact, Qiskit-oriented serialization that preserves more Qiskit-specific circuit structure. Use JSON-style data when you control both sides of a narrowly defined workflow and want an explicit schema. Use a framework-native format when portability is not the priority and faithful restoration inside one SDK matters most.
No format should be treated as a complete record of an experiment by default. Keep the serialized circuit alongside a manifest containing the SDK name and version, format version, target backend, transpilation settings, parameter values, shot count, measurement mapping, random seeds where applicable, and the date of export. This makes later validation possible when tools change.
| Format | Best use | Parameters and measurements | Custom gates and metadata | Portability and security notes |
|---|---|---|---|---|
| OpenQASM 2 | Simple gate-and-measurement exchange across tools that support its grammar | Parameters and expressions are more limited than in many SDKs; measurements are represented explicitly | Some custom operations can be declared, but importer support and definitions must be checked | Readable and easy to review; validate input and avoid executing untrusted content without controls |
| OpenQASM 3 | Richer language features and newer exchange workflows | Better support for typed values, expressions, control flow, and classical behavior, subject to tool support | Definitions and metadata may not survive conversion consistently | Potentially more expressive, but cross-SDK support is uneven; confirm the exact supported subset |
| QPY | Saving and restoring Qiskit circuit objects | Designed to preserve Qiskit circuit details and parameter objects within compatible Qiskit workflows | Can retain Qiskit-specific structure better than a general interchange format | Not a universal cross-SDK format; treat files as serialized data and use trusted readers and version testing |
| JSON-style representation | Internal APIs, audit records, or a deliberately small interchange schema | Whatever your schema defines; parameter names, values, and measurement maps must be specified explicitly | Possible to preserve custom data, but only if every consumer implements the same schema | Portable in principle, but schema drift and unsafe deserialization are major risks |
| Framework-native format | Reproducible work inside one SDK or application | Usually strongest for that framework's objects and conventions | Often preserves native gates, transforms, and metadata best | Lowest portability; pin versions and document dependencies before sharing |
Checklist by scenario
1. Sharing a circuit with a collaborator
- Choose OpenQASM for a tool-neutral exchange only after listing the gates, measurements, parameters, and classical operations that the recipient needs.
- Include the original source code or a human-readable gate listing alongside the exported file.
- Record qubit order, classical-bit order, endianness assumptions, and the meaning of every measured bit.
- Include a small reference test: expected counts, probabilities, or expectation values for a known simulator configuration.
- Send metadata separately when the format cannot reliably preserve it, including experiment name, purpose, parameter values, and execution settings.
2. Moving from one SDK to another
- Reduce the circuit to a common gate set before export where practical. Replace unsupported high-level operations with explicit decompositions.
- Decide whether symbolic parameters should remain symbolic. If the receiving SDK cannot represent the same expressions, export a parameter manifest or concrete values.
- Check whether measurements are terminal, mid-circuit, conditional, or grouped. These behaviors are not interchangeable.
- Import into the target SDK, print or inspect the resulting circuit, and compare operation order, qubit indices, and measurement mapping.
- Run both versions with the same logical inputs and compare results using an appropriate tolerance rather than expecting identical raw shot counts.
3. Moving from a simulator to hardware
- Preserve the logical circuit as a baseline; do not treat a hardware-transpiled circuit as the only source artifact.
- Transpile or compile for the selected target only after confirming supported gates, connectivity, measurement behavior, and timing constraints.
- Record the target, optimization settings, layout, routing choices, shots, and any mitigation or calibration options.
- Compare the pre-transpilation simulator result with the post-transpilation result before interpreting hardware noise.
- Keep backend results separate from the portable circuit. A circuit file alone does not reproduce device conditions.
4. Building an automated conversion pipeline
- Define a canonical internal representation, such as an operation list with explicit qubit indices and parameter expressions.
- Make exporters and importers report unsupported gates, dropped metadata, altered measurements, and unresolved parameters instead of silently continuing.
- Use versioned schemas and fixtures containing empty circuits, single-qubit gates, entangling gates, measurements, parameters, custom gates, and unsupported operations.
- Validate every conversion with structural checks and statistical checks. A successful parse is not proof of semantic equivalence.
What to double-check
Gate semantics: Similar names do not guarantee identical definitions or parameter conventions. Confirm rotation signs, angle units, control ordering, and matrix conventions when translating operations.
Qubit and bit ordering: A reversed bit string can make an unchanged circuit appear incorrect. Write down the mapping from logical qubits to physical or serialized positions and test a basis-state circuit that exposes ordering errors.
Parameters: Check parameter names, binding order, symbolic expressions, default values, and whether a parameter was accidentally converted to a fixed number during export. For batched execution, verify that the target SDK applies values to the intended gates.
Measurements: Confirm whether measurements are destructive, whether mid-circuit measurements are supported, how classical registers are grouped, and how results are formatted. For expectation-value workflows, confirm the observable and measurement grouping rather than comparing counts alone. See how to read quantum measurement results for a practical review of counts, probabilities, and expectation values.
Custom operations: A custom gate may require its definition, decomposition, matrix, or calibrated implementation. If the target only receives the gate name, it may reject the circuit or interpret it incorrectly. Export a standard decomposition when portability is more important than preserving the custom abstraction.
Metadata: Circuit labels, register names, annotations, scheduling information, calibration references, and provider-specific options are commonly the first details lost. Store them in a separate manifest with a clear relationship to the circuit file.
Security: Treat circuit files as untrusted input when they come from outside your team. Validate size, schema, operations, parameter ranges, and resource requirements. Prefer safe parsing libraries, avoid arbitrary code execution during deserialization, and run conversion jobs with restricted permissions when appropriate.
Common mistakes
- Assuming a file extension guarantees compatibility. OpenQASM support differs by language version and importer. Confirm the supported grammar and operation subset on both sides.
- Using QPY as a universal interchange format. QPY is useful for Qiskit-centered workflows, but it is not a general replacement for OpenQASM or a documented cross-SDK schema.
- Comparing only circuit diagrams. Two diagrams can look similar while differing in register ordering, parameter bindings, or measurement semantics.
- Ignoring transpilation. Hardware execution changes the gate sequence, depth, layout, and sometimes measurement behavior. Save both the logical and compiled forms.
- Expecting identical shot counts. Equivalent circuits can produce different finite-sample counts. Compare distributions, expectation values, or defined statistical criteria with a fixed test setup.
- Failing silently on unsupported features. A converter that drops a barrier, condition, custom gate, or metadata field without a warning creates a reproducibility problem.
- Overloading JSON with undocumented assumptions. A flexible schema is useful only when types, ordering, units, versioning, and required fields are explicit.
For a broader validation process, pair portability tests with the assertions and statistical checks described in how to test quantum programs. If the destination is real hardware, also review Qiskit transpilation and your backend selection checklist.
When to revisit
Review this portability checklist whenever you upgrade Qiskit, Cirq, PennyLane, an OpenQASM parser, or a provider integration. A release can change accepted syntax, importer behavior, parameter handling, gate definitions, or serialization APIs even when your source code appears unchanged. Re-run conversion fixtures after a major SDK upgrade and record the result in your project documentation.
Revisit the workflow before migrating providers, sharing a circuit outside your team, moving from simulation to hardware, introducing a custom gate, or changing how measurements and parameters are represented. It is also worth reviewing before seasonal planning cycles if your team regularly selects tools, refreshes developer environments, or audits reproducibility.
Use this final action list:
- Choose the exchange format based on the required portability, not convenience alone.
- Export the circuit and a separate, versioned metadata manifest.
- Inspect gates, parameters, measurements, ordering, and custom definitions after import.
- Run structural and statistical equivalence tests on a simulator.
- Compile for hardware only after the logical circuit passes validation.
- Record every conversion, warning, dropped field, tool version, and execution setting.
This process keeps a quantum circuit understandable when tools change. It also gives collaborators a practical way to distinguish a file that merely opens from one that still represents the experiment they intended to run.