Skip to content

Quick Start

This guide walks you through solving your first vehicle routing problem with TQrouting.

The Scenario

You have a depot and 3 customers. Each customer needs a delivery with a certain load. You have vehicles with limited capacity. The goal: find the shortest routes that serve all customers without exceeding vehicle capacity.

Step 1: Create the Router

from tqrouting import TQRouter

router = TQRouter()

The TQRouter is your main interface to the solver. Create it once and reuse it for multiple problems.

Step 2: Define the Problem

Create a VRPInstance — you can build it in code, load from a dictionary, or from a JSON file:

from tqrouting import VRPInstance, Customer, VehicleType, Location

instance = VRPInstance(
    customers=[
        Customer(location=Location(matrix_id=1), delivery_load=9),
        Customer(location=Location(matrix_id=2), delivery_load=4),
        Customer(location=Location(matrix_id=3), delivery_load=10),
    ],
    fleet=[
        VehicleType(
            start_location=Location(matrix_id=0),
            end_location=Location(matrix_id=0),
            capacity_load=20,
            n_vehicles=3,
        ),
    ],
    distance_matrix=[
        [0, 2, 5, 8],
        [2, 0, 7, 6],
        [5, 7, 0, 4],
        [8, 6, 4, 0],
    ],
)

from tqrouting import VRPInstance

instance = VRPInstance.from_dict({
    "customers": [
        {"location": {"matrix_id": 1}, "delivery_load": 9},
        {"location": {"matrix_id": 2}, "delivery_load": 4},
        {"location": {"matrix_id": 3}, "delivery_load": 10},
    ],
    "fleet": [
        {
            "start_location": {"matrix_id": 0},
            "end_location": {"matrix_id": 0},
            "capacity_load": 20,
            "n_vehicles": 3,
        }
    ],
    "distance_matrix": [
        [0, 2, 5, 8],
        [2, 0, 7, 6],
        [5, 7, 0, 4],
        [8, 6, 4, 0],
    ],
})

Save the dictionary above as problem.json:

{
  "customers": [
    {"location": {"matrix_id": 1}, "delivery_load": 9},
    {"location": {"matrix_id": 2}, "delivery_load": 4},
    {"location": {"matrix_id": 3}, "delivery_load": 10}
  ],
  "fleet": [
    {"start_location": {"matrix_id": 0}, "end_location": {"matrix_id": 0}, "capacity_load": 20, "n_vehicles": 3}
  ],
  "distance_matrix": [
    [0, 2, 5, 8],
    [2, 0, 7, 6],
    [5, 7, 0, 4],
    [8, 6, 4, 0]
  ]
}

and load it:

from tqrouting import VRPInstance

instance = VRPInstance.from_json("problem.json")

instance.to_json("problem.json") writes exactly this format, so any instance built in Python can be saved and loaded again. Unknown keys are rejected with a hint — see Serialization.

Here:

  • Customers are at matrix positions 1, 2, 3 with delivery loads of 9, 4, and 10 units
  • Fleet has up to 3 vehicles, each starting and ending at position 0 (depot), with 20 units capacity
  • Distance matrix is a 4×4 matrix (depot + 3 customers) with travel costs between all locations. It can represent either distances or durations depending on the problem.

Step 3: Solve

solution = router.solve(instance, time_limit=5)

Step 4: Read the Results

print(f"Feasible: {solution.is_feasible}")
print(f"Total duration: {solution.total_route_duration}")
print(f"Number of routes: {len(solution.routes)}")

for route in solution.routes:
    customers = [v.customer_id for v in route.visits]
    print(f"  Route {route.id}: {customers} (delivery load: {route.route_delivery_load})")

Output: 

Feasible: True
Total duration: 21.0
Number of routes: 2
  Route 0: [0] (delivery load: 9.0)
  Route 1: [2, 1] (delivery load: 14.0)

Next Steps