nextroute 1.11.1.dev0__cp39-cp39-win_amd64.whl

nextroute/__about__.py

@@ -0,0 +1,3 @@
+# © 2019-present nextmv.io inc
+
+__version__ = "v1.11.1.dev0"

nextroute/__init__.py

@@ -0,0 +1,18 @@
+# © 2019-present nextmv.io inc
+
+"""
+The Nextroute Python interface.
+
+Nextroute is a flexible engine for solving Vehicle Routing Problems (VRPs). The
+core of Nextroute is written in Go and this package provides a Python interface
+to it.
+"""
+
+from .__about__ import __version__
+from .options import Options as Options
+from .options import Verbosity as Verbosity
+from .solve import solve as solve
+from .version import nextroute_version as nextroute_version
+
+VERSION = __version__
+"""The version of the Nextroute Python package."""

nextroute/base_model.py

@@ -0,0 +1,24 @@
+# © 2019-present nextmv.io inc
+
+"""
+JSON class for data wrangling JSON objects.
+"""
+
+from typing import Any, Dict
+
+from pydantic import BaseModel
+
+
+class BaseModel(BaseModel):
+    """Base class for data wrangling tasks with JSON."""
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]):
+        """Instantiates the class from a dict."""
+
+        return cls(**data)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Converts the class to a dict."""
+
+        return self.model_dump(mode="json", exclude_none=True, by_alias=True)

nextroute/check/__init__.py

@@ -0,0 +1,28 @@
+# © 2019-present nextmv.io inc
+
+"""
+Check provides a plugin that allows you to check models and solutions.
+
+Checking a model or a solution checks the unplanned plan units. It checks each
+individual plan unit if it can be added to the solution. If the plan unit can
+be added to the solution, the report will include on how many vehicles and
+what the impact would be on the objective value. If the plan unit cannot be
+added to the solution, the report will include the reason why it cannot be
+added to the solution.
+
+The check can be invoked on a nextroute.Model or a nextroute.Solution. If the
+check is invoked on a model, an empty solution is created and the check is
+executed on this empty solution. An empty solution is a solution with all the
+initial stops that are fixed, initial stops that are not fixed are not added
+to the solution. The check is executed on the unplanned plan units of the
+solution. If the check is invoked on a solution, it is executed on the
+unplanned plan units of the solution.
+"""
+
+from .schema import Objective as Objective
+from .schema import ObjectiveTerm as ObjectiveTerm
+from .schema import Output as Output
+from .schema import PlanUnit as PlanUnit
+from .schema import Solution as Solution
+from .schema import Summary as Summary
+from .schema import Vehicle as Vehicle

nextroute/check/schema.py

@@ -0,0 +1,145 @@
+# © 2019-present nextmv.io inc
+
+"""
+This module contains definitions for the schema in the Nextroute check.
+"""
+
+from typing import Dict, List, Optional
+
+from nextroute.base_model import BaseModel
+
+
+class ObjectiveTerm(BaseModel):
+    """Check of the individual terms of the objective for a move."""
+
+    base: Optional[float] = None
+    """Base of the objective term."""
+    factor: Optional[float] = None
+    """Factor of the objective term."""
+    name: Optional[str] = None
+    """Name of the objective term."""
+    value: Optional[float] = None
+    """Value of the objective term, which is equivalent to `self.base *
+    self.factor`."""
+
+
+class Objective(BaseModel):
+    """Estimate of an objective of a move."""
+
+    terms: Optional[List[ObjectiveTerm]] = None
+    """Check of the individual terms of the objective."""
+    value: Optional[float] = None
+    """Value of the objective."""
+    vehicle: Optional[str] = None
+    """ID of the vehicle for which it reports the objective."""
+
+
+class Solution(BaseModel):
+    """Solution that the check has been executed on."""
+
+    objective: Optional[Objective] = None
+    """Objective of the start solution."""
+    plan_units_planned: Optional[int] = None
+    """Number of plan units planned in the start solution."""
+    plan_units_unplanned: Optional[int] = None
+    """Number of plan units unplanned in the start solution."""
+    stops_planned: Optional[int] = None
+    """Number of stops planned in the start solution."""
+    vehicles_not_used: Optional[int] = None
+    """Number of vehicles not used in the start solution."""
+    vehicles_used: Optional[int] = None
+    """Number of vehicles used in the start solution."""
+
+
+class Summary(BaseModel):
+    """Summary of the check."""
+
+    moves_failed: Optional[int] = None
+    """number of moves that failed. A move can fail if the estimate of a
+    constraint is incorrect. A constraint is incorrect if `ModelConstraint.
+    EstimateIsViolated` returns true and one of the violation checks returns
+    false. Violation checks are implementations of one or more of the
+    interfaces [SolutionStopViolationCheck], [SolutionVehicleViolationCheck] or
+    [SolutionViolationCheck] on the same constraint. Most constraints do not
+    need and do not have violation checks as the estimate is perfect. The
+    number of moves failed can be more than one per plan unit as we continue to
+    try moves on different vehicles until we find a move that is executable or
+    all vehicles have been visited."""
+    plan_units_best_move_failed: Optional[int] = None
+    """Number of plan units for which the best move can not be planned. This
+    should not happen if all the constraints are implemented correct."""
+    plan_units_best_move_found: Optional[int] = None
+    """Number of plan units for which at least one move has been found and the
+    move is executable."""
+    plan_units_best_move_increases_objective: Optional[int] = None
+    """Number of plan units for which the best move is executable but would
+    increase the objective value instead of decreasing it."""
+    plan_units_checked: Optional[int] = None
+    """Number of plan units that have been checked. If this is less than
+    `self.plan_units_to_be_checked` the check timed out."""
+    plan_units_have_no_move: Optional[int] = None
+    """Number of plan units for which no feasible move has been found. This
+    implies there is no move that can be executed without violating a
+    constraint."""
+    plan_units_to_be_checked: Optional[int] = None
+    """Number of plan units to be checked."""
+
+
+class PlanUnit(BaseModel):
+    """Check of a plan unit."""
+
+    best_move_failed: Optional[bool] = None
+    """True if the plan unit's best move failed to execute."""
+    best_move_increases_objective: Optional[bool] = None
+    """True if the best move for the plan unit increases the objective."""
+    best_move_objective: Optional[Objective] = None
+    """Estimate of the objective of the best move if the plan unit has a best
+    move."""
+    constraints: Optional[Dict[str, int]] = None
+    """Constraints that are violated for the plan unit."""
+    has_best_move: Optional[bool] = None
+    """True if a move is found for the plan unit. A plan unit has no move found
+    if the plan unit is over-constrained or the move found is too expensive."""
+    stops: Optional[List[str]] = None
+    """IDs of the sops in the plan unit."""
+    vehicles_have_moves: Optional[int] = None
+    """Number of vehicles that have moves for the plan unit. Only calculated if
+    the verbosity is very high."""
+    vehicles_with_moves: Optional[List[str]] = None
+    """IDs of the vehicles that have moves for the plan unit. Only calculated
+    if the verbosity is very high."""
+
+
+class Vehicle(BaseModel):
+    """Check of a vehicle."""
+
+    id: str
+    """ID of the vehicle."""
+
+    plan_units_have_moves: Optional[int] = None
+    """Number of plan units that have moves for the vehicle. Only calculated if
+    the depth is medium."""
+
+
+class Output(BaseModel):
+    """Output of a feasibility check."""
+
+    duration_maximum: Optional[float] = None
+    """Maximum duration of the check, in seconds."""
+    duration_used: Optional[float] = None
+    """Duration used by the check, in seconds."""
+    error: Optional[str] = None
+    """Error raised during the check."""
+    plan_units: Optional[List[PlanUnit]] = None
+    """Check of the individual plan units."""
+    remark: Optional[str] = None
+    """Remark of the check. It can be "ok", "timeout" or anything else that
+    should explain itself."""
+    solution: Optional[Solution] = None
+    """Start soltuion of the check."""
+    summary: Optional[Summary] = None
+    """Summary of the check."""
+    vehicles: Optional[List[Vehicle]] = None
+    """Check of the vehicles."""
+    verbosity: Optional[str] = None
+    """Verbosity level of the check."""

