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/backends.md
View on GitHub# Backends, Runtime Modes, Simulation, and Noise Management
Cloud authentication, QPU, session, and batch snippets are illustrative and were not executed in this refresh. Local evidence is listed in [sources.md](sources.md).
## BackendV2
Qiskit 2.x providers expose hardware and simulators through `BackendV2`. Important public attributes include:
```python
print(backend.name)
print(backend.num_qubits)
print(backend.operation_names)
print(backend.coupling_map)
print(backend.target)
print(backend.status())
```
The `Target` describes operation support, qubit operands, connectivity, and available timing/error metadata.
Do not use `backend.configuration()`, `BackendProperties`, or other BackendV1 patterns in new code.
## Connect to IBM Quantum
Use a securely saved account:
```python
from qiskit_ibm_runtime import QiskitRuntimeService
service = QiskitRuntimeService()
```
New account configurations use `channel="ibm_quantum_platform"`. See [setup.md](setup.md) for secure credential setup. Never embed or print an API key.
## Discover Backends
Select by requirements, not by a system name copied from a tutorial:
```python
backends = service.backends(
operational=True,
simulator=False,
min_num_qubits=20,
)
for candidate in backends:
status = candidate.status()
print(
candidate.name,
candidate.num_qubits,
status.pending_jobs,
)
```
For exploratory work:
```python
backend = service.least_busy(
operational=True,
simulator=False,
min_num_qubits=20,
)
```
Least busy is not necessarily best. For a production experiment, compare:
- required qubit count,
- connectivity and native two-qubit operations,
- calibration quality on candidate subgraphs,
- control-flow or fractional-gate requirements,
- plan and region,
- queue and expected execution time.
The bundled read-only inspector summarizes one selected backend:
```bash
python scripts/inspect_runtime.py --min-qubits 20
python scripts/inspect_runtime.py --backend BACKEND_NAME --json
```
## Inspect Target Capabilities
```python
target = backend.target
print("operations:", sorted(backend.operation_names))
print("supports if_else:", "if_else" in backend.operation_names)
print("supports reset:", "reset" in backend.operation_names)
print("coupling edges:", list(backend.coupling_map.get_edges()))
```
Operation support can vary by qubit tuple. A name appearing in `operation_names` does not imply every qubit or pair supports it.
## Prepare ISA Circuits
```python
from qiskit.transpiler import generate_preset_pass_manager
pass_manager = generate_preset_pass_manager(
backend=backend,
optimization_level=1,
seed_transpiler=23,
)
isa_circuit = pass_manager.run(circuit)
```
For Estimator:
```python
isa_observable = observable.apply_layout(isa_circuit.layout)
```
Runtime V2 primitives do not perform this conversion automatically.
## Job Mode
Use job mode for independent one-off primitive calls:
```python
from qiskit_ibm_runtime.executor_sampler import Sampler
sampler = Sampler(mode=backend)
job = sampler.run([isa_circuit], shots=1024)
job_id = job.job_id()
print("job_id:", job_id)
result = job.result()
```
Persist the ID before blocking. Retrieve later:
```python
service = QiskitRuntimeService()
job = service.job(job_id)
print(job.status())
result = job.result()
```
Cancel only if the experiment should no longer consume allocation:
```python
job.cancel()
```
## Batch Mode
Batch mode is for independent jobs that can be submitted together. It is available to Open Plan users.
```python
from qiskit_ibm_runtime import Batch
from qiskit_ibm_runtime.executor_sampler import Sampler
with Batch(backend=backend, max_time="10m") as batch:
sampler = Sampler(mode=batch)
jobs = [
sampler.run([isa_circuit], shots=1024)
for isa_circuit in isa_circuits
]
# The batch accepts no new jobs; submitted jobs can still finish.
results = [job.result() for job in jobs]
```
Batch jobs are scheduled as a group, but do not assume an application-level result order beyond the job list you preserve.
## Session Mode
Session mode is for iterative workloads such as VQE parameter updates:
```python
from qiskit_ibm_runtime import Session
from qiskit_ibm_runtime.executor_estimator import Estimator
with Session(backend=backend, max_time="20m") as session:
estimator = Estimator(mode=session)
jobs = [
estimator.run([pub], precision=0.03)
for pub in iterative_pubs
]
```
Open Plan users cannot submit session jobs; use job or batch mode. Sessions have maximum and interactive time-to-live limits. Close them as soon as submission is complete.
Creating `Estimator(mode=backend)` inside a session context still selects job mode. Use `mode=session`.
## Ideal Local Primitives
For small ideal circuits:
```python
from qiskit.primitives import StatevectorEstimator, StatevectorSampler
sampler = StatevectorSampler(seed=23)
estimator = StatevectorEstimator(seed=23)
```
These implementations use local statevector simulation and do not model backend noise. Sampler is finite-shot; zero-precision Estimator is exact only for unitary state preparation.
Memory for a dense statevector grows as \(2^n\). Use an algorithm-appropriate Aer method or tensor-network tooling for larger circuits.
## Aer Simulation
Install the pinned Aer distribution:
```bash
uv pip install "qiskit-aer==0.17.2"
```
Create an ideal Aer backend:
```python
from qiskit_aer import AerSimulator
aer = AerSimulator(method="automatic")
```
Run through Runtime's local-testing primitive interface:
```python
from qiskit.transpiler import generate_preset_pass_manager
from qiskit_ibm_runtime.executor_sampler import Sampler
pass_manager = generate_preset_pass_manager(
backend=aer,
optimization_level=1,
seed_transpiler=23,
)
isa_circuit = pass_manager.run(circuit)
sampler = Sampler(
mode=aer,
options={"simulator": {"seed_simulator": 23}},
)
result = sampler.run([isa_circuit], shots=1024).result()
```
The Runtime 0.50 client-side primitives perform preprocessing and postprocessing locally, including enabled mitigation/twirling paths. This differs from deprecated server-side primitives whose local mode ignored many options. Use `resilience_level=0` for an unmitigated Estimator baseline and inspect finalized options. Local results still do not verify service limits, scheduling, costs, or QPU mitigation effectiveness. `dry_run=True` on a remote backend is a server job returning random mock data, not Aer simulation.
## Approximate a Real Backend in Aer
```python
from qiskit_aer import AerSimulator
noisy_aer = AerSimulator.from_backend(backend)
pass_manager = generate_preset_pass_manager(
backend=noisy_aer,
optimization_level=1,
seed_transpiler=23,
)
noisy_isa = pass_manager.run(circuit)
sampler = Sampler(
mode=noisy_aer,
options={"simulator": {"seed_simulator": 23}},
)
result = sampler.run([noisy_isa], shots=4096).result()
```
This captures a subset of backend properties at model-construction time. It does not reproduce drift, all crosstalk, or every Runtime service behavior.
## Fake Backends
Fake backends provide a local `BackendV2` target and calibration-like snapshot:
```python
from qiskit_ibm_runtime.fake_provider import FakeSherbrooke
fake_backend = FakeSherbrooke()
```
Use them to test target-aware transpilation and Runtime local mode. Fake-backend class names can change; inspect the installed `qiskit_ibm_runtime.fake_provider` module before selecting one.
## Estimator Noise Management
Runtime Estimator exposes increasing levels of built-in mitigation:
```python
from qiskit_ibm_runtime.executor_estimator import Estimator
estimator = Estimator(
mode=backend,
options={"resilience_level": 1},
)
```
Current supported resilience levels:
- `0`: disable built-in resilience.
- `1`: measurement mitigation.
- `2`: measurement mitigation plus additional techniques such as ZNE, according to current defaults.
There is no resilience level 3 in the current V2 API.
Configure explicit techniques when the experiment requires control:
```python
estimator = Estimator(mode=backend)
estimator.options.dynamical_decoupling.enable = True
estimator.options.dynamical_decoupling.sequence_type = "XpXm"
estimator.options.twirling.enable_gates = True
estimator.options.twirling.num_randomizations = 32
estimator.options.twirling.shots_per_randomization = 100
estimator.options.resilience.zne_mitigation = True
estimator.options.resilience.zne.noise_factors = (1, 3, 5)
estimator.options.resilience.zne.extrapolator = "exponential"
```
Mitigation adds bias assumptions, circuit variants, shots, classical processing, and cost. It is not guaranteed to improve an observable.
## Sampler Noise Management
Sampler returns sampled classical data and does not use Estimator resilience levels:
```python
sampler = Sampler(mode=backend)
sampler.options.dynamical_decoupling.enable = True
sampler.options.dynamical_decoupling.sequence_type = "XpXm"
sampler.options.twirling.enable_gates = True
```
Measurement and gate-twirling defaults differ between Sampler and Estimator. Record `primitive.finalize_options().model_dump()` for the client-side implementation. Measurement mitigation forces measurement twirling; gate-based mitigation can force both. Explicitly enabled methods can override the meaning of `resilience_level=0`.
## Feature Compatibility
Some combinations are restricted. Current examples include incompatibilities among:
- fractional gates,
- gate twirling,
- probabilistic error amplification (PEA),
- probabilistic error cancellation (PEC),
- gate-folding zero-noise extrapolation (ZNE),
- some dynamic-circuit features.
Client-side Sampler 0.50 rejects input `BoxOp` circuits (including with twirling enabled in the tested wheel); dynamical decoupling rejects dynamic control flow. This is stricter than the current Sampler page, which only mentions boxes when twirling is disabled. Always consult the current Estimator/Sampler options and backend target. Do not copy a mitigation configuration between Runtime versions without revalidation.
## Fractional Gates
Request a backend target that exposes fractional gates when the algorithm benefits:
```python
backend = service.backend(
backend_name,
use_fractional_gates=True,
)
```
Compile against the returned object. `use_fractional_gates` changes the target and can affect compatibility with control flow and mitigation.
Qiskit Pulse is not an alternative; `qiskit.pulse` was removed in Qiskit 2.0.
## Third-Party Providers
Qiskit can target non-IBM providers through separately installed provider packages. Each provider controls:
- authentication,
- backend discovery,
- supported `BackendV2` features,
- whether native V2 primitives exist,
- transpilation plugins,
- result and cost semantics.
Prefer the provider's current documentation. If only `BackendV2` is available, adapt it with `BackendSamplerV2` or `BackendEstimatorV2`. Do not assume IBM Runtime options, sessions, or mitigation are portable.
## Operational Checklist
Before submitting:
1. Verify the account, plan, instance, and region.
2. Select a backend by circuit width and capabilities.
3. Compile and test locally against a fake/noisy backend.
4. Apply the circuit layout to Estimator observables.
5. Estimate the number of PUBs, circuits after randomization/mitigation, shots, and maximum execution time.
6. Choose job, batch, or session mode.
7. Save job IDs immediately.
8. Store versions, backend, target timestamp, compiler seed, primitive options, and metadata.
## Common Failures
- **Authentication failure**: use `ibm_quantum_platform`, verify the saved account, API key, and instance access.
- **Backend not found**: list accessible backends; systems and account entitlements change.
- **Circuit not ISA-compatible**: submit the circuit returned by the backend-specific pass manager.
- **Open Plan session error**: use job or batch mode.
- **Unsupported option combination**: check the current feature-compatibility table.
- **Unexpected queue/cost**: inspect the plan, mode TTL, precision, shots, mitigation, and twirling expansion.
- **Simulation differs from QPU**: document the model snapshot and unmodeled effects rather than tuning until outputs match.
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 |