OptSolvX in SBSCL: A Solver-Agnostic LP Core (GSoC 2025 Final Report)

Enhancing the Systems Biology Simulation Core Library (SBSCL) with a Solver-Agnostic Framework for Constraint-Based Simulation and Analysis

National Resource of Network Biology (NRNB)
Google Summer of Code 2025 Final Report

Name Michael Gaas

Mentors         Prof. Dr. Andreas Dräger, Matthias König

Overview

This work modernizes constraint-based simulation in the Systems Biology Simulation Core Library (SBSCL) by introducing a solver-agnostic linear programming (LP) core (OptSolvX), a thin integration layer within SBSCL, and a bridge from SBML/FBC to linear programs. The objective is to restore robust, portable Flux Balance Analysis (FBA) on current platforms, including ARM-based systems, while preserving SBSCL’s public API and keeping solver-specific concerns decoupled from biological model handling.

Implementation Summary

OptSolvX provides a minimal, solver-agnostic LP domain model with AbstractLPModel, Variable, Constraint, OptimizationDirection, and LPSolution, together with a stable adapter interface (LPSolverAdapter). A reference backend (for example CommonsMathSolver) shows the contract without introducing JSBML or native dependencies. The design keeps the surface small, with linear constraints and a single linear objective with explicit direction, which makes testing and backend interchangeability straightforward.

Figure 1. Proposed UML class diagram of the domain model: AbstractLPModel contains Variable and Constraint, carries OptimizationDirection, and produces an LPSolution; Constraint uses the Relation enum. In SBSCL, FbaToOptSolvX materializes this model from SBML/FBC prior to backend selection. Open as vector graphic

SBSCL integrates OptSolvX through org.simulator.optsolvx.OptSolvXSolverAdapter. The adapter requires the model to be built (model.isBuilt()), logs structured diagnostics with java.util.logging and MessageFormat, and transfers to the chosen OptSolvX backend, by default Commons Math. From the perspective of SBSCL’s public API, the integration stays non-intrusive.

Figure 2. Proposed UML diagram showing LPSolverAdapter with concrete backends (CommonsMathSolver, OjAlgoSolver); OptSolvXConfig.resolve(...) selects the backend (override/global/model), the chosen adapter reads an AbstractLPModel (vars/cons/objective) and returns an LPSolution. Open as vector graphic

A bridge, org.simulator.optsolvx.FbaToOptSolvX, connects SBML/FBC models to the LP core. It maps variable bounds, mass-balance constraints (S·v = 0), and the objective definition, and already creates bounds and objectives in the LP. Completing the mass-balance constraints will produce fully specified LPs directly from FBC-annotated models while keeping OptSolvX solver-agnostic.

Quality assurance covers both libraries. In SBSCL (JUnit 4), focused tests validate a little LP (minimization, equality constraints, bounds) and objective handling. In OptSolvX (JUnit 5), tests check the model contract and backend correctness with explicit double literals and precise tolerances. Old logging tools in SBSCL made it necessary to remove legacy XML parser stacks that conflicted with modern JDKs, and the documentation was extended with useful notes for the adapter and bridge.

Current State

An end-to-end run on the E. coli core model demonstrates the workflow. The bridge emits an LP with 95 variables and 72 constraints; the objective direction is MAXIMIZE. Using the OptSolvX → Commons Math backend, the instance is feasible with an objective value of ≈ 0.874 mmol/(gDW·h), and typical solve times are ~70–170 ms on Apple Silicon (ARM M3). Representative logs report LP size, objective direction, and feasibility. OptSolvX is developed on JDK 22 while emitting Java 8 bytecode for downstream compatibility; SBSCL targets Java 8 and executes cleanly on JDK 22 after classpath adjustments. Unit and smoke tests pass and provide structured diagnostics suitable for CI.

Remaining Work

The immediate tasks are the completion of the FBC mapping (robust S·v = 0 generation, reversibility handling, objective weights and senses, and consistent variable naming) and the extension of backend support. A GLPK and CBC backend is under way; and SCIP, CPLEX and Gurobi are natural next candidates. Adopt settings-based solver selection (COBRApy-style) with a global default and per-model override, honoring environment variables and falling back to the default when the requested solver is unavailable. Numerically, tolerances should be centralized (typical ranges 1e-6 to 1e-9), with explicit signaling of infeasible and unbounded cases and structured result reporting. Additional FBC fixtures (e.g., BiGG snippets) and CI coverage for edge cases will further strengthen regression protection. Finally, the distribution strategy for OptSolvX (vendoring, submodule, or publication to Maven Central) should be settled to streamline adoption.

Upstream Status and Code Availability

All code and pull requests are available in public repositories. The SBSCL repository contains the integration and bridge work, including a pull request titled “Make OptSolvX the default LP/FBA backend, introduce SBML-FBC→LP bridge, and fix XML classpath issue” Pull Request. General background information about the library is also available on Wikipedia. The OptSolvX repository hosts the LP core, adapter interface, and reference backend.

Challenges and Lessons Learned

Contributing to SBSCL in an active open source setting made the value of transparent workflows clear. Code, issues, and reviews are public, which keeps decisions traceable and collaboration straightforward. The dual Java toolchain showed a concrete issue early: several JDK 22 conveniences are unavailable when targeting Java 8. Replacing those calls with Java-8-safe equivalents, pinning the relevant Maven plugins, and setting the maven-compiler-plugin source and target to 1.8 restored portable builds. A difference solution between two solvers that first appeared as a global versus local optimum was traced back to configuration drift in objective sense, presolve, and bound configuration. Making bounds and equality constraints explicit and aligning settings was the solution for matching results across backends. Early tests, especially a simple maximization case, revealed edge conditions such as negative values from missing lower bounds and incomplete bound handling. Adding proper bounds, centralizing tolerances around 1e-8, and making status reporting explicit stabilized behavior across different solvers. My most useful practice through the project was taking short notes throughout the week that captured what was done, what comes next, and what remains open, which made it much easier to resume work. Overall, contributing to this open-source project improved my time management, reinforced common coding practices in a shared environment, and enhanced daily collaboration to keep the project on track and more important, working.

Reproducibility

Both projects are built with Maven. OptSolvX is compiled with mvn clean package and emits Java 8 bytecode while running on JDK 22. SBSCL builds with mvn clean package as well. The test suite covers the bridge and adapter, and an end-to-end run on the E. coli core model records the LP size, objective direction, feasibility, and objective value. Numerical tolerances used in tests are conservative and documented in code to facilitate comparison across backends.

Conclusion

OptSolvX provides a compact, solver-agnostic LP core, linked into SBSCL with a light-weight adapter and an SBML/FBC-to-LP bridge. The implementation already runs end to end on a published model, with clear error messages and stable outputs on current toolchains. Finishing the FBC mapping and adding more backends are straightforward follow-ups. With this base, SBSCL can run constraint-based simulations across platforms without solver-specific hacks, and users can switch solvers without touching model code. The same design also leaves room for methods like flux variability analysis and wider testing on community models.