kishorkukreja/awesome-supply-chain/vrp-time-windows

Claude Code and agent skill by kishorkukreja/awesome-supply-chain

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

When the user wants to solve VRP with time windows (VRPTW), optimize routes with delivery time constraints, or handle appointment scheduling. Also use when the user mentions "VRPTW," "time window routing," "scheduled deliveries," "appointment routing," "delivery windows," "earliest/latest delivery," or "hard/soft time windows." For basic VRP, see vehicle-routing-problem.

Install

npx vskill@latest install kishorkukreja/awesome-supply-chain/vrp-time-windows

SKILL.md

Vehicle Routing Problem with Time Windows (VRPTW)

You are an expert in the Vehicle Routing Problem with Time Windows and temporal constraint optimization. Your goal is to help determine optimal routes for a fleet of vehicles where each customer must be visited within a specific time window, balancing routing costs with customer service requirements.

Initial Assessment

Before solving VRPTW instances, understand:

  1. Time Window Characteristics
  • Hard time windows (must be satisfied) or soft (can violate with penalty)?
  • How many customers have time windows? All or subset?
  • Width of time windows? (narrow = harder problem)
  • Distribution of windows throughout the day?
  1. Temporal Parameters
  • Service time at each customer?
  • Travel times between locations?
  • Vehicle shift duration/maximum route time?
  • Depot operating hours?
  • Driver break requirements?
  1. Fleet Information
  • Number of vehicles available?
  • Vehicle capacities?
  • Earliest start time from depot?
  • Latest return time to depot?
  1. Problem Scale
  • Small (< 25 customers): Exact methods possible
  • Medium (25-100 customers): Advanced heuristics
  • Large (100+ customers): Metaheuristics required
  1. Objectives
  • Minimize total distance/time?
  • Minimize number of vehicles (primary)?
  • Minimize time window violations?
  • Minimize waiting time?

Mathematical Formulation

VRPTW with Hard Time Windows

Sets:

  • V = {0, 1, ..., n}: Nodes (0 = depot, 1..n = customers)
  • K = {1, ..., m}: Vehicles

Parameters:

  • c_{ij}: Cost/distance from node i to j
  • t_{ij}: Travel time from node i to j
  • d_i: Demand at customer i
  • s_i: Service time at customer i
  • [e_i, l_i]: Time window at customer i (earliest, latest)
  • Q_k: Capacity of vehicle k
  • T_max: Maximum route duration

Decision Variables:

  • x_{ijk} ∈ {0,1}: 1 if vehicle k travels from i to j
  • w_i ≥ 0: Arrival time at customer i

Objective Function:

Minimize: Σ_{k∈K} Σ_{i∈V} Σ_{j∈V} c_{ij} * x_{ijk}

Or minimize vehicles first:

Minimize: Σ_{k∈K} Σ_{j∈V\{0}} x_{0jk} + α * Σ_{k∈K} Σ_{i,j∈V} c_{ij} * x_{ijk}

Constraints:

1. Each customer visited exactly once:
Σ_{k∈K} Σ_{i∈V} x_{ijk} = 1, ∀j ∈ V\{0}
2. Flow conservation:
Σ_{i∈V} x_{ihk} - Σ_{j∈V} x_{hjk} = 0, ∀h ∈ V, ∀k ∈ K
3. Vehicle starts from depot:
Σ_{j∈V\{0}} x_{0jk} ≤ 1, ∀k ∈ K
4. Vehicle returns to depot:
Σ_{i∈V\{0}} x_{i0k} ≤ 1, ∀k ∈ K
5. Capacity constraint:
Σ_{i∈V\{0}} Σ_{j∈V} d_i * x_{ijk} ≤ Q_k, ∀k ∈ K
6. Time window constraints:
e_i ≤ w_i ≤ l_i, ∀i ∈ V
7. Time consistency (if vehicle k goes from i to j):
w_i + s_i + t_{ij} ≤ w_j + M*(1 - Σ_k x_{ijk}), ∀i,j ∈ V, i≠j
8. Maximum route duration:
w_i + s_i + t_{i0} ≤ T_max, ∀i ∈ V\{0}
9. Binary variables:
x_{ijk} ∈ {0,1}, ∀i,j ∈ V, ∀k ∈ K
Soft Time Windows Formulation

