API

The routing optimization-focused API lets users easily map their problems to familiar data concepts, such as environments, fleets, and tasks. The NVIDIA cuOpt API describes the routing problem (distance matrices and depot and delivery locations), the available resources (vehicle properties, capacity, speed limits, operating hours and costs, maximum run time), and constraints (max and min number of vehicles, time windows, break periods, refueling locations, max travel distance and max operating time).

After the problem is fully described, the API allows a ‘solve()’ call to calculate the optimal solution found in the available time.

Note

The solve function returns the solution but may need parsing before being displayed or dispatched to real drivers.

Listed below is a simple example illustrating cuOpt Service Python Thin Client API usage:

Copy
Copied!
            

from cuopt_thin_client import CuOptServiceClient cuopt_service_client = CuOptServiceClient( client_id=cuopt_client_id, client_secret=cuopt_client_secret, ) with open(cuopt_problem_data_file_path, "r") as f: cuopt_problem_data = json.load(f) ''' The problem_data_file should contain a JSON with the following details: cost_waypoint_graph_data: Waypoint graph of the Cost Matrix travel_time_waypoint_graph_data: Waypoint graph of the Travel time matrix cost_matrix_data: Cost matrix travel_time_matrix_data: Travel time matrix fleet_data: Fleet information task_data: Task Waypoint graph of solver_config: Solver settings For more details, see https://docs.nvidia.com/cuopt/user-guide/serv_api.html. ''' optimized_routes = cuopt_service_client.get_optimized_routes( cuopt_problem_data)

As noted in the green comment text above, a problem_data is sent to the cuOpt solver in a single JSON file. The following sample JSON below is a template dictionary that includes all possible cuOpt inputs. This dictionary is populated with values of 0, which can be swapped for your input values in your problem. Here you can see what the expected data type is for all of the input parameters. Most values should be lists of integers. However, some are nested lists, strings, boolean values, or dictionaries.

Copy
Copied!
            

{ "cost_waypoint_graph_data": { "waypoint_graph": { "property1": { "edges": [ 0 ], "offsets": [ 0 ], "weights": [ 0 ] }, "property2": { "edges": [ 0 ], "offsets": [ 0 ], "weights": [ 0 ] } } }, "travel_time_waypoint_graph_data": { "waypoint_graph": { "property1": { "edges": [ 0 ], "offsets": [ 0 ], "weights": [ 0 ] }, "property2": { "edges": [ 0 ], "offsets": [ 0 ], "weights": [ 0 ] } } }, "cost_matrix_data": { "cost_matrix": { "property1": [ [ 0 ] ], "property2": [ [ 0 ] ] } }, "travel_time_matrix_data": { "cost_matrix": { "property1": [ [ 0 ] ], "property2": [ [ 0 ] ] } }, "fleet_data": { "vehicle_locations": [ [ 0 ] ], "vehicle_ids": [ "string" ], "capacities": [ [ 0 ] ], "priorities": [ 0 ], "vehicle_time_windows": [ [ 0 ] ], "vehicle_break_time_windows": [ [ [ 0 ] ] ], "vehicle_break_durations": [ [ 0 ] ], "vehicle_break_locations": [ 0 ], "vehicle_types": [ 0 ], "vehicle_order_match": [ { "vehicle_id": 0, "order_ids": [ 0 ] } ], "skip_first_trips": [ true ], "drop_return_trips": [ true ], "min_vehicles": 0, "vehicle_max_costs": [ 0 ], "vehicle_max_times": [ 0 ], }, "task_data": { "task_locations": [ 0 ], "task_ids": [ "string" ], "demand": [ [ 0 ] ], "pickup_and_delivery_pairs": [ [ 0 ] ], "task_time_windows": [ [ 0 ] ], "service_times": [ 0 ], "priorities": [ 0 ], "prizes": [ 0 ], "order_vehicle_match": [ { "order_id": 0, "vehicle_ids": [ 0 ] } ], "mandatory_task_ids": [ 0 ] }, "solver_config": { "time_limit": 0, "objectives": { "cost": 0, "travel_time": 0, "variance_route_size": 0, "variance_route_service_time": 0 }, "config_file": "string", "verbose_mode": true, "error_logging": true, "drop_infeasible_tasks": false } }

Important

