Project layout

Qsolve reads qsolve.yaml at the root of the workflow, and the two schemas, the example inputs and the entrypoint module at the paths qsolve.yaml gives. benchmarks/cases.yaml is read at that fixed path. Everything else is yours.

The workflow does not have to be the whole repository: when you submit, you can name a subfolder (for example workflows/max-cut), and that folder is then the root described here. It must be a relative path of letters, digits, ., _, - and /, never absolute, never .., never starting with a dot. If it holds no qsolve.yaml at the chosen commit, the submission is refused with No qsolve.yaml in the folder '<folder>' of this repository at that commit.

The layout

This is the published max-cut example, which every example follows:

max-cut/
  qsolve.yaml               required
  README.md                 recommended
  LICENSE                   recommended
  schemas/
    input.json              required
    output.json             required
  src/
    __init__.py             keep it: the examples all have one
    workflow.py             your Workflow class
    qubo/                   your own modules (QAOA, classical solvers)
  examples/
    ring_6.json             required: at least one example input
  benchmarks/
    cases.yaml              required to publish
    inputs/                 larger benchmark inputs
  tests/                    your own tests, not published
  requirements.lock         optional

Entrypoint and package name

The manifest's entrypoint is package.module:ClassName. The examples use a package called src, so the entrypoint is src.workflow:MaxCut. Keep src/__init__.py and import your own modules relatively:

from .qubo import Qubo, plan_qaoa, sample_qaoa
from qsolve import Context, Estimate, InvalidSolution, Outcome, Workflow, WorkflowError

Importable modules

Workflows run with no network and no package installs, and your own Dockerfile is ignored. Your code may import:

• the Python standard library;
• qsolve;
• numpy, scipy, sklearn, qiskit, qiskit_aer and pyscf;
• pydantic, jsonschema, yaml, typer and rich.

Anything else is lint error E040. A package pinned in requirements.lock but unavailable produces warning W042, and the run rejects the import, so a workflow that needs another package cannot be published today. Files under tests/ are exempt.

Data files

Ship the data your workflow needs inside the repository and read it from disk, as electrolyte-solvent-screen does with src/geometries.json. A run sees only the repository and a scratch directory. Data-preparation scripts that need other packages belong outside the repository or in a folder your code never imports; the examples keep them in a separate tools/ folder.

Left out of the published snapshot

Publishing stores an immutable copy of the repository. These are skipped:

• directories named __pycache__, .git, .venv, .pytest_cache, .ruff_cache, .mypy_cache, node_modules and tests, wherever they are in the tree, and any file or directory whose name starts with ~;
• .pyc and .pyo files, .DS_Store, Thumbs.db and desktop.ini.

Everything else, including the README, the LICENSE and your example inputs, is in the snapshot, so changing any of it needs a new version, and changing only what is skipped (for example a test) does not. See Versioning.

Limits and rejected content

The lint counts everything except __pycache__, .git, .venv, .pytest_cache, .ruff_cache, .mypy_cache and node_modules, so it counts tests/, while the snapshot step does not. The secret scan skips files over 1 MB and common binary types (.png, .jpg, .gif, .pdf, .zip, .npy, .npz).

Never put a provider token in the repository; your code never needs one. Every lint code is in Lint codes.