Quick Start

Run your first scheduling campaign in two commands. Both are copy-paste, the whole path finishes in seconds on a fresh clone, and every result is deterministic — re-running prints the same numbers.

⚡ Two Commands To A First Run

# 1 — install the workspace (one time)
uv sync --all-extras --group dev
 
# 2 — build and run the bundled smoke campaign
uv run python experiments/scripts/run_smoke_pilot.py

The script serializes its configuration to experiments/configs/smoke-pilot.json — the same JSON the dispatchatlas-lab subcommands (validate, run) consume via --config — so the script and the CLI examples in the troubleshooting guide run the identical recipe.

You should see a short summary like this:

campaign_id: smoke-pilot
config: ...\experiments\configs\smoke-pilot.json
planned_runs: 4
estimated_wall_time_seconds: 2.0
completed_runs: 4
failed_attempts: 0

completed_runs: 4 with failed_attempts: 0 means it worked: two solvers each ran against two benchmark instances, and every run produced a valid schedule. Any other result points at an incomplete install — see troubleshooting.

🧩 First-Use Terms

The summary above uses a handful of domain terms. The whole toolkit is built on these:

• Benchmark instance — one generated scheduling problem: a set of tasks, the resources that run them (a task may demand several at once), and the constraints between them.
• Solver — an algorithm that assigns tasks to resources over time and returns a schedule.
• Objective — the quantity a solver optimizes. The smoke campaign uses makespan: the moment the last task finishes (lower is better).
• Campaign — a batch that runs chosen solvers across chosen benchmarks for a set number of repeats, recording every run as evidence.
• Seed / deterministic — a fixed number that makes every random choice reproducible, so the same inputs always yield the same schedule.
• Feasible — a schedule where every task is placed, no resource is over-committed, and every dependency is respected.

🛠️ Build A Solve Yourself

To construct a single solve in code rather than running the bundled campaign, save this as quickstart.py anywhere inside the checkout and run it with uv run python quickstart.py:

from dispatchatlas.bench import smoke_benchmark_provider
from dispatchatlas.core import DisclosureLabel, TerminationPolicy, derive_seed
from dispatchatlas.solve import default_solver_registry
 
provider = smoke_benchmark_provider(root_seed=20260527)
problem = provider.get_problem(provider.list_problem_ids()[0])
 
registry = default_solver_registry()
solvers = registry.select(
    objective="makespan",
    disclosure_label=DisclosureLabel.CORE,
)
 
solver = registry.create(solvers[0].solver_id)
run = solver.solve(
    problem=problem,
    stop=TerminationPolicy(max_iterations=solvers[0].default_stop.max_iterations),
    seed=derive_seed(20260527, "docs.quickstart", 0),
)
 
print(run.result.feasible)

It prints True: the selected solver produced a feasible schedule. The three moving parts mirror the campaign above — smoke_benchmark_provider materializes the deterministic benchmark catalog from one seed, registry.select filters solvers to those that support the makespan objective at the public core evidence tier, and solver.solve runs under explicit stop criteria with a seed derived from stable coordinates so the run replays identically.

🧭 Where To Go Next

1. Take the guided tour — a narrated walk of the whole generate → solve → analyze → explore arc that builds on the smoke campaign you just ran.
2. Work through the tutorials — first compare two solvers on one benchmark instance, then run a small campaign and read its results.
3. Graduate to the campaign engine and the reproducible campaigns workspace for checkpointed, resumable runs.
4. Explore how the same metadata drives the benchmark catalog, result preview, and solver recommender.