localmip 2.0.8

Python bindings for the Local-MIP solver

Python Bindings (pybind11)

This folder provides a pybind11 module that exposes Local_MIP to Python without touching the main solver code.

The bindings expose the core solver configuration and result-query API used in normal runs, including .set parameter-file loading, plus the in-memory modeling interface.

Install from PyPI

For Linux x86_64:

python3 -m pip install localmip

Import it directly:

import localmip_py as lm

Install from the repository

From repo root:

python3 -m pip install ./python-bindings

This builds both the Local-MIP core and the pybind11 extension during installation. After installation, the module can be imported directly:

python3 -c "import localmip_py as lm; print(lm.LocalMIP)"

Run the demos

From repo root:

python3 python-bindings/sample.py
python3 python-bindings/model_api_demo.py
python3 python-bindings/test_python_api.py
python3 python-bindings/smoke_test.py

Development build without pip

The legacy local build flow is still supported. From repo root:

PY_EXE="$(python3 -c 'import sys; print(sys.executable)')"
PYTHON_EXECUTABLE="${PY_EXE}" python-bindings/build.sh

Output: python-bindings/build/localmip_py.cpython-*.so (exact suffix depends on Python version).

Use the same interpreter for build and run so the compiled module suffix matches the interpreter that imports it:

PY_EXE="$(python3 -c 'import sys; print(sys.executable)')"
PYTHON_EXECUTABLE="${PY_EXE}" python-bindings/build.sh
"${PY_EXE}" python-bindings/sample.py
"${PY_EXE}" python-bindings/model_api_demo.py
"${PY_EXE}" python-bindings/test_python_api.py
"${PY_EXE}" python-bindings/smoke_test.py

Use in Python

If installed with pip:

import localmip_py as lm

If using the local development build, either put the build directory at the front of PYTHONPATH or copy the .so next to your script:

import sys
sys.path.insert(0, "python-bindings/build")  # prefer the local build
import localmip_py as lm

solver = lm.LocalMIP()
solver.set_model_file("test-set/sct1.mps")
solver.set_sol_path("py_example.sol")
solver.set_time_limit(10.0)
solver.set_log_obj(True)

# Optional: register a start callback
stats = {"calls": 0}

def start_cbk(ctx, user_data):
    user_data["calls"] += 1
    if ctx.shared.binary_idx_list:
        idx = ctx.shared.binary_idx_list[0]
        ctx.current_values[idx] = 1.0

solver.set_start_cbk(start_cbk, stats)
solver.run()

print("Feasible:", solver.is_feasible(), "Obj:", solver.get_obj_value())
print("Start callback calls:", stats["calls"])

Model API (Programmatic Modeling)

The bindings also expose Local-MIP's Model API, which lets you build a model directly in Python (mirrors example/model-api/model_api_demo.cpp).

Run the demo:

PY_EXE="$(python3 -c 'import sys; print(sys.executable)')"
"${PY_EXE}" python-bindings/model_api_demo.py

Smoke test:

PY_EXE="$(python3 -c 'import sys; print(sys.executable)')"
"${PY_EXE}" python-bindings/test_python_api.py

Key symbols:

• lm.Sense.{minimize,maximize}
• lm.VarType.{binary,general_integer,real,fixed}
• LocalMIP.set_param_set_file(...)
• LocalMIP.set_bms_unsat_con(...), set_bms_mtm_unsat_op(...), set_bms_sat_con(...), set_bms_mtm_sat_op(...), set_bms_flip_op(...), set_bms_easy_op(...), set_bms_random_op(...)
• LocalMIP.get_solution()
• ModelVar.requires_integrality()
• lm.ModelPrepareOptions, lm.PreparedModel.from_file(...)
• lm.ModelBuilder.add_var(...), add_con(...), and prepare(...)

Shared model, multiple Python workers

LocalMIP(prepared_model) keeps the frozen model alive and shares it without copying. Each solver has independent RNG and search state:

import threading
import localmip_py as lm

options = lm.ModelPrepareOptions()
model = lm.PreparedModel.from_file("instance.mps", options)
solvers = [lm.LocalMIP(model) for _ in range(4)]

for seed, solver in enumerate(solvers, start=1):
    solver.set_random_seed(seed)
    solver.set_time_limit(10.0)
    solver.set_log_obj(False)

workers = [threading.Thread(target=solver.run) for solver in solvers]
for worker in workers:
    worker.start()
for worker in workers:
    worker.join()

run() releases the GIL, so independent searches can execute concurrently. Python callbacks reacquire the GIL, so callback-heavy searches may serialize while callbacks run. Local-MIP does not create Python threads or merge results; the application schedules the workers and selects the final incumbent.

Each LocalMIP object accepts exactly one run() call, including a call that ends by throwing an exception. Create another solver for a new seed or model; multiple solvers can reuse the same PreparedModel.

Notes

• pip install ./python-bindings compiles the Local-MIP core and the extension together inside the wheel build.
• The local helper script python-bindings/build.sh still works for iterative development builds.
• Long-running run() releases the GIL; Python callbacks reacquire the GIL before execution.
• Callback contexts (Start::Start_Ctx, etc.) are exposed as structured Python objects with read-only shared sequence views and writable fields where the solver expects mutation.
• NeighborCtx.op_size is derived from clear_ops(), set_single_op(...), and append_op(...); update move outputs through those helpers instead of writing the size directly.
• Python callbacks can optionally receive a Python user_data object; if omitted, the old shorter callback signatures still work.
• Writable start/restart callback values and custom moves are checked for finite values, bounds, and integrality before the solver accepts them.