Hugging Face's logo

ai4co
/
routefinder

Reinforcement Learning
rl4co
Model card Files
xet
Community
5

Improve model card: Add pipeline tag, library, paper link, and detailed content

#4
by nielsr HF Staff - opened
base: refs/heads/main
←
from: refs/pr/4
Discussion Files changed
+264
-2
Files changed (1) hide show
  1. README.md +264 -2
README.md CHANGED
@@ -1,7 +1,269 @@
1
  ---
2
  license: mit
 
 
3
  ---
4
 
5
- # RouteFinder Checkpoints
6
 
7
- You may find instructions here: https://github.com/ai4co/routefinder
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  ---
2
  license: mit
3
+ pipeline_tag: reinforcement-learning
4
+ library_name: pytorch
5
  ---
6
 
7
+ # RouteFinder: Towards Foundation Models for Vehicle Routing Problems
8
 
9
+ This model is described in the paper [RouteFinder: Towards Foundation Models for Vehicle Routing Problems](https://huggingface.co/papers/2406.15007).
10
+
11
+ [![arXiv](https://img.shields.io/badge/arXiv-2406.15007-b31b1b.svg)](https://arxiv.org/abs/2406.15007) [![OpenReview](https://img.shields.io/badge/%E2%99%96%ufe0f-OpenReview-8b1b16)](https://openreview.net/forum?id=QzGLoaOPiY) [![Slack](https://img.shields.io/badge/slack-chat-611f69.svg?logo=slack)](https://join.slack.com/t/rl4co/shared_invite/zt-1ytz2c1v4-0IkQ8NQH4TRXIX8PrRmDhQ)
12
+ [![License: MIT](https://img.shields.io/badge/License-MIT-red.svg)](https://opensource.org/licenses/MIT)[![Test](https://github.com/ai4co/routefinder/actions/workflows/tests.yml/badge.svg)](https://github.com/ai4co/routefinder/actions/workflows/tests.yml)<a href="https://colab.research.google.com/github/ai4co/routefinder/blob/main/examples/1.quickstart.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"></a>[![HuggingFace Models](https://img.shields.io/badge/%F0%9F%A4%97-Models-yellow)](https://huggingface.co/ai4co/routefinder)[![HuggingFace Dataset](https://img.shields.io/badge/%F0%9F%A4%97-Dataset-yellow)](https://huggingface.co/datasets/ai4co/routefinder)
13
+
14
+ ---
15
+
16
+ ## Abstract
17
+
18
+ This paper introduces RouteFinder, a comprehensive foundation model framework to tackle different Vehicle Routing Problem (VRP) variants. Our core idea is that a foundation model for VRPs should be able to represent variants by treating each as a subset of a generalized problem equipped with different attributes. We propose a unified VRP environment capable of efficiently handling any combination of these attributes. The RouteFinder model leverages a modern transformer-based encoder and global attribute embeddings to improve task representation. Additionally, we introduce two reinforcement learning techniques to enhance multi-task performance: mixed batch training, which enables training on different variants at once, and multi-variant reward normalization to balance different reward scales. Finally, we propose efficient adapter layers that enable fine-tuning for new variants with unseen attributes. Extensive experiments on 48 VRP variants show RouteFinder outperforms recent state-of-the-art learning methods. Our code is publicly available at this https URL .
19
+
20
+ The official code, full documentation, and further details can be found on the [GitHub repository](https://github.com/ai4co/routefinder).
21
+
22
+ <div align="center">
23
+ <img src="https://github.com/ai4co/routefinder/raw/main/assets/overview.png" alt="RouteFinder Overview" style="width: 100%; height: auto;">
24
+ </div>
25
+
26
+
27
+ ## 📰 News
28
+ - **Sep 2025**: A new version (`v0.4.0`) has been released. We have now added better installation instructions, released models and dataset on HugginFace, and more. Also, we are delighted to announce that RouteFinder has been accepted at TMLR 2025! See details on the [release notes](https://github.com/ai4co/routefinder/releases/tag/v0.4.0)
29
+ - **Feb 2025**: A new version (`v0.3.0`) of RouteFinder has been released. We have added several improvements, among which increasing the number of VRP variants from 24 to 48! See details on the [release notes](https://github.com/ai4co/routefinder/releases/tag/v0.3.0)
30
+ - **Oct 2024**: A new version (`v0.2.0`) of RouteFinder has been released! We have added the latest contributions from our preprint and much improved codebase
31
+ - **Jul 2024**: RouteFinder has been accepted as an **Oral** presentatation at the [ICML 2024 FM-Wild Workshop](https://icml-fm-wild.github.io/)!
32
+
33
+
34
+ ## 🚀 Installation
35
+
36
+ We use [uv](https://github.com/astral-sh/uv) (Python package manager) to manage the dependencies:
37
+
38
+ ```bash
39
+ uv venv --python 3.12 # create a new virtual environment
40
+ source .venv/bin/activate # activate the virtual environment
41
+ uv sync --all-extras # for all dependencies
42
+ ```
43
+
44
+ Note that this project is also compatible with normal `pip install -e .` in case you use a different package manager.
45
+
46
+ ## 🏁 Quickstart
47
+
48
+ ### Download data and checkpoints
49
+
50
+ To download the data and checkpoints from HuggingFace automatically, you can use:
51
+
52
+ ```bash
53
+ python scripts/download_hf.py
54
+ ```
55
+
56
+
57
+ ### Running
58
+
59
+ We recommend exploring [this quickstart notebook](https://github.com/ai4co/routefinder/blob/main/examples/1.quickstart.ipynb) to get started with the `RouteFinder` codebase!
60
+
61
+
62
+ The main runner (example here of main baseline) can be called via:
63
+
64
+ ```bash
65
+ python run.py experiment=main/rf/rf-transformer-100
66
+ ```
67
+ You may change the experiment by using the `experiment=YOUR_EXP`, with the path under [`configs/experiment`](https://github.com/ai4co/routefinder/tree/main/configs/experiment) directory.
68
+
69
+
70
+
71
+
72
+ ### Testing
73
+
74
+ You may use the provided test function to test the model:
75
+
76
+ ```bash
77
+ python test.py --checkpoint checkpoints/100/rf-transformer.ckpt
78
+ ```
79
+
80
+ or with additional parameters:
81
+
82
+ ```
83
+ usage: test.py [-h] --checkpoint CHECKPOINT [--problem PROBLEM] [--size SIZE] [--datasets DATASETS] [--batch_size BATCH_SIZE]
84
+ [--device DEVICE] [--remove-mixed-backhaul | --no-remove-mixed-backhaul]
85
+
86
+ options:
87
+ -h, --help show this help message and exit
88
+ --checkpoint CHECKPOINT
89
+ Path to the model checkpoint
90
+ --problem PROBLEM Problem name: cvrp, vrptw, etc. or all
91
+ --size SIZE Problem size: 50, 100, for automatic loading
92
+ --datasets DATASETS Filename of the dataset(s) to evaluate. Defaults to all under data/{problem}/ dir
93
+ --batch_size BATCH_SIZE
94
+ --device DEVICE
95
+ --remove-mixed-backhaul, --no-remove-mixed-backhaul
96
+ Remove mixed backhaul instances. Use --no-remove-mixed-backhaul to keep them. (default: True)
97
+ ```
98
+
99
+
100
+ We also have a notebook to automatically download and test models on the CVRPLIB [here](https://github.com/ai4co/routefinder/blob/main/examples/2.eval-cvrplib.ipynb)!
101
+
102
+ ### Other scripts
103
+
104
+ - Data generation: We also include scripts to re-generate data manually (reproducible via random seeds) with `python scripts/generate_data.py`.
105
+
106
+ - Classical baselines (OR-Tools and HGS-PyVRP): We additionally include a script to solve the problems using classical baselines with e.g. `python scripts/run_or_solvers.py --num_procs 20 --solver pyvrp` to run PyVRP with 20 processes on all the dataset.
107
+
108
+
109
+ ## 🔁 Reproducing Experiments
110
+
111
+ ### Main Experiments
112
+ The `main` experiments on 100 nodes are (rf=RouteFinder) RF-TE: [`rf/rf-transformer-100`](https://github.com/ai4co/routefinder/blob/main/configs/experiment/main/rf/rf-transformer-100.yaml), RF-POMO: [`rf/rf-100`](https://github.com/ai4co/routefinder/blob/main/configs/experiment/main/rf/rf-100.yaml), RF-MoE: [`rf/rf-moe-100`](https://github.com/ai4co/routefinder/blob/main/configs/experiment/main/rf/rf-moe-100.yaml), MTPOMO [`mtpomo-100`](https://github.com/ai4co/routefinder/blob/main/configs/experiment/main/mtpomo/mtpomo-100.yaml) and MVMoE [`mvmoe-100`](https://github.com/ai4co/routefinder/blob/main/configs/experiment/main/mvmoe/mvmoe-100.yaml). You may substitute `50` instead for 50 nodes. Note that we separate 50 and 100 because we created an automatic validation dataset reporting for all variants at different sizes (i.e. [here](https://github.com/ai4co/routefinder/blob/main/configs/experiment/rfbase-100.yaml)).
113
+
114
+
115
+
116
+ Note that additional Hydra options as described [here](https://rl4co.readthedocs.io/en/latest/_content/start/hydra.html). For instance, you can add `+trainer.devices="[0]"` to run on a specific GPU (i.e., GPU 0).
117
+
118
+ ### Ablations and more
119
+
120
+ Other configs are available under [`configs/experiment`](https://github.com/ai4co/routefinder/tree/main/configs/experiment) directory.
121
+
122
+
123
+ ### EAL (Efficient Adapter Layers)
124
+
125
+ To run EAL, you may use the following command:
126
+
127
+ ```bash
128
+ python run_eal.py
129
+ ```
130
+
131
+ with the following parameters:
132
+
133
+ ```
134
+ usage: run_eal.py [-h] [--model_type MODEL_TYPE] [--experiment EXPERIMENT]
135
+ [--variants_finetune VARIANTS_FINETUNE]
136
+ [--checkpoint CHECKPOINT] [--lr LR] [--num_runs NUM_RUNS]
137
+
138
+ options:
139
+ -h, --help show this help message and exit
140
+ --model_type MODEL_TYPE
141
+ Model type: rf, mvmoe, mtpomo
142
+ --experiment EXPERIMENT
143
+ Experiment type
144
+ --variants_finetune VARIANTS_FINETUNE
145
+ Variants to finetune on
146
+ --checkpoint CHECKPOINT
147
+ --lr LR
148
+ --num_runs NUM_RUNS
149
+ ```
150
+
151
+ with additional parameters that can be found in the [eal.py](https://github.com/ai4co/routefinder/blob/main/eal.py) file.
152
+
153
+ ### Development
154
+
155
+ To test automatically if the code works, you can run:
156
+ ```bash
157
+ python -m pytest tests/*
158
+ ```
159
+
160
+
161
+
162
+ ## 🚚 Available Environments
163
+
164
+ <div align="center">
165
+ <img src="https://github.com/ai4co/routefinder/raw/main/assets/vrp.png" alt="VRP Problems" style="width: 100%; height: auto;">
166
+ </div>
167
+
168
+
169
+ We consider 48 VRP variants. All variants include the base Capacity (C). The $k=5$ features O, B, L, TW, and MD can be combined into any subset, including the empty set and itself (i.e., a power set with $2^k = 32$ possible combinations. The Mixed (M) global feature creates new Mixed Backhaul (MB) variants in generalization studies, adding 16 more variants.
170
+ We have the following environments available:
171
+
172
+ | **VRP Variant** | **Capacity (C)** | **Open Route (O)** | **Backhaul (B)** | **Mixed (M)** | **Duration Limit (L)** | **Time Windows (TW)** | **Multi-depot (MD)** |
173
+ |------------------|:----------------:|:------------------:|:----------------:|:-------------:|:----------------------:|:---------------------:|:-------------------:|
174
+ | CVRP | ✔ | | | | | | |
175
+ | OVRP | ✔ | ✔ | | | | | |
176
+ | VRPB | ✔ | | ✔ | | | | |
177
+ | VRPL | ✔ | | | | ✔ | | |
178
+ | VRPTW | ✔ | | | | | ✔ | |
179
+ | OVRPTW | ✔ | ✔ | | | | ✔ | |
180
+ | OVRPB | ✔ | ✔ | ✔ | | | | |
181
+ | OVRPL | ✔ | ✔ | | | ✔ | | |
182
+ | VRPBL | ✔ | | ✔ | | ✔ | | |
183
+ | VRPBTW | ✔ | | ✔ | | | ✔ | |
184
+ | VRPLTW | ✔ | | | | ✔ | ✔ | |
185
+ | OVRPBL | ✔ | ✔ | ✔ | | ✔ | | |
186
+ | OVRPBTW | ✔ | ✔ | ✔ | | | ✔ | |
187
+ | OVRPLTW | ✔ | ✔ | | | ✔ | ✔ | |
188
+ | VRPBLTW | ✔ | | ✔ | | ✔ | ✔ | |
189
+ | OVRPBLTW | ✔ | ✔ | ✔ | | ✔ | ✔ | ✔ |
190
+ | VRPMB | ✔ | | ✔ | ✔ | | | |
191
+ | OVRPMB | ✔ | ✔ | ✔ | ✔ | | | |
192
+ | VRPMBL | ✔ | | ✔ | ✔ | ✔ | | |
193
+ | VRPMBTW | ✔ | | ✔ | ✔ | | ✔ | |
194
+ | OVRPMBL | ✔ | ✔ | ✔ | ✔ | ✔ | | |
195
+ | OVRPMBTW | ✔ | ✔ | ✔ | ✔ | | ✔ | |
196
+ | VRPMBLTW | ✔ | | ✔ | ✔ | ✔ | ✔ | |
197
+ | OVRPMBLTW | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | |
198
+ | MDCVRP | ✔ | | | | | | ✔ |
199
+ | MDOVRP | ✔ | ✔ | | | | | ✔ |
200
+ | MDVRPB | ✔ | | ✔ | | | | ✔ |
201
+ | MDVRPL | ✔ | | | | ✔ | | ✔ |
202
+ | MDVRPTW | ✔ | | | | | ✔ | ✔ |
203
+ | MDOVRPTW | ✔ | ✔ | | | | ✔ | ✔ |
204
+ | MDOVRPB | ✔ | ✔ | ✔ | | | | ✔ |
205
+ | MDOVRPL | ✔ | ✔ | | | ✔ | | ✔ |
206
+ | MDVRPBL | ✔ | | ✔ | | ✔ | | ✔ |
207
+ | MDVRPBTW | ✔ | | ✔ | | | ✔ | ✔ |
208
+ | MDVRPLTW | ✔ | | | | ✔ | ✔ | ✔ |
209
+ | MDOVRPBL | ✔ | ✔ | ✔ | | ✔ | | ✔ |
210
+ | MDOVRPBTW | ✔ | ✔ | ✔ | | | ✔ | ✔ |
211
+ | MDOVRPLTW | ✔ | ✔ | | | ✔ | ✔ | ✔ |
212
+ | MDVRPBLTW | ✔ | | ✔ | | ✔ | ✔ | ✔ |
213
+ | MDOVRPBLTW | ✔ | ✔ | ✔ | | ✔ | ✔ | ✔ |
214
+ | MDVRPMB | ✔ | | ✔ | ✔ | | | ✔ |
215
+ | MDOVRPMB | ✔ | ✔ | ✔ | ✔ | | | ✔ |
216
+ | MDVRPMBL | ✔ | | ✔ | ✔ | ✔ | | ✔ |
217
+ | MDVRPMBTW | ✔ | | ✔ | ✔ | | ✔ | ✔ |
218
+ | MDOVRPMBL | ✔ | ✔ | ✔ | ✔ | ✔ | | ✔ |
219
+ | MDOVRPMBTW | ✔ | ✔ | ✔ | ✔ | | ✔ | ✔ |
220
+ | MDVRPMBLTW | ✔ | | ✔ | ✔ | ✔ | ✔ | ✔ |
221
+ | MDOVRPMBLTW | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
222
+
223
+
224
+ We additionally provide as baseline solvers for all baselines 1) [OR-Tools](https://github.com/google/or-tools) and 2) the SotA [PyVRP](https://github.com/PyVRP/PyVRP).
225
+
226
+ ### A tip for you!
227
+
228
+ Do you want to improve the performance of your model with no effort? Use our Transformer structure, based on recent models such as Llama and DeepSeek ;)
229
+
230
+ <div align="center">
231
+ <img src="https://github.com/ai4co/routefinder/raw/main/assets/rf-te.png" alt="VRP Problems" style="width: 50%; height: auto;">
232
+ </div>
233
+
234
+
235
+
236
+ ### Known Bugs
237
+ - For some reason, there seem to be bugs when training on M series processors from Apple (but not during inference somehow?). We recommend training with a discrete GPU. We'll keep you posted with updates!
238
+
239
+
240
+ ### 🤗 Acknowledgements
241
+
242
+ - https://github.com/FeiLiu36/MTNCO/tree/main
243
+ - https://github.com/RoyalSkye/Routing-MVMoE
244
+ - https://github.com/yd-kwon/POMO
245
+ - https://github.com/ai4co/rl4co
246
+
247
+
248
+ ## 🤩 Citation
249
+ If you find RouteFinder valuable for your research or applied projects:
250
+
251
+ ```bibtex
252
+ @article{
253
+ berto2025routefinder,
254
+ title={{RouteFinder: Towards Foundation Models for Vehicle Routing Problems}},
255
+ author={Federico Berto and Chuanbo Hua and Nayeli Gast Zepeda and Andr{\'e} Hottung and Niels Wouda and Leon Lan and Junyoung Park and Kevin Tierney and Jinkyoo Park},
256
+ journal={Transactions on Machine Learning Research},
257
+ issn={2835-8856},
258
+ year={2025},
259
+ url={https://openreview.net/forum?id=QzGLoaOPiY},
260
+ }
261
+ ```
262
+
263
+ ---
264
+
265
+ <div align="center">
266
+ <a href="https://github.com/ai4co">
267
+ <img src="https://raw.githubusercontent.com/ai4co/assets/main/svg/ai4co_animated_full.svg" alt="AI4CO Logo" style="width: 30%; height: auto;">
268
+ </a>
269
+ </div>