nextroute 1.12.0__cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

nextroute/schema/output.py

@@ -0,0 +1,140 @@
+# © 2019-present nextmv.io inc
+
+"""
+Defines the output class.
+"""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from nextroute.base_model import BaseModel
+from nextroute.check.schema import Output as CheckOutput
+from nextroute.schema.location import Location
+from nextroute.schema.statistics import Statistics
+
+
+class Version(BaseModel):
+    """A version used for solving."""
+
+    sdk: str
+    """Nextmv SDK."""
+
+
+class StopOutput(BaseModel):
+    """Basic structure for the output of a stop."""
+
+    id: str
+    """ID of the stop."""
+    location: Location
+    """Location of the stop."""
+
+    custom_data: Optional[Any] = None
+    """Custom data of the stop."""
+
+
+class PlannedStopOutput(BaseModel):
+    """Output of a stop planned in the solution."""
+
+    stop: StopOutput
+    """Basic information on the stop."""
+
+    arrival_time: Optional[datetime] = None
+    """Actual arrival time at this stop."""
+    cumulative_travel_distance: Optional[float] = None
+    """Cumulative distance to travel from the first stop to this one, in meters."""
+    cumulative_travel_duration: Optional[float] = None
+    """Cumulative duration to travel from the first stop to this one, in seconds."""
+    custom_data: Optional[Any] = None
+    """Custom data of the stop."""
+    duration: Optional[float] = None
+    """Duration of the service at the stop, in seconds."""
+    early_arrival_duration: Optional[float] = None
+    """Duration of early arrival at the stop, in seconds."""
+    end_time: Optional[datetime] = None
+    """End time of the service at the stop."""
+    late_arrival_duration: Optional[float] = None
+    """Duration of late arrival at the stop, in seconds."""
+    mix_items: Optional[Any] = None
+    """Mix items at the stop."""
+    start_time: Optional[datetime] = None
+    """Start time of the service at the stop."""
+    target_arrival_time: Optional[datetime] = None
+    """Target arrival time at this stop."""
+    travel_distance: Optional[float] = None
+    """Distance to travel from the previous stop to this one, in meters."""
+    travel_duration: Optional[float] = None
+    """Duration to travel from the previous stop to this one, in seconds."""
+    waiting_duration: Optional[float] = None
+    """Waiting duratino at the stop, in seconds."""
+
+
+class VehicleOutput(BaseModel):
+    """Output of a vehicle in the solution."""
+
+    id: str
+    """ID of the vehicle."""
+
+    alternate_stops: Optional[List[str]] = None
+    """List of alternate stops that were planned on the vehicle."""
+    custom_data: Optional[Any] = None
+    """Custom data of the vehicle."""
+    route: Optional[List[PlannedStopOutput]] = None
+    """Route of the vehicle, which is a list of stops that were planned on
+    it."""
+    route_duration: Optional[float] = None
+    """Total duration of the vehicle's route, in seconds."""
+    route_stops_duration: Optional[float] = None
+    """Total duration of the stops of the vehicle, in seconds."""
+    route_travel_distance: Optional[float] = None
+    """Total travel distance of the vehicle, in meters."""
+    route_travel_duration: Optional[float] = None
+    """Total travel duration of the vehicle, in seconds."""
+    route_waiting_duration: Optional[float] = None
+    """Total waiting duration of the vehicle, in seconds."""
+
+
+class ObjectiveOutput(BaseModel):
+    """Information of the objective (value function)."""
+
+    name: str
+    """Name of the objective."""
+
+    base: Optional[float] = None
+    """Base of the objective."""
+    custom_data: Optional[Any] = None
+    """Custom data of the objective."""
+    factor: Optional[float] = None
+    """Factor of the objective."""
+    objectives: Optional[List[Dict[str, Any]]] = None
+    """List of objectives. Each list is actually of the same class
+    `ObjectiveOutput`, but we avoid a recursive definition here."""
+    value: Optional[float] = None
+    """Value of the objective, which is equivalent to `self.base *
+    self.factor`."""
+
+
+class Solution(BaseModel):
+    """Solution to a Vehicle Routing Problem (VRP)."""
+
+    unplanned: Optional[List[StopOutput]] = None
+    """List of stops that were not planned in the solution."""
+    vehicles: Optional[List[VehicleOutput]] = None
+    """List of vehicles in the solution."""
+    objective: Optional[ObjectiveOutput] = None
+    """Information of the objective (value function)."""
+    check: Optional[CheckOutput] = None
+    """Check of the solution, if enabled."""
+
+
+class Output(BaseModel):
+    """Output schema for Nextroute."""
+
+    options: Dict[str, Any]
+    """Options used to obtain this output."""
+    version: Version
+    """Versions used for the solution."""
+
+    solutions: Optional[List[Solution]] = None
+    """Solutions to the problem."""
+    statistics: Optional[Statistics] = None
+    """Statistics of the solution."""

