The seven example workflows

The examples repository holds seven complete, self-contained workflows. Copy the closest one and change it. Start with max-cut, then generic-qubo.

Every folder holds README.md, qsolve.yaml, src/workflow.py with the algorithm in small modules beside it, benchmarks/cases.yaml and tests/. Run any of them with qsolve test <folder> or qsolve run <folder> -i <folder>/examples/<file>.json. The chemistry workflows need PySCF (Linux, macOS or WSL).

max-cut

Splits a weighted graph into two groups so the edges between the groups weigh as much as possible.

• Input: nodes, a list of names, and edges as [u, v] or [u, v, weight]. Duplicate edges and self-loops are rejected in __init__.
• Output: the two groups, the cut weight and the total edge weight.
• Parameters: layers, shots, train_shots, optimizer_iters, train_on (sim or backend).
• Methods: QAOA (quantum); exhaustive search, switching to annealing above 22 variables (reference); simulated annealing (classical).
• Cases: six, including a complete graph where low-depth QAOA struggles and a fake:fez@1.6 case with min_fidelity: 0.97.

An edge of weight w is cut when x_i + x_j - 2 x_i x_j = 1, so the workflow builds a QUBO and minimises it; evaluate returns the negative cut weight and answer turns it back. Angles are trained noise-free on a statevector, and only the final circuit goes to the target.

Learn from it: estimate() built from a plan of circuits and shots, so the quote matches the run; the quantum method capping itself at two layers on noise-model and hardware targets; one ctx.report_mitigation call declaring readout correction.

generic-qubo

Minimises x'Qx + offset over binary variables for any square matrix, with an optional "exactly k ones" constraint.

• Input: Q (up to 24 by 24), optional labels, offset and cardinality.
• Output: the assignment, the variables set to 1 and the objective value.
• Parameters: the same five as max-cut.
• Cases: six, with and without the cardinality constraint, up to 18 variables.

With cardinality, the circuit starts in the uniform superposition of every state with k ones (a Dicke state) and mixes with an XY ring, so every sample is valid and no penalty term is needed.

Learn from it: optional schema fields, with x-ui: {"advanced": true} on offset, and a constraint handled in the circuit.

portfolio-optimization

Chooses exactly k assets from up to 24, trading expected return against risk: risk_aversion * x'Cx - mu'x with exactly k ones.

• Input: assets, num_to_select, risk_aversion and either expected_returns with covariance, or returns_history. The bundled real-data example holds statistics of 12 US industry portfolios from 2015 to 2024.
• Output: selected assets, equal weights, expected return, risk and whether the constraint holds.
• Parameters: layers, shots, train_shots, optimizer_iters, constraint_mode (mixer or penalty), penalty_scale, init (dicke or product), train_on.
• Cases: nine, including real data, penalty mode and a noise-model case on 5 assets.

Learn from it: a top-level anyOf in the input schema for two ways to describe one problem; x-ui.format: percent in the output schema; enum parameters that switch the method (mixer keeps every sample valid, penalty post-selects); and tolerances that grow honestly with problem size, max_gap: 0.0 at 10 assets and 0.10 at 14.

molecular-ground-state

Ground-state energy of a closed-shell molecule or ion with VQE in a chosen active space, reported beside the exact active-space energy, Hartree-Fock, MP2 and full-space CCSD(T).

• Input: a built-in name (H2, LiH, HF, N2, CO, BeH2, H2O, NH3, CH4, Li+, Na+), or xyz text or atoms; charge; basis; and an optional active_space of up to 6 orbitals.
• Output: the energy in Hartree, kcal/mol, kJ/mol and eV with its error bar, the error against the exact reference, the share of correlation energy recovered, and whether chemical accuracy (1.6 mHa) is met.
• Parameters: ansatz (uccsd or hea), shots, optimizer_iters.
• Methods: VQE (quantum); exact active-space solution, CASCI (reference); Hartree-Fock, MP2 and CCSD(T) (classical).
• Metric: relative_error with tolerance_abs: 0.0016.
• Cases: five, including a custom NH3 geometry and a noise-model case with min_fidelity: 0.99.

The trial state is trained noise-free, then the energy is measured in groups of commuting Pauli terms, one circuit per group, in one batch. On noise-model and hardware targets the workflow uses a compact circuit, mitigates the counts with readout correction, electron-count post-selection and zero-noise extrapolation, and reports them with report_mitigation.

Learn from it: Outcome(solution=None, ...) for measured and library energies, labelled reported; MethodUnavailable when CCSD(T) was not computed; a tolerance in the objective's own units; one batched ctx.sampler.run for many measurement circuits.

interaction-energy

A binding, solvation, adsorption or reaction energy as a signed sum of system energies, each from VQE.

• Input: systems, named species each given as a built-in name or xyz with a charge; basis; an active_space; and optional terms, a coefficient per system. Without terms the first system counts +1 and the others -1, a binding energy.
• Output: the combined energy with error bars, per-system energies and the Hartree-Fock, exact and CCSD(T) references.
• Parameters: ansatz, shots, optimizer_iters.
• Cases: four, including Li+ binding to water and to ammonia, and the energy cost of stretching H2.

Error bars of the combined energy add in quadrature, so a small interaction energy needs more shots than a total energy.

Learn from it: one workflow serving many chemistries through its input; mitigation reported once per measured circuit, with a steps ladder only when a single system is computed.

electrolyte-solvent-screen

Ranks candidate battery-electrolyte solvents by how strongly each binds a Li+ ion, with each binding energy computed by VQE and checked against exact and MP2 references.

• Input: solvents from seven built-in molecules (EC, FEC, DMC, DME, THF, ACN, water), up to four custom_solvents with your own geometries of the molecule and its Li+ complex, basis and active_space.
• Output: a ranking with each binding energy split into mean-field and correlation parts, the strongest and weakest binder, whether the VQE ranking matches the exact one, and any neighbouring pair whose order is inside the error bars.
• Parameters: shots, optimizer_iters, ansatz.
• Resources: a 7200 second limit and 4096 MB, because it builds seven-system problems at 6-31G*.
• Cases: four, with tolerances of about three times the shot noise of the combined objective.

Learn from it: curated data shipped inside the repository (src/geometries.json), since runs have no network; an active space centred on the binding site and chosen identically in the complex and the free solvent, so no fake binding energy appears; results that say "unresolved" instead of ranking inside the noise.

quantum-kernel-classifier

Binary classification with a quantum-kernel support vector machine, tuned by cross-validation and compared on a held-out test set against a tuned RBF-SVM, logistic regression, a random forest and gradient boosting.

• Input: a built-in dataset (breast_cancer, or synthetic moons, circles, xor and blobs), your own data table, or explicit train and test tables; test_fraction.
• Output: test accuracy with a 95% Wilson interval, the best classical accuracy, a paired McNemar test against the RBF-SVM, the confusion matrix, predictions and a check of the measured kernel against the exact one.
• Parameters: reps, bandwidth (both 0 for automatic tuning), shots, kernel_mode (sampled or exact).
• Metric: error_rate. The objective is the test error rate.
• Cases: five, with test sets of 200 or more points.

Every kernel entry is one circuit, and all circuits of a Gram matrix go through ctx.sampler in one call. Each method's solution is its list of predictions and evaluate scores them against the true labels, so no method can claim a better error rate than its predictions earn.

Learn from it: the error_rate metric, which needs n_test in the quantum outcome's details; mitigation by readout correction and a depolarizing rescale fitted on mirror circuits, reported for one representative circuit, with whole-matrix quality in the answer's kernel_check; kernel_mode: exact, which still sends eight spot-check circuits because the quantum method must use the backend.

See Your first workflow and Writing the workflow.