How to Port Quantum Circuits Between Qiskit, Cirq, PennyLane and Amazon Braket — Checklist & Migration Template
quantum SDKmigration checklistgate mappingtranspilationbackend compatibilityquantum developer tools

How to Port Quantum Circuits Between Qiskit, Cirq, PennyLane and Amazon Braket — Checklist & Migration Template

QQubit Daily Editorial Team
2026-11-11
8 min read

Use this practical checklist to port circuits and hybrid workflows between Qiskit, Cirq, PennyLane, and Amazon Braket without hidden semantic errors.

Moving a quantum circuit between Qiskit, Cirq, PennyLane, and Amazon Braket is more than translating gate names. This checklist helps you preserve qubit order, measurements, parameter behavior, transpilation assumptions, noise tests, and optimizer workflows while giving you a repeatable migration template for future SDK or backend changes.

Overview

A quantum program usually contains several layers that can be lost during a migration:

  • Algorithm logic: the mathematical sequence of operations, such as an oracle, variational ansatz, or phase-estimation component.
  • Circuit representation: qubit indexes, registers, controls, parameters, barriers, mid-circuit measurements, and classical conditions.
  • Execution behavior: shots, measurement formatting, result aggregation, seeding, batching, and device selection.
  • Hardware adaptation: supported gates, coupling or connectivity constraints, native operations, pulse assumptions, and transpiler settings.
  • Classical workflow: gradients, optimizers, parameter binding, callbacks, checkpoints, and stopping criteria.

Qiskit, Cirq, PennyLane, and Amazon Braket can all express common circuit patterns, but they do not present them through identical objects or execution interfaces. A safe port therefore starts with a framework-neutral specification instead of copying lines of code one by one.

Before changing SDKs, document the source environment. Record the SDK and plugin versions, Python version, simulator or hardware target, number of shots, random-seed policy, measurement convention, and any transpilation or compilation options. Keep this record beside the migrated implementation so a later failure can be traced to a code change, a compiler change, or a backend change.

For background, see this Qiskit, Cirq, and PennyLane comparison, then use the quantum circuit resource estimation guide to capture the original circuit’s qubit count, gate count, depth, and shot requirements.

Checklist by scenario

Scenario 1: Porting a gate-based circuit

  1. Freeze the specification. Write down the number of logical qubits, register names, initial state, gate sequence, parameters, measurement bases, and expected outputs.
  2. Define the qubit-order convention. State whether the first logical qubit maps to the lowest or highest bit in displayed bitstrings. Do not assume two SDKs use the same presentation order.
  3. Build a gate mapping table. Map each source operation to a target operation, including argument order, control-target order, parameter units, and whether the operation is natively supported.
  4. Separate logical gates from compilation. First reproduce the logical circuit on a simulator. Only then add routing, decomposition, optimization, or hardware-specific compilation.
  5. Compare distributions, not just one sample. Run enough shots to compare counts or probabilities under the same state-preparation and measurement assumptions.

A useful starting table looks like this:

Logical operationTypical naming issueMigration check
HadamardOften represented as HConfirm the target operation acts on the intended qubit.
Pauli X, Y, ZUsually consistent, but object names differCheck matrix convention and qubit index.
Controlled-XMay appear as CX or CNOTVerify control and target order.
Controlled-ZMay use CZ or a controlled operation wrapperConfirm both qubits and any decomposition.
Rotation gatesRX, RY, and RZ may use different parameter objectsCheck angle units, symbolic binding, and sign conventions.
MeasurementMeasurement APIs and result keys varyConfirm basis, classical destination, and bitstring order.

Scenario 2: Moving a variational or hybrid model

A PennyLane-to-Braket example, or a Qiskit-to-PennyLane migration, often involves more than a circuit. The model may include data encoding, trainable parameters, a gradient method, an optimizer, and a device wrapper. Port these components separately.

  1. Run the circuit with fixed numerical parameters and fixed input data.
  2. Compare the scalar expectation values or probability vectors before introducing an optimizer.
  3. Test parameter binding independently from the circuit definition.
  4. Compare gradients using a small, known parameter set. If analytic differentiation is not available or behaves differently, use a clearly documented numerical reference.
  5. Recreate the optimizer only after the forward pass and gradient behavior agree.
  6. Compare loss values, parameter updates, convergence criteria, and checkpoint formats on the same small dataset.

For data-encoding workflows, preserve the feature scaling and angle convention as carefully as the gates. A circuit can be structurally identical while producing different results if one implementation normalizes features, wraps angles, or orders input features differently. The quantum machine learning data-encoding guide is a useful companion for this stage.

Scenario 3: Moving to a cloud backend or real device

  1. Choose the target backend only after the logical circuit passes simulator tests.
  2. Check the backend’s accepted operations, maximum circuit dimensions, measurement capabilities, connectivity, and execution restrictions in its current documentation.
  3. Record the compilation or transpilation settings used for the target.
  4. Inspect the compiled circuit rather than treating compilation as a black box.
  5. Run a small calibration or smoke-test circuit before submitting the full workload.
  6. Compare hardware results with a noise-aware simulation where practical, while recognizing that a simulator is an approximation of device behavior.

