Add FICO Xpress Optimizer backend support

[XPRSc4v4]

Hi!

This PR adds support for the FICO Xpress Optimizer to PyOptInterface. The implementation follows the established patterns from the Gurobi and COPT backends, adapting Xpress-specific features to fit the PyOptInterface design.

Supported Features

• Linear and mixed-integer linear programming (LP/MILP)
• Quadratic objectives and constraints (QP/QCP/MIQP/MIQCP)
• Second-order cone constraints (mapped to quadratic constraints, auto-detected by Xpress)
• Exponential cone constraints (mapped to nonlinear formulas)
• Nonlinear programming via formula-based modeling (NLP)
• Special Ordered Sets (SOS1/SOS2)
• Optimization callbacks with the APIs currently supported by the other solvers

Implementation Notes

Xpress-Specific Adaptations:

1. Global Environment Management: Xpress requires global initialization/cleanup via XPRSinit/XPRSfree. This is handled through a reference-counted XpressEnv class to ensure proper lifecycle management across multiple model instances.

2. Quadratic Term Scaling: Xpress uses different conventions for quadratic terms:

   • Objectives: 0.5 * x'Qx (diagonal coefficients need 2x scaling)
   • Constraints: x'Qx (off-diagonal coefficients need 0.5x scaling)

   The implementation handles this transparently in set_objective and add_quadratic_constraint.

3. Callback Threading: Xpress callbacks receive thread-local problem clones. The implementation uses a swap mechanism to ensure the user interacts with the correct problem instance, with proper GIL management. Callbacks are serialized via XPRS_MUTEXCALLBACKS=1 to avoid race conditions. Note: this implementation does not support Python's new free-threading feature (PEP 703). If you plan to add free-threading support to PyOptInterface, we can adapt the Xpress backend to enable parallel callbacks, which Xpress supports natively.

4. Callback Interface: PyOptInterface's single callback with context enumeration is mapped to Xpress's native multi-callback interface internally, maintaining consistency with other backends. Xpress provides additional callback contexts and APIs that allow customization of other optimization aspects (e.g., branching rules). Let me know if you're interested in extending PyOptInterface to support these advanced features.

5. Parameter Access: The implementation preserves Xpress naming conventions: "controls" for read/write optimizer parameters, "attributes" for read-only model and optimization status information.

Testing

All existing PyOptInterface tests pass with the Xpress backend. Additionally, a TSP callback example demonstrates the integration of optimization callbacks with lazy constraint generation.

Documentation

User documentation has been added in docs/source/xpress.md, covering installation, basic usage, and Xpress-specific considerations.

Please let me know if any design choices need adjustment to better align with PyOptInterface conventions, or if you have questions about the implementation. Happy to discuss further details or make modifications as needed.

Thanks for the great library!

Best,
Francesco

[metab0t]

Thanks for your hard work on this heroic PR!

I will look into your PR next week.

[metab0t]

I have gone through the code changes and your implementation is quite neat. I am not familiar with the C API of xpress and our existing tests can ensure the basic correctness of solver interfaces.

My only concern is that we should contain the header files (with C API) in POI, so that the project can be built standalone. This is important because I need to build and distribute wheels via GitHub actions and do not want to bother to download the whole package of solvers. Is it OK with you? If so, I will include the headers and modify the cmakelists accordingly.

[XPRSc4v4]

Hi, I completely understand the need to include the headers for standalone builds.
I've forwarded the request to the appropriate people to check if we're allowed to redistribute the header files. I'll let you know when I'll hear back.
Worst case, I can create a minimal header file containing only the symbol definitions used by POI, which should avoid any licensing concerns.

[XPRSc4v4]

Hi! Since I can't predict how long it might take to get a definitive answer about including xprs.h in the repo, I've added a hand-written forward declarations header that enables standalone compilation.

This header contains only the minimal type declarations, function signatures, and constants needed by POI to compile against the Xpress API.

I hope this works for you. Let me know if there are any other improvements you'd like to see!

[metab0t]

Great!
Will merge it soon and release a new version later.

[metab0t]

It always takes some time to ensure c++ code compiles correctly on different platforms, as CI has revealed some build errors @XPRSc4v4 :

Windows: The unistd.h header file is not found, ref: https://github.com/metab0t/PyOptInterface/actions/runs/20410111317/job/58645614134#step:5:686

I also find the XPRESS_MODEL_MODE::CALLBACK where CALLBACK is already defined by windows headers, so maybe it should be changed to a new name.

Mac: an error with std::visit, ref: https://github.com/metab0t/PyOptInterface/actions/runs/20410111310/job/58645614098#step:5:140

Update: these issues have been easily fixed with the help of AI.