---
library_name: pytorch
tags:
  - tsp
  - combinatorial-optimization
  - route-optimization
  - transformer
  - branch-and-bound
  - euclidean-tsp
---

# AI TSP Problem V2

This repository contains the best V2 checkpoint from the `AI-TSP-Problem` project:

- GitHub: https://github.com/cochon123/AI-TSP-Problem

The task is a fixed-start / fixed-end Euclidean TSP path problem:

- the first node is the start
- the last node is the end
- every intermediate node must be visited exactly once
- the objective is the shortest possible path

## What This Model Is

This is a geometry-aware pointer-style Transformer trained on exact Rust-generated labels for small Euclidean TSP-path instances up to 20 nodes.

The model is useful in two ways:

1. `AI only`
   It predicts a very strong approximate route quickly.
2. `Hybrid AI + exact search`
   It provides warm starts and search guidance for an exact branch-and-bound solver.

Exactness does not come from the model itself. Exactness comes from the classical solver.

## Checkpoint

The published file is:

- `best_score.pt`

It is the best V2 checkpoint selected by the project scoring metric.

## Training Setup

- model width: `d_model = 384`
- encoder layers: `8`
- decoder layers: `4`
- attention heads: `8`
- FFN size: `1536`
- dropout: `0.05`
- training split: `train_v2`
- validation splits: `val`, `val_hard`

## Main Results

Uniform benchmark:

- beam exact route accuracy: `91.63%`
- beam mean optimality gap: `0.0496%`
- beam exact route accuracy on `n=17..20`: `88.09%`
- beam mean optimality gap on `n=17..20`: `0.0688%`

Hard benchmark:

- beam exact route accuracy: `93.55%`
- beam mean optimality gap: `0.0240%`

Hybrid exact-search benchmark:

- on `n=17..20`, the AI-guided hybrid solver reached about `1.60x` speedup over the plain branch-and-bound baseline

## How To Use

This checkpoint is tied to the project codebase and is not packaged as a standalone Hugging Face `transformers` model.

Use it from the GitHub repository:

```bash
git clone https://github.com/cochon123/AI-TSP-Problem.git
cd AI-TSP-Problem
PYTHONPATH=python/src python -m aifindpath.eval --checkpoint best_score.pt --data data/pilot_v2 --split test --beam 32
```

If you download the checkpoint from Hugging Face, point the project scripts at the local file path.

## Included Visuals

This model page also includes:

- the training loss curve
- the training accuracy curve
- the AI-only latency vs accuracy graph
- the AI-only latency vs gap graph

![Training Loss](training-loss.png)

![Training Accuracy](training-accuracy.png)

![AI Only: Latency vs Exact Route Accuracy](greedy-speed-vs-accuracy.png)

![AI Only: Latency vs Gap to Optimum](greedy-speed-vs-gap.png)

## Notes

- This is a research / engineering checkpoint, not a production API package.
- The browser demo in the GitHub repository uses lightweight in-browser heuristics, not this full checkpoint.
- If you only need a very strong route and not a proof of optimality, `AI only` can already be a reasonable operating mode.