Sync RouteOptimizer Hub snapshot (samples, format, license)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018-2026 Alfonso Bonillas / alioit.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,122 @@
+---
+license: mit
+pretty_name: RouteOptimizer
+tags:
+  - optimization
+  - operations-research
+  - mining
+  - fleet-dispatch
+  - milp
+  - pulp
+  - cbc
+  - routing
+task_categories:
+  - other
+---
+
+# RouteOptimizer
+
+**This is an operations-research optimization solver, not a machine-learning model.**
+There are **no trained weights**, no checkpoints, and no neural network to download.
+The files here are **sample mine scenarios**, the **scenario file format**, and pointers
+to install the solver itself.
+
+Rights: Alfonso Bonillas / [alioit.com](http://www.alioit.com). License: **MIT**
+([`LICENSE`](LICENSE)).
+
+## What it does
+
+- **Dispatch (A\*)** — builds a truck movement plan over a shift horizon from a
+  scenario file.
+- **Shift plan (MILP)** — solves a mine-wide truck-flow plan with **PuLP + CBC**
+  (open-source; no commercial solver license).
+
+Both tools read local JSON scenarios and write JSON results. They do **not** call
+SQL Server or the network at run time.
+
+## What it does not do
+
+- It does **not** train or serve ML models.
+- It does **not** include production haul databases or live telematics.
+- It does **not** require Gurobi, CPLEX, or other commercial solvers.
+- A second anonymized haul-history sample is **not** published until the data
+  owner approves release.
+
+## Install
+
+### pip package
+
+From the [GitHub repository](https://github.com/AlfonsoALIO/RouteOptimizer):
+
+```bash
+pip install "PuLP>=2.7,<3"
+pip install git+https://github.com/AlfonsoALIO/RouteOptimizer.git
+```
+
+Or clone and install locally:
+
+```bash
+git clone https://github.com/AlfonsoALIO/RouteOptimizer.git
+cd RouteOptimizer
+pip install .
+```
+
+Console scripts: `route-optimizer`, `route-optimizer-dispatch`,
+`route-optimizer-shift-plan`.
+
+### Docker image
+
+Build from the same repository (image tag matches the package version in
+`pyproject.toml`, currently `0.1.0`):
+
+```bash
+git clone https://github.com/AlfonsoALIO/RouteOptimizer.git
+cd RouteOptimizer
+./scripts/build_docker.sh
+# → route-optimizer:0.1.0
+```
+
+Run with a mounted folder and networking disabled:
+
+```bash
+docker run --rm --network=none \
+  -v "$PWD/samples:/data/samples:ro" \
+  -v "$PWD/out:/data/out" \
+  route-optimizer:0.1.0 \
+  dispatch /data/samples/tiny_feasible.json -o /data/out/dispatch.json --segments 8 --trucks 2
+```
+
+## Scenario file format
+
+See [`docs/scenario-format.md`](docs/scenario-format.md) (format version `"1"`).
+Units: tons, hours, minutes.
+
+## Sample scenarios
+
+| File | Role |
+|------|------|
+| [`samples/tiny_feasible.json`](samples/tiny_feasible.json) | Small mine; **dispatch and shift-plan** both succeed quickly |
+| [`samples/toy_mine.json`](samples/toy_mine.json) | Larger synthetic toy mine used by the in-repo fixture (dispatch) |
+
+```bash
+# pip — end-to-end on the small sample
+route-optimizer dispatch samples/tiny_feasible.json -o out/dispatch.json --segments 8 --trucks 2
+route-optimizer shift-plan samples/tiny_feasible.json -o out/shift_plan.json --segments 4
+
+# optional wall-clock cap
+route-optimizer dispatch samples/toy_mine.json -o out/toy_dispatch.json --segments 58 --trucks 21 --time-limit 60
+```
+
+## Links
+
+| Resource | URL |
+|----------|-----|
+| Source / pip install | https://github.com/AlfonsoALIO/RouteOptimizer |
+| Docker build script | https://github.com/AlfonsoALIO/RouteOptimizer/blob/master/scripts/build_docker.sh |
+| Scenario format | [`docs/scenario-format.md`](docs/scenario-format.md) |
+| License | [`LICENSE`](LICENSE) (MIT) |
+| alioit.com | http://www.alioit.com |
+
+## Citation / credit
+
+RouteOptimizer — Alfonso Bonillas / alioit.com — MIT License.

docs/scenario-format.md

@@ -0,0 +1,84 @@
+# 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")
+```

samples/README.md

@@ -0,0 +1,12 @@
+# Sample scenarios
+
+| File | Description |
+|------|-------------|
+| `toy_mine.json` | Published synthetic toy mine (format version 1). |
+| `tiny_feasible.json` | Small feasible mine for fast CLI / solver checks. |
+
+A second sample, exported from haul history and anonymized, will be published
+**only after the data owner approves its release**. It is not included in this
+repository yet.
+
+See [docs/scenario-format.md](../docs/scenario-format.md) for the file format.

samples/tiny_feasible.json

@@ -0,0 +1,63 @@
+{
+  "arcs": [
+    {
+      "destination": "S",
+      "source": "garage",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "garage",
+      "source": "S",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "C",
+      "source": "S",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "S",
+      "source": "C",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "garage",
+      "source": "C",
+      "travel_time_minutes": 15.0
+    }
+  ],
+  "demands": [
+    {
+      "destination": "C",
+      "source": "S",
+      "tons": 100.0
+    }
+  ],
+  "fleet_size": 2,
+  "format_version": "1",
+  "locations": [
+    {
+      "name": "garage",
+      "resident_capacity": 4
+    },
+    {
+      "name": "S",
+      "resident_capacity": 2
+    },
+    {
+      "name": "C",
+      "resident_capacity": 2
+    }
+  ],
+  "shift_length_hours": 1.0,
+  "trucks": [
+    {
+      "name": "truck_1",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_2",
+      "tonnage_capacity": 100.0
+    }
+  ]
+}

samples/toy_mine.json

@@ -0,0 +1,270 @@
+{
+  "arcs": [
+    {
+      "destination": "L1",
+      "source": "garage",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "L2",
+      "source": "garage",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "garage",
+      "source": "L1",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "garage",
+      "source": "L2",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "garage",
+      "source": "W",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "S1",
+      "source": "garage",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "S2",
+      "source": "garage",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "garage",
+      "source": "S1",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "garage",
+      "source": "S2",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "garage",
+      "source": "C",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "L1",
+      "source": "W",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "W",
+      "source": "L1",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "S1",
+      "source": "W",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "W",
+      "source": "S1",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "S2",
+      "source": "W",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "W",
+      "source": "S2",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "S1",
+      "source": "C",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "C",
+      "source": "S1",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "S2",
+      "source": "C",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "C",
+      "source": "S2",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "L2",
+      "source": "C",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "C",
+      "source": "L2",
+      "travel_time_minutes": 15.0
+    },
+    {
+      "destination": "C",
+      "source": "L1",
+      "travel_time_minutes": 15.0
+    }
+  ],
+  "demands": [
+    {
+      "destination": "C",
+      "source": "S1",
+      "tons": 8000.0
+    },
+    {
+      "destination": "C",
+      "source": "S2",
+      "tons": 1200.0
+    },
+    {
+      "destination": "C",
+      "source": "L1",
+      "tons": 4000.0
+    },
+    {
+      "destination": "W",
+      "source": "S1",
+      "tons": 1600.0
+    },
+    {
+      "destination": "W",
+      "source": "S2",
+      "tons": 2000.0
+    },
+    {
+      "destination": "W",
+      "source": "L1",
+      "tons": 1000.0
+    }
+  ],
+  "fleet_size": 21,
+  "format_version": "1",
+  "locations": [
+    {
+      "name": "S1",
+      "resident_capacity": 2
+    },
+    {
+      "name": "S2",
+      "resident_capacity": 2
+    },
+    {
+      "name": "L1",
+      "resident_capacity": 2
+    },
+    {
+      "name": "L2",
+      "resident_capacity": 2
+    },
+    {
+      "name": "W",
+      "resident_capacity": 2
+    },
+    {
+      "name": "C",
+      "resident_capacity": 2
+    },
+    {
+      "name": "garage",
+      "resident_capacity": 21
+    }
+  ],
+  "shift_length_hours": 12.0,
+  "trucks": [
+    {
+      "name": "truck_1",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_2",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_3",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_4",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_5",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_6",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_7",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_8",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_9",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_10",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_11",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_12",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_13",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_14",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_15",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_16",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_17",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_18",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_19",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_20",
+      "tonnage_capacity": 100.0
+    },
+    {
+      "name": "truck_21",
+      "tonnage_capacity": 100.0
+    }
+  ]
+}