Cuopt Routing API Python

NVIDIAOfficialCreated by NVIDIA cuOpt Team

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

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

Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/cuopt-routing-api-python/download

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:

Problem type — TSP, VRP, or PDP?
Locations — How many? Depot(s)? Cost or distance between pairs (matrix or derived)?
Orders / tasks — Which locations must be visited? Demand or service per stop?
Fleet — Number of vehicles, capacity per vehicle (and per dimension if multiple), start/end locations?
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

Problem	Fix
Empty solution	Widen time windows or check travel times
Infeasible orders	Increase fleet or capacity
Status != 0 with time windows	Add `add_transit_time_matrix()`
Wrong cost	Check cost_matrix is symmetric
`compute_waypoint_sequence` alters route_df	It 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

examples.md — VRP, PDP, multi-depot
server_examples.md — REST client (curl, Python)
Reference models: This skill's assets/ — vrp_basic, pdp_basic. See assets/README.md.

Escalate

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

Files

ATTRIBUTION.mdAdded by AutoGineer941 B
BENCHMARK.md4.6 KiB
LICENSELicence file added by AutoGineer11.2 KiB
SKILL.md3.6 KiB
assets/README.md553 B
assets/pdp_basic/README.md257 B
assets/pdp_basic/model.pyScript1.5 KiB
assets/vrp_basic/README.md272 B
assets/vrp_basic/model.pyScript838 B
evals/evals.json8.7 KiB
references/examples.md6.9 KiB
references/server_examples.md5.7 KiB
skill-card.md4.0 KiB
skill.oms.sig6.1 KiB

references/server_examples.md

Routing: REST Server Examples

Start the Server

# Start server
python -m cuopt_server.cuopt_service --ip 0.0.0.0 --port 8000 &

# Wait and verify
sleep 5
curl -s http://localhost:8000/cuopt/health

Basic VRP (curl)

REQID=$(curl -s -X POST "http://localhost:8000/cuopt/request" \
  -H "Content-Type: application/json" \
  -H "CLIENT-VERSION: custom" \
  -d '{
    "cost_matrix_data": {
      "data": {"0": [[0,10,15,20],[10,0,12,18],[15,12,0,10],[20,18,10,0]]}
    },
    "travel_time_matrix_data": {
      "data": {"0": [[0,10,15,20],[10,0,12,18],[15,12,0,10],[20,18,10,0]]}
    },
    "task_data": {
      "task_locations": [1, 2, 3],
      "demand": [[10, 15, 20]],
      "task_time_windows": [[0, 100], [10, 80], [20, 90]],
      "service_times": [5, 5, 5]
    },
    "fleet_data": {
      "vehicle_locations": [[0, 0], [0, 0]],
      "capacities": [[50, 50]],
      "vehicle_time_windows": [[0, 200], [0, 200]]
    },
    "solver_config": {
      "time_limit": 5
    }
  }' | jq -r '.reqId')

echo "Request ID: $REQID"

# Poll for solution
sleep 2
curl -s "http://localhost:8000/cuopt/solution/$REQID" \
  -H "Content-Type: application/json" \
  -H "CLIENT-VERSION: custom" | jq .

VRP with Time Windows (Python requests)

import requests
import time

SERVER = "http://localhost:8000"
HEADERS = {"Content-Type": "application/json", "CLIENT-VERSION": "custom"}

payload = {
    "cost_matrix_data": {
        "data": {
            "0": [
                [0, 10, 15, 20, 25],
                [10, 0, 12, 18, 22],
                [15, 12, 0, 10, 15],
                [20, 18, 10, 0, 8],
                [25, 22, 15, 8, 0]
            ]
        }
    },
    "travel_time_matrix_data": {
        "data": {
            "0": [
                [0, 10, 15, 20, 25],
                [10, 0, 12, 18, 22],
                [15, 12, 0, 10, 15],
                [20, 18, 10, 0, 8],
                [25, 22, 15, 8, 0]
            ]
        }
    },
    "task_data": {
        "task_locations": [1, 2, 3, 4],
        "demand": [[20, 30, 25, 15]],
        "task_time_windows": [[0, 50], [10, 60], [20, 70], [0, 80]],
        "service_times": [5, 5, 5, 5]
    },
    "fleet_data": {
        "vehicle_locations": [[0, 0], [0, 0]],
        "capacities": [[100, 100]],
        "vehicle_time_windows": [[0, 200], [0, 200]]
    },
    "solver_config": {
        "time_limit": 10
    }
}

# Submit request
response = requests.post(f"{SERVER}/cuopt/request", json=payload, headers=HEADERS)
response.raise_for_status()
req_id = response.json()["reqId"]
print(f"Request submitted: {req_id}")

# Poll for solution
for attempt in range(30):
    response = requests.get(f"{SERVER}/cuopt/solution/{req_id}", headers=HEADERS)
    result = response.json()

    if "response" in result:
        solver_response = result["response"].get("solver_response", {})
        print(f"\nSolution found!")
        print(f"Status: {solver_response.get('status', 'N/A')}")
        print(f"Cost: {solver_response.get('solution_cost', 'N/A')}")

        if "vehicle_data" in solver_response:
            for vid, vdata in solver_response["vehicle_data"].items():
                route = vdata.get("route", [])
                print(f"Vehicle {vid}: {' -> '.join(map(str, route))}")
        break
    else:
        print(f"Waiting... (attempt {attempt + 1})")
        time.sleep(1)

Pickup and Delivery (curl)

REQID=$(curl -s -X POST "http://localhost:8000/cuopt/request" \
  -H "Content-Type: application/json" \
  -H "CLIENT-VERSION: custom" \
  -d '{
    "cost_matrix_data": {
      "data": {"0": [[0,10,20,30,40],[10,0,15,25,35],[20,15,0,10,20],[30,25,10,0,15],[40,35,20,15,0]]}
    },
    "travel_time_matrix_data": {
      "data": {"0": [[0,10,20,30,40],[10,0,15,25,35],[20,15,0,10,20],[30,25,10,0,15],[40,35,20,15,0]]}
    },
    "task_data": {
      "task_locations": [1, 2, 3, 4],
      "demand": [[10, -10, 15, -15]],
      "pickup_and_delivery_pairs": [[0, 1], [2, 3]]
    },
    "fleet_data": {
      "vehicle_locations": [[0, 0]],
      "capacities": [[50]]
    },
    "solver_config": {
      "time_limit": 10
    }
  }' | jq -r '.reqId')

echo "Request ID: $REQID"

# Poll for solution
sleep 2
curl -s "http://localhost:8000/cuopt/solution/$REQID" \
  -H "Content-Type: application/json" \
  -H "CLIENT-VERSION: custom" | jq .

Terminology Reference

Python API	REST Server API
`order_locations`	`task_locations`
`set_order_time_windows()`	`task_time_windows`
`set_order_service_times()`	`service_times`
`add_transit_time_matrix()`	`travel_time_matrix_data`
`set_pickup_delivery_pairs()`	`pickup_and_delivery_pairs`

Common Payload Mistakes

// ❌ WRONG field name
"transit_time_matrix_data": {...}

// ✅ CORRECT
"travel_time_matrix_data": {...}

// ❌ WRONG capacity format (per vehicle)
"capacities": [[50], [50]]

// ✅ CORRECT (per dimension across vehicles)
"capacities": [[50, 50]]

Additional References (tested in CI)

For more complete examples, read these files:

Example	File	Description
Basic Routing (Python)	`docs/cuopt/source/cuopt-server/examples/routing/examples/basic_routing_example.py`	VRP via REST
Basic Routing (curl)	`docs/cuopt/source/cuopt-server/examples/routing/examples/basic_routing_example.sh`	Shell script
Initial Solution	`docs/cuopt/source/cuopt-server/examples/routing/examples/initial_solution_example.py`	Warm starting
Initial Solution (curl)	`docs/cuopt/source/cuopt-server/examples/routing/examples/initial_solution_example.sh`	Warm start shell

These examples are tested by CI (ci/test_doc_examples.sh) and represent canonical usage.

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

2026-11-09

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