Concepts

DynaSchedBench separates dynamic scheduling experiments into a few explicit objects. Understanding these objects makes the command-line tools much easier to use.

Input Model

An InputModel JSON file describes the scheduling problem before any random events are generated. It contains:

  • plant: machines, machine groups, job families, and routes.

  • scale: horizon, optional fixed job count, and validation-only scale hints.

  • dynamics: arrival-rate pattern over time.

  • targets: desired utilization, due-date tightness, arrival variability, processing-time variability, disturbance level, and load balance.

  • dynamic_scenarios: probabilities for cancellations, priority changes, emergency jobs, processing-time changes, maintenance, batches, route changes, and due-date changes.

  • calibration: how the generator should tune parameters to match targets.

  • outputs: default output directory when dsbx-gen gen is not given -o.

The schema is defined by dsbx.Gen.models.inputs.InputModel.

Generated Instance

dsbx-gen gen transforms an input model into a concrete dynamic scheduling instance. A generated instance directory is the handoff point between the generator, simulator, agents, evaluation, and visualization.

Typical files are:

  • input_model.json: normalized model used by the generator.

  • events.jsonl: event stream, one JSON event per line.

  • static_jobs.json: generated jobs, families, routes, and due dates.

  • static_machines.json: generated machines and groups.

  • final_metrics.json: realized instance-level metrics.

  • pareto_info.json: Pareto-front metadata for MOO or hybrid calibration.

  • report.md: readable generation report.

Event Stream

The simulator consumes events.jsonl. Events represent external dynamics such as arrivals, cancellations, priority changes, machine breakdowns, maintenance, processing-time changes, route changes, rework, and due-date changes. Events are applied over simulated time. Scheduling actions are not stored in this file; they are produced by agents during rollout.

Simulator Snapshot

A Snapshot is the simulator state at a decision time. It includes current time, machine states, queues, jobs, operation states, and static context. The snapshot is used by:

  • dsbx.Env.DynaSchedEnv to build observations and legal actions.

  • Agents to choose scheduling actions.

  • Evaluation to compute metrics.

  • Visualization to draw final schedules and time-series diagnostics.

Environment And Agent

DynaSchedEnv wraps the simulator as a single-agent environment. At each decision point:

  1. The environment returns an observation.

  2. The agent reads legal actions.

  3. The agent selects one action or lets time advance when no action is legal.

  4. The environment applies the action and records a trajectory step.

Actions use job and machine information, commonly:

{
  "job_id": "job_0001",
  "machine_group": "cutting",
  "machine_id": "cut-1"
}

machine_id is optional for agents that select only a machine group; the environment can resolve candidates when possible.

Trajectory

A trajectory records an agent rollout. DynaSchedBench supports both full JSON trajectories and streaming JSONL summaries for large runs.

Use trajectories for:

  • recomputing metrics with dsbx-eval from-trajectory;

  • checking hard scheduling constraints with dsbx-eval check-schedule;

  • plotting Gantt charts and metric curves with dsbx-vis;

  • debugging LLM decisions with the specialized debug commands.

Cold-Start And Warm-Start Modes

Cold-start experiments begin with an initially empty system and arrivals over time. Warm-start experiments initialize work in process before the first decision. The input model controls this through evaluation.mode and evaluation.initial_wip_method. Evaluation and visualization commands also provide --warm and --warmup-ratio options to ignore an initial warm-up window when computing or plotting selected metrics.