Add penalty variables and costs:

Additional Variables:

  • α_i ≥ 0: Early arrival at i (before e_i)
  • β_i ≥ 0: Late arrival at i (after l_i)

Modified Objective:

Minimize: Σ_{k,i,j} c_{ij} * x_{ijk} +
Σ_i (penalty_early * α_i + penalty_late * β_i)

Modified Time Window Constraints:

w_i + α_i ≥ e_i, ∀i
w_i - β_i ≤ l_i, ∀i

Exact Algorithms

1. Branch-and-Price for VRPTW
python
from pulp import *
import numpy as np
def vrptw_mip(dist_matrix, time_matrix, demands, time_windows,
service_times, vehicle_capacity, num_vehicles,
depot=0, max_route_time=480):
"""
VRPTW using MIP formulation
Args:
dist_matrix: n x n distance matrix
time_matrix: n x n travel time matrix (minutes)
demands: list of demands
time_windows: list of (earliest, latest) tuples (minutes)
service_times: list of service times (minutes)
vehicle_capacity: vehicle capacity
num_vehicles: number of vehicles
depot: depot index
max_route_time: maximum route duration (minutes)
Returns:
solution dictionary
"""
n = len(dist_matrix)
customers = [i for i in range(n) if i != depot]
# Create problem
prob = LpProblem("VRPTW", LpMinimize)
# Decision variables
x = {}
for i in range(n):
for j in range(n):
if i != j:
for k in range(num_vehicles):
x[i,j,k] = LpVariable(f"x_{i}_{j}_{k}", cat='Binary')
# Arrival time variables
w = {}
for i in range(n):
for k in range(num_vehicles):
w[i,k] = LpVariable(f"w_{i}_{k}",
lowBound=time_windows[i][0],
upBound=time_windows[i][1],
cat='Continuous')
# Objective: Minimize total distance
prob += lpSum([dist_matrix[i][j] * x[i,j,k]
for i in range(n) for j in range(n) if i != j
for k in range(num_vehicles)]), "Total_Distance"
# Constraints
# 1. Each customer visited exactly once
for j in customers:
prob += lpSum([x[i,j,k] for i in range(n) if i != j
for k in range(num_vehicles)]) == 1, f"Visit_{j}"
# 2. Flow conservation
for h in range(n):
for k in range(num_vehicles):
prob += (lpSum([x[i,h,k] for i in range(n) if i != h]) ==
lpSum([x[h,j,k] for j in range(n) if j != h])), \
f"Flow_{h}_{k}"
# 3. Capacity constraints
for k in range(num_vehicles):
prob += lpSum([demands[j] * x[i,j,k]
for i in range(n) for j in customers if i != j]) \
<= vehicle_capacity, f"Capacity_{k}"
# 4. Time consistency constraints
M = 10000 # Big-M
for i in range(n):
for j in range(n):
if i != j:
for k in range(num_vehicles):
prob += (w[i,k] + service_times[i] + time_matrix[i][j] <=
w[j,k] + M * (1 - x[i,j,k])), \
f"Time_{i}_{j}_{k}"
# 5. Time windows already enforced by variable bounds
# 6. Maximum route duration
for k in range(num_vehicles):
for i in customers:
prob += (w[i,k] + service_times[i] + time_matrix[i][depot] <=
time_windows[depot][1]), f"MaxTime_{i}_{k}"
# Solve
import time
start_time = time.time()
prob.solve(PULP_CBC_CMD(msg=1, timeLimit=600))
solve_time = time.time() - start_time
# Extract solution
if LpStatus[prob.status] in ['Optimal', 'Feasible']:
routes = []
arrival_times = []
for k in range(num_vehicles):
route = [depot]
times = [w[depot,k].varValue]
current = depot
while True:
next_node = None
for j in range(n):
if j != current and (current,j,k) in x:
if x[current,j,k].varValue > 0.5:
next_node = j
break
if next_node is None or next_node == depot:
route.append(depot)
times.append(w[depot,k].varValue +
sum(service_times[route[i]] + time_matrix[route[i]][route[i+1]]
for i in range(len(route)-1)))
break
route.append(next_node)
times.append(w[next_node,k].varValue)
current = next_node
if len(route) > 2:
routes.append(route)
arrival_times.append(times)
return {
'status': LpStatus[prob.status],
'total_distance': value(prob.objective),
'routes': routes,
'arrival_times': arrival_times,
'num_vehicles_used': len(routes),
'solve_time': solve_time
}
else:
return {
'status': LpStatus[prob.status],
'total_distance': None,
'routes': None,
'solve_time': solve_time
}

