Merge pull request #2 from joshivanhoe/feat/optionally-combine-func-grad

Provide option to compute objective value and gradient in the same function

Author: joshivanhoe

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10"]
+        python-version: ["3.9", "3.10", "3.11"]
 
     steps:
     - uses: actions/checkout@v3

.github/workflows/release.yml

@@ -0,0 +1,39 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.11'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

README.md

@@ -53,9 +53,9 @@ from halfspace import Model
 model = Model()
 
 # Define variables
-x = model.add_var(lb=0, ub=1)  # add a variable
-y = model.add_var(var_type="B")  # add a binary variable
-z = model.add_var_tensor(shape=(5,), lb=0, ub=1)  # add a tensor of variables
+x = model.add_var(lb=0, ub=1, name="x")  # add a variable
+y = model.add_var(var_type="B", name="y")  # add a binary variable
+z = model.add_var_tensor(shape=(5,), lb=0, ub=1, name="z")  # add a tensor of variables
 
 # Define objective terms (these are summed to create the objective)
 model.add_objective_term(var=x, func=lambda x: (x - 1) ** 2)  # add an objective term for one variable
@@ -77,7 +77,9 @@ model.start = [(x, 0), (y, 0)] + [(z[i], 0) for i in range(5)]
 
 # Solve model
 status = model.optimize()
-print(status, model.objective_value)
+print(model.objective_value) # get the best objective value
+print(model.var_value(x))  # get the value of a variable directly
+print(model.var_value("y"))  # get the value of a variable by name
 ```
 
 ## Troubleshooting
@@ -115,20 +117,9 @@ Clone the repository using `git`:
 git clone https://github.com/joshivanhoe/halfspace
 ````
 
-Create a fresh virtual environment using `venv`:
-
-```bash
-python3.10 -m venv halfspace
-```
-
-Alternatively, this can be done using `conda`:
-
-```bash
-conda create -n halfspace python=3.10
-```
-
-Note that currently Python 3.10 is recommended.
-Activate the environment and navigate to the cloned `halfspace` directory. Install a locally editable version of the package using `pip`:
+Create a fresh virtual environment using `venv` or `conda`.
+Activate the environment and navigate to the cloned `halfspace` directory.
+Install a locally editable version of the package using `pip`:
 
 ```bash
 pip install -e .

pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "halfspace-optimizer"
-version = "0.0.3"
+version = "0.1.0"
 authors = [
   { name="Joshua Ivanhoe", email="[email protected]" },
 ]
 description = "Cutting-plane solver for mixed-integer convex optimization problems"
 readme = "README.md"
 license = {file = "LICENSE"}
-requires-python = ">=3.9"
+requires-python = ">=3.9,<3.12"
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: MIT License",

src/halfspace/convex_term.py

@@ -4,9 +4,10 @@
 import numpy as np
 
 QueryPoint = dict[mip.Var, float]
-Input = Union[float, Iterable[float], np.ndarray]
 Var = Union[mip.Var, Iterable[mip.Var], mip.LinExprTensor]
+Input = Union[float, Iterable[float], np.ndarray]
 Func = Callable[[Input], float]
+FuncWithGrad = Callable[[Input], tuple[float, Union[float, np.ndarray]]]
 Grad = Callable[[Input], Union[float, np.ndarray]]
 
 
@@ -16,8 +17,8 @@ class ConvexTerm:
     def __init__(
         self,
         var: Var,
-        func: Func,
-        grad: Optional[Grad] = None,
+        func: Union[Func, FuncWithGrad],
+        grad: Optional[Union[Grad, bool]] = None,
         step_size: float = 1e-6,
         name: str = "",
     ):
