SDK reference

qsolve-sdk is the bridge between a plain Qiskit workflow and the Qsolve platform. It contains no quantum algorithm. You bring circuits, error mitigation and classical methods; the SDK runs them on Qsolve's backends, records every circuit that leaves your code, re-evaluates every answer and measures the numbers. The platform runs this same package inside its sandbox, so a workflow that passes qsolve test on your machine behaves the same on Qsolve.

This page is the map. Each area has its own reference page with every public name, its signature, parameters, return value, exceptions and an example.

Install

pip install qsolve-sdk            # the package; Python 3.12 or newer, Qiskit 2.x
pip install "qsolve-sdk[ibm]"     # also the IBM runtime: device noise models and IBM hardware

The package installs the qsolve command (see The qsolve command line) and the Python package qsolve. The ibm extra is needed for fake:<device> noise-model targets as well as for real IBM hardware, so install it if you use either (the scaffold's third benchmark case uses a noise model).

import qsolve
print(qsolve.__version__)      # for example "1.0.0"; "0.0.0+local" when run from an uninstalled source tree

What you import

Everything a workflow needs is exported from the top-level package. These 24 names are the whole of qsolve.__all__:

A workflow's own code normally needs only the first seven names plus Estimate:

from qsolve import Context, Estimate, InvalidSolution, MethodUnavailable, Outcome, Workflow, WorkflowError

Module map

Names outside qsolve.__all__ are importable from their module (from qsolve.metering import fidelity) and are documented in the pages below, but they are the harness's own machinery, not the contract with your workflow. See What is stable.

How the pieces fit

qsolve.yaml  ->  load_workflow()  ->  Manifest + two JSON Schemas
                      |
input.json  ->  validate_input()      (jsonschema; WorkflowError on a mismatch)
                      |
        _instantiate(): import entrypoint, YourWorkflow(input, params), size() vs envelope
                      |
   run_methods(): every declared method, reference and classical first, quantum last
        |                  |
        | classical ctx    | quantum ctx
        | backend refuses  | QsolveBackend -> Backend (Aer | fake | IBM | executor)
        |                  |          every circuit, shot and count -> metering.Recorder
        v                  v
   evaluate(solution) recomputes each objective      -> MethodResult (recomputed | reported)
        |
   headline(): accuracy, +/-, matches                -> Metrics
   metering.quality(): fidelity, depth, 2q gates     -> Quality
   answer(outcome) + output schema check             -> Result.answer
        |
   RunOutput(result=Result, provenance=Provenance)

In words:

1. You write a Workflow subclass (The Workflow class) and a manifest (The manifest).
2. The runner (run_workflow) loads and validates everything, builds your class, and calls run_methods (Runner and manifest).
3. Each method gets a Context. The quantum method's ctx.sampler, ctx.estimator and ctx.backend are the bridge objects, which send circuits to a backend; the classical methods get a context whose backend refuses (Backends and the Qiskit bridge).
4. Everything that crosses the backend is recorded by metering.Recorder, from which Qsolve computes circuit size and fidelity without trusting your code (Metering and cost).
5. The comparison recomputes each objective with your evaluate, flags contradictions and computes accuracy against the reference.
6. The output is a Result and a Provenance (Results and events).
7. qsolve test (run_benchmarks) runs this pipeline for every benchmark case and adds the validation gates; qsolve lint is the static check (Testing, linting and the sandbox).

When the platform calls what, and when you do

Environment variables

What is stable

Compatibility policy, in one place:

Versioning: the SDK follows semantic versioning (MAJOR.MINOR.PATCH): a patch fixes bugs only, a minor adds features without breaking public names, a major may break them. The workflow manifest has its own schema_version (currently 1); see Versioning.

Reference pages

• The Workflow class: Workflow, Outcome, Context, the exceptions.
• Runner and manifest: run_workflow, estimate_run, validate_input, load_workflow, Manifest, run_methods, headline.
• Backends and the Qiskit bridge: targets, get_backend, every backend class, QsolveBackend, QsolveSampler, QsolveEstimator.
• Metering and cost: Recorder, fidelity, Estimate, run-time prediction in qsolve.sim.
• Results and events: every field of Result, Provenance and friends; emit; circuit records.
• Testing, linting and the sandbox: run_benchmarks, case and gate models, lint_workflow, sandbox_entry.
• The qsolve command line: every command and flag.

Schema and manifest details live in their own references: The manifest, Parameters, Input schema reference, Output schema reference, Benchmarks and Lint codes.