Add support for ipopt solver (#142)

* Adding Ipopt as a supported solver in the array of solvers, 37 tests to fix for it to work properly

* Ipopt does not support VariableDomains as the type signature in poi is different

* Ipopt does not support maximization problems, implicitly change sign of objective and set to minimize

* Add a tolerance function since Ipopt has some numerical differences when comparing to integers and run all tests with that new function

* Raise not implemented exception when trying to write files using Ipopt since it's not supported by the optimizer

* Parametrize IO tests to not use Ipopt when testing writing files

* Skip MIP tests

* Skip arithmetic test of binary variables

* Fix quadrative objective, specially for ipopt since it needs to be negated when maximizing

* Adding portfolio optimization example to test QPs for IPOPT and Gurobi

* Add PyOptInterface dependendcy and update docs to include the binaries installation as well

* Small typo fix

* Run ruff format and ruff check

* Clarify installation instructions and fix CI pipeline

* Cleanup code

* Simplify testing

* Minor cleanup

* Fix errors and move to new cache

* Swap order of steps

* Install dependencies for ipopt

* Improve coverage and documentation

* Increase test coverage

* Fix tests that were being missed

* Include tests that were being skipped

---------

Co-authored-by: Martin Staadecker <[email protected]>

Author: eduardosalaz

.github/actions/setup_optimizers_linux/action.yml

@@ -5,7 +5,7 @@
 name: "Install optimizers on linux"
 
 inputs:
-  GUROBI_WLS: 
+  GUROBI_WLS:
     description: "..."
     required: true
   # COPT_CLIENT_INI:
@@ -17,7 +17,7 @@ inputs:
   # GITHUB_TOKEN:
   #   description: "..."
   #   required: true
-  CHECK_LICENSE: 
+  CHECK_LICENSE:
     description: "..."
     required: true
 
@@ -33,18 +33,22 @@ runs:
       id: cache-installers-linux
       uses: actions/cache@v4
       env:
-        cache-name: cache-installers-linux
+        cache-name: cache-installers-linux-v2
       with:
         path: ~/installers
-        key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('optimizer_version.toml') }}
+        key: ${{ runner.os }}-build-${{ env.cache-name }}-v2-${{ hashFiles('optimizer_version.toml') }}
         restore-keys: |
-          ${{ runner.os }}-build-${{ env.cache-name }}-
+          ${{ runner.os }}-build-${{ env.cache-name }}-v2-
 
-    - if: ${{ steps.cache-installers-linux.outputs.cache-hit != 'true' }}
+    - if: ${{ steps.cache-installers-linux-v2.outputs.cache-hit != 'true' }}
       shell: bash
       name: Download Installers
       run: |
         curl -L -o ~/installers/gurobi.tar.gz https://packages.gurobi.com/12.0/gurobi12.0.2_linux64.tar.gz
+        curl -L -o ~/installers/idaes-solvers.tar.gz https://github.com/IDAES/idaes-ext/releases/download/3.4.2/idaes-solvers-ubuntu2204-x86_64.tar.gz
+
+    # curl -L -o ~/installers/copt.tar.gz https://pub.shanshu.ai/download/copt/7.2.8/linux64/CardinalOptimizer-7.2.8-lnx64.tar.gz
+    # curl -L -o ~/installers/mosek.tar.bz2 https://download.mosek.com/stable/10.2.0/mosektoolslinux64x86.tar.bz2
 
     - name: Setup Gurobi Installation
       shell: bash
@@ -59,13 +63,13 @@ runs:
         echo "PATH=${PATH}:${GUROBI_HOME}/bin" >> $GITHUB_ENV
         echo "LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${GUROBI_HOME}/lib" >> $GITHUB_ENV
         echo $GUROBI_HOME
-        
+
         # setup license using secrets
         echo "$GUROBI_WLS" > ~/gurobi.lic
         echo "GRB_LICENSE_FILE=${HOME}/gurobi.lic" >> $GITHUB_ENV
     - name: Test Gurobi
       if: ${{ inputs.CHECK_LICENSE == 'true' }}
