polyblocks 0.1.0__tar.gz → 0.2.0__tar.gz

{polyblocks-0.1.0 → polyblocks-0.2.0}/PKG-INFO

@@ -1,13 +1,14 @@
 Metadata-Version: 2.4
 Name: polyblocks
-Version: 0.1.0
+Version: 0.2.0
 Summary: Solvers for global monotonic optimisation problems
 Author: Ahmed Rashwan
 Author-email: Ahmed Rashwan <ar3009@bath.ac.uk>
 License-Expression: MIT
 Requires-Dist: numba>=0.65.1
+Requires-Dist: numerize>=0.12
 Requires-Dist: numpy>=2.2.6
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/RashwanA/polyblocks
 Description-Content-Type: text/markdown
 
@@ -19,9 +20,9 @@ This package provides a set of solvers for monotonic optimisation problems, whic
 $$
 \begin{aligned}
 \max_{x \in \mathbb{R}^n} \quad & f(x) \\
-\text{s.t.} \ \quad & x_l \le x \le x_u \\
-& g(x) \le 0 \\
-& h(x) \ge 0
+\text{s.t.} \ \quad & x_l \le x \le x_u, \\
+& g(x) \le 0, \\
+& h(x) \ge 0,
 \end{aligned}
 $$
 
@@ -29,7 +30,7 @@ where $f$, $g$, and $h$ are non-decreasing in each coordinate.
 This covers a broad class of non-convex problems, including polynomial programming along with many radio resource allocation problems in communications.
 
 Solvers are built around the **Polyblock Outer-approximation (POA)** algorithm: a branch-and-bound algorithm which iteratively refines a rectangular outer-approximation of the solution space.
