Mine scenario file format

Version: 1 (format_version field)

This JSON format describes one mine for both the A* dispatcher and the MILP shift planner. It matches the Story 2.1 scenario schema, with an explicit format version for on-disk files.

Units

Quantity	Unit
Demand	tons
Truck capacity	tons
Shift length	hours
Arc travel time	minutes

Top-level fields

Name	Type	Unit	Required	Description
`format_version`	string	—	yes (files)	Format version. Supported: `"1"`.
`locations`	array of objects	—	yes	Named places with queue capacity.
`arcs`	array of objects	—	yes	Directed travel links.
`demands`	array of objects	—	yes	Haul demand by source/destination.
`trucks`	array of objects	—	yes	Fleet members and capacities.
`shift_length_hours`	number	hours	yes	Shift horizon length.
`fleet_size`	integer	trucks	yes	Maximum trucks available.

`locations[]`

Name	Type	Unit	Required	Description
`name`	string	—	yes	Unique location id (e.g. `garage`, `S1`).
`resident_capacity`	integer	trucks	yes	Max trucks that may queue here (≥ 0).

`arcs[]`

Name	Type	Unit	Required	Description
`source`	string	—	yes	Must name a location.
`destination`	string	—	yes	Must name a location.
`travel_time_minutes`	number	minutes	yes	Positive travel time.
`distance`	number	(optional)	no	Optional distance; unused by solvers today.

`demands[]`

Name	Type	Unit	Required	Description
`source`	string	—	yes	Must name a location.
`destination`	string	—	yes	Must name a location.
`tons`	number	tons	yes	Non-negative tonnage for the shift.

`trucks[]`

Name	Type	Unit	Required	Description
`name`	string	—	yes	Unique truck id.
`tonnage_capacity`	number	tons	yes	Positive payload capacity.

Validation

Loading a file through core.scenario.load_scenario_file rejects:

a missing required field (error names the field)
an unknown location on an arc or demand (error names the location)
an unsupported format_version (error names the version)

Sample files

File	Status
`samples/tiny_feasible.json`	Small feasible mine (dispatch + shift plan)
`samples/toy_mine.json`	Published synthetic fixture (dispatch)
Haul-history anonymized sample	Not published until the data owner approves release

Python API

from core.scenario import load_scenario_file, write_scenario_file

scenario = load_scenario_file("samples/toy_mine.json")
write_scenario_file(scenario, "out/copy.json")