Added request generator interface (#255)

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 -   repo: https://github.com/python/black
-    rev: 24.1.1
+    rev: 24.3.0
     hooks:
     - id: black
       language_version: python3.9
@@ -9,4 +9,4 @@ repos:
     hooks:
     - id: blacken-docs
       additional_dependencies:
-        - black==24.2.0
+        - black==24.3.0

doc/request-generator-guide.rst

@@ -0,0 +1,4 @@
+Writing a request generator
+===========================
+
+Request generators are iterators

pyproject.toml

@@ -53,7 +53,7 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
-    "black==24.2.0",
+    "black==24.3.0",
     "commitizen",
     "pdbpp",
     "pre-commit",

src/ridepy/data_structures.py

@@ -1,3 +1,5 @@
+from collections.abc import Iterator
+
 from numpy import inf
 from abc import ABC, abstractmethod
 from enum import Enum
@@ -219,6 +221,9 @@ def __eq__(self, other: "TransportSpace"):
         return type(self) == type(other) and self.asdict() == other.asdict()
 
 
+class RequestGenerator(Iterator): ...
+
+
 Stoplist = List[Stop]
 """A list of `.Stop` objects. Specifies completely the current position and future actions a vehicle will make."""
 

src/ridepy/util/request_generators.py

@@ -1,10 +1,26 @@
 import random
+from abc import (
+    ABC,
+    abstractmethod,
+    abstractproperty,
+    abstractclassmethod,
+    abstractstaticmethod,
+)
+from typing import Optional, Union
+
 import numpy as np
 
-from ridepy.data_structures import TransportSpace, TransportationRequest
+from ridepy.data_structures import (
+    TransportSpace,
+    TransportationRequest,
+    RequestGenerator,
+)
+
+from ridepy.util.spaces import Euclidean2D
+from ridepy.util.spaces_cython import Euclidean2D as CyEuclidean2D
 
 
-class RandomRequestGenerator:
+class RandomRequestGenerator(RequestGenerator):
     """
     Generates random requests in the chosen transport space with a certain rate.
     The timewindows for the request are configurable.
@@ -39,16 +55,23 @@ def __init__(
             the rate of requests per time unit
         seed
             the random seed
-        pickup_timewindow_offset
-            each request's pickup_timewindow_min will be this much from the creation timestamp
         request_class
             the generated requests will be instances of this class. Needed to generate pythonic or cythonic requests at will.
+        pickup_timewindow_offset
+            Each request's pickup_timewindow_min will be this much from the creation
+            timestamp.
         max_pickup_delay
-            see class docstring
+            The maximum delay between the request creation timestamp and the pickup
+            time.
         max_delivery_delay_abs
-            see class docstring
+            The maximum absolute delay between the request creation timestamp and the
+            delivery time.
         max_delivery_delay_rel
-            see class docstring
+            The maximum **delay** between the request creation timestamp and the delivery
+            time relative to the direct actual direct travel time. Example: if the
+            direct travel time is 10 minutes and ``max_delivery_delay_rel`` is 0.5,
+            the delivery time will be at most 15 minutes after request creation.
+            I.e., delta_max = 1 + max_delivery_delay_rel.
         """
         if seed is not None:
             np.random.seed(seed)