Route schedule statistics (PyVRP#716)

N-Wouda · web-flow · commit a7126bb016d1 · 2024-12-17T14:42:53.000+01:00
* Route visit/schedule attributes

* Basic implementation, make the schedule data pickleable

* Add tests

* Add to notebook
diff --git a/docs/source/api/pyvrp.rst b/docs/source/api/pyvrp.rst
@@ -103,6 +103,9 @@ This object can be used to obtain the best observed solution, and detailed runti
    .. autoclass:: ProblemData
       :members:
 
+   .. autoclass:: ScheduledVisit
+      :members:
+
    .. autoclass:: DynamicBitset
       :members:
       :special-members: __and__, __or__, __xor__, __getitem__, __setitem__,
diff --git a/examples/basic_vrps.ipynb b/examples/basic_vrps.ipynb
@@ -323,9 +323,7 @@
     "    for route in routes\n",
     "]\n",
     "\n",
-    "header = list(data[0].keys())\n",
-    "rows = [datum.values() for datum in data]\n",
-    "tabulate(rows, header, tablefmt=\"html\")"
+    "tabulate(data, headers=\"keys\", tablefmt=\"html\")"
    ]
   },
   {
@@ -337,7 +335,6 @@
     "We can inspect the routes in more detail using the `plot_route_schedule` function.\n",
     "This will plot distance on the x-axis, and time on the y-axis, separating actual travel/driving time from waiting and service time.\n",
     "The clients visited are plotted as grey vertical bars indicating their time windows.\n",
-    "We can see a jump to the start of the time window in the main (earliest) time line when a vehicle arrives early at a customer and has to wait.\n",
     "In some cases, there is slack in the route indicated by a semi-transparent region on top of the earliest time line.\n",
     "The grey background indicates the remaining load of the truck during the route, where the (right) y-axis ends at the vehicle capacity."
    ]
@@ -350,7 +347,7 @@
    "outputs": [],
    "source": [
     "fig, axarr = plt.subplots(2, 2, figsize=(15, 9))\n",
-    "for idx, (ax, route) in enumerate(zip(axarr.reshape(-1), routes)):\n",
+    "for idx, (ax, route) in enumerate(zip(axarr.flatten(), routes)):\n",
     "    plot_route_schedule(\n",
     "        INSTANCE,\n",
     "        route,\n",
@@ -362,6 +359,56 @@
     "fig.tight_layout()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "de5c7ca0",
+   "metadata": {},
+   "source": [
+    "Each route begins at a given `start_time`, that can be obtained as follows.\n",
+    "Note that this start time is typically not zero, that is, routes do not have to start immediately at the beginning of the time horizon."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dea67223",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "solution = result.best\n",
+    "shortest_route = min(solution.routes(), key=len)\n",
+    "\n",
+    "shortest_route.start_time()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "88665bfb",
+   "metadata": {},
+   "source": [
+    "Some of the statistics presented in the plots above can also be obtained from the route schedule, as follows:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9f882942",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data = [\n",
+    "    {\n",
+    "        \"start_service\": visit.start_service,\n",
+    "        \"end_service\": visit.end_service,\n",
+    "        \"service_duration\": visit.service_duration,\n",
+    "        \"wait_duration\": visit.wait_duration,  # if vehicle arrives early\n",
+    "    }\n",
+    "    for visit in shortest_route.schedule()\n",
+    "]\n",
+    "\n",
+    "tabulate(data, headers=\"keys\", tablefmt=\"html\")"
+   ]
+  },
   {
    "attachments": {},
    "cell_type": "markdown",
@@ -455,7 +502,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": ".venv",
    "language": "python",
    "name": "python3"
   },
@@ -469,7 +516,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.13"
+   "version": "3.11.9"
   }
  },
  "nbformat": 4,
diff --git a/pyvrp/_pyvrp.pyi b/pyvrp/_pyvrp.pyi
@@ -205,6 +205,16 @@ class ProblemData:
     def __getstate__(self) -> tuple: ...
     def __setstate__(self, state: tuple, /) -> None: ...
 
