Merge pull request #411 from alphaville/feature/409-pybindings-error-handling

Handling errors via py bindings

Author: alphaville

Cargo.toml

@@ -42,7 +42,7 @@ homepage = "https://alphaville.github.io/optimization-engine/"
 repository = "https://github.com/alphaville/optimization-engine"
 
 # Version of this crate (SemVer)
-version = "0.12.0-alpha.1"
+version = "0.12.0-alpha.2"
 
 edition = "2018"
 

docs/example_navigation_py.mdx

@@ -154,9 +154,9 @@ sys.path.insert(1, './my_optimizers/navigation')
 import navigation
 
 solver = navigation.solver()
-result = solver.run(p=[-1.0, 2.0, 0.0],
-                    initial_guess=[1.0] * (nu*N))
-u_star = result.solution
+response = solver.run(p=[-1.0, 2.0, 0.0],
+                      initial_guess=[1.0] * (nu*N))
+u_star = response.get().solution
 
 
 # Plot solution
@@ -289,5 +289,5 @@ problem = og.builder.Problem(u, p, cost).with_constraints(bounds)
 Then, when we use the optimiser we to provide the vector `p`. For example, if `z0 = (-1, 2, 0)` and `xref = 1`, `yref = 0.6`, `thetaref = 0.05` we use
 
 ```python
-result = solver.run(p=[-1.0, 2.0, 0.0, 1.0, 0.6, 0.05])
+result = solver.run(p=[-1.0, 2.0, 0.0, 1.0, 0.6, 0.05]).get()
 ```

docs/python-bindings.md

@@ -70,6 +70,8 @@ so you will have to add it before you can import the optimizer.
 This can be done very easily:
 
 ```python
+import sys
+
 sys.path.insert(1, './my_optimizers/rosenbrock')
 import rosenbrock
 ```
@@ -78,22 +80,50 @@ Then you will be able to use it as follows:
 
 ```python
 solver = rosenbrock.solver()
-result = solver.run(p=[20., 1.])
+response = solver.run(p=[20., 1.])
+if not response.is_ok():
+    raise RuntimeError(response.get().message)
+
+result = response.get()
 u_star = result.solution
 ```
 
 In the first line, `solver = rosenbrock.solver()`, we obtain an instance of 
 `Solver`, which can be used to solve parametric optimization problems.
-In the second line, `result = solver.run(p=[20., 1.])`, we call the solver
+In the second line, `response = solver.run(p=[20., 1.])`, we call the solver
 with parameter $p=(20, 1)$. Method `run` accepts another three optional
 arguments, namely:
 
 - `initial_guess` (can be either a list or a numpy array),
 - `initial_lagrange_multipliers`, and 
 - `initial_penalty`
 
-The solver returns an object of type `OptimizerSolution` with the following 
-properties:
+The solver returns an object of type `SolverResponse`, similar to the TCP
+interface. First call `response.is_ok()` to determine whether the call
+succeeded, then call `response.get()` to obtain either a `SolverStatus`
+object or a `SolverError`. This mirrors the Python TCP interface, but without
+the socket transport layer.
+
+```python
+response = solver.run(p=[20., 1.])
+if response.is_ok():
+    result = response.get()
+    u_star = result.solution
+else:
+    error = response.get()
+    print(error.code, error.message)
+```
+
+The returned objects also implement `__repr__`, which makes them convenient to
+inspect in a Python REPL or notebook:
+
+```python
+response = solver.run(p=[20., 1.])
+print(response)
+print(response.get())
+```
+
+The `SolverStatus` object exposes the following properties:
 
 
 | Property                 | Explanation                                 |
@@ -112,6 +142,25 @@ properties:
 
 These are the same properties as those of `opengen.tcp.SolverStatus`.
 
+For backward compatibility, the generated module also exposes
+`OptimizerSolution` as an alias of `SolverStatus`.
+
+If the call fails, `response.get()` returns a `SolverError` with:
+
+| Property  | Explanation |
+|-----------|-------------|
+| `code`    | Error code, aligned with the TCP interface |
+| `message` | Detailed error message |
+
+The most common error codes are:
+
+| Code | Meaning |
+|------|---------|
+| `1600` | Initial guess has incompatible dimensions |
+| `1700` | Wrong dimension of initial Lagrange multipliers |
+| `2000` | Problem solution failed; the message includes the solver-side reason |
+| `3003` | Wrong number of parameters |
+
 
 ## Importing optimizer with variable name
 
