K-Dense-AI/scientific-agent-skills / skills/qiskit
qiskit
VerifiedBuilds, simulates, transpiles, and executes quantum circuits with Qiskit and IBM Quantum Runtime. Use for Qiskit 2.x circuits and operators, V2 Sampler or Estimator primitives, target-aware transpilation, local or noisy simulation, IBM QPU execution, Runtime sessions or batches, error mitigation, and Qiskit ecosystem packages.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.0 KB |
| references/algorithms.md | markdown | 10.9 KB |
| references/backends.md | markdown | 12.0 KB |
| references/circuits.md | markdown | 9.7 KB |
| references/migration.md | markdown | 11.0 KB |
| references/patterns.md | markdown | 9.4 KB |
| references/primitives.md | markdown | 14.0 KB |
| references/setup.md | markdown | 8.5 KB |
| references/sources.md | markdown | 14.8 KB |
| references/testing.md | markdown | 10.8 KB |
| references/transpilation.md | markdown | 10.9 KB |
| references/visualization.md | markdown | 8.2 KB |
| scripts/check_environment.py | script | 7.7 KB |
| scripts/inspect_runtime.py | script | 6.3 KB |
| scripts/run_local_primitives.py | script | 5.5 KB |
references/transpilation.md
View on GitHub# Target-Aware Transpilation
Transpilation rewrites an abstract circuit into an **instruction set architecture (ISA) circuit** that satisfies a specific backend `Target`:
- only supported instructions,
- valid qubit operands and connectivity,
- backend timing and control-flow constraints,
- an explicit virtual-to-physical qubit layout.
IBM Runtime V2 primitives require ISA circuits. They do not perform layout, routing, and basis translation automatically.
## Recommended Entry Point
Use a preset staged pass manager:
```python
from qiskit.transpiler import generate_preset_pass_manager
pass_manager = generate_preset_pass_manager(
backend=backend,
optimization_level=1,
seed_transpiler=17,
)
isa_circuit = pass_manager.run(circuit)
```
The pass manager can be reused for circuits targeting the same backend snapshot:
```python
isa_circuits = pass_manager.run(circuits)
```
`qiskit.transpile()` remains a convenient wrapper, but a pass manager is easier to reuse, inspect, and customize.
## The BackendV2 Target
`backend.target` is the source of supported operations and constraints:
```python
print("backend:", backend.name)
print("qubits:", backend.num_qubits)
print("operations:", sorted(backend.operation_names))
print("coupling map:", backend.coupling_map)
print("target:", backend.target)
```
Do not use these removed or legacy BackendV1 access patterns:
```python
# Do not use in Qiskit 2.x code:
# backend.configuration().basis_gates
# backend.properties()
# BackendProperties
```
For a synthetic target:
```python
from qiskit.transpiler import CouplingMap, Target
target = Target.from_configuration(
basis_gates=["cz", "sx", "rz"],
coupling_map=CouplingMap.from_line(5),
)
pass_manager = generate_preset_pass_manager(
target=target,
optimization_level=1,
seed_transpiler=17,
)
isa_circuit = pass_manager.run(circuit)
```
Prefer one coherent `backend` or `target`. Combining a backend with separate `basis_gates` or `coupling_map` inputs creates competing sources of truth and is discouraged.
## Preset Optimization Levels
| Level | Typical intent |
|---:|---|
| 0 | Minimal transformation needed to satisfy the target |
| 1 | Light optimization with relatively low compilation cost |
| 2 | More optimization and search |
| 3 | Heavier optimization and search; highest classical cost |
Higher does not guarantee a better experimental result. Compare levels using the same circuit, target snapshot, and seed:
```python
compiled = {}
for level in (0, 1, 2, 3):
manager = generate_preset_pass_manager(
backend=backend,
optimization_level=level,
seed_transpiler=17,
)
compiled[level] = manager.run(circuit)
```
Start with levels 1 and 3 for a bounded comparison. Evaluate target-native two-qubit operations, depth, estimated duration when available, and downstream result quality.
## Transpiler Stages
A preset `StagedPassManager` has six conceptual stages:
1. **init**: validate and synthesize high-level operations.
2. **layout**: map virtual qubits to physical qubits.
3. **routing**: add routing operations to satisfy connectivity.
4. **translation**: convert to target-supported instructions.
5. **optimization**: simplify and resynthesize the target circuit.
6. **scheduling**: apply hardware-aware timing passes when configured.
Qiskit 2.x scheduling does not restore `qiskit.pulse`; that module was removed.
Inspect the generated manager:
```python
print(pass_manager)
print(pass_manager.property_set)
```
The property set is primarily a pass-development and debugging interface; do not build long-term application logic around undocumented keys.
## Layouts and Observables
Transpilation can permute logical qubits. Estimator observables must be mapped to the final physical layout:
```python
from qiskit.quantum_info import SparsePauliOp
observable = SparsePauliOp.from_list([("ZZ", 1.0)])
isa_circuit = pass_manager.run(circuit)
isa_observable = observable.apply_layout(isa_circuit.layout)
```
Submit the mapped observable:
```python
pub = (isa_circuit, isa_observable, parameter_values)
```
Do not manually guess the permutation from a circuit drawing. Use `isa_circuit.layout`.
For a list of observables:
```python
isa_observables = [
observable.apply_layout(isa_circuit.layout)
for observable in observables
]
```
## Parameterized Workloads
Transpile the parameterized circuit once:
```python
parameterized_isa = pass_manager.run(parameterized_circuit)
isa_observable = observable.apply_layout(parameterized_isa.layout)
for values in optimizer_values:
pub = (parameterized_isa, isa_observable, [values])
result = estimator.run([pub], precision=0.03).result()[0]
```
This avoids repeated layout and routing. Retranspile only when the circuit structure, target, selected backend feature set, or compilation strategy changes.
## Initial Layouts
Use an explicit layout only when calibration analysis or a reproducibility requirement justifies it:
```python
pass_manager = generate_preset_pass_manager(
backend=backend,
optimization_level=2,
initial_layout=[3, 5, 8],
seed_transpiler=17,
)
```
An explicit layout bypasses the preset layout-selection logic. Confirm every physical qubit and interaction is supported by the target.
## Approximate Synthesis
`approximation_degree` trades unitary fidelity for potentially cheaper circuits:
```python
pass_manager = generate_preset_pass_manager(
backend=backend,
optimization_level=3,
approximation_degree=0.99,
seed_transpiler=17,
)
```
Treat approximation as an experimental parameter. Compare ideal-unitary error, native two-qubit count, and hardware outcome. Do not describe `0.99` as a universal one-percent error bound for the whole algorithm.
## Reproducibility
Set the transpiler seed explicitly:
```python
pass_manager = generate_preset_pass_manager(
backend=backend,
optimization_level=3,
seed_transpiler=17,
)
```
Qiskit 2.5 also supports `QISKIT_TRANSPILER_SEED`, but an explicit argument is clearer in reproducible code.
Record:
- Qiskit version,
- backend name and target/calibration timestamp if available,
- optimization level,
- seed,
- all non-default pass-manager arguments,
- input and output QPY artifacts,
- output layout and structural metrics.
A fixed seed stabilizes stochastic compiler choices; it does not freeze changing backend calibration data or package behavior across releases.
## Analyze Compiled Circuits
```python
def two_qubit_instruction_count(circuit):
return sum(
len(item.qubits) == 2
for item in circuit.data
)
print("logical depth:", circuit.depth())
print("ISA depth:", isa_circuit.depth())
print("ISA size:", isa_circuit.size())
print("ISA operations:", isa_circuit.count_ops())
print("two-qubit instructions:", two_qubit_instruction_count(isa_circuit))
print("layout:", isa_circuit.layout)
```
Count all two-qubit instructions rather than only `cx`; current targets may use `cz`, `ecr`, `rzz`, or other operations.
Circuit metrics are proxies. Calibration-aware quality depends on which physical qubits and operations were selected.
## Verify ISA Compatibility
Runtime rejects circuits that do not satisfy the target. A practical preflight is:
1. Compile using the exact backend.
2. Confirm the compiled width fits `backend.num_qubits`.
3. Inspect every instruction name and qubit tuple against `backend.target`.
4. Submit only the pass-manager output.
For advanced validation, use target APIs rather than a hardcoded basis list.
## Fake Backends and Aer
Test target-aware compilation without consuming QPU time:
```python
from qiskit.transpiler import generate_preset_pass_manager
from qiskit_ibm_runtime.fake_provider import FakeSherbrooke
fake_backend = FakeSherbrooke()
pass_manager = generate_preset_pass_manager(
backend=fake_backend,
optimization_level=1,
seed_transpiler=17,
)
isa_circuit = pass_manager.run(circuit)
```
Fake-backend availability can change between Runtime releases. List the installed fake-provider exports rather than assuming an old tutorial backend exists.
For an Aer noise model derived from a real backend:
```python
from qiskit_aer import AerSimulator
noisy_simulator = AerSimulator.from_backend(backend)
simulator_pass_manager = generate_preset_pass_manager(
backend=noisy_simulator,
optimization_level=1,
seed_transpiler=17,
)
simulator_circuit = simulator_pass_manager.run(circuit)
```
An Aer model is an approximation of the calibration data used to create it; it is not a faithful predictor of every QPU effect.
## Dynamic Circuits and Fractional Gates
Backend capabilities can depend on how the backend is requested:
```python
backend = service.backend(
backend_name,
use_fractional_gates=True,
)
```
Fractional-gate support and dynamic-control support have evolved across Runtime versions. The actual service keyword is `use_fractional_gates=True`; the fractional-gates guide currently contains a `fractional_gates=True` typo. Parameterized `rzz` angles must satisfy the returned target bounds (currently `[0, pi/2]` in the Runtime validator); parameter values outside the range are not repaired by compiling the symbolic circuit once. Inspect the returned target and current feature-compatibility documentation instead of assuming both are available for every backend and option combination.
If a circuit uses `if_else`, `while_loop`, `switch_case`, `for_loop`, or classical expressions:
- confirm the operations are present in `backend.operation_names`,
- compile against that returned backend object,
- check mitigation and fractional-gate compatibility,
- test the full branch behavior.
## Custom Pass Managers
Customize only after measuring a limitation in preset output:
```python
from qiskit.transpiler import PassManager
from qiskit.transpiler.passes import RemoveBarriers
cleanup = PassManager([RemoveBarriers()])
cleaned = cleanup.run(circuit)
```
For target-aware custom pipelines, use `StagedPassManager` or modify a generated preset stage. Every custom transformation must preserve circuit semantics, parameters, control flow, and global phase as appropriate.
Write regression tests based on operator/state equivalence for small circuits and application-level outputs for larger circuits.
## Common Failures
- **Circuit not ISA-compatible**: submit the pass-manager output, not the abstract input.
- **Wrong expectation value**: map the observable through `isa_circuit.layout`.
- **Too many routing operations**: compare layout methods, seeds, initial layouts, and circuit connectivity.
- **Compilation is slow**: lower the optimization level or reduce repeated transpilation.
- **BackendV1 attribute error**: replace `configuration()` and `properties()` access with BackendV2 target and direct attributes.
- **Unknown instruction**: inspect the exact backend target; do not use a generic basis copied from another device.
- **Dynamic-circuit rejection**: verify target control-flow operations and incompatible backend feature flags.
- **Non-reproducible comparison**: fix the seed and backend snapshot, and store all compiler settings.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |