Qiskit, Primitives, and Circuit Execution

What an SDK actually is

An SDK is an interface to circuits, simulators, transpilers, and hardware services — nothing more mystical than that. Interfaces change. Class names get renamed, primitives get reorganized, backends get deprecated. The stable content is the workflow underneath: build a circuit, choose a backend or primitive, set the shot count, run, collect the result, interpret the uncertainty, and record the environment.

That observation suggests a rule for anything you publish or hand to a colleague. The lesson — the circuit idea and its evidence requirements — is stable and should be written as if it will never expire. The exact API call is a dated note and should be labeled with the version it was checked against. Mixing the two guarantees stale material; separating them makes maintenance a fifteen-minute job.

Shots are statistics

Shot-based execution estimates probabilities by sampling, so ordinary sampling error applies:

With a true probability near one half and $S=100$ shots, the estimate can visibly wobble run to run; at $S=10000$ it should sit tight. This is not a quantum effect — it is the binomial distribution doing what it always does — and it means a count dictionary is meaningless without its shot count beside it. The full minimum execution record is:

• the circuit description,
• the SDK and its version,
• the backend or simulator,
• the shots and the seed, if one was used,
• the transpilation settings, if any,
• the result schema or counts, and
• the interpretation with its stated limitation.

Worked example: the Bell circuit, run properly

Define the circuit in quantum terms first, before any API gets involved:

• H on q0,
• CNOT from q0 to q1,
• measure q0 and q1.

The ideal distribution has support on $00$ and $11$ only. In a Qiskit-style workflow you build the circuit, pick a simulator or backend, execute with a chosen shot count, and inspect the counts. The exact class names may change next year; those evidence requirements will not.

Now the diagnostic reflex: if an ideal simulator returns counts on $01$ or $10$, suspect a bit-order mistake, a circuit error, a measurement mix-up, or a misreading of the output schema — in roughly that order — before suspecting the SDK. Libraries are usually innocent; conventions are usually guilty.

Where execution goes wrong

The first trap is treating a tutorial run as a scientific result. A count dictionary with no version, backend, transpilation settings, shots, or expected output attached is an anecdote. It might be a true anecdote, but nobody can check.

The second trap is letting API churn obscure the fundamentals. When a class gets renamed, the circuit does not change; when a primitive is reorganized, the Born rule does not notice. Keep the lesson stable, quarantine the version-specific commands, and update them on their own schedule.

The engineering view

An SDK is an integration boundary, and you should treat it the way you treat any external service: tests on your side, metadata flowing across. When something breaks, the debugging ladder from the figure tells you where to stand:

1. hand prediction,
2. local exact simulator,
3. SDK ideal simulator,
4. SDK noisy simulator,
5. hardware backend.

Move one rung at a time, and record the metadata at every rung. The hand prediction catches wrong mental models. The local simulator catches SDK misunderstandings. The ideal SDK simulator catches transpilation surprises. The noisy simulator separates modeled noise from hardware reality. Skip a rung and you will eventually spend an afternoon blaming hardware for a bit-order bug.

What this buys you in diligence

When a partner hands you a notebook, the price of trust is a short list: dependency versions, the backend, the shot count, the seed, the transpiled circuit, the expected output, and rerun instructions. A team that produces these in minutes has an engineering culture; a team that cannot has a demo.

Before adopting any SDK-based workflow into your own stack, run one known circuit through it and compare against your local reference. The integration risk of a tool you have not executed once is higher than any feature matrix suggests.

Exercise

Run an SDK reproducibility check. Specify or execute a Bell-circuit workflow against a simulator or backend with a fixed shot count.

• Record: SDK name and version, backend, circuit, shots, seed if used, the shape of the result object, and any API migration risk you notice.
• Expected: counts consistent with the ideal Bell prediction within sampling variation, interpreted using the standard-error formula.
• Check: compare the SDK output against the local mini-simulator expectation before drawing any conclusion.
• Decide: write one sentence stating whether this SDK workflow is ready for adoption, needs a refresh, or should remain a teaching-only artifact.

Check your understanding

Specify a small circuit execution end to end: backend, shots, result object, and reproducibility notes. A passing answer explains why $01$ appearing in ideal Bell simulation is a bug report about your code, not about the device.

Oral defense: walk a colleague down the debugging ladder for a hypothetical wrong result, naming what each rung rules out.

If you get stuck

If your run notes are missing metadata or you find yourself treating count variation as exact truth, revisit Chapter 36 (Python and Quantum Programming Workflow) for the run-record discipline, and Chapter 37 (Building a Small Simulator From Scratch) for the local ground truth that makes SDK output interpretable.