AutoGineer
Generated banner for Cuopt Routing API Python
Generated logo for Cuopt Routing API Python

Cuopt Routing API Python

NVIDIAOfficialCreated by NVIDIA cuOpt Team

  • Skill
  • Tool integration
  • Automation and integrations
  • Apache-2.0
  • Medium risk
  • Has scripts
Download ZIP

From the author

Vehicle routing (VRP, TSP, PDP) with cuOpt — Python API only. Use when the user is building or solving routing in Python.
— the description by NVIDIA cuOpt Team

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The cuOpt Python API provides tools for modeling and solving complex vehicle routing problems. It supports various problem types such as the Traveling Salesperson Problem (TSP), Vehicle Routing Problem (VRP), and Pickup and Delivery Problem (PDP). The API allows users to define data models, incorporate constraints like time windows, service times, and capacity dimensions, and execute solvers to generate optimized routes.

What it does

  • Defines data models for routing problems using Python.
  • Supports constraints including time windows, vehicle capacities, and service times.
  • Handles pickup and delivery pair requirements.
  • Provides solver settings to configure execution parameters.
  • Enables retrieval and display of optimized route results.
  • Offers a REST client interface for remote service interaction.

When to use it

  • When building routing solutions within a Python environment.
  • When solving VRP, TSP, or PDP scenarios.
  • When integrating routing logic into larger Python-based applications.
  • When needing to define specific fleet configurations and order constraints.

Advantages

  • Native Python API integration.
  • Flexible constraint modeling for complex logistics.
  • Support for both local execution and REST server interaction.
  • Structured error reporting for infeasible routing scenarios.

Usage examples

“How do I set up a basic VRP with time windows in cuOpt?”
The agent provides a Python code snippet demonstrating the initialization of a DataModel, adding cost and transit time matrices, and applying order time windows and vehicle capacities.
“How can I debug an infeasible order in my routing model?”
The agent explains how to check the solver status and use get_infeasible_orders() to identify which specific orders could not be routed.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/nvidia/cuopt-routing-api-python/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip cuopt-routing-api-python.zip -d .agents/skills

Documentation by NVIDIA cuOpt Team

cuOpt Routing — Python API

This skill is Python only. Routing has no C API in cuOpt.

Required questions

Ask these if not already clear:

  1. Problem type — TSP, VRP, or PDP?

  2. Locations — How many? Depot(s)? Cost or distance between pairs (matrix or derived)?

  3. Orders / tasks — Which locations must be visited? Demand or service per stop?

  4. Fleet — Number of vehicles, capacity per vehicle (and per dimension if multiple), start/end locations?

  5. Constraints — Time windows (earliest/latest arrival), service times, precedence (order A before B)?

Minimal VRP Example

import cudf
from cuopt import routing

cost_matrix = cudf.DataFrame([...], dtype="float32")
dm = routing.DataModel(n_locations=4, n_fleet=2, n_orders=3)
dm.add_cost_matrix(cost_matrix)
dm.set_order_locations(cudf.Series([1, 2, 3], dtype="int32"))
solution = routing.Solve(dm, routing.SolverSettings())

if solution.get_status() == 0:
    solution.display_routes()

Adding Constraints

# Time windows
dm.add_transit_time_matrix(transit_time_matrix)
dm.set_order_time_windows(earliest_series, latest_series)

# Capacities
dm.add_capacity_dimension("weight", demand_series, capacity_series)
dm.set_order_service_times(service_times)
dm.set_vehicle_locations(start_locations, end_locations)
dm.set_vehicle_time_windows(earliest_start, latest_return)

# Pickup-delivery pairs
dm.set_pickup_delivery_pairs(pickup_indices, delivery_indices)

# Precedence
dm.add_order_precedence(node_id=2, preceding_nodes=np.array([0, 1]))

Solution Checking

status = solution.get_status()  # 0=SUCCESS, 1=FAIL, 2=TIMEOUT, 3=EMPTY
if status == 0:
    route_df = solution.get_route()
    total_cost = solution.get_total_objective()
else:
    print(solution.get_error_message())
    print(solution.get_infeasible_orders().to_list())

Data Types (use explicit dtypes)

cost_matrix = cost_matrix.astype("float32")
order_locations = cudf.Series([...], dtype="int32")
demand = cudf.Series([...], dtype="int32")

Solver Settings

ss = routing.SolverSettings()
ss.set_time_limit(30)
ss.set_verbose_mode(True)
ss.set_error_logging_mode(True)

Common Issues

ProblemFix
Empty solutionWiden time windows or check travel times
Infeasible ordersIncrease fleet or capacity
Status != 0 with time windowsAdd add_transit_time_matrix()
Wrong costCheck cost_matrix is symmetric
compute_waypoint_sequence alters route_dfIt replaces the location column with waypoint ids in place — pass route_df.copy() if you still need cost-matrix indices (e.g. when iterating per truck)

Debugging

When status != 0: print(solution.get_error_message()) and print(solution.get_infeasible_orders().to_list()) to see which orders are infeasible.

Data types: Use explicit dtypes (float32, int32) for matrices and series to avoid silent errors.

Examples

Escalate

For contribution or build-from-source, see the developer skill.

Files

assets/vrp_basic/model.py

# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

"""
Minimal VRP: 4 locations, 1 vehicle, 3 orders. Cost matrix only.
"""

import cudf
from cuopt import routing

cost_matrix = cudf.DataFrame(
    [
        [0, 10, 15, 20],
        [10, 0, 12, 18],
        [15, 12, 0, 10],
        [20, 18, 10, 0],
    ],
    dtype="float32",
)

dm = routing.DataModel(n_locations=4, n_fleet=1, n_orders=3)
dm.add_cost_matrix(cost_matrix)
dm.set_order_locations(cudf.Series([1, 2, 3], dtype="int32"))

solution = routing.Solve(dm, routing.SolverSettings())

if solution.get_status() == 0:
    solution.display_routes()
    print(f"Total cost: {solution.get_total_objective()}")
else:
    print(f"Status: {solution.get_status()}", solution.get_error_message())

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

What our scanner noticed· Medium risk

  • Large base64-encoded blobs
  • Instructions that use the network
  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
NVIDIA cuOpt Team
Publisher
NVIDIA (Official)
Source
NVIDIA/skills · skills/cuopt-routing-api-python · commit fce3cca
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE-APACHE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by NVIDIA cuOpt Team or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download cuopt-routing-api-python.zip