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/circuits.md
View on GitHub# Circuits, Parameters, Control Flow, and Serialization
## Circuit Data Model
`QuantumCircuit` stores ordered quantum bits, classical bits, instructions, parameters, global phase, metadata, and optional real-time classical control flow.
```python
from qiskit import QuantumCircuit
circuit = QuantumCircuit(3, 3, name="ghz")
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.measure([0, 1, 2], [0, 1, 2])
print(circuit.num_qubits)
print(circuit.num_clbits)
print(circuit.depth())
print(circuit.count_ops())
```
Use explicit registers when result names or control-flow operands matter:
```python
from qiskit import ClassicalRegister, QuantumCircuit, QuantumRegister
qubits = QuantumRegister(2, "q")
syndrome = ClassicalRegister(1, "syndrome")
readout = ClassicalRegister(2, "readout")
circuit = QuantumCircuit(qubits, syndrome, readout)
```
Sampler V2 returns one data field per classical register, so meaningful register names improve result handling.
## Bit and Pauli Ordering
Qiskit uses little-endian conventions:
- Qubit 0 is conventionally the least-significant qubit.
- Count strings are printed most-significant classical bit first.
- The rightmost character of a Pauli label acts on qubit 0.
- Circuit diagrams normally draw qubit 0 at the top.
For a two-qubit operator, `"ZI"` applies `Z` to qubit 1 and identity to qubit 0. Never reverse strings based only on visual circuit order.
When translating a bitstring into graph vertices or variables, write and test an explicit conversion:
```python
def qiskit_bitstring_to_classical_values(bitstring: str) -> list[int]:
"""Decode one register in classical-bit order 0, 1, ..."""
return [int(bit) for bit in reversed(bitstring.replace(" ", ""))]
```
This yields classical-bit order, not qubit order. Map through each `measure(qubit, clbit)` instruction before interpreting variables. For multiple registers or `join_data`, decode with the recorded register order; blindly stripping spaces does not establish the qubit mapping.
## Gates and Instructions
```python
from math import pi
from qiskit import QuantumCircuit
circuit = QuantumCircuit(3)
# One-qubit gates
circuit.x(0)
circuit.h(1)
circuit.s(1)
circuit.t(2)
circuit.rx(pi / 3, 0)
circuit.ry(pi / 4, 1)
circuit.rz(pi / 5, 2)
# Two- and three-qubit gates
circuit.cx(0, 1)
circuit.cz(1, 2)
circuit.swap(0, 2)
circuit.ccx(0, 1, 2)
```
Prefer high-level gates while constructing the algorithm. Let a target-aware transpiler translate them to the selected backend's instruction set.
Barriers are directives that constrain some transpiler reordering and optimization. Use them only when the experimental boundary matters, not as visual decoration:
```python
circuit.barrier(label="logical-boundary")
```
## Measurements and Resets
```python
from qiskit import QuantumCircuit
circuit = QuantumCircuit(2, 2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure([0, 1], [0, 1])
```
`measure_all()` defaults to `add_bits=True`, adding a new register even when classical bits already exist (a name collision can change `meas`). Use `add_bits=False` only when sufficient classical bits exist and their ordering is intended:
```python
circuit = QuantumCircuit(2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure_all()
print([register.name for register in circuit.cregs])
```
Sampler requires measurement instructions for sampled classical output. Estimator generally uses circuits without final measurements.
Use `reset()` only when the execution target supports it:
```python
circuit.reset(0)
```
## Parameterized Circuits
Primitive PUBs are the preferred way to evaluate one parameterized circuit at many values.
```python
import numpy as np
from qiskit import QuantumCircuit
from qiskit.circuit import ParameterVector
theta = ParameterVector("theta", 3)
circuit = QuantumCircuit(3)
for qubit, parameter in enumerate(theta):
circuit.ry(parameter, qubit)
circuit.cx(0, 1)
circuit.cx(1, 2)
parameter_order = list(circuit.parameters)
parameter_values = np.array(
[
[0.0, 0.0, 0.0],
[0.1, 0.2, 0.3],
[0.4, 0.5, 0.6],
]
)
assert parameter_values.shape[-1] == len(parameter_order)
```
Do not assume that creation order and `circuit.parameters` order are interchangeable for arbitrary named parameters. Print or persist the order:
```python
print([parameter.name for parameter in circuit.parameters])
```
For debugging or APIs that require a bound circuit:
```python
bound = circuit.assign_parameters(
dict(zip(parameter_order, parameter_values[0], strict=True))
)
```
For iterative primitive workloads, keep the circuit parameterized and pass values in the PUB instead of producing and transpiling a bound circuit on every iteration.
## Composition and Reuse
```python
from qiskit import QuantumCircuit
prepare = QuantumCircuit(2, name="prepare")
prepare.h(0)
entangle = QuantumCircuit(2, name="entangle")
entangle.cx(0, 1)
combined = prepare.compose(entangle)
```
Map qubits explicitly when composing circuits with different widths:
```python
larger = QuantumCircuit(4)
larger.compose(combined, qubits=[1, 3], inplace=True)
```
Convert a reusable unitary subcircuit to a gate or instruction:
```python
bell_prep = combined.to_gate(label="Bell prep")
outer = QuantumCircuit(2)
outer.append(bell_prep, [0, 1])
```
Circuits containing measurements or other non-unitary instructions cannot be converted to a `Gate`.
## Current Circuit-Library Constructors
Qiskit 2.x is moving from mutable blueprint classes to functions and gates that build concrete objects immediately.
```python
from qiskit import QuantumCircuit
from qiskit.circuit.library import QFTGate, efficient_su2, real_amplitudes
ansatz = efficient_su2(
num_qubits=4,
reps=2,
entanglement="linear",
)
real_ansatz = real_amplitudes(
num_qubits=4,
reps=2,
entanglement="reverse_linear",
)
qft = QuantumCircuit(4)
qft.append(QFTGate(4), range(4))
```
The old `QFT` blueprint class is deprecated as of Qiskit 2.1 and is scheduled for removal in Qiskit 3.0. Use `QFTGate` or `qiskit.synthesis.qft.synth_qft_full`.
Other current constructors include:
```python
from qiskit.circuit.library import (
grover_operator,
n_local,
pauli_feature_map,
zz_feature_map,
)
```
Check the current API before using a class copied from an older tutorial; several blueprint classes have function replacements.
## Dynamic Circuits and Classical Control
Qiskit expresses structured real-time control flow with context managers:
```python
from qiskit import ClassicalRegister, QuantumCircuit, QuantumRegister
qubit = QuantumRegister(1, "q")
flag = ClassicalRegister(1, "flag")
circuit = QuantumCircuit(qubit, flag)
circuit.h(qubit[0])
circuit.measure(qubit[0], flag[0])
with circuit.if_test((flag[0], True)):
circuit.x(qubit[0])
```
Other structured builders include `if_test`, `while_loop`, `for_loop`, and `switch`.
Before executing dynamic circuits:
1. Confirm the selected backend target includes the required control-flow operations.
2. Transpile against that exact backend.
3. Check current compatibility among dynamic circuits, fractional gates, and mitigation options.
4. Test classical-register interpretation locally or on a fake backend.
Legacy `instruction.c_if(...)` patterns were removed in Qiskit 2.0.
## Circuit Inspection
```python
print("qubits:", circuit.num_qubits)
print("classical bits:", circuit.num_clbits)
print("parameters:", [parameter.name for parameter in circuit.parameters])
print("depth:", circuit.depth())
print("size:", circuit.size())
print("operations:", circuit.count_ops())
print("nonlocal gates:", circuit.num_nonlocal_gates())
```
These metrics are structural, not direct fidelity or cost estimates. Recompute them after target-aware transpilation.
## QPY Serialization
QPY preserves Qiskit circuits more faithfully than interchange formats intended for other tools:
```python
from pathlib import Path
from qiskit import qpy
path = Path("experiment.qpy")
with path.open("wb") as output_file:
qpy.dump(circuit, output_file)
with path.open("rb") as input_file:
loaded_circuits = qpy.load(input_file)
loaded = loaded_circuits[0]
```
QPY is forward-compatible: newer Qiskit releases can normally load older QPY files. Older releases are not expected to load QPY produced by newer versions.
Record the writing Qiskit version and retain source code for long-lived artifacts. Treat all external binary inputs as untrusted and enforce source, size, and version policies. Never substitute Python pickle for untrusted circuit data.
## OpenQASM Interchange
Use OpenQASM when interoperability is more important than preserving every Qiskit-specific object:
```python
from qiskit import qasm2, qasm3
qasm2_text = qasm2.dumps(circuit)
round_tripped = qasm2.loads(qasm2_text)
qasm3_text = qasm3.dumps(circuit)
```
OpenQASM 2 cannot represent all modern control-flow and classical-expression features. OpenQASM 3 import requires optional tooling and may not round-trip Qiskit metadata or custom instructions. Validate semantics after interchange.
## Common Circuit Mistakes
- **Wrong output register**: inspect `circuit.cregs` and use the corresponding Sampler result field.
- **Reversed interpretation**: account for count-string and Pauli-label ordering explicitly.
- **Parameter shape mismatch**: make the final value-array dimension equal `len(circuit.parameters)`.
- **Duplicate measurements**: use `remove_final_measurements()` before adding a new measurement scheme.
- **Estimator failure**: remove final measurements and non-unitary instructions.
- **Unsupported control flow**: inspect `backend.operation_names` and `backend.target`.
- **Circuit wider than target**: compare `circuit.num_qubits` with `backend.num_qubits` before transpiling.
- **Unexpected optimization across boundaries**: add a barrier only when that behavior is intentional.
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 |