nextroute/schema/statistics.py

@@ -0,0 +1,149 @@
+# © 2019-present nextmv.io inc
+
+"""
+Schema for statistics.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import Field
+
+from nextroute.base_model import BaseModel
+
+
+class RunStatistics(BaseModel):
+    """
+    Statistics about a general run.
+
+    Parameters
+    ----------
+    duration : float, optional
+        Duration of the run in seconds.
+    iterations : int, optional
+        Number of iterations.
+    custom : Union[Any, Dict[str, Any]], optional
+        Custom statistics created by the user. Can normally expect a `Dict[str,
+        Any]`.
+    """
+
+    duration: Optional[float] = None
+    """Duration of the run in seconds."""
+    iterations: Optional[int] = None
+    """Number of iterations."""
+    custom: Optional[
+        Union[
+            Any,
+            Dict[str, Any],
+        ]
+    ] = None
+    """Custom statistics created by the user. Can normally expect a `Dict[str,
+    Any]`."""
+
+
+class ResultStatistics(BaseModel):
+    """
+    Statistics about a specific result.
+
+    Parameters
+    ----------
+    duration : float, optional
+        Duration of the run in seconds.
+    value : float, optional
+        Value of the result.
+    custom : Union[Any, Dict[str, Any]], optional
+        Custom statistics created by the user. Can normally expect a `Dict[str,
+        Any]`.
+    """
+
+    duration: Optional[float] = None
+    """Duration of the run in seconds."""
+    value: Optional[float] = None
+    """Value of the result."""
+    custom: Optional[
+        Union[
+            Any,
+            Dict[str, Any],
+        ]
+    ] = None
+    """Custom statistics created by the user. Can normally expect a `Dict[str,
+    Any]`."""
+
+
+class DataPoint(BaseModel):
+    """
+    A data point.
+
+    Parameters
+    ----------
+    x : float
+        X coordinate of the data point.
+    y : float
+        Y coordinate of the data point.
+    """
+
+    x: float
+    """X coordinate of the data point."""
+    y: float
+    """Y coordinate of the data point."""
+
+
+class Series(BaseModel):
+    """
+    A series of data points.
+
+    Parameters
+    ----------
+    name : str, optional
+        Name of the series.
+    data_points : List[DataPoint], optional
+        Data of the series.
+    """
+
+    name: Optional[str] = None
+    """Name of the series."""
+    data_points: Optional[List[DataPoint]] = None
+    """Data of the series."""
+
+
+class SeriesData(BaseModel):
+    """
+    Data of a series.
+
+    Parameters
+    ----------
+    value : Series, optional
+        A series for the value of the solution.
+    custom : List[Series], optional
+        A list of series for custom statistics.
+    """
+
+    value: Optional[Series] = None
+    """A series for the value of the solution."""
+    custom: Optional[List[Series]] = None
+    """A list of series for custom statistics."""
+
+
+class Statistics(BaseModel):
+    """
+    Statistics of a solution.
+
+    Parameters
+    ----------
+    run : RunStatistics, optional
+        Statistics about the run.
+    result : ResultStatistics, optional
+        Statistics about the last result.
+    series_data : SeriesData, optional
+        Series data about some metric.
+    statistics_schema : str, optional
+        Schema (version). This class only supports `v1`.
+    """
+
+    run: Optional[RunStatistics] = None
+    """Statistics about the run."""
+    result: Optional[ResultStatistics] = None
+    """Statistics about the last result."""
+    series_data: Optional[SeriesData] = None
+    """Data of the series."""
+    statistics_schema: Optional[str] = Field(alias="schema", default="v1")
+    """Schema (version). This class only supports `v1`."""

nextroute/schema/stop.py

@@ -0,0 +1,65 @@
+# © 2019-present nextmv.io inc
+
+"""
+Defines the stop class.
+"""
+
+from datetime import datetime
+from typing import Any, List, Optional
+
+from nextroute.base_model import BaseModel
+from nextroute.schema.location import Location
+
+
+class StopDefaults(BaseModel):
+    """Default values for a stop."""
+
+    compatibility_attributes: Optional[List[str]] = None
+    """Attributes that the stop is compatible with."""
+    duration: Optional[int] = None
+    """Duration of the stop in seconds."""
+    early_arrival_time_penalty: Optional[float] = None
+    """Penalty per second for arriving at the stop before the target arrival time."""
+    late_arrival_time_penalty: Optional[float] = None
+    """Penalty per second for arriving at the stop after the target arrival time."""
+    max_wait: Optional[int] = None
+    """Maximum waiting duration in seconds at the stop."""
+    quantity: Optional[Any] = None
+    """Quantity of the stop."""
+    start_time_window: Optional[Any] = None
+    """Time window in which the stop can start service."""
+    target_arrival_time: Optional[datetime] = None
+    """Target arrival time at the stop."""
+    unplanned_penalty: Optional[int] = None
+    """Penalty for not planning a stop."""
+
+
+class Stop(StopDefaults):
+    """Stop is a location that must be visited by a vehicle in a Vehicle
+    Routing Problem (VRP.)"""
+
+    id: str
+    """Unique identifier for the stop."""
+    location: Location
+    """Location of the stop."""
+
+    custom_data: Optional[Any] = None
+    """Arbitrary data associated with the stop."""
+    mixing_items: Optional[Any] = None
+    """Defines the items that are inserted or removed from the vehicle when visiting the stop."""
+    precedes: Optional[Any] = None
+    """Stops that must be visited after this one on the same route."""
+    succeeds: Optional[Any] = None
+    """Stops that must be visited before this one on the same route."""
+
+
+class AlternateStop(StopDefaults):
+    """An alternate stop can be serviced instead of another stop."""
+
+    id: str
+    """Unique identifier for the stop."""
+    location: Location
+    """Location of the stop."""
+
+    custom_data: Optional[Any] = None
+    """Arbitrary data associated with the stop."""

nextroute/schema/vehicle.py

@@ -0,0 +1,72 @@
+# © 2019-present nextmv.io inc
+
+"""
+Defines the vehicle class.
+"""
+
+from datetime import datetime
+from typing import Any, List, Optional
+
+from nextroute.base_model import BaseModel
+from nextroute.schema.location import Location
+
+
+class InitialStop(BaseModel):
+    """Represents a stop that is already planned on a vehicle."""
+
+    id: str
+    """Unique identifier of the stop."""
+
+    fixed: Optional[bool] = None
+    """Whether the stop is fixed on the route."""
+
+
+class VehicleDefaults(BaseModel):
+    """Default values for vehicles."""
+
+    activation_penalty: Optional[int] = None
+    """Penalty of using the vehicle."""
+    alternate_stops: Optional[List[str]] = None
+    """A set of alternate stops for which only one should be serviced."""
+    capacity: Optional[Any] = None
+    """Capacity of the vehicle."""
+    compatibility_attributes: Optional[List[str]] = None
+    """Attributes that the vehicle is compatible with."""
+    end_location: Optional[Location] = None
+    """Location where the vehicle ends."""
+    end_time: Optional[datetime] = None
+    """Latest time at which the vehicle ends its route."""
+    max_distance: Optional[int] = None
+    """Maximum distance in meters that the vehicle can travel."""
+    max_duration: Optional[int] = None
+    """Maximum duration in seconds that the vehicle can travel."""
+    max_stops: Optional[int] = None
+    """Maximum number of stops that the vehicle can visit."""
+    max_wait: Optional[int] = None
+    """Maximum aggregated waiting time that the vehicle can wait across route stops."""
+    min_stops: Optional[int] = None
+    """Minimum stops that a vehicle should visit."""
+    min_stops_penalty: Optional[float] = None
+    """Penalty for not visiting the minimum number of stops."""
+    speed: Optional[float] = None
+    """Speed of the vehicle in meters per second."""
+    start_level: Optional[Any] = None
+    """Initial level of the vehicle."""
+    start_location: Optional[Location] = None
+    """Location where the vehicle starts."""
+    start_time: Optional[datetime] = None
+    """Time when the vehicle starts its route."""
+
+
+class Vehicle(VehicleDefaults):
+    """A vehicle services stops in a Vehicle Routing Problem (VRP)."""
+
+    id: str
+    """Unique identifier of the vehicle."""
+
+    custom_data: Optional[Any] = None
+    """Arbitrary custom data."""
+    initial_stops: Optional[List[InitialStop]] = None
+    """Initial stops planned on the vehicle."""
+    stop_duration_multiplier: Optional[float] = None
+    """Multiplier for the duration of stops."""

nextroute/solve.py

@@ -0,0 +1,145 @@
+# © 2019-present nextmv.io inc
+
+"""
+Methods for solving a Vehicle Routing Problem with Nextroute.
+"""
+
+import json
+import os
+import platform
+import subprocess
+from typing import Any, Dict, Union
+
+from nextroute.options import Options
+from nextroute.schema.input import Input
+from nextroute.schema.output import Output
+
+SUPPORTED_OS = ["linux", "windows", "darwin"]
+"""The operating systems supported by the Nextroute engine."""
+SUPPORTED_ARCHITECTURES = ["amd64", "x86_64", "arm64", "aarch64"]
+"""The architectures supported by the Nextroute engine."""
+
+
+def solve(
+    input: Union[Input, Dict[str, Any]],
+    options: Union[Options, Dict[str, Any]],
+) -> Output:
+    """
+    Solve a Vehicle Routing Problem (VRP) using the Nextroute engine. The input
+    and options are passed to the engine, and the output is returned. The input
+    and options can be provided as dictionaries or as objects, although the
+    recommended way is to use the classes, as they provide validation.
+
+    Examples
+    --------
+
+    * Using default options to load an input from a file.
+        ```python
+        import json
+
+        import nextroute
+
+        with open("input.json") as f:
+            data = json.load(f)
+
+        input = nextroute.schema.Input.from_dict(data)
+        options = nextroute.Options()
+        output = nextroute.solve(input, options)
+        print(output)
+        ```
+
+    * Using custom options to load an input from a file.
+        ```python
+        import json
+
+        import nextroute
+
+        with open("input.json") as f:
+            data = json.load(f)
+
+        input = nextroute.schema.Input.from_dict(data)
+        options = nextroute.Options(
+            solve=nextroute.ParallelSolveOptions(duration=2),
+        )
+        output = nextroute.solve(input, options)
+        print(output)
+        ```
+
+    * Using custom dict options to load an input from a file.
+        ```python
+        import json
+
+        import nextroute
+
+        with open("input.json") as f:
+            data = json.load(f)
+
+        input = nextroute.schema.Input.from_dict(data)
+        options = {
+            "solve": {
+                "duration": 2,
+            },
+        }
+        output = nextroute.solve(input, options)
+        print(output)
+        ```
+
+
+    Parameters
+    ----------
+    input : Union[schema.Input, Dict[str, Any]]
+        The input to the Nextroute engine. If a dictionary is provided, it will
+        be converted to an Input object to validate it.
+    options : Union[Options, Dict[str, Any]]
+        The options for the Nextroute engine. If a dictionary is provided, it
+        will be converted to an Options object.
+
+    Returns
+    -------
+    schema.Output
+        The output of the Nextroute engine. You can call the `to_dict` method
+        on this object to get a dictionary representation of the output.
+    """
+
+    if isinstance(input, dict):
+        input = Input.from_dict(input)
+
+    input_stream = json.dumps(input.to_dict())
+
+    if isinstance(options, dict):
+        options = Options.from_dict(options)
+
+    os_name = platform.system().lower()
+    if os_name not in SUPPORTED_OS:
+        raise Exception(f'unsupported operating system: "{os_name}", supported os are: {", ".join(SUPPORTED_OS)}')
+
+    architecture = platform.machine().lower()
+    if architecture not in SUPPORTED_ARCHITECTURES:
+        raise Exception(
+            f'unsupported architecture: "{architecture}", supported arch are: {", ".join(SUPPORTED_ARCHITECTURES)}'
+        )
+
+    executable = os.path.join(os.path.dirname(__file__), "bin", "nextroute.exe")
+    if not os.path.exists(executable):
+        raise Exception(f"missing Nextroute binary: {executable}")
+
+    option_args = options.to_args()
+    args = [executable] + option_args
+
+    try:
+        result = subprocess.run(
+            args,
+            env=os.environ,
+            check=True,
+            text=True,
+            capture_output=True,
+            input=input_stream,
+        )
+
+    except subprocess.CalledProcessError as e:
+        raise Exception(f"error running Nextroute binary: {e.stderr}") from e
+
+    raw_output = result.stdout
+    output = Output.from_dict(json.loads(raw_output))
+
+    return output

nextroute/version.py

@@ -0,0 +1,12 @@
+# © 2019-present nextmv.io inc
+
+import os
+import subprocess
+
+
+def nextroute_version() -> str:
+    """
+    Get the version of the embedded Nextroute binary.
+    """
+    executable = os.path.join(os.path.dirname(__file__), "bin", "nextroute.exe")
+    return subprocess.check_output([executable, "--version"]).decode().strip()