API: Model.getSolVal supports MatrixExpr (#1183)

* Support MatrixExpr in solution retrieval

Allow MatrixExpr to be queried from Solution and Model methods: add MatrixExpr to type annotations for Solution.__getitem__ and Model.getSolVal, update return types to include np.ndarray, and improve the runtime type check in __getitem__ with a clear TypeError. Simplify best-solution value retrieval by delegating to Solution.__getitem__ (removing the manual loop over MatrixExpr), and update docstrings to reflect the new accepted types and return values.

* Simplify stage check and inline best sol pointer

Refactor model method to directly check SCIP stage (raise a Warning when in INIT or FREE) instead of using an intermediate boolean, and inline the SCIP_SOL* variable declaration when obtaining the best solution. Improves readability and removes an unnecessary temporary variable without changing behavior.

* Add return type annotation to getVal

Annotate Model.getVal in src/pyscipopt/scip.pxi with an explicit return type Union[float, np.ndarray] and remove an extra space in the parameter list. This clarifies that getVal may return either a scalar float or a NumPy array and improves static typing and IDE/type-checker support.

* Add test for Model.getSolVal and getVal

Add test_getSolVal to cover issue #1136. The test creates a Model with a binary scalar and a binary matrix variable, sets an objective, optimizes and obtains the best solution. It asserts that getSolVal(sol, var) matches getVal(var) for both scalar and matrix variables (values expected to be zeros), and verifies that passing a non-variable to getVal or getSolVal raises TypeError.

* Changelog: Model.getSolVal supports MatrixExpr

Add a CHANGELOG entry noting that Model.getSolVal now accepts MatrixExpr. This documents the new support for MatrixExpr inputs in the Model.getSolVal API.

* Use numpy array comparisons in tests

Replace usages of built-in all(...) with np.array_equal(...) to correctly compare array-like results from m.getSolVal and m.getVal. Import numpy as np and construct the expected value as np.array([0, 0]). Also remove an unused itertools import and reorder pyscipopt imports for clarity.

* Refine type hints: use np alias and add overloads

Improve typing in src/pyscipopt/scip.pyi: import Union and overload, alias numpy as np, and switch class bases from numpy.ndarray to np.ndarray. Add overloads for Model.getSolVal and Model.getVal to distinguish scalar returns (Expr/GenExpr -> float) from matrix returns (MatrixExpr -> np.ndarray), improving type accuracy for consumers and IDE/type-checkers.

* Reorder imports in tests/test_model.py

Move 'from helpers.utils import random_mip_1' below the pyscipopt imports to group third-party and local imports (style-only change; no functional impact).

* Apply suggestion from @Joao-Dionisio

---------

Co-authored-by: João Dionísio <57299939+Joao-Dionisio@users.noreply.github.com>

Author: Zeroto521

CHANGELOG.md

@@ -8,6 +8,7 @@
 - Wrapped isObjIntegral() and test
 - Added structured_optimization_trace recipe for structured optimization progress tracking
 - Added methods: getPrimalDualIntegral()
+- getSolVal() supports MatrixExpr now
 ### Fixed
 - getBestSol() now returns None for infeasible problems instead of a Solution with NULL pointer
 - all fundamental callbacks now raise an error if not implemented

src/pyscipopt/scip.pxi

@@ -1098,7 +1098,16 @@ cdef class Solution:
         sol.scip = scip
         return sol
 
-    def __getitem__(self, expr: Union[Expr, MatrixExpr]):
+    def __getitem__(
+        self,
+        expr: Union[Expr, GenExpr, MatrixExpr],
+    ) -> Union[float, np.ndarray]:
+        if not isinstance(expr, (Expr, GenExpr, MatrixExpr)):
+            raise TypeError(
+                "Argument 'expr' has incorrect type, expected 'Expr', 'GenExpr', or "
+                f"'MatrixExpr', got {type(expr).__name__!r}"
+            )
+
         self._checkStage("SCIPgetSolVal")
         return expr._evaluate(self)
 
@@ -10968,75 +10977,63 @@ cdef class Model:
     def getSolVal(
         self,
         Solution sol,
-        expr: Union[Expr, GenExpr],
+        expr: Union[Expr, GenExpr, MatrixExpr],
     ) -> Union[float, np.ndarray]:
         """
-        Retrieve value of given variable or expression in the given solution or in
-        the LP/pseudo solution if sol == None
+        Retrieve value of given variable or expression in the given solution.
 
         Parameters
         ----------
         sol : Solution
-        expr : Expr
-            polynomial expression to query the value of
+            Solution to query the value from. If None, the current LP/pseudo solution is
+            used.
+
+        expr : Expr, GenExpr, MatrixExpr
+            Expression to query the value of.
 
         Returns
         -------
-        float
+        float or np.ndarray
 
         Notes
         -----
         A variable is also an expression.
 
         """
-        if not isinstance(expr, (Expr, GenExpr)):
-            raise TypeError(
-                "Argument 'expr' has incorrect type (expected 'Expr' or 'GenExpr', "
-                f"got {type(expr)})"
-            )
         # no need to create a NULL solution wrapper in case we have a variable
         return (sol or Solution.create(self._scip, NULL))[expr]
 
-    def getVal(self, expr: Union[Expr, GenExpr, MatrixExpr] ):
+    def getVal(self, expr: Union[Expr, GenExpr, MatrixExpr]) -> Union[float, np.ndarray]:
         """
         Retrieve the value of the given variable or expression in the best known solution.
         Can only be called after solving is completed.
 
         Parameters
         ----------
         expr : Expr, GenExpr or MatrixExpr
+            Expression to query the value of.
 
         Returns
         -------
-        float
+        float or np.ndarray
 
         Notes
         -----
         A variable is also an expression.
 
         """
-        cdef SCIP_SOL* current_best_sol
-
-        stage_check = SCIPgetStage(self._scip) not in [SCIP_STAGE_INIT, SCIP_STAGE_FREE]
-        if not stage_check:
+        if SCIPgetStage(self._scip) in {SCIP_STAGE_INIT, SCIP_STAGE_FREE}:
             raise Warning("Method cannot be called in stage ", self.getStage())
 
         # Ensure _bestSol is up-to-date (cheap pointer comparison)
-        current_best_sol = SCIPgetBestSol(self._scip)
+        cdef SCIP_SOL* current_best_sol = SCIPgetBestSol(self._scip)
         if self._bestSol is None or self._bestSol.sol != current_best_sol:
             self._bestSol = Solution.create(self._scip, current_best_sol)
 
         if self._bestSol.sol == NULL and SCIPgetStage(self._scip) != SCIP_STAGE_SOLVING:
             raise Warning("No solution available")
 
-        if isinstance(expr, MatrixExpr):
-            result = np.empty(expr.shape, dtype=float)
-            for idx in np.ndindex(result.shape):
-                result[idx] = self.getSolVal(self._bestSol, expr[idx])
-        else:
-            result = self.getSolVal(self._bestSol, expr)
-
-        return result
+        return self._bestSol[expr]
 
     def hasPrimalRay(self):
         """

src/pyscipopt/scip.pyi

@@ -1,6 +1,6 @@
-from typing import ClassVar
+from typing import ClassVar, Union, overload
 
-import numpy
+import numpy as np
 from _typeshed import Incomplete
 from typing_extensions import disjoint_base
 
@@ -496,7 +496,7 @@ class LP:
     def solve(self, dual: Incomplete = ...) -> Incomplete: ...
     def writeLP(self, filename: Incomplete) -> Incomplete: ...
 
-class MatrixConstraint(numpy.ndarray):
+class MatrixConstraint(np.ndarray):
     def getConshdlrName(self) -> Incomplete: ...
     def isActive(self) -> Incomplete: ...
     def isChecked(self) -> Incomplete: ...
@@ -512,7 +512,7 @@ class MatrixConstraint(numpy.ndarray):
     def isSeparated(self) -> Incomplete: ...
     def isStickingAtNode(self) -> Incomplete: ...
 
-class MatrixExpr(numpy.ndarray):
+class MatrixExpr(np.ndarray):
     def _evaluate(self, sol: Incomplete) -> Incomplete: ...
     def __array_ufunc__(
         self,
@@ -522,7 +522,7 @@ class MatrixExpr(numpy.ndarray):
         **kwargs: Incomplete,
     ) -> Incomplete: ...
 
-class MatrixExprCons(numpy.ndarray):
+class MatrixExprCons(np.ndarray):
     def __array_ufunc__(
         self,
         ufunc: Incomplete,
@@ -1215,7 +1215,10 @@ class Model:
         self, sol: Incomplete, original: Incomplete = ...
     ) -> Incomplete: ...
     def getSolTime(self, sol: Incomplete) -> Incomplete: ...
-    def getSolVal(self, sol: Incomplete, expr: Incomplete) -> Incomplete: ...
+    @overload
+    def getSolVal(self, sol: Solution, expr: Union[Expr, GenExpr]) -> float: ...
+    @overload
+    def getSolVal(self, sol: Solution, expr: MatrixExpr) -> np.ndarray: ...
     def getSols(self) -> Incomplete: ...
     def getSolvingTime(self) -> Incomplete: ...
     def getStage(self) -> Incomplete: ...
@@ -1227,7 +1230,10 @@ class Model:
     def getTransformedCons(self, cons: Incomplete) -> Incomplete: ...
     def getTransformedVar(self, var: Incomplete) -> Incomplete: ...
     def getTreesizeEstimation(self) -> Incomplete: ...
-    def getVal(self, expr: Incomplete) -> Incomplete: ...
+    @overload
+    def getVal(self, expr: Union[Expr, GenExpr]) -> float: ...
+    @overload
+    def getVal(self, expr: MatrixExpr) -> np.ndarray: ...
     def getValsLinear(self, cons: Incomplete) -> Incomplete: ...
     def getVarDict(self, transformed: Incomplete = ...) -> Incomplete: ...
     def getVarLbDive(self, var: Incomplete) -> Incomplete: ...

tests/test_model.py

@@ -1,10 +1,13 @@
-import pytest
-import os
 import itertools
+import os
+
+import numpy as np
+import pytest
 
-from pyscipopt import Model, SCIP_STAGE, SCIP_PARAMSETTING, SCIP_BRANCHDIR, quicksum
+from pyscipopt import SCIP_BRANCHDIR, SCIP_PARAMSETTING, SCIP_STAGE, Model, quicksum
 from helpers.utils import random_mip_1
 
+
 def test_model():
     # create solver instance
     s = Model()
@@ -616,3 +619,26 @@ def create_model_and_get_objects():
 
     assert repr(x) == ""
     assert repr(c) == ""
+
+
+def test_getSolVal():
+    # fix #1136
+
+    m = Model()
+    x = m.addVar(vtype="B")
+    y = m.addMatrixVar(2, vtype="B")
+
+    m.setObjective(x + y.sum())
+    m.optimize()
+    sol = m.getBestSol()
+
+    assert m.getSolVal(sol, x) == m.getVal(x)
+    assert m.getVal(x) == 0
+
+    assert np.array_equal(m.getSolVal(sol, y), m.getVal(y))
+    assert np.array_equal(m.getVal(y), np.array([0, 0]))
+
+    with pytest.raises(TypeError):
+        m.getVal("not_a_var")
+    with pytest.raises(TypeError):
+        m.getSolVal(sol, "not_a_var")