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.
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:
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.
{
"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
}
}
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.
Bugs should be formally submitted using the NGC cuOpt Service landing page
Errors and Causes
"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
"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
Authentication Error: Invalid Client ID or Client Secret
Invalid Client ID or Secret has been provided; please ensure they match.
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
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
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
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
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
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
cuOpt Error: Bad Request - 400: task_time_windows must be greater than or equal to 0
Task time window contains the non-negative value
cuOpt Error: Bad Request - 400: service_times must be greater than or equal to 0
Service time should be a non-negative value
cuOpt Error: Bad Request - 400: priorities must be within the range of [0, 255]
Task/Job Priorities should lie within [0, 255]
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
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.
cuOpt Error: Bad Request - 400: Vehicle priorities must be within the range of [0, 255]
Vehicle Priorities should lie within [0, 255]
cuOpt Error: Bad Request - 400: All capacity dimensions values must be 0 or greater
Vehicle capacity should be non-negative
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