| # 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`](../samples/tiny_feasible.json) | Small feasible mine (dispatch + shift plan) | |
| | [`samples/toy_mine.json`](../samples/toy_mine.json) | Published synthetic fixture (dispatch) | |
| | Haul-history anonymized sample | **Not published** until the data owner approves release | |
|
|
| ## Python API |
|
|
| ```python |
| 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") |
| ``` |
|
|
