Iterated Local Search How-to

The Iterated Local Search (ILS) solver reuses the operator registry to alternate between local improvement phases and diversification perturbations. It sits between simulated annealing and the Tabu prototype: deterministic local search with optional hybrid MIP restarts.

Basic Usage

fhops solve-ils examples/tiny7/scenario.yaml \
    --out tmp/tiny7_ils.csv \
    --iters 250 --perturbation-strength 3 --stall-limit 10 \
    --batch-neighbours 4 --parallel-workers 4 \
    --telemetry-log tmp/ils_runs.jsonl

Key options:

--perturbation-strength

Number of perturbation steps executed after each local search cycle (default: 3).

--stall-limit

Non-improving iterations before perturbation/restart logic triggers (default: 10).

--hybrid-use-mip / --hybrid-mip-time-limit

Opt-in hybrid path that launches a time-boxed MIP solve once stalls exceed the limit. Results are converted back into the heuristic schedule when feasible.

--batch-neighbours / --parallel-workers

Reuse the batched neighbour generation/evaluation infrastructure from SA. Defaults keep the sequential single-thread behaviour.

Telemetry

ILS telemetry mirrors SA metadata (initial/best score, operator weights/stats) and adds:

  • perturbations – diversification steps executed.

  • restarts – restarts triggered via hybrid or perturbation.

  • improvement_steps – count of local search improvements.

  • hybrid_use_mip / hybrid_mip_time_limit – hybrid configuration echoed for diagnostics.

Benchmarks

fhops bench suite --include-ils emits additional ils rows alongside SA/Tabu/MIP results. Current runs (tiny7/med42/large84, 250 iterations) show ILS closing small gaps faster than Tabu while remaining slightly behind SA. The solver stays opt-in until we complete the hybrid warm-start investigation documented in notes/metaheuristic_roadmap.md.