nextroute/options.py

@@ -0,0 +1,225 @@
+# © 2019-present nextmv.io inc
+
+"""
+Options for working with the Nextroute engine.
+"""
+
+import json
+from enum import Enum
+from typing import Any, Dict, List
+
+from pydantic import Field
+
+from nextroute.base_model import BaseModel
+
+# Arguments that require a duration suffix.
+_DURATIONS_ARGS = [
+    "-check.duration",
+    "-solve.duration",
+    "-solve.plateau.duration",
+]
+
+# Arguments that require a string enum.
+_STR_ENUM_ARGS = [
+    "CHECK_VERBOSITY",
+]
+
+
+class Verbosity(str, Enum):
+    """Format of an `Input`."""
+
+    OFF = "off"
+    """The check engine is not run."""
+    LOW = "low"
+    """Low verbosity for the check engine."""
+    MEDIUM = "medium"
+    """Medium verbosity for the check engine."""
+    HIGH = "high"
+    """High verbosity for the check engine."""
+
+
+class Options(BaseModel):
+    """Options for using Nextroute."""
+
+    CHECK_DURATION: float = 30
+    """Maximum duration of the check, in seconds."""
+    CHECK_VERBOSITY: Verbosity = Verbosity.OFF
+    """Verbosity of the check engine."""
+    FORMAT_DISABLE_PROGRESSION: bool = False
+    """Whether to disable the progression series."""
+    MODEL_CONSTRAINTS_DISABLE_ATTRIBUTES: bool = False
+    """Ignore the compatibility attributes constraint."""
+    MODEL_CONSTRAINTS_DISABLE_CAPACITIES: List[str] = Field(default_factory=list)
+    """Ignore the capacity constraint for the given resource names."""
+    MODEL_CONSTRAINTS_DISABLE_CAPACITY: bool = False
+    """Ignore the capacity constraint for all resources."""
+    MODEL_CONSTRAINTS_DISABLE_DISTANCELIMIT: bool = False
+    """Ignore the distance limit constraint."""
+    MODEL_CONSTRAINTS_DISABLE_GROUPS: bool = False
+    """Ignore the groups constraint."""
+    MODEL_CONSTRAINTS_DISABLE_MAXIMUMDURATION: bool = False
+    """Ignore the maximum duration constraint."""
+    MODEL_CONSTRAINTS_DISABLE_MAXIMUMSTOPS: bool = False
+    """Ignore the maximum stops constraint."""
+    MODEL_CONSTRAINTS_DISABLE_MAXIMUMWAITSTOP: bool = False
+    """Ignore the maximum stop wait constraint."""
+    MODEL_CONSTRAINTS_DISABLE_MAXIMUMWAITVEHICLE: bool = False
+    """Ignore the maximum vehicle wait constraint."""
+    MODEL_CONSTRAINTS_DISABLE_MIXINGITEMS: bool = False
+    """Ignore the do not mix items constraint."""
+    MODEL_CONSTRAINTS_DISABLE_PRECEDENCE: bool = False
+    """Ignore the precedence (pickups & deliveries) constraint."""
+    MODEL_CONSTRAINTS_DISABLE_STARTTIMEWINDOWS: bool = False
+    """Ignore the start time windows constraint."""
+    MODEL_CONSTRAINTS_DISABLE_VEHICLEENDTIME: bool = False
+    """Ignore the vehicle end time constraint."""
+    MODEL_CONSTRAINTS_DISABLE_VEHICLESTARTTIME: bool = False
+    """Ignore the vehicle start time constraint."""
+    MODEL_CONSTRAINTS_ENABLE_CLUSTER: bool = False
+    """Enable the cluster constraint."""
+    MODEL_OBJECTIVES_CAPACITIES: str = ""
+    """
+    Capacity objective, provide triple for each resource
+    `name:default;factor:1.0;offset;0.0`.
+    """
+    MODEL_OBJECTIVES_CLUSTER: float = 0.0
+    """Factor to weigh the cluster objective."""
+    MODEL_OBJECTIVES_EARLYARRIVALPENALTY: float = 1.0
+    """Factor to weigh the early arrival objective."""
+    MODEL_OBJECTIVES_LATEARRIVALPENALTY: float = 1.0
+    """Factor to weigh the late arrival objective."""
+    MODEL_OBJECTIVES_MINSTOPS: float = 1.0
+    """Factor to weigh the min stops objective."""
+    MODEL_OBJECTIVES_STOPBALANCE: float = 0.0
+    """Factor to weigh the stop balance objective."""
+    MODEL_OBJECTIVES_TRAVELDURATION: float = 0.0
+    """Factor to weigh the travel duration objective."""
+    MODEL_OBJECTIVES_UNPLANNEDPENALTY: float = 1.0
+    """Factor to weigh the unplanned objective."""
+    MODEL_OBJECTIVES_VEHICLEACTIVATIONPENALTY: float = 1.0
+    """Factor to weigh the vehicle activation objective."""
+    MODEL_OBJECTIVES_VEHICLESDURATION: float = 1.0
+    """Factor to weigh the vehicles duration objective."""
+    MODEL_PROPERTIES_DISABLE_DURATIONGROUPS: bool = False
+    """Ignore the durations groups of stops."""
+    MODEL_PROPERTIES_DISABLE_DURATIONS: bool = False
+    """Ignore the durations of stops."""
+    MODEL_PROPERTIES_DISABLE_INITIALSOLUTION: bool = False
+    """Ignore the initial solution."""
+    MODEL_PROPERTIES_DISABLE_STOPDURATIONMULTIPLIERS: bool = False
+    """Ignore the stop duration multipliers defined on vehicles."""
+    MODEL_PROPERTIES_MAXIMUMTIMEHORIZON: int = 15552000
+    """Maximum time horizon for the model in seconds."""
+    MODEL_VALIDATE_DISABLE_RESOURCES: bool = False
+    """Disable the resources validation."""
+    MODEL_VALIDATE_DISABLE_STARTTIME: bool = False
+    """Disable the start time validation."""
+    MODEL_VALIDATE_ENABLE_MATRIX: bool = False
+    """Enable matrix validation."""
+    MODEL_VALIDATE_ENABLE_MATRIXASYMMETRYTOLERANCE: int = 20
+    """Percentage of acceptable matrix asymmetry, requires matrix validation enabled."""
+    SOLVE_DURATION: float = 5
+    """Maximum duration, in seconds, of the solver."""
+    SOLVE_ITERATIONS: int = -1
+    """
+    Maximum number of iterations, -1 assumes no limit; iterations are counted
+    after start solutions are generated.
+    """
+    SOLVE_PARALLELRUNS: int = -1
+    """
+    Maximum number of parallel runs, -1 results in using all available
+    resources.
+    """
+    SOLVE_PLATEAU_ABSOLUTETHRESHOLD: float = -1
+    """Absolute threshold for significant improvement."""
+    SOLVE_PLATEAU_DURATION: float = 0.0
+    """Maximum duration, in seconds, without (significant) improvement."""
+    SOLVE_PLATEAU_ITERATIONS: int = 0
+    """Maximum number of iterations without (significant) improvement."""
+    SOLVE_PLATEAU_RELATIVETHRESHOLD: float = 0.0
+    """Relative threshold for significant improvement."""
+    SOLVE_RUNDETERMINISTICALLY: bool = False
+    """Run the parallel solver deterministically."""
+    SOLVE_STARTSOLUTIONS: int = -1
+    """
+    Number of solutions to generate on top of those passed in; one solution
+    generated with sweep algorithm, the rest generated randomly.
+    """
+
+    def to_args(self) -> List[str]:
+        """
+        Convert the options to command-line arguments.
+
+        Returns
+        ----------
+        List[str]
+            The flattened options as a list of strings.
+        """
+
+        opt_dict = self.to_dict()
+
+        default_options = Options()
+        default_options_dict = default_options.to_dict()
+
+        args = []
+        for key, value in opt_dict.items():
+            # We only care about custom options, so we skip the default ones.
+            default_value = default_options_dict.get(key)
+            if value == default_value:
+                continue
+
+            key = f"-{key.replace('_', '.').lower()}"
+
+            str_value = json.dumps(value)
+            if key in _DURATIONS_ARGS:
+                str_value = str_value + "s"  # Transforms into seconds.
+
+            if str_value.startswith('"') and str_value.endswith('"'):
+                str_value = str_value[1:-1]
+
+            # Nextroute’s Go implementation does not support boolean flags with
+            # values. If the value is a boolean, then we only append the key if
+            # the value is True.
+            should_append_value = True
+            if isinstance(value, bool):
+                if not value:
+                    continue
+
+                should_append_value = False
+
+            args.append(key)
+            if should_append_value:
+                args.append(str_value)
+
+        return args
+
+    @classmethod
+    def extract_from_dict(cls, data: Dict[str, Any]) -> "Options":
+        """
+        Extracts options from a dictionary. This dictionary may contain more
+        keys that are not part of the Nextroute options.
+
+        Parameters
+        ----------
+        data : Dict[str, Any]
+            The dictionary to extract options from.
+
+        Returns
+        ----------
+        Options
+            The Nextroute options.
+        """
+
+        options = cls()
+        for key, value in data.items():
+            key = key.upper()
+            if not hasattr(options, key):
+                continue
+
+            # Enums need to be handled manually.
+            if key == "CHECK_VERBOSITY":
+                value = Verbosity(value)
+
+            setattr(options, key, value)
+
+        return options