-Full details are available in the accompanying paper: **LINK**
+Full details are available in the [accompanying paper](https://arxiv.org/pdf/2608.13694).
 
 ## Installation
 
@@ -49,7 +50,7 @@ pip install .
 
 The package includes three built-in solvers: `BasePOA`, `BalancedPOA`, and `TreePOA`.
 Of these `TreePOA` typically has the best empirical performance as it uses an efficient tree-based representation of the solution space.
-All solvers implement the common `ABPolyblock` interface, which exposes a set of subroutines used by the POA algorithm.
+All solvers implement the common `ABPolyblock` interface, which exposes a set of subroutines used by the POA algorithm. See the [interface documentation](https://rashwana.github.io/polyblocks/interface/) for details.
 Users may also define custom solvers by implementing this interface.
 
 ## Usage
@@ -77,6 +78,7 @@ sol = TreePOA.solve(
     x_u=(1., 1.),
 )
 
+# solution: x=0.6, y=0.8
 print(f"status={sol.status}, obj={sol.obj:.2f}, x={sol.x.round(2)}")
 ```
 
@@ -85,9 +87,9 @@ Geometric programming example:
 ```python
 from polyblocks import TreePOA
 
-# maximise x y z
-# subject to x (y + z) <= 4,
-#            y z <= 4,
+# maximise x*y*z
+# subject to x*(y + z) <= 4,
+#            y*z <= 4,
 #            x, y, z ∈ [0, 4]
 
 def obj(x):
@@ -98,14 +100,14 @@ def ub_oracle(x):
     cons2 = x[:,1:].prod(1) <= 4.
     return cons1 * cons2
 
+# solution: x=1, y=2, z=2
 sol = TreePOA.solve(
     obj=obj,
     ub_oracle=ub_oracle,
     x_l=(0., 0., 0.),
     x_u=4.,             # bounds are broadcast
-    verbose_gap=10,     # print progress every 10 iterations
+    verbose_gap=50,     # print progress every 50 iterations
 )
-print(f"status={sol.status}, obj={sol.obj:.2f}, x={sol.x.round(2)}")
 ```
 
 Objectives and oracles are expected to accept batched inputs of shape `(num_points, dim)`.

{polyblocks-0.1.0 → polyblocks-0.2.0}/README.md

@@ -6,9 +6,9 @@ This package provides a set of solvers for monotonic optimisation problems, whic
 $$
 \begin{aligned}
 \max_{x \in \mathbb{R}^n} \quad & f(x) \\
-\text{s.t.} \ \quad & x_l \le x \le x_u \\
-& g(x) \le 0 \\
-& h(x) \ge 0
+\text{s.t.} \ \quad & x_l \le x \le x_u, \\
+& g(x) \le 0, \\
+& h(x) \ge 0,
 \end{aligned}
 $$
 
@@ -16,7 +16,7 @@ where $f$, $g$, and $h$ are non-decreasing in each coordinate.
 This covers a broad class of non-convex problems, including polynomial programming along with many radio resource allocation problems in communications.
 
 Solvers are built around the **Polyblock Outer-approximation (POA)** algorithm: a branch-and-bound algorithm which iteratively refines a rectangular outer-approximation of the solution space.
-Full details are available in the accompanying paper: **LINK**
+Full details are available in the [accompanying paper](https://arxiv.org/pdf/2608.13694).
 
 ## Installation
 
@@ -36,7 +36,7 @@ pip install .
 
 The package includes three built-in solvers: `BasePOA`, `BalancedPOA`, and `TreePOA`.
 Of these `TreePOA` typically has the best empirical performance as it uses an efficient tree-based representation of the solution space.
-All solvers implement the common `ABPolyblock` interface, which exposes a set of subroutines used by the POA algorithm.
+All solvers implement the common `ABPolyblock` interface, which exposes a set of subroutines used by the POA algorithm. See the [interface documentation](https://rashwana.github.io/polyblocks/interface/) for details.
 Users may also define custom solvers by implementing this interface.
 
 ## Usage
@@ -64,6 +64,7 @@ sol = TreePOA.solve(
     x_u=(1., 1.),
 )
 
+# solution: x=0.6, y=0.8
 print(f"status={sol.status}, obj={sol.obj:.2f}, x={sol.x.round(2)}")
 ```
 
@@ -72,9 +73,9 @@ Geometric programming example:
 ```python
 from polyblocks import TreePOA
 
-# maximise x y z
-# subject to x (y + z) <= 4,
-#            y z <= 4,
+# maximise x*y*z
+# subject to x*(y + z) <= 4,
+#            y*z <= 4,
 #            x, y, z ∈ [0, 4]
 
 def obj(x):
@@ -85,14 +86,14 @@ def ub_oracle(x):
     cons2 = x[:,1:].prod(1) <= 4.
     return cons1 * cons2
 
+# solution: x=1, y=2, z=2
 sol = TreePOA.solve(
     obj=obj,
     ub_oracle=ub_oracle,
     x_l=(0., 0., 0.),
     x_u=4.,             # bounds are broadcast
-    verbose_gap=10,     # print progress every 10 iterations
+    verbose_gap=50,     # print progress every 50 iterations
 )
-print(f"status={sol.status}, obj={sol.obj:.2f}, x={sol.x.round(2)}")
 ```
 
 Objectives and oracles are expected to accept batched inputs of shape `(num_points, dim)`.

{polyblocks-0.1.0 → polyblocks-0.2.0}/pyproject.toml

@@ -1,11 +1,12 @@
 [project]
 name = "polyblocks"
-version = "0.1.0"
+version = "0.2.0"
 description = "Solvers for global monotonic optimisation problems"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dependencies = [
     "numba>=0.65.1",
+    "numerize>=0.12",
     "numpy>=2.2.6",
 ]
 license = "MIT"

{polyblocks-0.1.0 → polyblocks-0.2.0}/pyproject.toml.orig

@@ -1,14 +1,15 @@
 [project]
 name = "polyblocks"
-version = "0.1.0"
+version = "0.2.0"
 description = "Solvers for global monotonic optimisation problems"
 readme = "README.md"
 authors = [
     { name = "Ahmed Rashwan", email = "ar3009@bath.ac.uk" }
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dependencies = [
     "numba>=0.65.1",
+    "numerize>=0.12",
     "numpy>=2.2.6",
 ]
 license = "MIT"

{polyblocks-0.1.0 → polyblocks-0.2.0}/src/polyblocks/__init__.py

@@ -1,5 +1,5 @@
-from .abstract import ABPolyblock, Solution
+from .abstract import ABPolyblock, Solution, Status
 from .naive import BalancedPOA, BasePOA
 from .tree import TreePOA
 
-__all__ = ["ABPolyblock", "BalancedPOA", "BasePOA", "Solution", "TreePOA"]
+__all__ = ["ABPolyblock", "BalancedPOA", "BasePOA", "Solution", "Status", "TreePOA"]

{polyblocks-0.1.0 → polyblocks-0.2.0}/src/polyblocks/abstract.py

@@ -1,6 +1,7 @@
 from abc import ABC, abstractmethod
 from collections.abc import Callable
 from dataclasses import dataclass
+from enum import StrEnum
 from functools import partial
 from time import perf_counter
 
@@ -10,6 +11,27 @@ from numpy.typing import ArrayLike, NDArray
 from .utils import monotone_proj, print_row, tighten
 
 
+class Status(StrEnum):
+    """
+    Termination status of `ABPolyblock.solve`.
+
+    Attributes:
+        MAX_ITER: Iteration limit reached before convergence.
+        INFEASIBLE_X_L: Problem infeasible since `x_l` not in normal set.
+        OPTIMAL: Solver converged and certified the incumbent as optimal.
+        INFEASIBLE_RELAXATION: No feasible point found under the current relaxation.
+        MAX_POLYBLOCK_SIZE: Polyblock size exceeded `POLYBLOCK_LIMIT`.
+        TIME_LIMIT: Time limit exceeded before convergence.
+    """
+
+    MAX_ITER = "Maximum iterations reached."
+    INFEASIBLE_X_L = "Problem Infeasible since `x_l` not in normal set."
+    OPTIMAL = "Optimal!"
+    INFEASIBLE_RELAXATION = "Infeasible under current relaxation."
+    MAX_POLYBLOCK_SIZE = "Maximum polyblock size exceeded."
+    TIME_LIMIT = "Time limit exceeded."
+
+
 @dataclass
 class Solution:
     """
@@ -20,16 +42,18 @@ class Solution:
         obj: Optimal (or best attained) objective value.
         best_bound: Best upper-bound on the optimal objective.
         success: Whether the solver returned an optimal solution.
-        status: Description of the termination status.
+        status: Termination status.
         n_iter: Number of iterations executed.
+        runtime: Total runtime of the solver.
     """
 
     x: NDArray | None = None
     obj: float = -np.inf
     best_bound: float = np.inf
     success: bool = False
-    status: str = "Maximum iterations reached"
+    status: Status = Status.MAX_ITER
     n_iter: int = 0
+    runtime: float = 0.0
 
 
 class ABPolyblock(ABC):
@@ -214,7 +238,7 @@ class ABPolyblock(ABC):
             raise ValueError("`x_u` must be no smaller than `x_l` element-wise.")
         elif not ub_oracle(x_l[None]):
             sol.success = True
-            sol.status = "Problem Infeasible since `x_l` not in normal set."
+            sol.status = Status.INFEASIBLE_X_L
             if verbose:
                 print(sol.status)
             return sol
@@ -266,15 +290,15 @@ class ABPolyblock(ABC):
             if empty:
                 sol.success = True
                 if sol.x is not None:
-                    sol.status = "Optimal!"
+                    sol.status = Status.OPTIMAL
                 else:
-                    sol.status = "Infeasible under current relaxation."
+                    sol.status = Status.INFEASIBLE_RELAXATION
                 break
             elif polyblock.size > cls.POLYBLOCK_LIMIT:
-                sol.status = "Maximum polyblock size exceeded."
+                sol.status = Status.MAX_POLYBLOCK_SIZE
                 break
             elif perf_counter() - start_time > time_limit:
-                sol.status = "Time limit exceeded."
+                sol.status = Status.TIME_LIMIT
                 break
 
             if verbose and i % verbose_gap == 0:
@@ -290,11 +314,13 @@ class ABPolyblock(ABC):
 
         sol.n_iter = i + 1
         sol.best_bound = polyblock.best_bound
+        sol.runtime = perf_counter() - start_time
         if verbose:
             print(
                 f"{sol.status}, "
-                f"itr: {sol.n_iter}, "
-                f"Best solution: {sol.x}, "
+                f"Iter: {sol.n_iter}, "
+                f"Runtime: {sol.runtime:.2f} s, "
+                f"Best solution: {sol.x.round(2)}, "
                 f"Obj: {sol.obj:.3f}"
             )
 

{polyblocks-0.1.0 → polyblocks-0.2.0}/src/polyblocks/utils.py

@@ -1,6 +1,7 @@
 from collections.abc import Callable
 
 import numpy as np
+from numerize.numerize import numerize
 from numpy.linalg import norm
 from numpy.typing import NDArray
 
@@ -11,7 +12,7 @@ def monotone_proj(
     oracle: Callable,
     eps=1e-4,
     delta=0.0,
-):
+) -> NDArray:
     """
     Perform a vectorised bisection search to compute monotone projections onto the `delta`-eroded normal set corresponding to the given oracle.
 
@@ -48,7 +49,7 @@ def monotone_proj(
     return lb * diff + vertices
 
 
-def tighten(root: NDArray, reduced: NDArray, oracle: Callable, eps=1e-4):
+def tighten(root: NDArray, reduced: NDArray, oracle: Callable, eps=1e-4) -> NDArray:
     """Tighten the box anchored at `root` using a monotone oracle."""
 
     reduced = reduced.copy()
@@ -90,7 +91,7 @@ def print_row(*, header: bool = True, **columns):
     cells = []
     for name, value in columns.items():
         if isinstance(value, int):
-            value = f"{value:#.2g}"
+            value = f"{numerize(value, decimals=2)}"
         elif isinstance(value, float):
             value = f"{value:#.4g}"
         else: