Qiskit

Qiskit

Overview

This skill curates the upstream Qiskit workflow into an operator-ready guide for modern Qiskit usage.

Use it when the task is to:

• build or modify quantum circuits in Qiskit,
• choose an appropriate execution path for local validation versus hardware-backed runs,
• transpile against a real backend or target,
• use primitives-oriented workflows instead of stale execution idioms,
• troubleshoot environment, transpilation, runtime, or credential failures,
• preserve upstream provenance and workflow intent during review or handoff.

This enhancement keeps the original skill identity and scope, but sharpens it around current operational practice: isolated installs, backend-aware transpilation, primitives-first execution, secure credential handling, and concrete failure recovery.

When to Use This Skill

Use this skill when:

• You are building Qiskit circuits, observables, or experiment workflows in Python.
• You need to decide between local validation and backend-targeted execution.
• You need a reviewable workflow for circuit construction, transpilation, execution, and result interpretation.
• You are working with IBM Quantum-compatible Qiskit workflows and want guidance that avoids legacy patterns.
• You need to assess whether a proposed Qiskit plan is modern, safe, and likely to run.

Do not use this skill as the primary guide when:

• The request is mainly about quantum theory tutoring rather than operational Qiskit work.
• The user wants a non-Qiskit SDK or provider-native workflow outside documented Qiskit support.
• The main problem is generic Python packaging, secret-management architecture, or scientific post-processing beyond Qiskit execution.
• The user asks for speculative benchmarking claims without actual backend data or target constraints.

Operating Table

Workflow

1. Confirm the task type before writing code

   • Measurement distribution from a circuit: prefer a Sampler-style workflow.
   • Expectation values of observables: prefer an Estimator-style workflow.
   • Local correctness check only: use a local primitive first.
   • Real hardware or runtime-managed execution: plan around the target backend before transpiling.

2. Prepare a clean environment

   • Create and activate a fresh virtual environment.
   • Install Qiskit using current official guidance.
   • Verify the installed version before debugging API behavior.
   • Avoid mixing old tutorial snippets with a newer installed package set.

3. Build the smallest correct circuit first

   • Start with the required qubit count, classical measurements, and observable definitions.
   • Keep the first version simple enough to inspect visually and reason about.
   • If hardware execution is likely, avoid introducing unsupported or expensive structure too early.

4. Choose a target execution path

   • Local validation: use local primitives to confirm circuit logic and expected output shape.
   • Backend-targeted execution: inspect the target backend or target model before optimization.
   • Repeated runtime calls or grouped jobs: use Runtime session or batch concepts only when they add clear value.

5. Transpile against the real target when backend execution matters

   • Check qubit capacity, supported instructions, connectivity, and basis behavior.
   • Transpile against the actual backend or target, not a generic placeholder.
   • Treat transpilation as part of feasibility, not just final optimization.

6. Run and interpret results carefully

   • Local results are useful for logic validation, not for proving hardware behavior.
   • Hardware results can vary because of noise, queueing, calibration drift, and runtime options.
   • Compare observed output with expected structure, shot count, and measurement semantics.

7. Document assumptions before handoff

   • Record the environment, primitive choice, target backend, transpilation intent, and any backend-dependent caveats.
   • If you used migration-sensitive APIs, note the version context explicitly.

Setup and Installation

Use a fresh Python virtual environment whenever possible.

Example safe setup flow:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install qiskit
python -c "import qiskit; print(qiskit.__version__)"

Setup guidance:

• Prefer isolated environments over system-wide installs.
• Verify the installed Qiskit version before assuming an API from an older example still exists.
• If the user already has a broken environment, inspect package versions before changing code.
• Do not hardcode API tokens in scripts, notebooks, shell history, or examples.

For IBM Quantum access:

• Use the supported credential-saving flow from official documentation.
• Prefer environment-backed or secure local configuration over inline secrets.
• Treat account, project, and backend access as configuration inputs that may differ across users.

Building Quantum Circuits

When constructing circuits:

• Model the smallest circuit that expresses the intended computation.
• Add measurements only when the task requires sampled outcomes.
• For expectation-value workflows, keep observables and circuit preparation clearly separated.
• Use circuit diagrams and qubit counts to catch logic mistakes early.

Good operator habits:

• Confirm whether the user needs sampled counts, probabilities, or expectation values.
• Keep classical registers and measurement structure explicit.
• Avoid assuming that a circuit that works locally will map efficiently to hardware.
• If hardware execution is the goal, design with connectivity and transpilation overhead in mind.

Transpilation and Backend Selection

Backend-aware transpilation is mandatory whenever real backend execution is part of the task.

Before transpiling, check:

• target qubit count,
• supported instructions or effective basis behavior,
• connectivity or routing constraints,
• measurement requirements,
• optimization level,
• shot budget and runtime expectations.

Operational guidance:

• Transpile against the actual backend or target whenever the results must be hardware-relevant.
• Expect depth and gate counts to change materially after routing and optimization.
• Treat large swap insertion or depth growth as a signal to revisit circuit structure or backend choice.
• If transpilation takes unexpectedly long, reduce circuit size, inspect optimization settings, or simplify the target goal.

Review questions:

• Does the circuit fit the backend's qubit and instruction constraints?
• Is the chosen backend sensible for the circuit width and routing burden?
• Is the requested optimization level aligned with speed versus quality needs?
• Is the operator interpreting transpiled depth and layout changes before execution?

Execution on Simulators vs Hardware