@@ -27,14 +28,16 @@ def __init__(
             var: mip.Var or iterable of mip.Var or mip.LinExprTensor
                 The variable(s) included in the term. This can be provided in the form of a single  variable, an
                 iterable of multiple variables or a variable tensor.
-            func: callable mapping float(s) or array to float
+            func: callable
                 A function for computing the term's value. This function should except one argument for each
                 variable in `var`. If `var` is a variable tensor, then the function should accept a single array.
-            grad: callable mapping float(s) or array to float or array, default=`None`
+            grad: callable or bool, default=`None`
                 A function for computing the term's gradient. This function should except one argument for each
                 variable in `var`. If `var` is a variable tensor, then the function should accept a single array. If
-                `None`, then the gradient is approximated numerically.
-                using the central finite difference method.
+                `None`, then the gradient is approximated numerically using the central finite difference method. If
+                `grad` is instead a Boolean and is `True`, then `func` is assumed to return a tuple where the first
+                element is the function value and the second element is the gradient. This is useful when the gradient
+                is expensive to compute.
             step_size: float, default=`1e-6`
                 The step size used for numerical gradient approximation. If `grad` is provided, then this argument is
                 ignored.
@@ -49,7 +52,7 @@ def __init__(
 
     def __call__(
         self, query_point: QueryPoint, return_grad: bool = False
-    ) -> Union[float, tuple[float, np.ndarray]]:
+    ) -> Union[float, tuple[float, Union[float, np.ndarray]]]:
         """Evaluate the term and (optionally) its gradient.
 
         Args:
@@ -65,7 +68,9 @@ def __call__(
         """
         x = self._get_input(query_point=query_point)
         value = self._evaluate_func(x=x)
-        if return_grad:
+        if self.grad is True and not return_grad:
+            return value[0]
+        elif self.grad is not True and return_grad:
             return value, self._evaluate_grad(x=x)
         return value
 
@@ -95,8 +100,13 @@ def _get_input(self, query_point: QueryPoint) -> Input:
             return np.array([query_point[var] for var in self.var])
         return query_point[self.var]
 
-    def _evaluate_func(self, x: Input) -> float:
-        """Evaluate the function value."""
+    def _evaluate_func(
+        self, x: Input
+    ) -> Union[float, tuple[float, Union[float, np.ndarray]]]:
+        """Evaluate the function value.
+
+        If `grad=True`, then both the value of the function and it's gradient are returned.
+        """
         if isinstance(self.var, (mip.Var, mip.LinExprTensor)):
             return self.func(x)
         if isinstance(self.var, Iterable):
@@ -105,7 +115,7 @@ def _evaluate_func(self, x: Input) -> float:
 
     def _evaluate_grad(self, x: Input) -> Union[float, np.ndarray]:
         """Evaluate the gradient."""
-        if self.grad is None:
+        if not self.grad:
             return self._approximate_grad(x=x)
         if isinstance(self.var, (mip.Var, mip.LinExprTensor)):
             return self.grad(x)

src/halfspace/model.py

@@ -5,7 +5,7 @@
 import numpy as np
 import pandas as pd
 
-from .convex_term import ConvexTerm, Input, Var, Func, Grad
+from .convex_term import ConvexTerm, Input, Var, Func, FuncWithGrad, Grad
 from .utils import check_scalar, log_table_header, log_table_row
 
 Start = list[tuple[mip.Var, float]]
@@ -155,8 +155,8 @@ def add_linear_constr(self, constraint: mip.LinExpr, name: str = "") -> mip.Cons
     def add_nonlinear_constr(
         self,
         var: Var,
-        func: Func,
-        grad: Optional[Grad] = None,
+        func: Union[Func, FuncWithGrad],
+        grad: Optional[Union[Grad, bool]] = None,
         name: str = "",
     ) -> ConvexTerm:
         """Add a nonlinear constraint to the model.
@@ -165,14 +165,16 @@ def add_nonlinear_constr(
             var: mip.Var or iterable of mip.Var or mip.LinExprTensor
                 The variable(s) included in the term. This can be provided in the form of a single  variable, an
                 iterable of multiple variables or a variable tensor.
-            func: callable mapping float(s) or array to float
+            func: callable
                 A function for computing the term's value. This function should except one argument for each
                 variable in `var`. If `var` is a variable tensor, then the function should accept a single array.
-            grad: callable mapping float(s) or array to float or array, default=`None`
+            grad: callable or bool, default=`None`
                 A function for computing the term's gradient. This function should except one argument for each
                 variable in `var`. If `var` is a variable tensor, then the function should accept a single array. If
-                `None`, then the gradient is approximated numerically.
-                using the central finite difference method.
+                `None`, then the gradient is approximated numerically using the central finite difference method. If
+                `grad` is instead a Boolean and is `True`, then `func` is assumed to return a tuple where the first
+                element is the function value and the second element is the gradient. This is useful when the gradient
+                is expensive to compute.
             name: str, default=''
                 The name of the constraint.
 
@@ -192,8 +194,8 @@ def add_nonlinear_constr(
     def add_objective_term(
         self,
         var: Var,
-        func: Func,
-        grad: Optional[Grad] = None,
+        func: Union[Func, FuncWithGrad],
+        grad: Optional[Union[Grad, bool]] = None,
         name: str = "",
     ) -> ConvexTerm:
         """Add an objective term to the model.
@@ -202,14 +204,16 @@ def add_objective_term(
             var: mip.Var or iterable of mip.Var or mip.LinExprTensor
                 The variable(s) included in the term. This can be provided in the form of a single  variable, an
                 iterable of multiple variables or a variable tensor.
-            func: callable mapping float(s) or array to float
+            func: callable
                 A function for computing the term's value. This function should except one argument for each
                 variable in `var`. If `var` is a variable tensor, then the function should accept a single array.
-            grad: callable mapping float(s) or array to float or array, default=`None`
+            grad: callable or bool, default=`None`
                 A function for computing the term's gradient. This function should except one argument for each
                 variable in `var`. If `var` is a variable tensor, then the function should accept a single array. If
-                `None`, then the gradient is approximated numerically.
-                using the central finite difference method.
+                `None`, then the gradient is approximated numerically using the central finite difference method. If
+                `grad` is instead a Boolean and is `True`, then `func` is assumed to return a tuple where the first
+                element is the function value and the second element is the gradient. This is useful when the gradient
+                is expensive to compute.
             name: str, default=''
                 The name of the term.
 
@@ -365,7 +369,9 @@ def var_by_name(self, name: str) -> mip.Var:
         """Get a variable by name."""
         return self._model.var_by_name(name=name)
 
-    def var_value(self, x: Union[Input, str]) -> Union[float, np.ndarray]:
+    def var_value(
+        self, x: Union[mip.Var, mip.LinExprTensor, str]
+    ) -> Union[float, np.ndarray]:
         """Get the value one or more decision variables corresponding to the best solution.
 
         Args: