This repository studies where search freedom matters in a location-routing problem (LRP): at the route layer, the facility layer, or through coupled facility–route reconstruction. The contribution is controlled ablation, benefit-source decomposition, and process diagnostics—not a claim of a new benchmark best.
中文简介：本项目研究选址—路径问题中的分层搜索自由度，通过受控消融、等时比较和过程诊断，量化设施拓扑调整与路径细化各自的作用。
How much performance comes from relaxing the initial facility topology, and when do stronger facility neighborhoods provide value beyond a simple open-one/close-one move?
- A controlled comparison separating fixed-facility path search from facility-adjusting search.
- Explicit PF-noop control for the fourth operator slot.
- A progression from SF to SF+ and JFR, under equal-iteration, equal-time, scale-extension, and long-budget settings.
- Greedy versus regret-2 repair contrasts and process diagnostics for acceptance, best updates, and topology changes.
- A provenance-preserving public refactor with synthetic tests and immutable precomputed summaries.
| Method | Facility freedom | Facility slot |
|---|---|---|
| PF | Initial open set fixed | No facility slot; path neighborhoods only |
| PF-noop | Initial open set fixed | Explicit no-op, consuming a slot without repair |
| SF | Adjustable | Random close-one or nearby open-one |
| SF+ | Adjustable | Targeted close, targeted open, or swap-one |
| JFR | Adjustable | Close a targeted facility and reconstruct its complete customer group |
All methods use seeded randomness. Greedy repair chooses the lowest current insertion increment; regret-2 prioritizes customers whose best alternative would be costly to lose.
- Under highly redundant initial facility topologies, facility-layer search substantially reduced dependence on the initial open-facility structure.
- The facility-layer benefit shrank markedly when the initial topology was already close to a low-cost structure.
- More complex SF+ and JFR neighborhoods did not stably outperform simple SF across scenarios.
- Facility perturbations primarily supported early topology correction, while route neighborhoods primarily supported later refinement.
These statements summarize historical formal experiments in results/precomputed; the refactoring session did not rerun them.
src/lrp_search_diagnostics/: typed algorithm, evaluation, validation, and diagnostic components.experiments/: safe CLI entry points with 10–20 customer synthetic defaults.configs/: historical formal configurations, explicitly disabled as defaults.scripts/: user-supplied data preparation, result validation, and figure generation.notebooks/: two output-free analysis notebooks; no solver duplication.results/precomputed/: historical summaries plus SHA-256 manifest.tests/: invariants, method semantics, and reproducibility smoke tests.docs/: methodology, interpretation, reproducibility, and validation evidence.
Python 3.11 or newer is recommended.
python -m venv .venv
python -m pip install -e .Development checks can be enabled with python -m pip install -e '.[dev]'. No package installation is required to inspect the precomputed CSV files.
python experiments/run_main_ablation.py --help
python experiments/run_main_ablation.py --scenario synthetic-12 --method SF --seed 2026 --iterations 20
python scripts/validate_results.pyThe default run is a small synthetic smoke test. It is not a Solomon benchmark experiment and does not update historical results.
Formal settings are recorded in configs/ and explained in reproducibility.md. They are intentionally not defaults. The current prepare_data.py is a partial parser, not the historical paper-ready preprocessing pipeline: it does not recreate candidate facilities, the road-distance matrix, representative scenario selection, or experiment parameters. Full formal reruns are outside the scope of this repository-cleaning session.
These files come from formal runs performed during the paper stage. The public subset is checked through SHA-256, schema, row counts, and mapping to the values actually printed in the final paper. The refactoring session did not rerun the full experiments. See results/README.md, result provenance, and results/precomputed/manifest.json. full_experiment_rerun is false.
The current package provides a reproducible experiment interface and has syntax, import, method-semantic, feasibility, fixed-seed, and synthetic smoke-test coverage. It is not claimed to be bit-for-bit, row-for-row, or iteration-for-iteration equivalent to every historical notebook run.
- The public refactor has synthetic invariant/smoke validation but has not yet been numerically cross-validated against every historical raw run.
- Solomon data redistribution rights were not established; raw benchmark files and customer-level derivatives are excluded.
- The service-time proxy is an optimization proxy. It is not presented as a real cold-chain deterioration model.
- PF-noop equalizes slot presence, not effective repair or local-search calls.
- Historical notebooks recorded environment-specific errors; the retained results therefore remain precomputed evidence pending an authorized clean full rerun.
The historical study used user-supplied Solomon-style VRPTW files. Candidate facilities were produced from customer coordinates using K-means in the historical workflow. Original Solomon instances are not distributed here because redistribution permission has not been confirmed; users must obtain them from a lawful, authoritative source. Processed benchmark-derived files with uncertain redistribution rights are also excluded. See data/README.md. The MIT license covers original repository code and documentation only and does not automatically cover third-party data.
See CITATION.cff.
Original source code and documentation are released under the MIT License. Third-party datasets, derived benchmark records, personal documents, and excluded paper submissions are not licensed by this repository.