Use the transpilation and optimization guide for a deeper hardware workflow, and review quantum hardware metrics before treating a backend comparison as an algorithm comparison.

Scenario 4: Migrating a test suite or teaching project

Small canonical circuits are better migration tests than a single large application circuit. Use these five cases:

  1. Basis-state test: prepare a computational-basis state and verify measurement labels and bit order.
  2. Superposition test: apply a Hadamard to one qubit and compare the expected probability structure.
  3. Entanglement test: create a two-qubit correlated state and verify joint outcomes, not independent marginal counts.
  4. Parameterized rotation test: bind several angles, including zero and a negative value, and compare expectation values.
  5. Measurement test: measure selected qubits or observables and confirm that unused bits, result keys, and aggregation rules are handled consistently.

Once these pass, add a representative circuit from the production workload. This order makes a failure easier to localize. The quantum program testing and debugging workflow provides additional test and diagnosis patterns.

What to double-check

Gate and parameter semantics

Similar names do not guarantee identical behavior. Confirm matrix definitions, control order, rotation-angle signs, parameter units, and whether a target SDK automatically decomposes an operation. Custom gates deserve special attention: export their definition or expand them into a documented basis before porting.

Qubit and result ordering

Bitstring display order is one of the most common causes of a false migration failure. Compare a known basis state and label every qubit explicitly. When comparing counts, normalize result keys into a shared convention before calculating differences.

Measurements and observables

Distinguish a sampled measurement from an exact expectation-value calculation. Check whether the target returns counts, samples, probabilities, state vectors, or observable values. Also verify whether measurements can occur mid-circuit and whether classical conditions are supported in the selected execution path.

Transpilation and native gates

A logical circuit may be portable even when its compiled form is not. Record the target’s native gate set, connectivity model, routing method, optimization level, and any constraints on two-qubit operations. Compare logical depth and compiled depth separately. A change in depth or gate count may be an expected result of targeting different hardware rather than a programming error.

Noise, shots, and reproducibility

Exact simulator output and sampled hardware output should not be held to the same tolerance. Define acceptance criteria before running the migration: exact equality for small state-vector tests, numerical tolerance for expectation values, and distribution-based checks for shot results. Record shot count, seed behavior, noise model, and backend execution date when those details affect reproducibility.

Optimizer and gradient workflows

Hybrid migrations can fail silently when the forward circuit works but the training loop does not. Check parameter shapes, gradient sign, differentiation method, optimizer state, learning-rate interpretation, batching, and stopping rules. Save one fixed batch and one known parameter vector as a regression fixture.

Common mistakes

  • Translating syntax before documenting behavior. A line-by-line rewrite can preserve code shape while changing qubit order or measurement meaning.
  • Testing only on a large circuit. Large circuits combine too many possible causes. Start with the five canonical circuits and add complexity gradually.
  • Comparing raw result dictionaries. Normalize bit order, key formatting, shot counts, and measurement registers first.
  • Ignoring implicit compilation. A backend may insert swaps, decompose gates, or alter depth. Inspect the compiled result.
  • Reusing source optimizer settings blindly. Different gradient estimators, batching behavior, and execution costs can change the practical meaning of an optimizer configuration.
  • Assuming simulator agreement proves hardware equivalence. Simulator tests validate logic; hardware tests also reflect calibration, noise, connectivity, and execution conditions.
  • Failing to record versions. SDK APIs, plugins, compiler behavior, and backend capabilities can change. Store the versions and target details with the test results.

When a migration fails, classify the difference before changing the code: representation error, semantic error, compilation difference, stochastic variation, or hardware effect. This prevents a real qubit-order bug from being hidden by a loose numerical tolerance.

When to revisit

Keep this migration checklist as a living engineering document. Revisit it before switching SDKs, adding a new provider, moving from simulation to hardware, upgrading a major dependency, or changing a variational model’s optimizer or gradient method. It is also worth reviewing before seasonal planning cycles when teams select development targets or refresh reproducibility requirements.

At each review, update four items:

  1. Compatibility table: verify gate names, decompositions, measurement forms, parameter binding, and supported circuit features in the target documentation.
  2. Backend notes: record the selected target, connectivity assumptions, native operations, compilation settings, and any execution limitations relevant to the workload.
  3. Regression suite: rerun the five canonical circuits plus one representative production circuit, saving both expected results and tolerances.
  4. Version record: note the SDK, plugin, runtime, and backend identifiers used for the test. Add a “last tested” date to the project’s migration notes.

A practical migration template is: freeze the source → map operations → port the logical circuit → run canonical tests → inspect compilation → adapt noise and shots → port the hybrid loop → validate the target backend → record versions and differences. Following that sequence turns an SDK migration from a fragile rewrite into a repeatable quantum programming workflow. For cloud execution context, see the IBM Quantum and Amazon Braket cloud workflow.

Related Topics

#quantum SDK#migration checklist#gate mapping#transpilation#backend compatibility#quantum developer tools
Q

Qubit Daily Editorial Team

Quantum Programming Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.