@@ -122,6 +171,9 @@ The limitation of this syntax is that it makes it difficult to change the name o
 A better syntax would be:
 
 ```python
+import os
+import sys
+
 optimizers_dir = "my_optimizers"
 optimizer_name = "rosenbrock"
 sys.path.insert(1, os.path.join(optimizers_dir, optimizer_name))

open-codegen/CHANGELOG.md

@@ -19,6 +19,8 @@ Note: This is the Changelog file of `opengen` - the Python interface of OpEn
 ### Changed
 
 - Extended `RosConfiguration` so it can be used for both ROS and ROS2 package generation
+- Breaking change: the direct interface (Python bindings) now has an API which mirrors that of the TCP interface: the method `solve` returns either a solution or an error object. Website documentation is updated. New unit tests are implemented. Note that `solver.run()` does not return the solution object directly, but rather works in the same way as the TCP interface: it returns a response object (instance of `SolverResponse`), on which the method `.get()` returns either a `SolverStatus` or `SolverError`.
+- Added helpful `__repr__` methods to generated Python binding response/status/error objects, TCP solver response/error objects, and `GeneratedOptimizer` for easier inspection and debugging
 - Updated generated TCP server and C interface templates to work with the richer Rust solver error model and expose better failure information to clients
 
 

open-codegen/VERSION

@@ -1 +1 @@
-0.11.0a1
+0.11.0a2

open-codegen/main.py

@@ -44,23 +44,21 @@ def get_open_local_absolute_path():
                                           meta,
                                           build_config,
                                           solver_cfg)
-builder.build()
+# builder.build()
 
 sys.path.insert(1, os.path.join(optimizers_dir, optimizer_name))
 rosenbrock = __import__(optimizer_name)
 
 solver = rosenbrock.solver()
-result = solver.run(p=[0.5, 8.5], initial_guess=[1, 2, 3, 4, 0])
-print(" ")
-print(f"solution = {result.solution}")
-print(f"time = {result.solve_time_ms} ms")
-print(f"penalty = {result.penalty}")
-print(f"infeasibility f1 = {result.f1_infeasibility}")
-print(f"infeasibility f2 = {result.f2_norm}")
-print(f"status = {result.exit_status}")
-print(f"inner = {result.num_inner_iterations}")
-print(f"outer = {result.num_outer_iterations}")
-print(f"cost = {result.cost}")
+response = solver.run(p=[0.5, 8.5], initial_guess=[1, 2, 3, 4, 0]) # SolverResponse
+
+if response.is_ok():    
+    result = response.get() # SolverStatus
+    print(type(result))
+else:    
+    error = response.get() # SolverError
+    print(type(error))
+
 
 # Preconditioned    Non-preconditioned
 # -------------------------------------

open-codegen/opengen/ocp/builder.py

@@ -113,6 +113,19 @@ def backend_kind(self):
         """Backend kind used by this optimizer wrapper."""
         return self.__backend_kind
 
+    def __repr__(self):
+        """Return a concise summary of the generated optimizer wrapper."""
+        return (
+            "GeneratedOptimizer("
+            f"optimizer_name={self.__optimizer_name!r}, "
+            f"backend_kind={self.__backend_kind!r}, "
+            f"shooting={self.__shooting.value!r}, "
+            f"nx={self.__nx}, "
+            f"nu={self.__nu}, "
+            f"horizon={self.__horizon}, "
+            f"target_dir={self.__target_dir!r})"
+        )
+
     def start(self):
         """Start the backend if it is a local TCP server.
 
@@ -229,6 +242,10 @@ def __casadi_version():
             return casadi_version
         return GeneratedOptimizer.__safe_package_version("casadi")
 
+    @staticmethod
+    def __format_backend_error(error):
+        return getattr(error, "message", str(error))
+
     def save(self, json_path=None):
         """Save a manifest that can later recreate this optimizer.
 
@@ -327,8 +344,10 @@ def solve(
         :param initial_penalty: optional initial penalty parameter
         :param parameter_values: named parameter values
         :return: :class:`OcpSolution`
+        :raises ValueError: if required named parameters are missing or have
+            incompatible dimensions
         :raises RuntimeError: if the backend is unavailable or the low-level
-            solve call fails
+            solve call fails; backend-specific error messages are propagated
         """
         packed_parameters = self.__pack_parameters(parameter_values)
 
@@ -341,6 +360,10 @@ def solve(
             )
             if raw is None:
                 raise RuntimeError("solver failed")
+            if hasattr(raw, "is_ok") and hasattr(raw, "get"):
+                if not raw.is_ok():
+                    raise RuntimeError(self.__format_backend_error(raw.get()))
+                raw = raw.get()
         elif self.__backend_kind == "tcp":
             self.start()
             response = self.__backend.call(
@@ -350,7 +373,7 @@ def solve(
                 initial_penalty=initial_penalty,
             )
             if not response.is_ok():
-                raise RuntimeError(str(response.get()))
+                raise RuntimeError(self.__format_backend_error(response.get()))
             raw = response.get()
         else:
             raise RuntimeError("optimizer backend is not available")

open-codegen/opengen/tcp/solver_error.py

@@ -1,5 +1,5 @@
 class SolverError:
-    """Class for storing solver status in the event of an error."""
+    """Structured solver error returned by TCP or direct Python bindings."""
 
     def __init__(self, error):
         """Constructs instance of :class:`~opengen.tcp.solver_error.SolverError`
@@ -38,3 +38,7 @@ def message(self):
         :rtype: str
         """
         return self.__dict__["__message"]
+
+    def __repr__(self):
+        """Return a concise one-line representation of the error."""
+        return f"SolverError(code={self.code}, message={self.message!r})"

open-codegen/opengen/tcp/solver_response.py

@@ -3,7 +3,13 @@
 
 
 class SolverResponse:
-    """Stores a solver response of type SolverStatus or SolverError."""
+    """Stores a solver response of type SolverStatus or SolverError.
+
+    This wrapper is used by both the TCP interface and the direct Python
+    bindings generated by OpEn. Call :meth:`is_ok` first, then
+    :meth:`get` to obtain either a :class:`SolverStatus` or a
+    :class:`SolverError`.
+    """
 
     def __init__(self, d):
         """Constructs instance of :class:`~opengen.tcp.solver_response.SolverResponse`
@@ -38,4 +44,22 @@ def get(self):
         return self.__response
 
     def __getitem__(self, key):
+        """Proxy attribute access to the wrapped status or error object."""
         return getattr(self.__response, key)
+
+    def __repr__(self):
+        """Return a concise one-line summary suitable for debugging."""
+        if self.is_ok():
+            status = self.get()
+            return (
+                "SolverResponse(ok=True, "
+                f"exit_status={status.exit_status!r}, "
+                f"num_outer_iterations={status.num_outer_iterations}, "
+                f"num_inner_iterations={status.num_inner_iterations})"
+            )
+        error = self.get()
+        return (
+            "SolverResponse(ok=False, "
+            f"code={error.code}, "
+            f"message={error.message!r})"
+        )