The qsolve command line

qsolve is installed with qsolve-sdk (pip install "qsolve-sdk[ibm]"). It is a Typer application with six commands, all working on a workflow directory on your machine. The platform runs the same SDK code, so these are the checks it applies. The Python behind each command is documented in the SDK reference.

Global options

qsolve [OPTIONS] COMMAND [ARGS]...

Running qsolve with no command prints the help and exits 2 (the usage-error code of the Click library under Typer).

Targets

The --target option of run, estimate and test takes one of:

See Backends and targets. estimate does not run anything, so its --target is only passed to your workflow's estimate(); it is not checked.

Environment variables

Exit codes

qsolve init

qsolve init NAME [--summary TEXT] [--directory PATH]

Creates a complete workflow in <directory>/<NAME> that solves a small QUBO with QAOA and passes every gate.

Files created:

<NAME>/
  qsolve.yaml               the manifest, with name and summary filled in
  README.md                 a short readme with the develop commands
  benchmarks/cases.yaml     three cases: two noise-free, one on fake:fez@1.6
  examples/qubo_5.json      a 5-variable example input
  schemas/input.json
  schemas/output.json
  src/__init__.py
  src/workflow.py           the Qiskit workflow (class Qubo)
  tests/test_workflow.py    a pytest file that runs the example through run_workflow

It creates no LICENSE and no requirements.lock, so qsolve lint warns W051 until you add a license file. File meanings: Project layout. Walk-through: Your first workflow.

On success it prints:

Created <path>
Next: cd <NAME> && qsolve test .   (edit src/workflow.py: it is plain Qiskit)

The summary and the name are written into qsolve.yaml as quoted YAML strings, so --summary "Pick: the depots # fast" is stored exactly as typed.

qsolve validate

qsolve validate [WORKFLOW]

Loads qsolve.yaml, reads both schema files and checks every example input listed under inputs.examples against the input schema. Prints, in green:

OK depot-picker v0.1.0

validate does not check the schemas against Qsolve's restrictions and does not inspect your code; lint does that. It does not require that at least one example exists; lint and test do.

qsolve lint

qsolve lint [WORKFLOW]

Runs the static checks the platform applies before it executes anything. None of your code runs. Each finding is one line: the severity (upper case, padded to 7 characters), the code, the message and, when there is one, the path (relative to the workflow, shown dim):

WARNING W051 no LICENSE file found
0 error(s), 1 warning(s)

With no findings it prints No problems found. Otherwise the last line is <n> error(s), <m> warning(s). Errors print in red, warnings in yellow. It exits 1 when there is at least one error; warnings alone exit 0. A missing or invalid manifest is reported as a finding (E001, E002), not as a crash. Every code is explained in Lint codes.

qsolve run

qsolve run WORKFLOW --input FILE [--target T] [--seed N] [--param key=value]... [--out FILE]

Runs the workflow once on one input, with every declared method.

qsolve run . -i examples/qubo_5.json --seed 1 -p layers=1

            depot-picker v0.1.0 on aer-cpu
┌───────────────────────────────┬─────────────────────┐
│ Metric                        │ Value               │
├───────────────────────────────┼─────────────────────┤
│ Objective (quantum)           │ -10                 │
│ Objective (Exhaustive search) │ -10                 │
│ Gap vs baseline               │ 0.000%              │
│ Uncertainty                   │ exact (stderr None) │
│ Shots                         │ 4000                │
│ Run time (s)                  │ 2.22                │
└───────────────────────────────┴─────────────────────┘
QAOA (quantum approximate optimisation): -10; Exhaustive search: -10 (accuracy 100.00%).

The table title is <workflow> v<version> on <device>. The row labelled with the reference is named after the reference method's manifest title. After the table it prints the result's summary sentence, and Wrote <path> when --out was given.

The --out file is the RunOutput as JSON: a result object (answer, objectives, gap, uncertainty, per-method results, metrics, quality measurements) and a provenance object (input hash, parameters, seed, target, device, shots, timings, result hash). Every field is described in Results and events.

An unexpected exception in your own code, or a workflow directory with no valid qsolve.yaml (use validate first), is not caught by run and prints a Python traceback, exit code 1.

qsolve estimate

qsolve estimate WORKFLOW --input FILE [--target T]

Validates the input and sizes the run without executing any method (no circuit runs), printing the estimate as JSON.

{
  "qubits": 5,
  "circuits_on_target": 1,
  "shots_on_target": 4000,
  "classical_cost_class": "low",
  "runtime_s": null,
  "notes": [],
  "by_default": false
}

by_default is true when the workflow gives no estimate() and Qsolve fell back to one circuit and params["shots"] shots. runtime_s, when the workflow predicts it, includes the fixed 20 s run overhead. There is no --param option, so the estimate uses the manifest defaults. Errors are the same Error: <message> lines as for run (invalid input, envelope, and so on), exit 1. The fields are explained in Metering and cost.

qsolve test

qsolve test [WORKFLOW] [--target T] [--out FILE]

Runs the validation gates and every benchmark case, as the platform does on submission.

It prints a table of gates (name, pass or FAIL, detail), a table of cases titled Cases on <target> (name, result, relative gap, mitigated fidelity, seconds; - for a missing value; a failed case shows its reason after FAIL), then ALL GATES PASSED in green or FAILED in red. See Your first workflow for a real output and Benchmarks for each gate and expect key. The JSON report holds workflow, version, target, passed, gates, cases and total_time_s (BenchmarkReport).

A target that cannot be used (for example ibm: without a token) does not stop the command; each affected case fails with the reason in its row. qsolve test runs every case once, then the first case again and an estimate, so with --target ibm:<device> it spends your own IBM quota. qsolve test does not run lint; run qsolve lint . too, because the platform runs both. Cases listed under hardware_cases: are never run by qsolve test.

A typical loop

qsolve validate . && qsolve lint . && qsolve test .

Because every command exits non-zero on failure, this stops at the first problem. Run it before every submission; see Validation and publishing.

The same checks from Python