nextroute/schema/__init__.py

@@ -0,0 +1,29 @@
+# © 2019-present nextmv.io inc
+
+"""
+Schema (class) definitions for the entities in Nextroute.
+"""
+
+from .input import Defaults as Defaults
+from .input import DurationGroup as DurationGroup
+from .input import Input as Input
+from .location import Location as Location
+from .output import ObjectiveOutput as ObjectiveOutput
+from .output import Output as Output
+from .output import PlannedStopOutput as PlannedStopOutput
+from .output import Solution as Solution
+from .output import StopOutput as StopOutput
+from .output import VehicleOutput as VehicleOutput
+from .output import Version as Version
+from .statistics import DataPoint as DataPoint
+from .statistics import ResultStatistics as ResultStatistics
+from .statistics import RunStatistics as RunStatistics
+from .statistics import Series as Series
+from .statistics import SeriesData as SeriesData
+from .statistics import Statistics as Statistics
+from .stop import AlternateStop as AlternateStop
+from .stop import Stop as Stop
+from .stop import StopDefaults as StopDefaults
+from .vehicle import InitialStop as InitialStop
+from .vehicle import Vehicle as Vehicle
+from .vehicle import VehicleDefaults as VehicleDefaults

nextroute/schema/input.py

@@ -0,0 +1,87 @@
+# © 2019-present nextmv.io inc
+
+"""
+Defines the input class.
+"""
+
+from datetime import datetime
+from typing import Any, List, Optional, Union
+
+from nextroute.base_model import BaseModel
+from nextroute.schema.stop import AlternateStop, Stop, StopDefaults
+from nextroute.schema.vehicle import Vehicle, VehicleDefaults
+
+
+class Defaults(BaseModel):
+    """Default values for vehicles and stops."""
+
+    stops: Optional[StopDefaults] = None
+    """Default values for stops."""
+    vehicles: Optional[VehicleDefaults] = None
+    """Default values for vehicles."""
+
+
+class DurationGroup(BaseModel):
+    """Represents a group of stops that get additional duration whenever a stop
+    of the group is approached for the first time."""
+
+    duration: int
+    """Duration to add when visiting the group."""
+    group: List[str]
+    """Stop IDs contained in the group."""
+
+
+class MatrixTimeFrame(BaseModel):
+    """Represents a time-dependent duration matrix or scaling factor."""
+
+    start_time: datetime
+    """Start time of the time frame."""
+    end_time: datetime
+    """End time of the time frame."""
+    matrix: Optional[List[List[float]]] = None
+    """Duration matrix for the time frame."""
+    scaling_factor: Optional[float] = None
+    """Scaling factor for the time frame."""
+
+
+class TimeDependentMatrix(BaseModel):
+    """Represents time-dependent duration matrices."""
+
+    vehicle_ids: Optional[List[str]] = None
+    """Vehicle IDs for which the duration matrix is defined."""
+    default_matrix: List[List[float]]
+    """Default duration matrix."""
+    matrix_time_frames: Optional[List[MatrixTimeFrame]] = None
+    """Time-dependent duration matrices."""
+
+
+class Input(BaseModel):
+    """Input schema for Nextroute."""
+
+    stops: List[Stop]
+    """Stops that must be visited by the vehicles."""
+    vehicles: List[Vehicle]
+    """Vehicles that service the stops."""
+
+    alternate_stops: Optional[List[AlternateStop]] = None
+    """A set of alternate stops for the vehicles."""
+    custom_data: Optional[Any] = None
+    """Arbitrary data associated with the input."""
+    defaults: Optional[Defaults] = None
+    """Default values for vehicles and stops."""
+    distance_matrix: Optional[List[List[float]]] = None
+    """Matrix of travel distances in meters between stops."""
+    duration_groups: Optional[List[DurationGroup]] = None
+    """Duration in seconds added when approaching the group."""
+    duration_matrix: Optional[
+        Union[
+            List[List[float]],
+            TimeDependentMatrix,
+            List[TimeDependentMatrix],
+        ]
+    ] = None
+    """Matrix of travel durations in seconds between stops as a single matrix or duration matrices."""
+    options: Optional[Any] = None
+    """Arbitrary options."""
+    stop_groups: Optional[List[List[str]]] = None
+    """Groups of stops that must be part of the same route."""

nextroute/schema/location.py

@@ -0,0 +1,16 @@
+# © 2019-present nextmv.io inc
+
+"""
+Defines the location class.
+"""
+
+from nextroute.base_model import BaseModel
+
+
+class Location(BaseModel):
+    """Location represents a geographical location."""
+
+    lat: float
+    """Latitude of the location."""
+    lon: float
+    """Longitude of the location."""