Heuristic Presets & Registry Guide

This how-to explains how to configure FHOPS heuristics via operator presets, explicit weight overrides, and opt-in features such as parallel evaluation, Iterated Local Search (ILS), and Tabu Search. Use it alongside the CLI reference (CLI Reference) and benchmarking how-to (Benchmarking Harness) to design repeatable tuning workflows.

Shared Solver Cheat Sheet

+=============================+=================+=============================================================+=============================================================================+=========================================================================================================================================================+ | solver | default_profile | search_strategy | best_for | tuning_notes | +=============================+=================+=============================================================+=============================================================================+=========================================================================================================================================================+ | Simulated Annealing (SA) | balanced | Probabilistic move/swap neighbourhood with cooling schedule | Small-to-medium bundles needing quick feasible schedules | Use –sa-iters 2500+ for med42; –compare-preset diversify exposes swap-heavy exploration, while mobilisation preset biases toward distance-aware moves | +—————————–+—————–+————————————————————-+—————————————————————————–+———————————————————————————————————————————————————+ | SA (mobilisation preset) | mobilisation | Adds mobilisation_shake and higher landing penalties | Scenarios with tight landing caps or long walk thresholds | Pair with –compare-preset mobilisation plus lower –sa-iters to highlight mobilisation shake vs. default | +—————————–+—————–+————————————————————-+—————————————————————————–+———————————————————————————————————————————————————+ | Iterated Local Search (ILS) | ils_default | Deterministic restart loop wrapping greedy local search | Fine-tuning SA solutions on bounded horizons (<=150 assignments) | Expose –include-ils with ~400 iterations; set –ils-batch-neighbours 4 when CPU budget allows | +—————————–+—————–+————————————————————-+—————————————————————————–+———————————————————————————————————————————————————+ | Tabu Search | tabu_default | Short-term memory over swap/move neighbourhood | High-mobility cases (synthetic tier) where aggressive diversification helps | –tabu-iters 2500 plus automatic tenure delivered best synthetic_small runs; capture telemetry for objective trace | +—————————–+—————–+————————————————————-+—————————————————————————–+———————————————————————————————————————————————————+

FHOPS exposes the same metaheuristics benchmarked in the manuscript:

Simulated annealing remains the default baseline (bench suite uses it unless disabled). The manuscript cites both the balanced preset (general-purpose) and the mobilisation preset (escapes landing-cap traps). Operator weights ship in profiles.py, so the exporter can surface them in the shared table.
Iterated local search is included to show deterministic improvement over SA in short horizons (e.g., tiny7). The solver piggybacks on SA assignments when --include-ils is passed, reinforcing that end-users can reuse telemetry outputs.
Tabu search demonstrates diversification on synthetic bundles: objective traces show convergence parity with SA but at lower runtime. The manuscript will highlight how automatic tenure selection removes another tuning burden.

These notes accompany the shared heuristics_matrix.csv so both the PDF and Sphinx docs can present identical solver guidance.

Preset Overview

Operator presets provide named weight profiles for the heuristic registry. Each preset targets a specific behaviour:

default: Balanced swap/move operators with advanced moves disabled (baseline behaviour).
explore: Enables advanced neighbourhoods (block insertion, cross exchange, mobilisation shake) with moderate weights to diversify search.
mobilisation: Prioritises mobilisation shake moves for distance-constrained scenarios.
stabilise: Dampens advanced operators and boosts intra-machine moves to consolidate schedules.

List presets with:

fhops solve-heur ... --list-operator-presets

Applying Presets

Use --operator-preset to enable one or more presets. When multiple presets are supplied they are merged in order; later presets overwrite weights from earlier ones.

# Balanced baseline
fhops solve-heur examples/tiny7/scenario.yaml --out tmp/tiny7_sa.csv \
    --operator-preset default

# Diversification-heavy profile
fhops solve-heur examples/med42/scenario.yaml --out tmp/med42_explore.csv \
    --operator-preset explore --operator-preset mobilisation

Explicit Overrides

Presets can be combined with --operator (to restrict the enabled set) and --operator-weight name=value overrides. Overrides apply after presets.

fhops solve-heur examples/large84/scenario.yaml --out tmp/large84_custom.csv \
    --operator-preset explore \
    --operator-weight mobilisation_shake=0.5 \
    --operator swap --operator move --operator block_insertion

Solver-Specific Parameters

All heuristics share the registry, but each solver exposes additional knobs alongside the preset controls:

