A Qiskit transpiler workflow should begin with a measurable target: fewer two-qubit gates, lower depth, a compatible layout, or a circuit that fits the hardware's available instructions. This guide provides a reusable checklist for configuring transpilation, comparing optimization results, and deciding when a custom pass manager is justified.
Overview
Transpilation converts an abstract quantum circuit into a form that a selected target backend can execute. The process may rewrite gates, map logical qubits to physical qubits, route interactions across a coupling graph, and translate operations into the backend's supported instruction set.
For a simulator, the main concern may be execution time or compatibility. For real quantum hardware, circuit depth and two-qubit gate count are often especially important because additional operations can increase exposure to noise. These are practical optimization goals, not guarantees of better results: always compare the transpiled circuit and validate the algorithm's output.
Start with Qiskit's standard transpile() workflow. It is usually the best baseline because it incorporates the target's instruction set and connectivity. A minimal pattern looks like this:
from qiskit import QuantumCircuit, transpile
circuit = QuantumCircuit(3)
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.measure_all()
# Use a configured backend or target in your project.
transpiled = transpile(
circuit,
backend=backend,
optimization_level=2,
seed_transpiler=123
)
print("Depth:", transpiled.depth())
print("Operations:", transpiled.count_ops())
The optimization level is a useful starting point, not a substitute for measurement. Compare levels on representative circuits and record depth, operation counts, layout, routing behavior, and compilation time. If the result is not good enough, move to explicit pass-manager configuration rather than changing several options at once.
Checklist by scenario
Scenario 1: You are targeting a real backend
- Confirm the target. Use the backend or target object that represents the device you will actually run on. A circuit optimized for one coupling map may require different routing on another.
- Inspect supported instructions. Do not assume that every familiar gate is native to the device. Let the target guide basis translation, or explicitly verify the final operation set.
- Begin with a standard optimization level. Run a small benchmark at levels 1, 2, and 3 when compilation time permits. The highest level is not automatically best for every circuit.
- Measure two-qubit operations. Inspect
transpiled.count_ops()and identify the operations that represent entangling gates on the selected target. These often deserve more attention than single-qubit gate totals. - Check depth after routing. A circuit that is shallow before transpilation can become substantially deeper when nonadjacent interactions require swaps.
- Fix randomness for comparisons. Set
seed_transpilerwhen comparing layouts, routing choices, or software changes. Reproducibility makes regression testing meaningful.
Scenario 2: You are using a simulator
A simulator may not require hardware connectivity, so avoid applying hardware routing unless your experiment is intended to model a particular device. You can still transpile to a chosen basis or target to test what a later hardware run might look like. For algorithm development, compare the original circuit with a simulator-compatible transpiled circuit and preserve the same measurement interpretation.
Scenario 3: The default workflow is not enough
Use a custom PassManager when you need a repeatable compilation policy, a fixed layout strategy, custom analysis, or a controlled comparison between routing methods. A pass manager is a sequence of analysis, transformation, and cleanup passes. The exact pass names and import paths can change between Qiskit releases, so consult the installed version's API documentation and test the complete pipeline in a pinned environment.
Conceptually, a custom pipeline usually contains these stages:
- Analysis: collect information about connectivity, depth, commutation, or layout quality.
- Layout: assign logical qubits to physical qubits.
- Routing: insert operations needed to satisfy connectivity.
- Translation: convert gates into the target instruction set.
- Optimization: cancel, combine, or rewrite operations where legal.
- Scheduling or cleanup: apply timing-aware transformations only when the target and experiment require them.
Do not construct this sequence from memory alone. Pass dependencies matter: a routing pass needs layout and connectivity information, while a later optimization pass may expose opportunities that did not exist earlier.
What to double-check
| Area | What to inspect | Why it matters |
|---|---|---|
| Optimization level | Depth, gate counts, compile time, and output stability | More aggressive processing can cost time without improving the metric you care about. |
| Layout | Initial logical-to-physical qubit assignment | A poor assignment can create avoidable routing operations. |
| Routing | Inserted swaps and resulting two-qubit gates | Connectivity constraints can dominate the final circuit. |
| Basis translation | Final instruction names and gate decomposition | The backend must support the resulting operations. |
| Depth | circuit.depth() before and after transpilation | Depth provides a compact view of sequential work, although it does not capture every hardware cost. |
| Operation counts | circuit.count_ops(), especially entangling operations | Counts reveal whether optimization reduced the operations most relevant to the experiment. |
| Semantics | Measurements, classical registers, barriers, and parameter values | A smaller circuit is not useful if it changes the intended computation. |
Keep the original circuit unchanged and save each transpiled variant with metadata: Qiskit version, backend or target, optimization level, seed, routing and layout choices, and measured resource counts. This makes before-and-after reviews reproducible and helps identify changes caused by a software upgrade rather than by the circuit itself.
For a broader planning view, pair this review with quantum circuit resource estimation. If the circuit will run in the cloud, also account for shots, batching, queues, and provider limits using the quantum cloud job planning guide.
Common mistakes
- Optimizing the pre-transpiled circuit only. Hardware routing can change the resource profile dramatically. Review the final circuit, not just the source code.
- Counting all gates equally. A reduction in single-qubit gates may matter less than one additional layer of entangling operations. Define a priority order before testing.
- Using a coupling map from another device. Connectivity and instruction targets belong to the selected backend. Reuse configuration only after verifying that it still matches the target.
- Adding passes without checking dependencies. A custom pass manager is a pipeline, not a bag of independent optimizers. Validate its output at every stage while developing it.
- Ignoring semantic checks. Compare counts or sampled distributions on a simulator for small circuits. Confirm that measurements and parameterized behavior remain equivalent.
- Assuming one transpilation result is universal. Layout, routing, seeds, backend targets, and SDK versions can change the result. Record the inputs used for every comparison.
- Optimizing without a baseline. Preserve a simple default-transpiler result. It gives you a reference for whether custom work actually improves the selected metric.
When a custom pass manager becomes difficult to maintain, return to the standard transpiler and isolate one change at a time. The goal is a reliable compilation policy, not the longest configuration.
When to revisit
Revisit this checklist whenever you target a different backend, change the circuit's qubit count or interaction pattern, alter measurement requirements, or move from simulation to hardware. Also repeat the comparison after a Qiskit upgrade, because pass behavior, defaults, supported targets, and import paths may change.
A practical maintenance routine is to keep a small regression suite containing representative circuits: a shallow circuit, a connectivity-heavy circuit, a parameterized variational circuit, and a circuit with classical measurement logic. For each one, record depth, operation counts, compilation time, and semantic checks. Run the suite before a release, before a major experiment, and during planned environment updates.
Before submitting a job, use this final action list:
- Confirm the backend or simulator target and its installed SDK version.
- Transpile with a documented baseline and fixed seed where comparisons matter.
- Compare depth, two-qubit operations, total operations, and compile time.
- Inspect the final layout, routing additions, instruction set, and measurements.
- Run a small semantic check before spending hardware time or cloud budget.
- Save the circuit, configuration, metrics, and environment details for later review.
This workflow keeps Qiskit circuit optimization grounded in evidence. Start with the backend-aware default, introduce custom pass-manager choices only when the measurements justify them, and update the checklist whenever the target or toolchain changes.