nextmv 0.1.0.dev2__tar.gz → 0.1.0.dev4__tar.gz

{nextmv-0.1.0.dev2 → nextmv-0.1.0.dev4}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.1
 Name: nextmv
-Version: 0.1.0.dev2
+Version: 0.1.0.dev4
 Summary: The Python SDK for Nextmv
 Project-URL: Homepage, https://www.nextmv.io
 Project-URL: Documentation, https://www.nextmv.io/docs
 Project-URL: Repository, https://github.com/nextmv-io/nextmv-py
 Author-email: Nextmv <tech@nextmv.io>
+Maintainer-email: Nextmv <tech@nextmv.io>
 License:                                  Apache License
                                    Version 2.0, January 2004
                                 http://www.apache.org/licenses/

{nextmv-0.1.0.dev2 → nextmv-0.1.0.dev4}/nextmv/cloud/application.py

@@ -78,6 +78,10 @@ class PollingOptions(BaseModel):
     """Maximum number of tries to use."""
 
 
+_DEFAULT_POLLING_OPTIONS: PollingOptions = PollingOptions()
+"""Default polling options to use when polling for a run result."""
+
+
 class RunInformation(BaseModel):
     """Information of a run."""
 
@@ -473,7 +477,7 @@ class Application:
         upload_id_used = upload_id is not None
         if not upload_id_used and input_size > _MAX_RUN_SIZE:
             upload_url = self.upload_url()
-            self.upload_large_input(upload_url=upload_url, input=input)
+            self.upload_large_input(input=input, upload_url=upload_url)
             upload_id = upload_url.upload_id
             upload_id_used = True
 
@@ -510,7 +514,7 @@ class Application:
         description: str | None = None,
         upload_id: str | None = None,
         run_options: dict[str, Any] | None = None,
-        polling_options: PollingOptions = None,
+        polling_options: PollingOptions = _DEFAULT_POLLING_OPTIONS,
     ) -> RunResult:
         """
         Submit an input to start a new run of the application and poll for the
@@ -526,8 +530,7 @@ class Application:
             description: Description of the run.
             upload_id: ID to use when running a large input.
             run_options: Options to use for the run.
-            polling_options: Options to use when polling for the run result. If
-                not provided, the default options will be used.
+            polling_options: Options to use when polling for the run result.
 
          Returns:
             Result of the run.
@@ -596,7 +599,7 @@ class Application:
     def run_result_with_polling(
         self,
         run_id: str,
-        polling_options: PollingOptions,
+        polling_options: PollingOptions = _DEFAULT_POLLING_OPTIONS,
     ) -> RunResult:
         """
         Get the result of a run. The result includes the run output. This
@@ -605,6 +608,7 @@ class Application:
 
         Args:
             run_id: ID of the run.
+            polling_options: Options to use when polling for the run result.
 
         Returns:
             Result of the run.
@@ -613,9 +617,6 @@ class Application:
             requests.HTTPError: If the response status code is not 2xx.
         """
 
-        if polling_options is None:
-            polling_options = PollingOptions()
-
         time.sleep(polling_options.initial_delay)
         delay = polling_options.delay
         polling_ok = False
@@ -643,15 +644,15 @@ class Application:
 
     def upload_large_input(
         self,
-        upload_url: UploadURL,
         input: dict[str, Any],
+        upload_url: UploadURL,
     ) -> None:
         """
         Upload the file located at the given path to the provided upload URL.
 
         Args:
             upload_url: Upload URL to use for uploading the file.
-            input_path: Path to the input file.
+            input: Input to use for the run.
 
         Raises:
             requests.HTTPError: If the response status code is not 2xx.

nextmv-0.1.0.dev4/nextmv/nextroute/check/__init__.py