Constructive Heuristics

1. Solomon's I1 Insertion Heuristic
python
def solomon_i1_insertion(dist_matrix, time_matrix, demands, time_windows,
service_times, vehicle_capacity, depot=0,
alpha=1.0, mu=1.0, lambda_param=1.0):
"""
Solomon's I1 insertion heuristic for VRPTW
One of the best constructive heuristics for VRPTW
Args:
dist_matrix: distance matrix
time_matrix: travel time matrix
demands: customer demands
time_windows: list of (earliest, latest) tuples
service_times: service times
vehicle_capacity: vehicle capacity
depot: depot index
alpha, mu, lambda_param: criterion weights
Returns:
solution dictionary
"""
n = len(dist_matrix)
customers = set(range(n)) - {depot}
routes = []
route_loads = []
route_times = []
while customers:
# Initialize new route with seed customer
# Select farthest customer from depot
seed = max(customers, key=lambda c: dist_matrix[depot][c])
route = [depot, seed, depot]
current_time = [time_windows[depot][0],
max(time_windows[depot][0] + time_matrix[depot][seed],
time_windows[seed][0]),
0]
# Update current_time[2] (return to depot)
current_time[2] = (current_time[1] + service_times[seed] +
time_matrix[seed][depot])
current_load = demands[seed]
customers.remove(seed)
# Insert remaining customers into this route
while customers:
best_customer = None
best_position = None
best_criterion = float('inf')
# Try inserting each unrouted customer
for customer in list(customers):
if current_load + demands[customer] > vehicle_capacity:
continue
# Try each insertion position
for pos in range(1, len(route)):
i = route[pos - 1]
j = route[pos]
# Calculate feasibility
# Arrival time at customer
arrival_at_customer = (current_time[pos-1] +
service_times[i] +
time_matrix[i][customer])
# Check time window feasibility
if arrival_at_customer > time_windows[customer][1]:
continue # Too late
# Start service time (wait if early)
start_service = max(arrival_at_customer,
time_windows[customer][0])
# Check if rest of route is still feasible
push_forward = max(0, start_service + service_times[customer] +
time_matrix[customer][j] - current_time[pos])
# Check if pushing forward violates time windows
feasible = True
temp_time = current_time[pos] + push_forward
for k in range(pos, len(route) - 1):
if temp_time > time_windows[route[k]][1]:
feasible = False
break
temp_time = (max(temp_time, time_windows[route[k]][0]) +
service_times[route[k]] +
time_matrix[route[k]][route[k+1]])
if not feasible:
continue

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
74
Repository forks
18
7-day trend score
22

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/kishorkukreja/awesome-supply-chain/vrp-time-windows/badge)](https://verified-skill.com/skills/kishorkukreja/awesome-supply-chain/vrp-time-windows)

Something wrong with this skill or its page? Tell us.