nextroute 1.8.0.dev0__tar.gz → 1.8.0.dev2__tar.gz

{nextroute-1.8.0.dev0 → nextroute-1.8.0.dev2}/.github/workflows/release.yml

@@ -23,6 +23,21 @@ jobs:
     permissions:
       contents: write
     steps:
+      - name: ensure proper tagging
+        run: |
+          echo "If it's a pre-release, the version should contain a hyphen"
+          if [ ${{ inputs.IS_PRE_RELEASE }} = true ]; then
+            if [[ $VERSION != *-* ]]; then
+              echo "Pre-release versions should contain a hyphen"
+              exit 1
+            fi
+          else
+            if [[ $VERSION == *-* ]]; then
+              echo "Release versions should not contain a hyphen"
+              exit 1
+            fi
+          fi
+
       - name: ensure version is not already released
         run: |
           if git ls-remote --tags origin | grep -q "refs/tags/$VERSION"; then

{nextroute-1.8.0.dev0 → nextroute-1.8.0.dev2}/.nextmv/check_header.py

@@ -9,7 +9,7 @@ GO_HEADER = f"// {HEADER}"
 GO_IGNORE = []
 
 PYTHON_HEADER = f"# {HEADER}"
-PYTHON_IGNORE = ["venv/*"]
+PYTHON_IGNORE = ["venv/*", "tests/*"]
 
 
 def main() -> None:

{nextroute-1.8.0.dev0 → nextroute-1.8.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: nextroute
-Version: 1.8.0.dev0
+Version: 1.8.0.dev2
 Summary: Nextroute is an engine for solving Vehicle Routing Problems (VRPs).
 Project-URL: Homepage, https://www.nextmv.io
 Project-URL: Documentation, https://www.nextmv.io/docs/vehicle-routing

nextroute-1.8.0.dev2/VERSION

@@ -0,0 +1 @@
+v1.8.0-dev.2

{nextroute-1.8.0.dev0 → nextroute-1.8.0.dev2}/nextroute/__about__.py

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

{nextroute-1.8.0.dev0 → nextroute-1.8.0.dev2}/nextroute/__init__.py

@@ -9,6 +9,11 @@ to it.
 """
 
 from .__about__ import __version__
+from .options import DisableFormatOptions as DisableFormatOptions
+from .options import FormatOptions as FormatOptions
+from .options import Options as Options
+from .options import ParallelSolveOptions as ParallelSolveOptions
+from .solve import solve as solve
 
 VERSION = __version__
 """The version of the Nextroute Python package."""

{nextroute-1.8.0.dev0 → nextroute-1.8.0.dev2}/nextroute/check/__init__.py

@@ -19,6 +19,8 @@ solution. If the check is invoked on a solution, it is executed on the
 unplanned plan units of the solution.
 """
 
+from .options import Options as Options
+from .options import Verbosity as Verbosity
 from .schema import Objective as Objective
 from .schema import ObjectiveTerm as ObjectiveTerm
 from .schema import Output as Output

nextroute-1.8.0.dev2/nextroute/check/options.py

@@ -0,0 +1,31 @@
+# © 2019-present nextmv.io inc
+
+"""
+Options for the Nextroute check engine.
+"""
+
+from enum import Enum
+
+from nextroute.base_model import BaseModel
+
+
+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 the Nextroute check engine."""
+
+    duration: float = 30
+    """Maximum duration of the check, in seconds."""
+    verbosity: Verbosity = Verbosity.OFF
+    """Verbosity of the check engine."""

nextroute-1.8.0.dev2/nextroute/factory/__init__.py

@@ -0,0 +1,16 @@
+# © 2019-present nextmv.io inc
+
+"""
+Functionality for creating a ready-to-go Nextroute model.
+"""
+
+from .options import Constraints as Constraints
+from .options import DisableConstraints as DisableConstraints
+from .options import DisableProperties as DisableProperties
+from .options import DisableValidate as DisableValidate
+from .options import EnableConstraints as EnableConstraints
+from .options import EnableValidate as EnableValidate
+from .options import Objectives as Objectives
+from .options import Options as Options
+from .options import Properties as Properties
+from .options import Validate as Validate

nextroute-1.8.0.dev2/nextroute/factory/options.py

@@ -0,0 +1,146 @@
+# © 2019-present nextmv.io inc
+
+"""
+Options for the Nextroute factory.
+"""
+
+from typing import List
+
+from pydantic import Field
+
+from nextroute.base_model import BaseModel
+
+
+class DisableConstraints(BaseModel):
+    """Options for disabling specific constraints."""
+
+    attributes: bool = False
+    """Ignore the compatibility attributes constraint."""
+    capacity: bool = False
+    """Ignore the capacity constraint for all resources."""
+    capacities: List[str] = Field(default_factory=list)
+    """Ignore the capacity constraint for the given resource names."""
+    distance_limit: bool = False
+    """Ignore the distance limit constraint."""
+    groups: bool = False
+    """Ignore the groups constraint."""
+    maximum_duration: bool = False
+    """Ignore the maximum duration constraint."""
+    maximum_stops: bool = False
+    """Ignore the maximum stops constraint."""
+    maximum_wait_stop: bool = False
+    """Ignore the maximum stop wait constraint."""
+    maximum_wait_vehicle: bool = False
+    """Ignore the maximum vehicle wait constraint."""
+    mixing_items: bool = False
+    """Ignore the do not mix items constraint."""
+    precedence: bool = False
+    """Ignore the precedence (pickups & deliveries) constraint."""
+    vehicle_start_time: bool = False
+    """Ignore the vehicle start time constraint."""
+    vehicle_end_time: bool = False
+    """Ignore the vehicle end time constraint."""
+    start_time_windows: bool = False
+    """Ignore the start time windows constraint."""
+
+
+class EnableConstraints(BaseModel):
+    """Options for enabling specific constraints."""
+
+    cluster: bool = False
+    """Enable the cluster constraint."""
+
+
+class Constraints(BaseModel):
+    """Options for configuring constraints."""
+
+    disable: DisableConstraints = Field(default_factory=DisableConstraints)
+    """Options for disabling specific constraints."""
+    enable: EnableConstraints = Field(default_factory=EnableConstraints)
+    """Options for enabling specific constraints."""
+
+
+class Objectives(BaseModel):
+    """Options for configuring objectives."""
+
+    capacities: str = ""
+    """
+    Capacity objective, provide triple for each resource
+    `name:default;factor:1.0;offset;0.0`.
+    """
+    min_stops: float = 1.0
+    """Factor to weigh the min stops objective."""
+    early_arrival_penalty: float = 1.0
+    """Factor to weigh the early arrival objective."""
+    late_arrival_penalty: float = 1.0
+    """Factor to weigh the late arrival objective."""
+    vehicle_activation_penalty: float = 1.0
+    """Factor to weigh the vehicle activation objective."""
+    travel_duration: float = 0.0
+    """Factor to weigh the travel duration objective."""
+    vehicles_duration: float = 1.0
+    """Factor to weigh the vehicles duration objective."""
+    unplanned_penalty: float = 1.0
+    """Factor to weigh the unplanned objective."""
+    cluster: float = 0.0
+    """Factor to weigh the cluster objective."""
+
+
+class DisableProperties(BaseModel):
+    """Options for disabling specific properties."""
+
+    durations: bool = False
+    """Ignore the durations of stops."""
+    stop_duration_multipliers: bool = False
+    """Ignore the stop duration multipliers defined on vehicles."""
+    duration_groups: bool = False
+    """Ignore the durations groups of stops."""
+    initial_solution: bool = False
+    """Ignore the initial solution."""
+
+
+class Properties(BaseModel):
+    """Options for configuring properties."""
+
+    disable: DisableProperties = Field(default_factory=DisableProperties)
+    """Options for disabling specific properties."""
+
+
+class DisableValidate(BaseModel):
+    """Options for disabling specific validations."""
+
+    start_time: bool = False
+    """Disable the start time validation."""
+    resources: bool = False
+    """Disable the resources validation."""
+
+
+class EnableValidate(BaseModel):
+    """Options for enabling specific validations."""
+
+    matrix: bool = False
+    """Enable matrix validation."""
+    matrix_asymmetry_tolerance: int = 20
+    """Percentage of acceptable matrix asymmetry, requires matrix validation enabled."""
+
+
+class Validate(BaseModel):
+    """Options for configuring validations."""
+
+    disable: DisableValidate = Field(default_factory=DisableValidate)
+    """Options for disabling specific validations"""
+    enable: EnableValidate = Field(default_factory=EnableValidate)
+    """Options for enabling specific validations"""
+
+
+class Options(BaseModel):
+    """Options that configure how a Nextroute model is built."""
+
+    constraints: Constraints = Field(default_factory=Constraints)
+    """Options for configuring constraints."""
+    objectives: Objectives = Field(default_factory=Objectives)
+    """Options for configuring objectives."""
+    properties: Properties = Field(default_factory=Properties)
+    """Options for configuring properties."""
+    validate_options: Validate = Field(default_factory=Validate, alias="validate")
+    """Options for configuring validations."""

nextroute-1.8.0.dev2/nextroute/options.py

@@ -0,0 +1,151 @@
+# © 2019-present nextmv.io inc
+
+"""
+Options for working with the Nextroute engine.
+"""
+
+import json
+from typing import Any, Dict, List
+
+from pydantic import Field
+
+from nextroute.base_model import BaseModel
+from nextroute.check.options import Options as CheckOptions
+from nextroute.factory.options import Options as FactoryOptions
+
+_DURATIONS_ARGS = [
+    "-check.duration",
+    "-solve.duration",
+]
+
+
+class ParallelSolveOptions(BaseModel):
+    """Options for the parallel solver."""
+
+    iterations: int = -1
+    """
+    Maximum number of iterations, -1 assumes no limit; iterations are counted
+    after start solutions are generated.
+    """
+    duration: float = 5
+    """Maximum duration, in seconds, of the solver."""
+    parallel_runs: int = -1
+    """
+    Maximum number of parallel runs, -1 results in using all available
+    resources.
+    """
+    start_solutions: int = -1
+    """
+    Number of solutions to generate on top of those passed in; one solution
+    generated with sweep algorithm, the rest generated randomly.
+    """
+    run_deterministically: bool = False
+    """Run the parallel solver deterministically."""
+
+
+class DisableFormatOptions(BaseModel):
+    """Options for disabling/enabling the progression series."""
+
+    progression: bool = False
+    """Whether to disable the progression series."""
+
+
+class FormatOptions(BaseModel):
+    """Options for formatting the output of the solver."""
+
+    disable: DisableFormatOptions = Field(default_factory=DisableFormatOptions)
+    """Options for disabling/enabling the progression series."""
+
+
+class Options(BaseModel):
+    """Options for using Nextroute."""
+
+    check: CheckOptions = Field(default_factory=CheckOptions)
+    """Options for enabling the check engine."""
+    format: FormatOptions = Field(default_factory=FormatOptions)
+    """Options for the output format."""
+    model: FactoryOptions = Field(default_factory=FactoryOptions)
+    """Options for the ready-to-go model."""
+    solve: ParallelSolveOptions = Field(default_factory=ParallelSolveOptions)
+    """Options for the parallel solver."""
+
+    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()
+        flattened = _flatten(opt_dict)
+
+        default_options = Options()
+        default_options_dict = default_options.to_dict()
+        default_flattened = _flatten(default_options_dict)
+
+        args = []
+        for key, value in flattened.items():
+            # We only care about custom options, so we skip the default ones.
+            default_value = default_flattened.get(key)
+            if value == default_value:
+                continue
+
+            key = key.replace("_", "")
+
+            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
+
+
+def _flatten(nested: Dict[str, Any]) -> Dict[str, Any]:
+    """Flatten a nested dict."""
+
+    flattened = {}
+    for child_key, child_value in nested.items():
+        root_key = f"-{child_key}"
+        __set_children(flattened, root_key, child_value)
+
+    return flattened
+
+
+def __set_children(flattened: Dict[str, Any], parent_key: str, parent_value: Any):
+    """Helper function for `__flatten`. it is invoked recursively on a child
+    value. If the child is not a dict, then the value is simply set on the
+    flattened dict. If the child is a dict, then the function is invoked
+    recursively on the child’s values, unitl a non-dict values is hit."""
+
+    new_key = parent_key
+
+    if parent_value is None:
+        flattened[new_key] = parent_value
+        return
+
+    if isinstance(parent_value, dict):
+        for child_key, child_value in parent_value.items():
+            new_key = f"{parent_key}.{child_key}"
+            __set_children(flattened, new_key, child_value)
+        return
+
+    flattened[new_key] = parent_value

{nextroute-1.8.0.dev0 → nextroute-1.8.0.dev2}/nextroute/schema/output.py

@@ -8,7 +8,7 @@ from datetime import datetime
 from typing import Any, Dict, List, Optional
 
 from nextroute.base_model import BaseModel
-from nextroute.check import Output as checkOutput
+from nextroute.check.schema import Output as CheckOutput
 from nextroute.schema.location import Location
 from nextroute.schema.statistics import Statistics
 
@@ -122,7 +122,7 @@ class Solution(BaseModel):
     """List of vehicles in the solution."""
     objective: Optional[ObjectiveOutput] = None
     """Information of the objective (value function)."""
-    check: Optional[checkOutput] = None
+    check: Optional[CheckOutput] = None
     """Check of the solution, if enabled."""
 
 

nextroute-1.8.0.dev2/nextroute/solve.py

@@ -0,0 +1,150 @@
+# © 2019-present nextmv.io inc
+
+"""
+Methods for solving a Vehicle Routing Problem with Nextroute.
+"""
+
+import json
+import os
+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 = ["x86_64", "arm64", "aarch64"]
+"""The architectures supported by the Nextroute engine."""
+
+_ARCHITECTURE_TRANSLATION = {
+    "x86_64": "amd64",
+    "arm64": "arm64",
+    "aarch64": "arm64",
+}
+
+
+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.
+
+    Example:
+
+    * 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 = os.uname().sysname.lower()
+    if os_name not in SUPPORTED_OS:
+        raise Exception(f'unsupported operating system: "{os_name}", supported os are: {", ".join(SUPPORTED_OS)}')
+
+    architecture = os.uname().machine.lower()
+    if architecture not in SUPPORTED_ARCHITECTURES:
+        raise Exception(
+            f'unsupported architecture: "{architecture}", supported arch are: {", ".join(SUPPORTED_ARCHITECTURES)}'
+        )
+
+    binary_name = f"nextroute-{os_name}-{_ARCHITECTURE_TRANSLATION[architecture]}"
+    executable = os.path.join(os.path.dirname(__file__), "bin", binary_name)
+    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