@@ -0,0 +1,26 @@
+"""
+Check provides a plugin that allows you 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

nextmv-0.1.0.dev4/nextmv/nextroute/check/schema.py

@@ -0,0 +1,140 @@
+"""This module contains definitions for the schema in the Nextroute check."""
+
+
+from nextmv.base_model import BaseModel
+
+
+class ObjectiveTerm(BaseModel):
+    """Check of the individual terms of the objective for a move."""
+
+    base: float | None = None
+    """Base of the objective term."""
+    factor: float | None = None
+    """Factor of the objective term."""
+    name: str | None = None
+    """Name of the objective term."""
+    value: float | None = 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: list[ObjectiveTerm] | None = None
+    """Check of the individual terms of the objective."""
+    value: float | None = None
+    """Value of the objective."""
+    vehicle: str | None = None
+    """ID of the vehicle for which it reports the objective."""
+
+
+class Solution(BaseModel):
+    """Solution that the check has been executed on."""
+
+    objective: Objective | None = None
+    """Objective of the start solution."""
+    plan_units_planned: int | None = None
+    """Number of plan units planned in the start solution."""
+    plan_units_unplanned: int | None = None
+    """Number of plan units unplanned in the start solution."""
+    stops_planned: int | None = None
+    """Number of stops planned in the start solution."""
+    vehicles_not_used: int | None = None
+    """Number of vehicles not used in the start solution."""
+    vehicles_used: int | None = None
+    """Number of vehicles used in the start solution."""
+
+
+class Summary(BaseModel):
+    """Summary of the check."""
+
+    moves_failed: int | None = 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: int | None = 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: int | None = 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: int | None = 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: int | None = 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: int | None = 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: int | None = None
+    """Number of plan units to be checked."""
+
+
+class PlanUnit(BaseModel):
+    """Check of a plan unit."""
+
+    best_move_failed: bool | None = None
+    """True if the plan unit's best move failed to execute."""
+    best_move_increases_objective: bool | None = None
+    """True if the best move for the plan unit increases the objective."""
+    best_move_objective: Objective | None = None
+    """Estimate of the objective of the best move if the plan unit has a best
+    move."""
+    constraints: dict[str, int] | None = None
+    """Constraints that are violated for the plan unit."""
+    has_best_move: bool | None = 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: list[str] | None = None
+    """IDs of the sops in the plan unit."""
+    vehicles_have_moves: int | None = None
+    """Number of vehicles that have moves for the plan unit. Only calculated if
+    the verbosity is very high."""
+    vehicles_with_moves: list[str] | None = 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: int | None = 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: float | None = None
+    """Maximum duration of the check, in seconds."""
+    duration_used: float | None = None
+    """Duration used by the check, in seconds."""
+    error: str | None = None
+    """Error raised during the check."""
+    plan_units: list[PlanUnit] | None = None
+    """Check of the individual plan units."""
+    remark: str | None = None
+    """Remark of the check. It can be "ok", "timeout" or anything else that
+    should explain itself."""
+    solution: Solution | None = None
+    """Start soltuion of the check."""
+    summary: Summary | None = None
+    """Summary of the check."""
+    vehicles: list[Vehicle] | None = None
+    """Check of the vehicles."""
+    verbosity: str | None = None
+    """Verbosity level of the check."""

nextmv-0.1.0.dev4/nextmv/nextroute/schema/__init__.py

