aprender-tsp 0.2.0

Local TSP optimization with personalized .apr models
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

# aprender-tsp

Local TSP (Traveling Salesman Problem) optimization with personalized `.apr` models.

## Features

- **Multiple Solvers**: ACO (Ant Colony), Tabu Search, Genetic Algorithm, Hybrid
- **TSPLIB Support**: Standard benchmark instance format (berlin52, att48, eil51, etc.)
- **Model Persistence**: Train once, solve fast with `.apr` binary format
- **CLI & Library**: Use as command-line tool or Rust library
- **Deterministic**: Seed-based reproducibility for benchmarking

## Quick Start

```bash
# Install
cargo install aprender-tsp

# Train a model
aprender-tsp train instances/berlin52.tsp -o berlin52.apr --algorithm aco

# Solve new instances
aprender-tsp solve -m berlin52.apr instances/new-instance.tsp

# View model info
aprender-tsp info berlin52.apr

# Benchmark against known optimum
aprender-tsp benchmark berlin52.apr --instances instances/berlin52.tsp
```

## Algorithms

| Algorithm | Description | Best For |
|-----------|-------------|----------|
| ACO | Ant Colony Optimization | General TSP, exploration |
| Tabu | Tabu Search with 2-opt | Local refinement |
| GA | Genetic Algorithm | Large instances |
| Hybrid | GA + Tabu + ACO pipeline | Best quality |

## Library Usage

```rust
use aprender_tsp::{TspInstance, AcoSolver, TspSolver, Budget};

// Load instance
let instance = TspInstance::from_tsplib("berlin52.tsp")?;

// Solve with ACO
let mut solver = AcoSolver::new()
    .with_num_ants(20)
    .with_alpha(1.0)
    .with_beta(2.5);

let solution = solver.solve(&instance, Budget::iterations(1000))?;

println!("Tour length: {}", solution.length);
println!("Gap from optimal: {:.2}%", solution.optimality_gap(&instance)?);
```

## Pre-trained Models

POC models available on Hugging Face: [paiml/aprender-tsp-poc](https://huggingface.co/paiml/aprender-tsp-poc)

| Model | Instance | Gap from Optimal |
|-------|----------|------------------|
| berlin52-aco.apr | berlin52 | 1.92% |
| att48-aco.apr | att48 | 4.30% |
| eil51-aco.apr | eil51 | 4.07% |

## Instance Format

Supports TSPLIB format (`.tsp`):

```
NAME: example
TYPE: TSP
DIMENSION: 4
EDGE_WEIGHT_TYPE: EUC_2D
NODE_COORD_SECTION
1 0.0 0.0
2 1.0 0.0
3 1.0 1.0
4 0.0 1.0
EOF
```

Also supports CSV format with optional header.

## Model Format

`.apr` files are compact binary models (~77 bytes):
- Magic bytes: `APR\0`
- Version: 1
- CRC32 checksum for integrity
- Algorithm-specific parameters

## Part of Aprender

This crate uses `aprender::metaheuristics` for core optimization algorithms. See [aprender](https://github.com/paiml/aprender) for the full ML library.

## License

MIT