-      uses: nick-fields/retry@v3    # wait 30 seconds (5x) if all licenses are already in use
+      uses: nick-fields/retry@v3 # wait 30 seconds (5x) if all licenses are already in use
       with:
         max_attempts: 5
         retry_wait_seconds: 30
@@ -118,15 +122,16 @@ runs:
     #   run: |
     #     msktestlic
 
-    # - name: Setup IPOPT Installation
-    #   shell: bash
-    #   run: |
-    #     mkdir -p ~/ipopt
-    #     tar xfz ~/installers/idaes-solvers.tar.gz -C ~/ipopt
-    #     echo "PATH=${PATH}:${HOME}/ipopt" >> $GITHUB_ENV
-    #     echo "LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${HOME}/ipopt" >> $GITHUB_ENV
-    #     ls ~/ipopt
-    # - name: Test IPOPT
-    #   shell: bash
-    #   run: |
-    #     ipopt -v
+    - name: Setup IPOPT Installation
+      shell: bash
+      run: |
+        sudo apt-get install -y libopenblas-dev liblapack3 libgfortran5
+        mkdir -p ~/ipopt
+        tar xfz ~/installers/idaes-solvers.tar.gz -C ~/ipopt
+        echo "PATH=${PATH}:${HOME}/ipopt" >> $GITHUB_ENV
+        echo "LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${HOME}/ipopt" >> $GITHUB_ENV
+        ls ~/ipopt
+    - name: Test IPOPT
+      shell: bash
+      run: |
+        ipopt -v

.github/workflows/ci.yml

@@ -75,13 +75,13 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           cache: "pip"
+      - name: Install dependencies
+        run: |
+          pip install .[dev]
       - uses: ./.github/actions/setup_optimizers_linux
         with:
           GUROBI_WLS: ${{ secrets.GUROBI_WLS }}
           CHECK_LICENSE: true
-      - name: Install dependencies
-        run: |
-          pip install --editable .[dev]
       - name: Run tests and collect coverage
         run: pytest --cov
       - name: Upload coverage to Codecov

.vscode/settings.json

@@ -3,5 +3,11 @@
         "--markdown-docs", "--markdown-docs-syntax=superfences"
     ],
     "python.testing.unittestEnabled": false,
-    "python.testing.pytestEnabled": true
+    "python.testing.pytestEnabled": true,
+    "cSpell.words": [
+        "Gurobi",
+        "Pyoframe",
+        "ipopt",
+        "highs"
+    ]
 }

docs/contribute/index.md

