Quickstart

This page walks through the shortest useful DynaSchedBench workflow: install the package, generate one dynamic scheduling instance, run a baseline agent, evaluate the trajectory, and create plots.

1. Install DynaSchedBench

Install the public package from PyPI:

pip install dsbx

For development from a cloned repository:

python -m pip install -e .[dev,docs]

Confirm that the five release commands are available:

dsbx-gen --help
dsbx-agent --help
dsbx-eval --help
dsbx-vis --help
dsbx-sim --help

2. Prepare an input model

DynaSchedBench generation starts from an InputModel JSON file. The repository contains a compact tutorial example at docs/examples/minimal_input_model.json.

If you are reading this page on Read the Docs, create a local file named examples/minimal_input_model.json and copy the JSON from Input Model And Instance Format.

3. Generate an instance

dsbx-gen gen \
  -i docs/examples/minimal_input_model.json \
  -o runs/minimal \
  --max-calib-steps 5

The generated directory is the main artifact consumed by later commands. It contains:

• input_model.json: normalized configuration used for the run.

• events.jsonl: dynamic event stream.

• static_jobs.json: generated jobs and routes.

• static_machines.json: generated machine definitions.

• final_metrics.json: instance-level target/realized metrics.

• report.md: human-readable generation report.

4. Validate the event stream

dsbx-eval check-events \
  -c runs/minimal/input_model.json \
  -e runs/minimal/events.jsonl \
  --strict-events

Use this before running many agents. It catches malformed event streams, undefined job references, invalid dynamic-event ordering, and target-feasibility issues.

5. Run a baseline agent

dsbx-agent run \
  -d runs/minimal \
  -o runs/minimal/spt \
  -a spt \
  --random-seed 42

The -d/--dir argument points to the generated instance directory, not the original configuration file. Common alternatives are:

dsbx-agent run -d runs/minimal -o runs/minimal/random -a random --random-seed 42
dsbx-agent run -d runs/minimal -o runs/minimal/pdr_spt_lit -a pdr:SPT:LIT
dsbx-agent list-agents

Agent output usually includes:

• trajectory.json: full in-memory trajectory when enabled.

• trajectory_light.jsonl: streaming trajectory summary for large runs.

• metrics.json: scalar metrics from evaluate_trajectory.

• gantt.pdf: default schedule visualization.

6. Evaluate and visualize

dsbx-eval from-trajectory \
  -t runs/minimal/spt/trajectory_light.jsonl \
  -o runs/minimal/spt/metrics_recomputed.json

dsbx-vis gantt \
  -t runs/minimal/spt/trajectory_light.jsonl \
  -o runs/minimal/spt/gantt.pdf

dsbx-vis metric-curve \
  -t runs/minimal/spt/trajectory_light.jsonl \
  -m wip \
  -o runs/minimal/spt/wip.pdf

dsbx-vis events-timeline \
  -e runs/minimal/events.jsonl \
  -o runs/minimal/events_timeline.png

7. Use the Python API

The same scheduling loop can be embedded in experiments:

from pathlib import Path

from dsbx.Agents import SPTAgent
from dsbx.Env import DynaSchedEnv
from dsbx.Eval.Metrics import evaluate_trajectory
from dsbx.Gen import load_input_model

model = load_input_model(Path("docs/examples/minimal_input_model.json"))
env = DynaSchedEnv(model)
agent = SPTAgent()

obs = env.reset()
done = False

while not done:
    legal_actions = env.legal_actions()
    if not legal_actions:
        obs = env.advance_if_idle()
        continue

    action = agent.act(obs, legal_actions, env)
    obs, reward, done, info = env.step(action)

metrics = evaluate_trajectory(env.get_trajectory())
print(metrics)

For a deeper walkthrough, continue with Workflows.