Routing Examples#

This section contains examples for the cuOpt routing Python API.

TSP Batch Mode#

The routing Python API supports batch mode for solving many TSP (or routing) instances in a single call. Instead of calling cuopt.routing.Solve() repeatedly, you build a list of cuopt.routing.DataModel objects and call cuopt.routing.BatchSolve(). The solver runs the problems in parallel to improve throughput.

When to use batch mode:

  • You have many similar routing problems (e.g., dozens or hundreds of small TSPs).

  • You want to maximize throughput by utilizing the GPU across multiple problems at once.

  • Problem sizes and structure are compatible with the same cuopt.routing.SolverSettings (e.g., same time limit).

Returns: A list of cuopt.routing.Assignment objects, one per input data model, in the same order as data_model_list. Use cuopt.routing.Assignment.get_status() and other assignment methods to inspect each solution.

The following example builds several TSPs of different sizes, solves them in one batch, and prints a short summary per solution.

tsp_batch_example.py

 1# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 2# SPDX-License-Identifier: Apache-2.0
 3#
 4# TSP batch solve example: solve multiple TSP instances in one call for higher throughput.
 5# Use this when you have many similar routing problems (e.g., many small TSPs) to solve.
 6
 7import cudf
 8import numpy as np
 9
10from cuopt import routing
11
12
13def create_tsp_cost_matrix(n_locations):
14    """Create a simple symmetric cost matrix for a TSP of size n_locations."""
15    cost_matrix = np.zeros((n_locations, n_locations), dtype=np.float32)
16    for i in range(n_locations):
17        for j in range(n_locations):
18            cost_matrix[i, j] = abs(i - j)
19    return cudf.DataFrame(cost_matrix)
20
21
22def main():
23    # Define multiple TSP sizes to solve in one batch
24    tsp_sizes = [5, 8, 10, 6, 7, 9]
25
26    # Build one DataModel per TSP
27    data_models = []
28    for n_locations in tsp_sizes:
29        cost_matrix = create_tsp_cost_matrix(n_locations)
30        dm = routing.DataModel(n_locations, 1)  # n_locations, 1 vehicle (TSP)
31        dm.add_cost_matrix(cost_matrix)
32        data_models.append(dm)
33
34    # Shared solver settings for the batch
35    settings = routing.SolverSettings()
36    settings.set_time_limit(5.0)
37
38    # Solve all TSPs in batch (parallel execution)
39    solutions = routing.BatchSolve(data_models, settings)
40
41    # Inspect results
42    print(f"Solved {len(solutions)} TSPs in batch.")
43    for i, (size, solution) in enumerate(zip(tsp_sizes, solutions)):
44        status = solution.get_status()
45        status_str = (
46            "SUCCESS" if status == routing.SolutionStatus.SUCCESS else status
47        )
48        vehicle_count = solution.get_vehicle_count()
49        print(
50            f"  TSP {i} (size {size}): status={status_str}, vehicles={vehicle_count}"
51        )
52
53
54if __name__ == "__main__":
55    main()

Sample output:

Solved 6 TSPs in batch.
  TSP 0 (size 5): status=SUCCESS, vehicles=1
  TSP 1 (size 8): status=SUCCESS, vehicles=1
  TSP 2 (size 10): status=SUCCESS, vehicles=1
  ...

Notes:

  • All problems in the batch use the same cuopt.routing.SolverSettings (e.g., time limit, solver options).

  • Callbacks are not supported in batch mode.

  • For best practices when batching many instances, see the Add best practices for batch solving note in the release documentation.

On this page