handling errors via py bindings

alphaville · alphaville · commit 355f03526408 · 2026-03-27T21:59:46.000Z
- update unit tests
- and website docs
- and benchmarks
diff --git a/docs/example_navigation_py.mdx b/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()
 ```
diff --git a/docs/python-bindings.md b/docs/python-bindings.md
@@ -78,22 +78,37 @@ 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.])
+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`.
+
+```python
+response = solver.run(p=[20., 1.])
+if response.is_ok():
+    status = response.get()
+    u_star = status.solution
+else:
+    error = response.get()
+    print(error.code, error.message)
+```
+
+The `SolverStatus` object exposes the following properties:
 
 
 | Property                 | Explanation                                 |
@@ -112,6 +127,13 @@ properties:
 
 These are the same properties as those of `opengen.tcp.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 |
+
 
 ## Importing optimizer with variable name
 
diff --git a/open-codegen/opengen/templates/python/python_bindings.rs b/open-codegen/opengen/templates/python/python_bindings.rs
@@ -11,8 +11,11 @@ use {{ meta.optimizer_name }}::*;
 #[pymodule]
 fn {{ meta.optimizer_name }}(_py: Python, m: &PyModule) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(solver, m)?)?;
-    m.add_class::<OptimizerSolution>()?;
+    m.add_class::<SolverStatus>()?;
+    m.add_class::<SolverError>()?;
+    m.add_class::<SolverResponse>()?;
     m.add_class::<Solver>()?;
+    m.add("OptimizerSolution", m.getattr("SolverStatus")?)?;
     Ok(())
 }
 
@@ -22,9 +25,53 @@ fn solver() -> PyResult<Solver> {
     Ok(Solver { cache })
 }
 
+#[derive(Clone)]
+struct SolverStatusData {
+    exit_status: String,
+    num_outer_iterations: usize,
+    num_inner_iterations: usize,
+    last_problem_norm_fpr: f64,
+    f1_infeasibility: f64,
+    f2_norm: f64,
+    solve_time_ms: f64,
+    penalty: f64,
+    solution: Vec<f64>,
+    lagrange_multipliers: Vec<f64>,
+    cost: f64,
+}
+
+impl SolverStatusData {
+    fn from_status(status: AlmOptimizerStatus, solution: &[f64]) -> Self {
+        SolverStatusData {
+            exit_status: format!("{:?}", status.exit_status()),
+            num_outer_iterations: status.num_outer_iterations(),
+            num_inner_iterations: status.num_inner_iterations(),
+            last_problem_norm_fpr: status.last_problem_norm_fpr(),
+            f1_infeasibility: status.delta_y_norm_over_c(),
+            f2_norm: status.f2_norm(),
+            penalty: status.penalty(),
+            lagrange_multipliers: status.lagrange_multipliers().clone().unwrap_or_default(),
+            solve_time_ms: (status.solve_time().as_nanos() as f64) / 1e6,
+            solution: solution.to_vec(),
+            cost: status.cost(),
+        }
+    }
+}
+
+#[derive(Clone)]
+struct SolverErrorData {
+    code: i32,
+    message: String,
+}
+
+enum SolverResponsePayload {
+    Ok(SolverStatusData),
+    Err(SolverErrorData),
+}
+
 /// Solution and solution status of optimizer
 #[pyclass]
-struct OptimizerSolution {
+struct SolverStatus {
     #[pyo3(get)]
     exit_status: String,
     #[pyo3(get)]
@@ -49,6 +96,64 @@ struct OptimizerSolution {
     cost: f64,
 }
 
+impl From<SolverStatusData> for SolverStatus {
+    fn from(status: SolverStatusData) -> Self {
+        SolverStatus {
+            exit_status: status.exit_status,
+            num_outer_iterations: status.num_outer_iterations,
+            num_inner_iterations: status.num_inner_iterations,
+            last_problem_norm_fpr: status.last_problem_norm_fpr,
+            f1_infeasibility: status.f1_infeasibility,
+            f2_norm: status.f2_norm,
+            solve_time_ms: status.solve_time_ms,
+            penalty: status.penalty,
+            solution: status.solution,
+            lagrange_multipliers: status.lagrange_multipliers,
+            cost: status.cost,
+        }
+    }
+}
+
+#[pyclass]
+struct SolverError {
+    #[pyo3(get)]
+    code: i32,
+    #[pyo3(get)]
+    message: String,
+}
+
+impl From<SolverErrorData> for SolverError {
+    fn from(error: SolverErrorData) -> Self {
+        SolverError {
+            code: error.code,
+            message: error.message,
+        }
+    }
+}
+
+#[pyclass]
+struct SolverResponse {
+    payload: SolverResponsePayload,
+}
+
+#[pymethods]
+impl SolverResponse {
+    fn is_ok(&self) -> bool {
+        matches!(self.payload, SolverResponsePayload::Ok(_))
+    }
+
+    fn get(&self, py: Python<'_>) -> PyResult<PyObject> {
+        match &self.payload {
+            SolverResponsePayload::Ok(status) => {
+                Ok(Py::new(py, SolverStatus::from(status.clone()))?.into_py(py))
+            }
+            SolverResponsePayload::Err(error) => {
+                Ok(Py::new(py, SolverError::from(error.clone()))?.into_py(py))
+            }
+        }
+    }
+}
+
 #[pyclass]
 struct Solver {
     cache: AlmCache,
@@ -65,20 +170,24 @@ impl Solver {
         initial_guess: Option<Vec<f64>>,
         initial_lagrange_multipliers: Option<Vec<f64>>,
         initial_penalty: Option<f64>,
-    ) -> PyResult<Option<OptimizerSolution>> {
+    ) -> PyResult<SolverResponse> {
         let mut u = [0.0; {{meta.optimizer_name|upper}}_NUM_DECISION_VARIABLES];
 
         // ----------------------------------------------------
         // Set initial value
         // ----------------------------------------------------
         if let Some(u0) = initial_guess {
             if u0.len() != {{meta.optimizer_name|upper}}_NUM_DECISION_VARIABLES {
-                println!(
-                    "1600 -> Initial guess has incompatible dimensions: {} != {}",
-                    u0.len(),
-                    {{meta.optimizer_name|upper}}_NUM_DECISION_VARIABLES
-                );
-                return Ok(None);
+                return Ok(SolverResponse {
+                    payload: SolverResponsePayload::Err(SolverErrorData {
+                        code: 1600,
+                        message: format!(
+                            "initial guess has incompatible dimensions: provided {}, expected {}",
+                            u0.len(),
+                            {{meta.optimizer_name|upper}}_NUM_DECISION_VARIABLES
+                        ),
+                    }),
+                });
             }
             u.copy_from_slice(&u0);
         }
@@ -88,25 +197,33 @@ impl Solver {
         // ----------------------------------------------------
         if let Some(y0) = &initial_lagrange_multipliers {
             if y0.len() != {{meta.optimizer_name|upper}}_N1 {
-                println!(
-                    "1700 -> wrong dimension of Langrange multipliers: {} != {}",
-                    y0.len(),
-                    {{meta.optimizer_name|upper}}_N1
-                );
-                return Ok(None);
+                return Ok(SolverResponse {
+                    payload: SolverResponsePayload::Err(SolverErrorData {
+                        code: 1700,
+                        message: format!(
+                            "wrong dimension of Langrange multipliers: provided {}, expected {}",
+                            y0.len(),
+                            {{meta.optimizer_name|upper}}_N1
+                        ),
+                    }),
+                });
             }
         }
 
         // ----------------------------------------------------
         // Check parameter
         // ----------------------------------------------------
         if p.len() != {{meta.optimizer_name|upper}}_NUM_PARAMETERS {
-            println!(
-                "3003 -> wrong number of parameters: {} != {}",
-                p.len(),
-                {{meta.optimizer_name|upper}}_NUM_PARAMETERS
-            );
-            return Ok(None);
+            return Ok(SolverResponse {
+                payload: SolverResponsePayload::Err(SolverErrorData {
+                    code: 3003,
+                    message: format!(
+                        "wrong number of parameters: provided {}, expected {}",
+                        p.len(),
+                        {{meta.optimizer_name|upper}}_NUM_PARAMETERS
+                    ),
+                }),
+            });
         }
 
         // ----------------------------------------------------
@@ -121,23 +238,15 @@ impl Solver {
         );
 
         match solver_status {
-            Ok(status) => Ok(Some(OptimizerSolution {
-                exit_status: format!("{:?}", status.exit_status()),
-                num_outer_iterations: status.num_outer_iterations(),
-                num_inner_iterations: status.num_inner_iterations(),
-                last_problem_norm_fpr: status.last_problem_norm_fpr(),
-                f1_infeasibility: status.delta_y_norm_over_c(),
-                f2_norm: status.f2_norm(),
-                penalty: status.penalty(),
-                lagrange_multipliers: status.lagrange_multipliers().clone().unwrap_or_default(),
-                solve_time_ms: (status.solve_time().as_nanos() as f64) / 1e6,
-                solution: u.to_vec(),
-                cost: status.cost(),
-            })),
-            Err(_) => {
-                println!("2000 -> Problem solution failed (solver error)");
-                Ok(None)
-            }
+            Ok(status) => Ok(SolverResponse {
+                payload: SolverResponsePayload::Ok(SolverStatusData::from_status(status, &u)),
+            }),
+            Err(err) => Ok(SolverResponse {
+                payload: SolverResponsePayload::Err(SolverErrorData {
+                    code: 2000,
+                    message: format!("problem solution failed: {}", err),
+                }),
+            }),
         }
     }
 }
diff --git a/open-codegen/test/benchmark_open.py b/open-codegen/test/benchmark_open.py
@@ -39,14 +39,16 @@ def t_benchmark1(solver):
     a = np.random.uniform(0.5, 2)
     b = np.random.uniform(0.5, 15)
     c = np.random.uniform(0.9, 3)
-    _sol = solver.run([a, b, c])
+    response = solver.run([a, b, c])
+    _sol = response.get()
 
 
 def t_benchmark2(solver):
     x0 = np.random.uniform(-3.5, -2)
     y0 = np.random.uniform(-2.5, 2.5)
     # th0 = np.random.uniform(-0.3, 0.3)
-    _sol = solver.run([x0, y0, 0])
+    response = solver.run([x0, y0, 0])
+    _sol = response.get()
 
 
 def test_benchmark1(benchmark):
diff --git a/open-codegen/test/test.py b/open-codegen/test/test.py
