Moving a quantum circuit between OpenQASM, Qiskit, Cirq, and PennyLane is less like translating source code line by line and more like preserving a mathematical contract. This guide gives you a reusable workflow for converting circuits, checking qubit order and measurements, and proving that the translated version still behaves as intended.
Overview
A circuit can appear identical in two SDKs while producing different results because of changes in wire order, bit order, parameter interpretation, measurement placement, or compiler behavior. Portability therefore has two separate goals:
- Structural portability: the target circuit contains equivalent operations in an equivalent order.
- Behavioral portability: the target circuit produces the same state, unitary action, expectation values, or sampled distribution under the same assumptions.
Use the second goal as the acceptance criterion. Gate names alone are not enough. For example, an H gate followed by a CNOT may be structurally recognizable across frameworks, but a reversed control-target relationship changes the circuit. A measurement label such as 01 may also refer to a different physical assignment depending on the SDK.
Portability matrix
| Representation | Strength | Important checks | Typical limitation |
|---|---|---|---|
| OpenQASM 2 | Compact interchange for common gate and measurement circuits | Register names, classical-bit order, supported gates, custom definitions | Less expressive for newer control flow and richer program structure |
| OpenQASM 3 | More expressive circuit and program representation | Version support, timing, declarations, control flow, compiler coverage | Not every SDK or backend supports the same feature subset |
| Qiskit | Explicit circuit objects, transpilation, and OpenQASM interoperability | Qubit and classical-bit indexing, measurement mapping, transpiler changes | Export/import behavior depends on the circuit features and installed version |
| Cirq | Moment-oriented circuits with explicit qubit objects | Qubit identity, operation moments, measurement keys, simulator ordering | Some imported concepts need redesign rather than a direct syntax conversion |
| PennyLane | Device-independent quantum functions and differentiable parameters | Wire labels, operation availability, shot settings, gradients, measurements | A PennyLane tape or quantum function may not map directly to a static interchange file |
Treat interchange formats as a boundary, not a guarantee. A circuit that uses only standard gates, fixed parameters, and explicit measurements is usually easier to move than one relying on dynamic control flow, device-specific instructions, custom decompositions, mid-circuit measurement, or framework-specific differentiation.
Checklist by scenario
Qiskit to OpenQASM
- Record the circuit’s qubit count, classical-bit count, register names, and measurement map before export.
- Confirm whether the target format is OpenQASM 2 or OpenQASM 3. Do not assume that a file reader supporting one version supports the other.
- Inspect the exported text for gate definitions, barriers, resets, measurements, and unsupported instructions.
- Reload the file into an independent parser or target SDK and compare the circuit before running it on hardware.
OpenQASM to Cirq
- Create an explicit mapping from QASM qubit references to Cirq qubit objects. Keep this mapping in the conversion code rather than relying on visual position.
- Translate each operation in source order. For controlled gates, write down the control and target separately.
- Map classical measurement targets to stable measurement keys. A key is not necessarily the same thing as a QASM classical register.
- Compare statevector or unitary output on a simulator before comparing sampled results.
Qiskit to PennyLane
- Choose a wire convention and preserve it explicitly. For example, define whether source qubit index 0 maps to PennyLane wire 0 or to a reversed wire order.
- Separate circuit construction from measurement. PennyLane measurements may be probabilities, samples, expectation values, or a state, and those outputs are not interchangeable.
- Mark trainable parameters separately from fixed constants. A numeric angle and a differentiable parameter can produce the same gate while participating differently in optimization.
- Check whether every operation is supported by the selected device or must be decomposed into a supported gate set.
OpenQASM 2 to OpenQASM 3
Preserve the logical circuit first, then decide whether to use newer language features. Keep register declarations, gate definitions, measurement targets, and parameter units explicit. If the destination workflow only needs a static circuit, avoid adding control flow or timing constructs merely because the newer format permits them. A smaller common subset is often easier to validate.
When no direct converter is reliable
Use an intermediate, framework-neutral description: a list of operations, ordered wire identifiers, symbolic parameters, and measurement instructions. This is often safer than chaining several automatic converters. Generate the target circuit from that description and retain the original as a test fixture.
What to double-check
Qubit and bit ordering
Write down the meaning of every position in a statevector, unitary matrix, bitstring, and histogram key. Do not infer ordering from a single simple experiment. Test a basis state such as one with only a chosen qubit set to 1, then apply a gate that makes the distinction visible. Repeat the test for measurement output.
Gate definitions and parameter conventions
Compare matrices or decompositions for parameterized gates rather than matching names only. Confirm angle units, sign conventions, global phase expectations, and whether a controlled operation uses the same control-target order. Global phase does not change measurement probabilities, but it can matter when comparing full statevectors or composing circuits.
Measurements and shots
Use the same number of shots, random seed policy where available, basis rotations, and post-processing rules. A sampled histogram will not be identical on every run; compare distributions with an appropriate tolerance. For debugging, first compare exact statevectors or expectation values on a simulator, then compare samples.
Parameters and execution timing
Check whether a parameter is bound before execution, bound at submission time, or left symbolic. Verify parameter order when binding a vector of values. Also distinguish a circuit’s abstract depth from the depth after decomposition or transpilation. The translated circuit can be behaviorally equivalent while having different resource requirements. For a deeper review, use the quantum circuit resource estimation checklist.
Controlled operations and unsupported instructions
Ask whether a control is a quantum control, a classical condition, or a framework-level execution feature. These are not interchangeable. Replace unsupported operations with a documented decomposition and test that decomposition independently.
Common mistakes
- Trusting visual similarity: diagrams can hide reversed wires, omitted barriers, or changed measurement destinations.
- Comparing only one output: matching the all-zero result does not establish equivalence. Use basis-state tests, random parameter tests, and edge cases.
- Ignoring compiler transformations: optimization may alter gate count and layout while preserving the intended operation. Compare before and after compilation separately.
- Mixing logical and physical qubits: hardware mapping can insert swaps or change labels. Validate the logical circuit before interpreting hardware-level output.
- Assuming OpenQASM is lossless: export may omit framework metadata, gradient information, device settings, custom observables, or execution-specific behavior.
- Using sampled results to diagnose every issue: shot noise can conceal a deterministic translation error. Begin with exact or high-precision simulator comparisons.
- Failing to record versions and assumptions: save the source SDK version, target SDK version, interchange format version, gate set, wire map, and test tolerances with the converted circuit.
Keep a small portability test suite in the repository. Include an empty circuit, single-qubit gates, a controlled gate, a parameterized rotation, an entangling circuit, and a circuit with measurements on nonconsecutive wires. The suite becomes a practical guardrail during SDK upgrades.
When to revisit
Review a portability layer whenever you change an SDK, compiler, simulator, backend, interchange format, or circuit-generation dependency. Re-run the suite before migrating a project, reproducing a paper in another framework, or moving from simulation to hardware. A six-month compatibility review is also a sensible maintenance interval, even when the application has not changed.
At each review, check current import and export support, parameter binding behavior, measurement ordering, controlled-operation handling, and compiler decompositions. Record known incompatibilities in the project documentation instead of relying on tribal knowledge. If a workflow uses QML or variational algorithms, repeat tests for gradients and expectation values as well as final samples; the PennyLane quantum machine learning tutorial provides useful context for hybrid execution patterns.
Final action checklist: freeze a reference circuit, document wire and bit order, choose the smallest common gate set, convert through one controlled path, compare unitary or statevector behavior, compare sampled measurements, inspect compiled depth, and store the conversion assumptions beside the code. If all checks pass, portability is demonstrated rather than presumed.