+class ScheduledVisit:
+    start_service: int
+    end_service: int
+    wait_duration: int
+    time_warp: int
+    @property
+    def service_duration(self) -> int: ...
+    def __getstate__(self) -> tuple: ...
+    def __setstate__(self, state: tuple, /) -> None: ...
+
 class Route:
     def __init__(
         self, data: ProblemData, visits: list[int], vehicle_type: int
@@ -239,6 +249,7 @@ class Route:
     def vehicle_type(self) -> int: ...
     def start_depot(self) -> int: ...
     def end_depot(self) -> int: ...
+    def schedule(self) -> list[ScheduledVisit]: ...
     def __getstate__(self) -> tuple: ...
     def __setstate__(self, state: tuple, /) -> None: ...
 
diff --git a/pyvrp/cpp/Route.cpp b/pyvrp/cpp/Route.cpp
@@ -3,6 +3,7 @@
 #include "LoadSegment.h"
 
 #include <algorithm>
+#include <cassert>
 #include <fstream>
 #include <numeric>
 
@@ -14,6 +15,23 @@ using pyvrp::Route;
 
 using Client = size_t;
 
+Route::ScheduledVisit::ScheduledVisit(Duration startService,
+                                      Duration endService,
+                                      Duration waitDuration,
+                                      Duration timeWarp)
+    : startService(startService),
+      endService(endService),
+      waitDuration(waitDuration),
+      timeWarp(timeWarp)
+{
+    assert(startService <= endService);
+}
+
+Duration Route::ScheduledVisit::serviceDuration() const
+{
+    return endService - startService;
+}
+
 Route::Route(ProblemData const &data, Visits visits, size_t const vehicleType)
     : visits_(std::move(visits)), centroid_({0, 0}), vehicleType_(vehicleType)
 {
@@ -24,28 +42,24 @@ Route::Route(ProblemData const &data, Visits visits, size_t const vehicleType)
     DurationSegment ds = {vehType, vehType.startLate};
     std::vector<LoadSegment> loadSegments(data.numLoadDimensions());
 
-    size_t prevClient = startDepot_;
-
     auto const &distances = data.distanceMatrix(vehType.profile);
     auto const &durations = data.durationMatrix(vehType.profile);
 
-    for (size_t idx = 0; idx != size(); ++idx)
+    for (size_t prevClient = startDepot_; auto const client : visits_)
     {
-        auto const client = visits_[idx];
         ProblemData::Client const &clientData = data.location(client);
 
         distance_ += distances(prevClient, client);
-        travel_ += durations(prevClient, client);
         service_ += clientData.serviceDuration;
         prizes_ += clientData.prize;
 
+        auto const edgeDuration = durations(prevClient, client);
+        travel_ += edgeDuration;
+        ds = DurationSegment::merge(edgeDuration, ds, {clientData});
+
         centroid_.first += static_cast<double>(clientData.x) / size();
         centroid_.second += static_cast<double>(clientData.y) / size();
 
-        auto const clientDS = DurationSegment(clientData);
-        ds = DurationSegment::merge(
-            durations(prevClient, client), ds, clientDS);
-
         for (size_t dim = 0; dim != data.numLoadDimensions(); ++dim)
         {
             auto const clientLs = LoadSegment(clientData, dim);
@@ -81,6 +95,26 @@ Route::Route(ProblemData const &data, Visits visits, size_t const vehicleType)
     slack_ = ds.twLate() - ds.twEarly();
     timeWarp_ = ds.timeWarp(vehType.maxDuration);
     release_ = ds.releaseTime();
+
+    schedule_.reserve(size());
+    auto now = startTime_;
+    for (size_t prevClient = startDepot_; auto const client : visits_)
+    {
+        now += durations(prevClient, client);
+
+        ProblemData::Client const &clientData = data.location(client);
+        auto const wait = std::max<Duration>(clientData.twEarly - now, 0);
+        auto const timeWarp = std::max<Duration>(now - clientData.twLate, 0);
+
+        now += wait;
+        now -= timeWarp;
+
+        schedule_.emplace_back(
+            now, now + clientData.serviceDuration, wait, timeWarp);
+
+        now += clientData.serviceDuration;
+        prevClient = client;
+    }
 }
 
 Route::Route(Visits visits,
@@ -103,8 +137,10 @@ Route::Route(Visits visits,
              std::pair<double, double> centroid,
              size_t vehicleType,
              size_t startDepot,
-             size_t endDepot)
+             size_t endDepot,
+             std::vector<ScheduledVisit> schedule)
     : visits_(std::move(visits)),
+      schedule_(std::move(schedule)),
       distance_(distance),
       distanceCost_(distanceCost),
       excessDistance_(excessDistance),
@@ -140,6 +176,11 @@ Route::Visits::const_iterator Route::end() const { return visits_.cend(); }
 
 Route::Visits const &Route::visits() const { return visits_; }
 
+std::vector<Route::ScheduledVisit> const &Route::schedule() const
+{
+    return schedule_;
+}
+
 Distance Route::distance() const { return distance_; }
 
 Cost Route::distanceCost() const { return distanceCost_; }
diff --git a/pyvrp/cpp/Route.h b/pyvrp/cpp/Route.h
@@ -18,12 +18,49 @@ namespace pyvrp
  */
 class Route
 {
+public:
+    /**
+     * Simple object that stores some data about a client visit.
+     *
+     * Attributes
+     * ----------
+     * start_service : int
+     *     Time at which the client service begins.
+     * end_service : int
+     *     Time at which the client service completes.
+     * service_duration : int
+     *     Duration of the service.
+     * wait_duration : int
+     *     If the vehicle arrives early, this is the duration it has to wait
+     *     until it can begin service.
+     * time_warp : int
+     *     If the vehicle arrives late, this is the duration it has to 'travel
+     *     back in time' to begin service. Non-zero time warp indicates an
+     *     infeasible route.
+     */
+    struct ScheduledVisit
+    {
+        Duration const startService = 0;
+        Duration const endService = 0;
+        Duration const waitDuration = 0;
+        Duration const timeWarp = 0;
+
+        ScheduledVisit(Duration startService,
+                       Duration endService,
+                       Duration waitDuration,
+                       Duration timeWarp);
+
+        [[nodiscard]] Duration serviceDuration() const;
+    };
+
+private:
     using Client = size_t;
     using Depot = size_t;
     using VehicleType = size_t;
     using Visits = std::vector<Client>;
 
-    Visits visits_ = {};           // Client visits on this route
+    Visits visits_ = {};                         // Client visits on this route
+    std::vector<ScheduledVisit> schedule_ = {};  // Client visit schedule data
     Distance distance_ = 0;        // Total travel distance on this route
     Cost distanceCost_ = 0;        // Total cost of travel distance
     Distance excessDistance_ = 0;  // Excess travel distance
@@ -64,6 +101,16 @@ class Route
      */
     [[nodiscard]] Visits const &visits() const;
 
+    /**
+     * Statistics about each client visit and the overall route schedule.
+     *
+     * .. note::
+     *
+     *    The schedule assumes the route starts at :meth:`~start_time`. Starting
+     *    later may be feasible, but shifts the schedule.
+     */
+    [[nodiscard]] std::vector<ScheduledVisit> const &schedule() const;
+
     /**
      * Total distance travelled on this route.
      */
@@ -239,7 +286,8 @@ class Route
           std::pair<double, double> centroid,
           VehicleType vehicleType,
           Depot startDepot,
-          Depot endDepot);
+          Depot endDepot,
+          std::vector<ScheduledVisit> schedule);
 };
 }  // namespace pyvrp
 