Please refer to the cuOpt Server API reference guide for Task, Fleet, and Solver Configuration payload options.

  • If the authentication is failing

    • Make sure Client ID and secret are set properly

    • Check if the secret is expired, and if expired, generate a new one

    • Delete cache for a token if nothing works

  • If you are failing to connect to the endpoint

    • Maybe you have a local cache that is pointing to the wrong function; please delete the cache to unblock

    • Or maybe the NVIDIA cloud service infrastructure is down

  • If a request starts polling for a result and stops after a while without a result

    • Please wait for some time and try to hit the endpoint that was provided at the end to retrieve the result

    • If the time taken is excessive for a simple problem, then engage cuOpt support

  • If you are getting HTTP errors 500 or 409, these are from cuOpt

    • Please capture any output from the program and send it to us via a bug or incident report. Also, the dataset used would be good too, but please ensure it does not contain proprietary details

  • If you are getting any other HTTP errors, they are from NVIDIA cloud service infrastructure

    • Please submit a bug report.

Important

Bugs should be formally submitted using the NGC cuOpt Service landing page

Errors and Causes

Copy
Copied!
            

"Environment variable 'CUOPT_CLIENT_ID' not found"

  • ID is not set in the environment variable

  • For Linux:

    • export CUOPT_CLIENT_ID=”SSA_CLIENT_ID”

  • Else, set it in the cli or pass it in the function call

Copy
Copied!
            

"Environment variable 'CUOPT_CLIENT_SECRET' not found"

  • SECRET is not set in the environment variable

  • For Linux:

    • export CUOPT_CLIENT_SECRET=”SSA_SECRET”

  • Else, set it in the cli or pass it in the function call

Copy
Copied!
            

Authentication Error: Invalid Client ID or Client Secret

  • Invalid Client ID or Secret has been provided; please ensure they match.

Copy
Copied!
            

cuOpt Error: Conflict - 409: Infeasible Solve

  • The problem set provided is not feasible; constraints need to relax or enable the drop_infeasible option, which will drop infeasible jobs/tasks

Copy
Copied!
            

404 Client Error: Not Found for URL: *********

  • Trying to hit the wrong endpoint

  • Maybe a version cache mismatch; the cache needs to be clear

    • rm -rf version_cache.json

Copy
Copied!
            

cuOpt Error: Bad Request - 400: All values in cost_matrix must be >= 0

  • If the cost/time matrix has a negative value, which is not accepted

Copy
Copied!
            

cuOpt Error: Bad Request - 400: All rows in the cost matrix must be of the same length

  • If the cost/time matrix is not a square matrix

Copy
Copied!
            

cuOpt Error: Bad Request - 400: task_locations represent index locations and must be greater than or equal to 0

  • If the task locations provided are a negative value or invalid

Copy
Copied!
            

cuOpt Error: Unprocessable Entity - 422: [{'loc': ……

  • Malformed JSON data, maybe the name or structure of JSON data is mismatched

  • Details would be in the error message

Copy
Copied!
            

cuOpt Error: Bad Request - 400: task_time_windows must be greater than or equal to 0

  • Task time window contains the non-negative value

Copy
Copied!
            

cuOpt Error: Bad Request - 400: service_times must be greater than or equal to 0

  • Service time should be a non-negative value

Copy
Copied!
            

cuOpt Error: Bad Request - 400: priorities must be within the range of [0, 255]

  • Task/Job Priorities should lie within [0, 255]

Copy
Copied!
            

cuOpt Error: Bad Request - 400: Fleet locations represent index locations and must be greater than or equal to 0

  • Vehicle location should be non-negative

Copy
Copied!
            

cuOpt Error: Internal Server Error - 500: cuOpt unhandled exception, please include this message in any error report: Return location must be between min 0 and max num_locations!

  • Vehicle location should lie within [0, max_num_locations], determined by cost matrix/waypoint graph size.

Copy
Copied!
            

cuOpt Error: Bad Request - 400: Vehicle priorities must be within the range of [0, 255]

  • Vehicle Priorities should lie within [0, 255]

Copy
Copied!
            

cuOpt Error: Bad Request - 400: All capacity dimensions values must be 0 or greater

  • Vehicle capacity should be non-negative

Copy
Copied!
            

cuOpt Error: Bad Request - 400: vehicle_time_windows: All vehicle time window values must be greater than or equal to 0

  • Vehicle time windows should be non-negative

© Copyright 2021-2023, NVIDIA. Last updated on Oct 30, 2023.