Simulated Annealing (`fhops solve-heur`)
- --sa-iters / --iters – iteration budget (default 5000).
- --sa-seed / --seed – RNG seed for reproducible runs.
- --batch-neighbours – proposals per iteration (pair with --parallel-workers to evaluate in parallel).
- --parallel-multistart – launch multiple runs in parallel; each honours the same presets/weights.
- --profile NAME – apply bundled configs (operators + batching). List via --list-profiles.
Iterated Local Search (`fhops solve-ils`)
- --ils-iters – number of ILS iterations between perturbations.
- --ils-seed – RNG seed.
- --ils-batch-neighbours / --ils-workers – batched evaluation controls.
- --ils-perturbation-strength – number of random moves during perturbation phases.
- --ils-stall-limit – iterations without improvement before perturbing.
- --ils-hybrid-use-mip / --ils-hybrid-mip-time-limit – optional MIP warm start when a small budget can improve the seed.
Tabu Search (`fhops solve-tabu`)
- --tabu-iters – number of iterations.
- --tabu-seed – RNG seed (controls candidate sampling).
- --tabu-tenure – explicit tabu tenure (0 = auto).
- --tabu-stall-limit – restarts when no improvement occurs.
- --tabu-batch-neighbours / --tabu-workers – batched move evaluation.

All three share --operator, --operator-weight, --operator-preset, and --profile so you can keep the same operator mix while experimenting with solver parameters. The shortcut fhops bench suite wires these flags through --sa-*, --ils-*, and --tabu-* options when comparing solvers side-by-side.

Parallel & Advanced Features

The registry-backed operators work across all heuristics. Opt-in features share the same options:

Batched neighbours: --batch-neighbours N samples multiple candidates per iteration. Pair with --parallel-workers to evaluate them concurrently.
Parallel multi-start: --parallel-multistart K launches multiple SA runs; use --parallel-workers to control worker concurrency. Telemetry logs record per-run stats.
Iterated Local Search: fhops solve-ils reuses presets/weights. Parallel knobs mirror SA.
Tabu Search: fhops solve-tabu accepts the same preset/weight flags while adding Tabu-specific parameters (tenure, stall limit).
Profiles: fhops solve-heur --profile explore applies a bundled configuration (operator presets, batching, multi-start). List options via fhops solve-heur --list-profiles; explicit CLI flags still override profile defaults.

Reference the dedicated how-tos for ILS and Tabu when tuning those solvers. * Parallel Heuristic Workflows details the opt-in parallel execution pathways shared across heuristics. * Iterated Local Search How-to and Tabu Search How-to dive into solver-specific parameters built on top of the registry.

Operator Catalogue

All heuristics share the registry operators:

swap: Exchange assignments between machines/day-shifts.
move: Reassign a block within the same machine to a different day/shift.
block_insertion: Insert a block into a new machine/shift slot, swapping out the previous occupant as needed.
cross_exchange: Cross-machine swap with additional feasibility checks (windows, locks, mobilisation impacts).
mobilisation_shake: Diversification move biased toward mobilisation-heavy adjustments (opt-in via presets).

Weights set to 0 disable the operator.

Telemetry & Benchmarking

Heuristic runs emit per-operator telemetry (proposals, acceptances, weights). Combine presets and overrides with telemetry logs to spot under-performing operators:

fhops solve-heur ... --telemetry-log tmp/heuristics.jsonl --show-operator-stats

Benchmark summaries include comparison columns (best heuristic solver, objective gaps, runtime ratios). Generate visualisations with:

fhops bench suite --include-ils --include-tabu --no-include-mip --out-dir tmp/bench_compare
python scripts/render_benchmark_plots.py tmp/bench_compare/summary.csv

When you add --compare-preset the benchmark suite replays the same scenario with multiple preset labels and records the results in preset_label. The summary also embeds two JSON blobs:

operators_config: Final weight mapping for the run (after presets + overrides).
operators_stats: Per-operator telemetry (proposals, accepted, skipped, weight, acceptance_rate).

Inspect them directly with jq or load them into Pandas for analysis:

fhops bench suite --compare-preset explore --compare-preset mobilisation \
    --include-ils --include-tabu --out-dir tmp/bench_compare
python - <<'PY'
import pandas as pd
df = pd.read_csv("tmp/bench_compare/summary.csv")
stats = df[df["solver"] == "sa"]["operators_stats"].iloc[0]
print(stats)
PY

Next Steps

Use the Benchmarking Harness how-to to interpret comparison metrics and plots.
See notes/metaheuristic_hyperparam_tuning.md for the long-term tuning roadmap.
When presets change, rerun fhops bench suite and regenerate plots with scripts/render_benchmark_plots.py before updating documentation.
For CLI flag details, refer back to CLI Reference.