diff --git a/pyvrp/cpp/bindings.cpp b/pyvrp/cpp/bindings.cpp
@@ -454,6 +454,31 @@ PYBIND11_MODULE(_pyvrp, m)
                 return data;
             }));
 
+    py::class_<Route::ScheduledVisit>(
+        m, "ScheduledVisit", DOC(pyvrp, Route, ScheduledVisit))
+        .def_readonly("start_service", &Route::ScheduledVisit::startService)
+        .def_readonly("end_service", &Route::ScheduledVisit::endService)
+        .def_readonly("wait_duration", &Route::ScheduledVisit::waitDuration)
+        .def_readonly("time_warp", &Route::ScheduledVisit::timeWarp)
+        .def_property_readonly("service_duration",
+                               &Route::ScheduledVisit::serviceDuration)
+        .def(py::pickle(
+            [](Route::ScheduledVisit const &visit) {  // __getstate__
+                return py::make_tuple(visit.startService,
+                                      visit.endService,
+                                      visit.waitDuration,
+                                      visit.timeWarp);
+            },
+            [](py::tuple t) {  // __setstate__
+                Route::ScheduledVisit visit(
+                    t[0].cast<pyvrp::Duration>(),   // start service
+                    t[1].cast<pyvrp::Duration>(),   // end service
+                    t[2].cast<pyvrp::Duration>(),   // wait duration
+                    t[3].cast<pyvrp::Duration>());  // time warp
+
+                return visit;
+            }));
+
     py::class_<Route>(m, "Route", DOC(pyvrp, Route))
         .def(py::init<ProblemData const &, std::vector<size_t>, size_t>(),
              py::arg("data"),
@@ -508,6 +533,7 @@ PYBIND11_MODULE(_pyvrp, m)
         .def("has_time_warp",
              &Route::hasTimeWarp,
              DOC(pyvrp, Route, hasTimeWarp))
+        .def("schedule", &Route::schedule, DOC(pyvrp, Route, schedule))
         .def("__len__", &Route::size, DOC(pyvrp, Route, size))
         .def(
             "__iter__",
@@ -549,9 +575,12 @@ PYBIND11_MODULE(_pyvrp, m)
                                       route.centroid(),
                                       route.vehicleType(),
                                       route.startDepot(),
-                                      route.endDepot());
+                                      route.endDepot(),
+                                      route.schedule());
             },
             [](py::tuple t) {  // __setstate__
+                using Schedule = std::vector<Route::ScheduledVisit>;
+
                 Route route(
                     t[0].cast<std::vector<size_t>>(),         // visits
                     t[1].cast<pyvrp::Distance>(),             // distance
@@ -573,7 +602,8 @@ PYBIND11_MODULE(_pyvrp, m)
                     t[17].cast<std::pair<double, double>>(),  // centroid
                     t[18].cast<size_t>(),                     // vehicle type
                     t[19].cast<size_t>(),                     // start depot
-                    t[20].cast<size_t>());                    // end depot
+                    t[20].cast<size_t>(),                     // end depot
+                    t[21].cast<Schedule>());                  // visit schedule
 
                 return route;
             }))
diff --git a/pyvrp/plotting/plot_route_schedule.py b/pyvrp/plotting/plot_route_schedule.py
diff --git a/tests/test_Route.py b/tests/test_Route.py