@@ -0,0 +1,25 @@
+"""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 DataPoint as DataPoint
+from .output import ObjectiveOutput as ObjectiveOutput
+from .output import Output as Output
+from .output import PlannedStopOutput as PlannedStopOutput
+from .output import ResultStatistics as ResultStatistics
+from .output import RunStatistics as RunStatistics
+from .output import Series as Series
+from .output import SeriesData as SeriesData
+from .output import Solution as Solution
+from .output import Statistics as Statistics
+from .output import StopOutput as StopOutput
+from .output import VehicleOutput as VehicleOutput
+from .output import Version as Version
+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

{nextmv-0.1.0.dev2 → nextmv-0.1.0.dev4}/nextmv/nextroute/schema/input.py

@@ -1,4 +1,4 @@
-"""Defines the input class"""
+"""Defines the input class."""
 
 from typing import Any
 

nextmv-0.1.0.dev4/nextmv/nextroute/schema/output.py

@@ -0,0 +1,202 @@
+"""Defines the output class."""
+
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import Field
+
+from nextmv.base_model import BaseModel
+from nextmv.nextroute.check import Output as checkOutput
+from nextmv.nextroute.schema.location import Location
+
+
+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: Any | None = 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: datetime | None = None
+    """Actual arrival time at this stop."""
+    cumulative_travel_distance: float | None = None
+    """Cumulative distance to travel from the first stop to this one, in meters."""
+    cumulative_travel_duration: float | None = None
+    """Cumulative duration to travel from the first stop to this one, in seconds."""
+    custom_data: Any | None = None
+    """Custom data of the stop."""
+    duration: float | None = None
+    """Duration of the service at the stop, in seconds."""
+    early_arrival_duration: float | None = None
+    """Duration of early arrival at the stop, in seconds."""
+    end_time: datetime | None = None
+    """End time of the service at the stop."""
+    late_arrival_duration: float | None = None
+    """Duration of late arrival at the stop, in seconds."""
+    mix_items: Any | None = None
+    """Mix items at the stop."""
+    start_time: datetime | None = None
+    """Start time of the service at the stop."""
+    target_arrival_time: datetime | None = None
+    """Target arrival time at this stop."""
+    travel_distance: float | None = None
+    """Distance to travel from the previous stop to this one, in meters."""
+    travel_duration: float | None = None
+    """Duration to travel from the previous stop to this one, in seconds."""
+    waiting_duration: float | None = 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: list[str] | None = None
+    """List of alternate stops that were planned on the vehicle."""
+    custom_data: Any | None = None
+    """Custom data of the vehicle."""
+    route: list[PlannedStopOutput] | None = None
+    """Route of the vehicle, which is a list of stops that were planned on
+    it."""
+    route_duration: float | None = None
+    """Total duration of the vehicle's route, in seconds."""
+    route_stops_duration: float | None = None
+    """Total duration of the stops of the vehicle, in seconds."""
+    route_travel_distance: float | None = None
+    """Total travel distance of the vehicle, in meters."""
+    route_travel_duration: float | None = None
+    """Total travel duration of the vehicle, in seconds."""
+    route_waiting_duration: float | None = 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: float | None = None
+    """Base of the objective."""
+    custom_data: Any | None = None
+    """Custom data of the objective."""
+    factor: float | None = None
+    """Factor of the objective."""
+    objectives: list[dict[str, Any]] | None = None
+    """List of objectives. Each list is actually of the same class
+    `ObjectiveOutput`, but we avoid a recursive definition here."""
+    value: float | None = None
+    """Value of the objective, which is equivalent to `self.base *
+    self.factor`."""
+
+
+class Solution(BaseModel):
+    """Solution to a Vehicle Routing Problem (VRP)."""
+
+    unplanned: list[StopOutput] | None = None
+    """List of stops that were not planned in the solution."""
+    vehicles: list[VehicleOutput] | None = None
+    """List of vehicles in the solution."""
+    objective: ObjectiveOutput | None = None
+    """Information of the objective (value function)."""
+    check: checkOutput | None = None
+    """Check of the solution, if enabled."""
+
+
+class RunStatistics(BaseModel):
+    """Statistics about a general run."""
+
+    duration: float | None = None
+    """Duration of the run in seconds."""
+    iterations: int | None = None
+    """Number of iterations."""
+    custom: Any | None = None
+    """Custom statistics created by the user. Can normally expect a `dict[str,
+    Any]`."""
+
+
+class ResultStatistics(BaseModel):
+    """Statistics about a specific result."""
+
+    duration: float | None = None
+    """Duration of the run in seconds."""
+    value: float | None = None
+    """Value of the result."""
+    custom: Any | None = None
+    """Custom statistics created by the user. Can normally expect a `dict[str,
+    Any]`."""
+
+
+class DataPoint(BaseModel):
+    """A 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."""
+
+    name: str | None = None
+    """Name of the series."""
+    data_points: list[DataPoint] | None = None
+    """Data of the series."""
+
+
+class SeriesData(BaseModel):
+    """Data of a series."""
+
+    value: Series | None = None
+    """A series for the value of the solution."""
+    custom: list[Series] | None = None
+    """A list of series for custom statistics."""
+
+
+class Statistics(BaseModel):
+    """Statistics of a solution."""
+
+    run: RunStatistics | None = None
+    """Statistics about the run."""
+    result: ResultStatistics | None = None
+    """Statistics about the last result."""
+    series_data: SeriesData | None = None
+    """Data of the series."""
+    statistics_schema: str | None = Field(alias="schema")
+    """Schema (version)."""
+
+
+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: list[Solution] | None = None
+    """Solutions to the problem."""
+    statistics: Statistics | None = None
+    """Statistics of the solution."""

{nextmv-0.1.0.dev2 → nextmv-0.1.0.dev4}/pyproject.toml

@@ -28,10 +28,13 @@ keywords = [
     "vehicle routing problem",
 ]
 license = { file = "LICENSE" }
+maintainers = [
+    { email = "tech@nextmv.io", name = "Nextmv" }
+]
 name = "nextmv"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "0.1.0.dev2"
+version = "0.1.0.dev4"
 
 [project.urls]
 Homepage = "https://www.nextmv.io"