lin-kernighan/README.md

Adaptive k-opt heuristic improving TSP tours by swapping edges to shorten routes.

# lin-kernighan

Adaptive k-opt heuristic improving TSP (traveling salesman problem) tours by swapping edges to shorten routes.

## Installation

```sh
npm install lin-kernighan
```

## Usage

```ts
import tsp from "lin-kernighan";

tsp([
  { latitude: 40.7128, longitude: -74.006 }, // New York
  { latitude: 34.0522, longitude: -118.2437 }, // Los Angeles
  { latitude: 55.7558, longitude: 37.6173 }, // Moscow
  { latitude: -33.8688, longitude: 151.2093 }, // Sydney
  { latitude: -22.9068, longitude: -43.1729 }, // Rio de Janeiro
]);
// => [
//   { latitude: 40.7128, longitude: -74.006 },   // New York
//   { latitude: -22.9068, longitude: -43.1729 }, // Rio de Janeiro
//   { latitude: -33.8688, longitude: 151.2093 }, // Sydney
//   { latitude: 55.7558, longitude: 37.6173 },   // Moscow
//   { latitude: 34.0522, longitude: -118.2437 }  // Los Angeles
// ]
```

## Algorithm

The Lin-Kernighan algorithm solves the Traveling Salesman Problem by finding the shortest route that visits all cities exactly once and returns to the starting point. Here's how it works in simple terms:

- You have multiple cities (points) to visit
- You need to find the shortest possible route that visits each city once
- The route must return to where you started

Here's a step by step process:

1. **Calculate Distances**

   - Measure the distance between every pair of cities
   - Uses the haversine formula for geographic coordinates (accounts for Earth's curvature)

2. **Create Initial Route**

   - Start at the first city
   - Always go to the nearest unvisited city next
   - This gives us a "decent" starting route (called nearest neighbor heuristic)

3. **Improve the Route (2-opt)**

   - Take any segment of the route and reverse it
   - If this makes the total distance shorter, keep the change
   - Try all possible segments until no improvements are found

4. **Further Improvements (3-opt)**

   - When 2-opt can't improve anymore, try more complex changes
   - Rearrange three segments of the route in different ways
   - Again, only keep changes that reduce total distance

5. **Repeat Until Optimal**
   - Keep trying improvements until no better route can be found
   - The result is a highly optimized tour

**Why It Works:**

- Starts with a reasonable solution instead of random
- Makes incremental improvements rather than starting over
- Uses local optimization to escape poor route choices
- Balances computation time with solution quality

## Performance Optimizations

This implementation includes several performance improvements while maintaining algorithm correctness:

- **Delta calculation**: Computes only edge differences instead of recalculating entire tour distance
- **Early termination**: Breaks loops immediately when improvement found rather than exhaustive search  
- **In-place operations**: Modifies tours directly to reduce memory allocations
- **First-improvement strategy**: Takes first beneficial swap found for faster convergence

These optimizations provide 2-5x speedup for typical TSP instances.