path-capi-python

Python wrapper for the PATH C API with Apple Silicon support for solving MCP and LCP models, with optional adapters for Pyomo workflows.

Overview

path-capi-python provides a thin, explicit bridge from Python to the PATH C API. The project is designed to:

• Load PATH shared libraries on modern platforms (including Apple Silicon).
• Expose core C API operations in a Pythonic interface.
• Support MCP/LCP solve workflows with deterministic diagnostics.
• Offer an optional adapter layer for Pyomo-centered workflows.

Scope

This repository wraps the PATH C API. It does not reimplement the PATH solver.

Installation

pip install path-capi-python            # C API wrapper only
pip install "path-capi-python[pyomo]"   # with the Pyomo adapter

The package does not ship the PATH solver itself. Download the PATH shared libraries from the PATH authors and point the wrapper at them:

export PATH_CAPI_LIBPATH=/absolute/path/to/libpath50.silicon.dylib
export PATH_CAPI_LIBLUSOL=/absolute/path/to/liblusol.silicon.dylib

PATH Licensing

This project is MIT-licensed for the wrapper code only. The underlying PATH solver is distributed under its own terms. Users are responsible for obtaining and complying with PATH licensing requirements.

Without a license string PATH runs in demonstration mode: at most 300 variables and 2,000 nonzeros. The PATH authors publish a free evaluation license that removes the size limit for a period of time; it is in the LICENSE file at https://pages.cs.wisc.edu/~ferris/path/julia/LICENSE. Set it before solving:

export PATH_LICENSE_STRING="<string from that LICENSE file>"

You can check what your runtime allows with PATHLoader.check_license(runtime, n_vars, nnz).

Initial Roadmap

• C API loader and runtime checks.
• Minimal MCP solve example with callbacks.
• Structured status and residual reporting.
• Optional Pyomo adapter prototype.

Current Status

• PATH shared library loader implemented (Path_Version, Path_CheckLicense).
• PATH runtime can be configured directly from PATH_CAPI_LIBPATH and PATH_CAPI_LIBLUSOL.
• Minimal linear MCP solve implemented through C callbacks.
• Nonlinear MCP solve implemented through residual/Jacobian callbacks with fixed sparsity.
• Example scripts available at examples/check_runtime.py and examples/minimal_mcp.py.
• Pyomo adapter can build callbacks from equality constraints and write solutions back to model variables.
• Pyomo solver plugin path_capi_bridge is registered through SolverFactory.

Runtime Setup

With the libraries set up as in Installation, verify the runtime first:

PYTHONPATH=src python3 examples/check_runtime.py

Then run the minimal MCP example:

PYTHONPATH=src python3 examples/minimal_mcp.py

Nonlinear MCP API

Use solve_nonlinear_mcp when the residual is not available in M, q form. Provide:

• bounds and start point (lb, ub, x0)
• a residual callback callback_f(x) -> F(x)
• a Jacobian callback callback_jac(x) -> values
• a fixed sparsity pattern via JacobianStructure

The Jacobian values must be returned in the same order implied by the column-compressed structure.

For Pyomo workflows, PyomoMCPAdapter also provides:

• build_nonlinear_callbacks(...)
• build_nonlinear_from_equality_constraints(...)
• solve_nonlinear(...)
• solve_nonlinear_from_equality_constraints(...)

Pyomo Solver Plugin

The package registers a native Pyomo solver plugin named path_capi_bridge. It currently targets square systems of active equality constraints and routes them through the PATH C API bridge.

import path_capi_python
from pyomo.environ import ConcreteModel, Constraint, SolverFactory, Var

model = ConcreteModel()
model.x1 = Var(initialize=1.5)
model.x2 = Var(initialize=0.5)
model.c1 = Constraint(expr=model.x1**2 - 3.0 == 0.0)
model.c2 = Constraint(expr=model.x1 + 2.0 * model.x2 - 2.0 == 0.0)

solver = SolverFactory("path_capi_bridge")
results = solver.solve(model, output=False)

Optional keyword arguments to solve(...):

• runtime: preloaded PATHRuntime
• path_lib, lusol_lib: explicit shared-library paths
• constraints: ordered equality constraints to use
• variables: ordered variables to use
• output: enable or suppress PATH output

Running Tests

Set library paths to your local PATH shared libraries before running tests:

PATH_CAPI_LIBPATH=/absolute/path/to/libpath50.silicon.dylib \
PATH_CAPI_LIBLUSOL=/absolute/path/to/liblusol.silicon.dylib \
PYTHONPATH=src python3 -m pytest -q

Development Notes

• Target platform priority: macOS arm64.
• Keep the low-level C API layer explicit and well-tested.
• Build higher-level adapters only after the C layer is stable.