@@ -28,6 +28,7 @@ We use [Material Docs](https://squidfunk.github.io/mkdocs-material/) for documen
 - `python ./tests/test_examples.py`: Regenerate the files in the `results` folder of an example (e.g. `tests/examples/sudoku/results/**`). You should only run this if the result files need to be regenerated, for example, if model variable names have changed.
 - `ruff check`: Ensures all the linter tests pass
 - `ruff format`: Ensures the code is properly formatted (this is run upon commit if you've installed the pre-commit hooks)
+- `python -m tests/test_examples.py` to regenerate the example result datasets.
 
 ## Details for repository maintainers
 

docs/learn/01_getting-started/01_installation.md

@@ -1,26 +1,51 @@
-## Install Pyoframe
+## 1. Install Pyoframe
 
 ```cmd
 pip install pyoframe
 ```
 
-## Install a solver
+## 2. Install a solver
 
-*[solver]: Solvers like HiGHS and Gurobi do the actual solving of your model. Pyoframe is a layer on top of the solver that makes it easy to build models and switch between solvers.
+Pyoframe makes it easy to build models but the actual solving of your model is done by a solver. You'll need to install one of the following solvers:
 
-=== "HiGHS (free)"
+=== "HiGHS (open-source)"
+
+    To install [HiGHS](https://highs.dev/) run:
 
     ```cmd
     pip install pyoframe[highs]
     ```
 
+    !!! warning "No support for quadratics in HiGHS"
+        Pyoframe does not support quadratic constraints when using HiGHS due to limitations in pyoptinterface, the library we use to communicate with HiGHS.
+
+
 === "Gurobi (commercial)"
 
-    1. [Install Gurobi](https://www.gurobi.com/downloads/gurobi-software/) from their website.
+    To install Gurobi:
+
+    1. [Download Gurobi](https://www.gurobi.com/downloads/gurobi-software/) from their website (login required) and follow the installation instructions.
     2. Ensure you have a valid Gurobi license installed on your machine.
 
-    Note: installing Gurobi via pip will not work since we access Gurobi through its C API not through Python.
+    !!! note "`pip` installation not possible"
+        Installing Gurobi via `pip` will not work. We use Gurobi's C API which is not available in the Python version of Gurobi.
+
+=== "Ipopt (free, nonlinear)"
+
+    To install [ipopt](https://coin-or.github.io/Ipopt/):
+
+    1. Run: `pip install pyoframe[ipopt]`
+    2. Download the [Ipopt binaries](https://github.com/coin-or/Ipopt/releases) from GitHub. Version 3.14.x is recommended since it is the latest version that we've tested.
+    3. On Windows, unpack the zip and add the `bin` folder to your Path variable. If not on Windows, you may have to build the solver from source, see further details [here](https://metab0t.github.io/PyOptInterface/getting_started.html#ipopt).
+
+    !!! warning "Continuous variables only"
+        Ipopt is a nonlinear solver for continuous variables only. Use another solver if you need to use binary or integer variables. 
+
+=== "Other solvers"
+
+    We'd be glad to consider adding more solvers. Create a [new issue](https://github.com/Bravos-Power/pyoframe/issues/new) or up-vote an existing one to show interest:
+
+    - Issue tracking interest in [COPT solver](https://github.com/Bravos-Power/pyoframe/issues/143)
+    - Issue tracking interest in [Mosek solver](https://github.com/Bravos-Power/pyoframe/issues/144)
 
-=== "Other Solvers"
 
-    We'd be glad to add more solvers! Just [let us know](https://github.com/Bravos-Power/pyoframe/pull/79) what you'd like :)

mkdocs.yml

@@ -65,6 +65,10 @@ plugins:
       handlers:
         python:
           options:
+            show_if_no_docstring: true
+            summary: true
+            extensions:
+              - dataclasses
             merge_init_into_class: true
             docstring_options:
               ignore_init_summary: true

pyproject.toml

@@ -47,8 +47,10 @@ dev = [
     "mkdocs-literate-nav",
     "mkdocs-table-reader-plugin",
     "markdown-hide-code>=0.1.1",
+    "pyoptinterface[nlp]"
 ]
 highs = ["highsbox"]
+ipopt = ["pyoptinterface[nlp]"]
 
 [tool.ruff]
 lint.select = ["E4", "E7", "E9", "F", "I", "W292", "W291"]

src/pyoframe/constants.py

@@ -2,7 +2,10 @@
 File containing shared constants used across the package.
 """
 
+from __future__ import annotations
+
 import typing
+from dataclasses import dataclass
 from enum import Enum
 from typing import Literal, Optional
 
@@ -15,10 +18,45 @@
 CONSTRAINT_KEY = "__constraint_id"
 SOLUTION_KEY = "solution"
 DUAL_KEY = "dual"
-SUPPORTED_SOLVERS = ["gurobi", "highs"]
-SUPPORTED_SOLVER_TYPES = Literal["gurobi", "highs"]
+
 KEY_TYPE = pl.UInt32
 
+
+@dataclass
+class Solver:
+    name: SUPPORTED_SOLVER_TYPES
+    supports_integer_variables: bool = True
+    supports_quadratics: bool = True
+    supports_duals: bool = True
+    supports_objective_sense: bool = True
+    supports_write: bool = True
+
+    def check_supports_integer_variables(self):
+        if not self.supports_integer_variables:
+            raise ValueError(
+                f"Solver {self.name} does not support integer or binary variables."
+            )
+
+    def check_supports_write(self):
+        if not self.supports_write:
+            raise ValueError(f"Solver {self.name} does not support .write()")
+
+    def __repr__(self):
+        return self.name
+
+
+SUPPORTED_SOLVERS = [
+    Solver("gurobi"),
+    Solver("highs", supports_quadratics=False, supports_duals=False),
+    Solver(
+        "ipopt",
+        supports_integer_variables=False,
+        supports_objective_sense=False,
+        supports_write=False,
+    ),
+]
+
+
 # Variable ID for constant terms. This variable ID is reserved.
 CONST_TERM = 0
 
@@ -49,7 +87,16 @@ class Config(metaclass=_ConfigMeta):
     Configuration options that apply to the entire library.
     """
 
-    default_solver: Optional[SUPPORTED_SOLVER_TYPES] = None
+    default_solver: SUPPORTED_SOLVER_TYPES | Solver | None = None
+    """
+    The solver to use when `pf.Model()` is called without specifying a solver.
+    If default_solver is not set (`None`),
+    Pyoframe will choose the first solver in SUPPORTED_SOLVERS that doesn't produce an error.
+
+    There is no reason why you set the solver here instead of passing it to the Model constructor.
+    This is mainly used for testing purposes.
+    """
+
     disable_unmatched_checks: bool = False
     float_to_str_precision: Optional[int] = 5
     print_uses_variable_names: bool = True
@@ -135,6 +182,11 @@ class UnmatchedStrategy(Enum):
 for enum, type in [(ObjSense, ObjSenseValue), (VType, VTypeValue)]:
     assert set(typing.get_args(type)) == {vtype.value for vtype in enum}
 
+SUPPORTED_SOLVER_TYPES = Literal["gurobi", "highs", "ipopt"]
+assert set(typing.get_args(SUPPORTED_SOLVER_TYPES)) == {
+    s.name for s in SUPPORTED_SOLVERS
+}
+
 
 class PyoframeError(Exception):
     pass

src/pyoframe/core.py

@@ -1132,13 +1132,20 @@ def __init__(self, lhs: Expression, sense: ConstraintSense):
         self._model = lhs._model
         self.sense = sense
         self.to_relax: Optional[FuncArgs] = None
-        self.attr = Container(self._set_attribute, self._get_attribute)
+        self._attr = Container(self._set_attribute, self._get_attribute)
 
         dims = self.lhs.dimensions
         data = pl.DataFrame() if dims is None else self.lhs.data.select(dims).unique()
 
         super().__init__(data)
 
+    @property
+    def attr(self) -> Container:
+        """
+        Allows reading and writing constraint attributes similarly to [Model.attr][pyoframe.Model.attr].
+        """
+        return self._attr
+
     def _set_attribute(self, name, value):
         self._assert_has_ids()
         col_name = name
@@ -1504,7 +1511,7 @@ def __init__(
         super().__init__(data)
 
         self.vtype: VType = VType(vtype)
-        self.attr = Container(self._set_attribute, self._get_attribute)
+        self._attr = Container(self._set_attribute, self._get_attribute)
         self._equals = equals
 
         if lb is not None and not isinstance(lb, (float, int)):
@@ -1516,6 +1523,13 @@ def __init__(
         else:
             self._ub_expr, self.ub = None, ub
 
+    @property
+    def attr(self) -> Container:
+        """
+        Allows reading and writing variable attributes similarly to [Model.attr][pyoframe.Model.attr].
+        """
+        return self._attr
+
     def _set_attribute(self, name, value):
         self._assert_has_ids()
         col_name = name
@@ -1559,11 +1573,16 @@ def _get_attribute(self, name):
             ).select(self.dimensions_unsafe + [col_name])
 
     def _assign_ids(self):
-        kwargs = dict(domain=self.vtype.to_poi())
+        assert self._model is not None
+
+        kwargs = {}
         if self.lb is not None:
-            kwargs["lb"] = self.lb
+            kwargs["lb"] = float(self.lb)
         if self.ub is not None:
-            kwargs["ub"] = self.ub
+            kwargs["ub"] = float(self.ub)
+        if self.vtype != VType.CONTINUOUS:
+            self._model.solver.check_supports_integer_variables()
+            kwargs["domain"] = self.vtype.to_poi()
 
         if self.dimensions is not None and self._model.use_var_names:
             df = (