Local-MIP

Local-MIP is a C++20 local-search solver for mixed integer programming. It ships with a lightweight CLI plus a focused C++/Python API and callback hooks to customize starts, restarts, weights, scoring functions, and neighborhood behavior.

Find out more about Local-MIP at https://local-mip.github.io/.

Although Local-MIP is freely available under the MIT license, we would be pleased to learn about users’ experiences and offer advice via email at peng.lin.csor@gmail.com.

Version History

Note: Local-MIP 1.0 has been archived and is available in Releases v1.0.1. The experimental results reported in the referenced papers (CP 2024 and Artificial Intelligence 2025) were obtained using Local-MIP 1.0.

Repository Layout

• src/ – solver entry (src/local_mip/Local_MIP.cpp), CLI wrapper (src/utils/main.cpp), search logic (src/local_search/), parsing (src/reader/), and model utilities (src/model_data/).
• src/model_api/ – Model API for programmatic model building (add variables/constraints from code).
• tests/ – unit, integration, and instance-driven tests (CMake/CTest).
• example/ – standalone API examples; buildable independently after preparing headers/static lib.
• test-set/ – sample .mps/.lp instances.
• build/ – generated build artifacts (created by ./build.sh).
• python-bindings/ – optional pybind11 bindings and Python packaging files.
• default.set – parameter configuration template.

Requirements

• CMake ≥ 3.15
• A C++20 compiler (GCC/Clang)
• bash, make, and standard POSIX utilities

Path 0: Install from PyPI

For Linux x86_64, install the published Python bindings directly:

python3 -m pip install localmip

Import the module in Python:

import localmip_py as lm

For repository-based development builds and Python demos, see python-bindings/README.md.

---

Path 1: Use the CLI Solver

Build

From the repository root:

# Release build (recommended)
./build.sh release

# Debug build with assertions/logging
./build.sh debug

# Build everything (core + examples + python bindings)
./build.sh all

# Clean build artifacts
./build.sh clean

The solver binary and static library are written to build/ (e.g., build/Local-MIP, build/libLocalMIP.a). ./build.sh all additionally prepares/builds the example/ demos and the pybind11 module under python-bindings/build/.

Run

Run from build/ so relative paths resolve:

cd build
./Local-MIP -i ../test-set/2club200v15p5scn.mps -t 300 -b 1 -l 1

Note: CLI flags support both short (e.g., -i) and long (e.g., --model_file) forms. Run ./Local-MIP --help to see the exact mapping for your version.

Command Line Parameters

Run ./Local-MIP --help (from build/) to see available CLI flags. The default.set template lists every parameter with its default value and brief notes; it can be used as-is or customized.

MPS Support

The reader now handles RANGES sections (SOS data is still rejected with an error).

Parameter Configuration File

You can use a configuration file to set parameters instead of (or in addition to) command line arguments. The repository includes default.set as a template with all available parameters and their default values.

Example:

cd build
./Local-MIP --param_set_file ../default.set --model_file ../test-set/2club200v15p5scn.mps

Format rules:

• One parameter per line: parameter_name = value
• Lines starting with # or ; are comments
• Command line arguments override values from the configuration file
• See default.set for descriptions and valid ranges

Tests

CTest targets are defined in tests/CMakeLists.txt.

./build.sh debug   # or release
cd build

# Run unit test subset
ctest --output-on-failure -R "^(api|callbacks|constraint_recognition|scoring|model_manager|reader|move_operations|neighbor_config)$"

# Run integration tests
ctest --output-on-failure -R "^integration$"

# Run all tests (including per-instance sweeps)
ctest --output-on-failure

---

Path 2: Use as a Library

The public C++ and Python interfaces expose the core solver configuration used in normal runs, including parameter-file loading, along with result queries, in-memory modeling, and callback registration.

C++ static library

• The core build produces build/libLocalMIP.a; headers live under src/.
• Link against the static library directly or follow the example projects under example/.

Model API (programmatic model building)

If you want to build a MIP model from code (instead of reading .mps/.lp), use the Model API:

• C++ demo: example/model-api/model_api_demo.cpp (see example/model-api/README.md)
• Python demo: python-bindings/model_api_demo.py (requires the pybind11 module)

Important: Model API usage is single-run. Build the model once, call run once, and do not add variables/constraints after run. To solve again, create a new model instance.

Build & run (one-time):

# Build core + all examples + python bindings
./build.sh all

# Run the C++ Model API demo
cd example/model-api
./model_api_demo

# Run the Python Model API demo
cd ../../
python3 python-bindings/model_api_demo.py

Callbacks (customize the solver)

Local-MIP exposes multiple callback hooks (start, restart, weight, neighbor generation, neighbor scoring, lift scoring). Predefined demos live under example/ (e.g., start-callback/, restart-callback/, weight-callback/, neighbor-config/, neighbor-userdata/, scoring-neighbor/, scoring-lift/). The C++ API exposes typed callback signatures with optional void* user_data; the Python bindings now expose structured callback context objects plus optional user_data objects so the same customization pattern is available from Python. Refer to the example READMEs and callback type declarations in src/local_search/ for details.

Example projects (C++ API)

Examples are decoupled from the main tree. Prepare once, then build (or run ./build.sh all to do this automatically):

cd example
./prepare.sh   # copies libLocalMIP.a, headers, and sample test-set files into example/
./build.sh     # builds all demos

Notable demo directories:

• simple-api/ – minimal solver usage
• model-api/ – build models programmatically via the Model API
• start-callback/, restart-callback/, weight-callback/ – callback hooks
• scoring-lift/, scoring-neighbor/ – custom scoring in feasible/infeasible phases
• neighbor-config/, neighbor-userdata/ – neighbor configuration and custom operators

Each demo binary is emitted inside its directory. The canonical flow is to run it from example/ after ./build.sh:

cd example
./simple-api/simple_api_demo

File-backed demos now also resolve the bundled sample instance when launched from their own subdirectory, so cd example/simple-api && ./simple_api_demo works too. Pass a custom instance path as argv[1] when needed.

Python bindings (pybind11)

Located in python-bindings/ (separate from the core).

Install from PyPI on Linux x86_64:

python3 -m pip install localmip
python3 -c "import localmip_py as lm; print(lm.LocalMIP)"

Quick start from the repository:

python3 -m pip install ./python-bindings
python3 python-bindings/sample.py

# Model API demo (build models programmatically)
python3 python-bindings/model_api_demo.py

# Smoke test for parameter files + callback contexts
python3 python-bindings/test_python_api.py

For iterative local development, python-bindings/build.sh still builds the extension into python-bindings/build/, and the repository demos prefer that local build when it exists. The sample loads test-set/2club200v15p5scn.mps, runs the solver, and writes py_example.sol. Python callbacks receive structured context objects, expose writable solver state where appropriate, and optionally accept a Python user_data object. If your python3 is not the same interpreter used during build, rebuild with PYTHON_EXECUTABLE=/path/to/python3 python-bindings/build.sh and use that same interpreter to run the scripts.

---

Development Notes

• Code style: C++20, two-space indentation, local headers before system headers, prefer printf-family.
• Keep CLI parameters in sync with src/utils/paras.h and help text.

Reference

If you use Local-MIP in an academic context, please cite the following articles:

Important: The experimental results reported in the papers below were obtained using Local-MIP 1.0 (GitHub release v1.0.1).

1. Journal Version (Artificial Intelligence, 2025)
   Peng Lin, Shaowei Cai, Mengchuan Zou, Jinkun Lin,
   Local-MIP: Efficient local search for mixed integer programming,
   Artificial Intelligence, Volume 348, 2025, 104405.
   doi.org/10.1016/j.artint.2025.104405

2. Conference Version (CP 2024, Best Paper Award)
   Peng Lin, Mengchuan Zou, and Shaowei Cai.
   An Efficient Local Search Solver for Mixed Integer Programming. In Proceedings of the 30th International Conference on Principles and Practice of Constraint Programming (CP 2024).
   doi.org/10.4230/LIPIcs.CP.2024.19.

---

BibTeX

@article{LIN2025104405,
title = {Local-MIP: Efficient local search for mixed integer programming},
journal = {Artificial Intelligence},
volume = {348},
pages = {104405},
year = {2025},
issn = {0004-3702},
doi = {https://doi.org/10.1016/j.artint.2025.104405},
url = {https://www.sciencedirect.com/science/article/pii/S0004370225001249},
author = {Peng Lin and Shaowei Cai and Mengchuan Zou and Jinkun Lin},
}

@InProceedings{lin_et_al:LIPIcs.CP.2024.19,
  author =	{Lin, Peng and Zou, Mengchuan and Cai, Shaowei},
  title =	{{An Efficient Local Search Solver for Mixed Integer Programming}},
  booktitle =	{30th International Conference on Principles and Practice of Constraint Programming (CP 2024)},
  pages =	{19:1--19:19},
  series =	{Leibniz International Proceedings in Informatics (LIPIcs)},
  ISBN =	{978-3-95977-336-2},
  ISSN =	{1868-8969},
  year =	{2024},
  volume =	{307},
  URL =		{https://drops.dagstuhl.de/entities/document/10.4230/LIPIcs.CP.2024.19},
  doi =		{10.4230/LIPIcs.CP.2024.19},
}

---

New Records for Open Instances

Local-MIP has set new records for several benchmark instances in the MIPLIB dataset, including:

1. sorrell7
2. genus-sym-g31-8
3. supportcase22
4. cdc7-4-3-2
5. genus-sym-g62-2
6. genus-g61-25
7. ns1828997
8. neos-4232544-orira
9. scpm1
10. scpn2