Introduced an osqp.SolverStatus enum (#172)

* introduced an osqp.SolverStatus enum
* support for SolverError values from osqp; raising OSQPExceptions when we should

Author: vineetbansal

examples/basic_usage.py

@@ -17,8 +17,15 @@
     # Setup workspace and change alpha parameter
     prob.setup(P, q, A, l, u, alpha=1.0)
 
+    # Settings can be changed using .update_settings()
+    prob.update_settings(polishing=1)
+
     # Solve problem
-    res = prob.solve()
+    res = prob.solve(raise_error=True)
+
+    # Check solver status
+    # For all values, see https://osqp.org/docs/interfaces/status_values.html
+    assert res.info.status_val == osqp.SolverStatus.OSQP_SOLVED
 
     print('Status:', res.info.status)
     print('Objective value:', res.info.obj_val)

examples/exception_handling.py

@@ -0,0 +1,33 @@
+import osqp
+import numpy as np
+from scipy import sparse
+
+
+"""
+
+`osqp.OSQPException`s might be raised during `.setup()`, `.update_settings()`,
+or `.solve()`. This example demonstrates how to catch an `osqp.OSQPException`
+raised during `.setup()`, and how to compare it to a specific `osqp.SolverError`.
+
+Exceptions other than `osqp.OSQPException` might also be raised, but these
+are typically errors in using the wrapper, and are not raised by the underlying
+`osqp` library itself.
+
+"""
+
+if __name__ == '__main__':
+
+    P = sparse.triu([[2.0, 5.0], [5.0, 1.0]], format='csc')
+    q = np.array([3.0, 4.0])
+    A = sparse.csc_matrix([[-1.0, 0.0], [0.0, -1.0], [-1.0, 3.0], [2.0, 5.0], [3.0, 4]])
+    l = -np.inf * np.ones(A.shape[0])
+    u = np.array([0.0, 0.0, -15.0, 100.0, 80.0])
+
+    prob = osqp.OSQP()
+
+    try:
+        prob.setup(P, q, A, l, u)
+    except osqp.OSQPException as e:
+        # Our problem is non-convex, so we get a osqp.OSQPException
+        # during .setup()
+        assert e == osqp.SolverError.OSQP_NONCVX_ERROR

src/bindings.cpp.in

@@ -151,8 +151,7 @@ PyOSQPSolver::PyOSQPSolver(
 
     OSQPInt status = osqp_setup(&this->_solver, &this->_P.getcsc(), (OSQPFloat *)this->_q.data(), &this->_A.getcsc(), (OSQPFloat *)this->_l.data(), (OSQPFloat *)this->_u.data(), m, n, settings);
     if (status) {
-        std::string message = "Setup Error (Error Code " + std::to_string(status) + ")";
-        throw py::value_error(message);
+        throw py::value_error(std::to_string(status));
     }
 }
 
@@ -199,7 +198,12 @@ OSQPInt PyOSQPSolver::solve() {
 }
 
 OSQPInt PyOSQPSolver::update_settings(const OSQPSettings& new_settings) {
-    return osqp_update_settings(this->_solver, &new_settings);
+    OSQPInt status = osqp_update_settings(this->_solver, &new_settings);
+    if (status) {
+        throw py::value_error(std::to_string(status));
+    } else {
+        return status;
+    }
 }
 
 OSQPInt PyOSQPSolver::update_rho(OSQPFloat rho_new) {
@@ -353,6 +357,20 @@ PYBIND11_MODULE(@OSQP_EXT_MODULE_NAME@, m) {
     .value("OSQP_UNSOLVED", OSQP_UNSOLVED)
     .export_values();
 
+    // Solver Errors
+    py::enum_<osqp_error_type>(m, "osqp_error_type", py::module_local())
+    .value("OSQP_NO_ERROR", OSQP_NO_ERROR)
+    .value("OSQP_DATA_VALIDATION_ERROR", OSQP_DATA_VALIDATION_ERROR)
+    .value("OSQP_SETTINGS_VALIDATION_ERROR", OSQP_SETTINGS_VALIDATION_ERROR)
+    .value("OSQP_LINSYS_SOLVER_INIT_ERROR", OSQP_LINSYS_SOLVER_INIT_ERROR)
+    .value("OSQP_NONCVX_ERROR", OSQP_NONCVX_ERROR)
+    .value("OSQP_MEM_ALLOC_ERROR", OSQP_MEM_ALLOC_ERROR)
+    .value("OSQP_WORKSPACE_NOT_INIT_ERROR", OSQP_WORKSPACE_NOT_INIT_ERROR)
+    .value("OSQP_ALGEBRA_LOAD_ERROR", OSQP_ALGEBRA_LOAD_ERROR)
+    .value("OSQP_CODEGEN_DEFINES_ERROR", OSQP_CODEGEN_DEFINES_ERROR)
+    .value("OSQP_DATA_NOT_INITIALIZED", OSQP_DATA_NOT_INITIALIZED)
+    .value("OSQP_FUNC_NOT_IMPLEMENTED", OSQP_FUNC_NOT_IMPLEMENTED);
+
     // Preconditioner Type
     py::enum_<osqp_precond_type>(m, "osqp_precond_type", py::module_local())
     .value("OSQP_NO_PRECONDITIONER", OSQP_NO_PRECONDITIONER)

src/osqp/__init__.py

@@ -2,9 +2,12 @@
 #   and is not in version control.
 from osqp._version import version as __version__  # noqa: F401
 from osqp.interface import (  # noqa: F401
+    OSQPException,
     OSQP,
     constant,
     algebra_available,
     algebras_available,
     default_algebra,
+    SolverStatus,
+    SolverError,
 )

src/osqp/interface.py

@@ -1,6 +1,7 @@
 import sys
 import os
 from types import SimpleNamespace
+from enum import IntEnum
 import shutil
 import subprocess
 import warnings
@@ -49,10 +50,31 @@ def default_algebra():
     raise RuntimeError('No algebra backend available!')
 
 
-def constant(which, algebra):
+def default_algebra_module():
+    """
+    Get the default algebra module.
+    Note: importlib.import_module is cached so we pay almost no penalty
+      for repeated calls to this function.
+    """
+    return importlib.import_module(_ALGEBRA_MODULES[default_algebra()])
+
+
+def constant(which, algebra='builtin'):
+    """
+    Get a named constant from the extension module.
+    Since constants are typically consistent across osqp algebras,
+    we use the `builtin` algebra (always guaranteed to be available)
+    by default.
+    """
     m = importlib.import_module(_ALGEBRA_MODULES[algebra])
     _constant = getattr(m, which, None)
 
+    if which in m.osqp_status_type.__members__:
+        warnings.warn(
+            'Direct access to osqp status values will be deprecated. Please use the SolverStatus enum instead.',
+            PendingDeprecationWarning,
+        )
+
     # If the constant was exported directly as an atomic type in the extension, use it;
     # Otherwise it's an enum out of which we can obtain the raw value
     if isinstance(_constant, (int, float, str)):
@@ -67,7 +89,57 @@ def constant(which, algebra):
         raise RuntimeError(f'Unknown constant {which}')
 
 
+def construct_enum(name, binding_enum_name):
+    """
+    Dynamically construct an IntEnum from available enum members.
+    For all values, see https://osqp.org/docs/interfaces/status_values.html
+    """
+    m = default_algebra_module()
+    binding_enum = getattr(m, binding_enum_name)
+    return IntEnum(name, [(v.name, v.value) for v in binding_enum.__members__.values()])
+
+
+SolverStatus = construct_enum('SolverStatus', 'osqp_status_type')
+SolverError = construct_enum('SolverError', 'osqp_error_type')
+
+
+class OSQPException(Exception):
+    """
+    OSQPException is raised by the wrapper interface when it encounters an
+    exception by the underlying OSQP solver.
+    """
+
+    def __init__(self, error_code=None):
+        if error_code:
+            self.args = (error_code,)
+
+    def __eq__(self, error_code):
+        return len(self.args) > 0 and self.args[0] == error_code
+
+
 class OSQP:
+
+    """
+    For OSQP bindings (see bindings.cpp.in) that throw `ValueError`s
+    (through `throw py::value_error(...)`), we catch and re-raise them
+    as `OSQPException`s, with the correct int value as args[0].
+    """
+
+    @classmethod
+    def raises_error(cls, fn, *args, **kwargs):
+        try:
+            return_value = fn(*args, **kwargs)
+        except ValueError as e:
+            if e.args:
+                error_code = None
+                try:
+                    error_code = int(e.args[0])
+                except ValueError:
+                    pass
+            raise OSQPException(error_code)
+        else:
+            return return_value
+
     def __init__(self, *args, **kwargs):
         self.m = None
         self.n = None
@@ -253,7 +325,7 @@ def update_settings(self, **kwargs):
             raise ValueError(f'Unrecognized settings {list(kwargs.keys())}')
 
         if settings_changed and self._solver is not None:
-            self._solver.update_settings(self.settings)
+            self.raises_error(self._solver.update_settings, self.settings)
 
     def update(self, **kwargs):
         # TODO: sanity-check on types/dimensions
@@ -310,7 +382,8 @@ def setup(self, P, q, A, l, u, **settings):
         self.ext.osqp_set_default_settings(self.settings)
         self.update_settings(**settings)
 
-        self._solver = self.ext.OSQPSolver(
+        self._solver = self.raises_error(
+            self.ext.OSQPSolver,
             P,
             q,
             A,
@@ -327,16 +400,23 @@ def warm_start(self, x=None, y=None):
         # TODO: sanity checks on types/dimensions
         return self._solver.warm_start(x, y)
 
-    def solve(self, raise_error=False):
+    def solve(self, raise_error=None):
+        if raise_error is None:
+            warnings.warn(
+                'The default value of raise_error will change to True in the future.',
+                PendingDeprecationWarning,
+            )
+            raise_error = False
+
         self._solver.solve()
 
         info = self._solver.info
-        if info.status_val == self.constant('OSQP_NON_CVX'):
+        if info.status_val == SolverStatus.OSQP_NON_CVX:
             info.obj_val = np.nan
         # TODO: Handle primal/dual infeasibility
 
-        if info.status_val != self.constant('OSQP_SOLVED') and raise_error:
-            raise ValueError('Problem not solved!')
+        if info.status_val != SolverStatus.OSQP_SOLVED and raise_error:
+            raise OSQPException(info.status_val)
 
         # Create a Namespace of OSQPInfo keys and associated values
         _info = SimpleNamespace(**{k: getattr(info, k) for k in info.__class__.__dict__ if not k.startswith('__')})
@@ -445,7 +525,7 @@ def adjoint_derivative_compute(self, dx=None, dy=None):
                 'Problem has not been solved. ' 'You cannot take derivatives. ' 'Please call the solve function.'
             )
 
-        if results.info.status != 'solved':
+        if results.info.status_val != SolverStatus.OSQP_SOLVED:
             raise ValueError('Problem has not been solved to optimality. ' 'You cannot take derivatives')
 
         if dy is None:
@@ -467,7 +547,7 @@ def adjoint_derivative_get_mat(self, as_dense=True, dP_as_triu=True):
                 'Problem has not been solved. ' 'You cannot take derivatives. ' 'Please call the solve function.'
             )
 
-        if results.info.status != 'solved':
+        if results.info.status_val != SolverStatus.OSQP_SOLVED:
             raise ValueError('Problem has not been solved to optimality. ' 'You cannot take derivatives')
 
         P, _ = self._derivative_cache['P'], self._derivative_cache['q']
@@ -501,7 +581,7 @@ def adjoint_derivative_get_vec(self):
                 'Problem has not been solved. ' 'You cannot take derivatives. ' 'Please call the solve function.'
             )
 
-        if results.info.status != 'solved':
+        if results.info.status_val != SolverStatus.OSQP_SOLVED:
             raise ValueError('Problem has not been solved to optimality. ' 'You cannot take derivatives')
 
         dq = np.empty(self.n).astype(self._dtype)

src/osqp/nn/torch.py

@@ -122,9 +122,7 @@ def _get_update_flag(n_batch: int) -> bool:
                 """
                 num_solvers = len(solvers)
                 if num_solvers not in (0, n_batch):
-                    raise RuntimeError(
-                        f'Invalid number of solvers: expected 0 or {n_batch},' f' but got {num_solvers}.'
-                    )
+                    raise RuntimeError(f'Invalid number of solvers: expected 0 or {n_batch}, but got {num_solvers}.')
                 return num_solvers == n_batch
 
             def _inner_solve(i, update_flag, q, l, u, P_val, P_idx, A_val, A_idx, solver_type, eps_abs, eps_rel):
@@ -157,8 +155,8 @@ def _inner_solve(i, update_flag, q, l, u, P_val, P_idx, A_val, A_idx, solver_typ
                         eps_rel=eps_rel,
                     )
                 result = solver.solve()
-                status = result.info.status
-                if status != 'solved':
+                status = result.info.status_val
+                if status != osqp.SolverStatus.OSQP_SOLVED:
                     # TODO: We can replace this with something calmer and
                     # add some more options around potentially ignoring this.
                     raise RuntimeError(f'Unable to solve QP, status: {status}')