The manifest

qsolve.yaml sits at the root of a workflow repository. It names the workflow, points to its schemas and class, declares its parameters and methods, and sets its size and resource limits. It is the only place these are declared, and the platform stores a copy of it with every published version.

How the manifest is checked

Three checks read it, in this order:

1. Load (qsolve validate, and the first thing every other command does). The file must be valid YAML and match the model below. Failure prints Invalid workflow: followed by the reason and exits 1. On submission and in qsolve lint the same failure is reported as lint error E002 (invalid workflow definition: ...); a missing file is E001.
2. Schema files. The two schema paths are read. See Input and output schemas.
3. Lint and gates. Further manifest rules (examples, license, hardware cases) are lint codes; see Lint codes.

Rules that apply at every level:

• Unknown keys are rejected, in the top level and in every nested object. A typo such as enveloppe: fails the load with the validator's Extra inputs are not permitted message naming the key.
• Required keys that are missing fail with Field required. Wrong types fail with a message naming the field; for example, version: 1.0 is read by YAML as a number and rejected, so write 1.0.0.
• Values are not coerced. A string where a number is expected, or a number where a string is expected, is an error.

The platform also re-validates the stored manifest every time it accepts a run, with the same code.

A complete manifest

This is the manifest of the max-cut example (version 1.0.2), which uses every section. Long prose strings are shortened here; the full file is in examples/max-cut/qsolve.yaml.

schema_version: 1
name: max-cut
version: 1.0.2
family: qubo_optimization
summary: Split a weighted graph into two groups to maximize the total weight of edges between them (network partitioning, clustering, circuit layout)
license: Apache-2.0
tags: [graph, partitioning, qubo, qaoa, logistics]

inputs:
  schema: schemas/input.json
  examples: [examples/ring_6.json]
parameters:
  - {name: layers, label: Circuit depth, type: int, default: 3, min: 1, max: 8, description: "More layers can find better answers but take longer to train"}
  - {name: shots, label: Final shots, type: int, default: 4000, min: 100, max: 20000, description: Final sampling shots}
  - {name: train_shots, label: Shots per training step, type: int, default: 1000, min: 100, max: 8000, description: Shots per optimizer step when training is sampled}
  - {name: optimizer_iters, label: Optimiser iterations, type: int, default: 100, min: 5, max: 400, description: COBYLA iterations}
  - {name: train_on, label: Train angles on, type: enum, default: sim, choices: [sim, backend], description: "sim trains noise-free and uses the device only to measure"}
outputs:
  schema: schemas/output.json

entrypoint: src.workflow:MaxCut

category: Networks and logistics
objective: {label: Negative cut weight, unit: "", decimals: 3}
metric: {kind: relative_gap, note: "100% means the quantum objective equals the best classical objective. It falls by the relative amount the quantum objective is worse."}
methods:
  - id: qaoa
    role: quantum
    title: QAOA (quantum approximate optimisation)
    what: A short quantum circuit that alternates between favouring low-cost answers and mixing possibilities.
    strength: Samples good answers directly from a quantum state.
    limit: On today's noisy chips only small circuits stay faithful.
  - id: exhaustive-or-annealing
    role: reference
    title: Exhaustive search (annealing beyond 22 variables)
    what: Tries every possible answer and keeps the best one.
    strength: Provably the best answer whenever it can run exhaustively.
    limit: Beyond 22 variables it is a heuristic with no guarantee.
  - id: annealing
    role: classical
    title: Simulated annealing
    what: Starts from a random answer and keeps trying small changes.
    strength: Fast, scales to large problems, and usually lands close to the best answer.
    limit: No guarantee that it finds the best answer.

envelope:
  max_qubits: 24
  max_variables: 24
  notes: "Up to 24 nodes per run"

targets:
  simulators: [cpu, gpu]
  qpu: [ibm]
  min_qubits_qpu: 4

resources:
  timeout_s: 1800
  memory_mb: 1536
  network: none

runtime:
  python: "3.12"
  dependencies: requirements.lock

Top-level fields

Things that are not manifest keys

Because unknown keys are rejected, these will fail the load if you add them:

• Visibility, first-party status, ownership. The platform sets them: a new developer workflow starts unlisted and becomes public when an admin approves it (or when auto-publish is on). There is nothing to declare.
• Pricing and cost hints. There is no price field. The quote for a run comes from what your estimate() returns and the platform's rate card; see Credits and pricing and Writing the workflow.
• Error mitigation. Mitigation is code you write, and you report its result at run time with ctx.report_mitigation(...). There is no manifest switch; see Error mitigation and fidelity.
• Benchmark cases and hardware cases. They live in benchmarks/cases.yaml; see Benchmarks.

Inputs and outputs

Both have the same shape:

For inputs, at least one example is required (lint E024), and each must read and validate against the input schema (lint E023). The example files are copied into the version's record and shown to researchers as starting points. For outputs, examples is accepted but not used. The schema files themselves are checked by lint E020 to E022 (see Input and output schemas).

Parameters

Each entry declares one setting a user can change. Every field, the type rules and how values reach your code are in Parameters. In short:

objective

Describes the number each method reaches, so every value is shown with the right label and unit. The platform never writes this text itself.

metric

Picks one of three accuracy formulas. You choose a kind and explain it in words; you do not supply a formula. Benchmarks gives the formulas and the rule for when a result matches the baseline.

Methods

methods lists every method Qsolve runs and compares on each input. You need exactly one quantum and exactly one reference, any number of classical, and at least two methods in total. The platform runs the classical methods first and the quantum method last.

List-level errors: method ids must be unique, and declare exactly one method with role 'quantum' (or 'reference'). A list with fewer than two methods also fails the load.

Each method is implemented by a method of your Workflow class. The role decides the name, and the id only matters for classical:

A declared method with no matching Python method stops the run with method 'x' is declared in the manifest but the workflow has no name method. A reference method that touches the quantum backend fails the run with QuantumNotAllowed; a classical one that does is shown as unavailable. Qsolve shows title, what, strength and limit as written and never writes its own text about your workflow, so write for someone who does not know the method.

envelope

The largest problem the workflow accepts.

How it is enforced:

• After your __init__ runs, Qsolve calls size() and refuses the input if the result is greater than either max_variables or max_qubits, before any circuit runs and before anything is charged. The message is Problem has <n> variables; this workflow supports at most <smaller of the two> (<notes>). In practice the smaller of the two is the limit.
• max_qubits is also a hard cap in the sandbox: a circuit with more qubits than this is refused by the executor with circuit exceeds the allowed qubit count.
• The input form shows notes next to "Your problem".
• It is separate from your input schema bounds. The schema (maxItems, maximum, ...) rejects a malformed input with Invalid input at <path>: <reason>; the envelope rejects a well-formed input whose size, as your size() reports it, is too big. Set both: schema bounds so the form can show limits early, and the envelope as the size limit that holds whatever shape the input takes.

targets

A run requesting an unlisted target is refused with HTTP 422 target_not_supported and the message This workflow does not support target 'x'., with the workflow's lists attached. For ibm:<device>, the device name after the colon must match ^[A-Za-z0-9_.-]{1,64}$. Noise-model targets (fake:...) are not accepted by the run API, so they are not listed here; they exist for benchmark cases and local runs. If hardware_cases are declared in benchmarks/cases.yaml, qpu: [ibm] is required (lint E054). See Backends and targets and Machines and targets.

resources

How the limits are applied:

• Timeout. The sandbox stops a run at timeout_s with exceeded its <n>s compute limit. The platform also caps every run at its own maximum, 4 hours by default, whatever the manifest asks. Time spent waiting for a quantum computer does not count against it: the limit is extended by the queue wait, up to a platform cap (6 hours by default).
• Up-front check. If the run time predicted from your estimate() (its runtime_s, to which the SDK adds 20 s of run overhead) is above the effective limit (the smaller of timeout_s and the platform cap), the run is refused before it starts with run_too_long.
• Validation. The benchmark run during validation uses a time limit of timeout_s raised to at least 300 seconds and capped at 7200, and memory capped at 8192 MB. A heavy workflow therefore gets its whole timeout_s up to 2 hours while validating.

runtime

Examples of choices

A chemistry workflow measures energies, so it uses an absolute tolerance in the objective's units. From molecular-ground-state:

objective: {label: Ground-state energy, unit: "Ha", decimals: 6}
metric: {kind: relative_error, tolerance_abs: 0.0016, note: "1 minus the energy difference to the exact active-space answer, as a fraction of that answer. Total energies are large numbers, so read the error in mHa too: chemical accuracy is 1.6 mHa."}

A classifier's objective is an error rate. From quantum-kernel-classifier:

objective: {label: Test error rate, unit: "", decimals: 3}
metric: {kind: error_rate, note: "Share of held-out test points classified correctly, with its 95% interval. Fewer test points mean a wider interval."}

An error-rate workflow must put the number of test cases in its quantum method's Outcome.details as n_test, so the interval can be computed. See Writing the workflow.

Resources scale with the work. max-cut (a 24-variable QAOA) asks for the defaults of 1800 s and 1536 MB; molecular-ground-state runs a chemistry solver, so it asks for timeout_s: 3600 and memory_mb: 2048; electrolyte-solvent-screen runs up to eight chemistry systems and asks for timeout_s: 7200. The envelope scales the same way: 24 qubits for the graph problems, 12 for the chemistry ones (6 active orbitals), 8 for the kernel classifier (one qubit per feature).

Validate it

qsolve validate .

A manifest error prints Invalid workflow: with the field and reason, and exits 1. After the manifest loads, validate also checks that every example validates against the input schema. Common errors are in Troubleshooting and every lint code is in Lint codes.