Add lower_bound()/upper_bound() expression operators

docs/CHANGELOG.md

@@ -13,6 +13,13 @@ All notable changes to GemsPy are documented here.
   compute tighter variable bounds from the first solve. Each model declares
   what a heuristic reads/writes via `models[].heuristics` in
   `optim-config.yml`.
+- **`lower_bound(variable_name)`** and **`upper_bound(variable_name)`** operators in the
+  expression language, usable in `extra-outputs` and port-field-definitions. Both take a bare
+  variable identifier and return its *current* lower/upper bound post-solve — in particular
+  reflecting mutations made by thermal heuristics (see "Integer strategy and thermal
+  heuristics" above), which previously had no way to be surfaced in results. Validated at
+  model-build time; using them inside constraints, binding-constraints, objective
+  contributions, or variable bounds raises a `ValueError`.
 
 ## [0.1.3] - 2026-07-24
 

docs/agents/testing.md

@@ -23,7 +23,7 @@ nature (they build a study with `gems_craft` and solve it with `gems_runner` in
 | Unit — gems_craft / system | `tests/unittests/gems_craft/system/` | Model, network, and port object behaviour |
 | Unit — gems_craft / system parsing | `tests/unittests/gems_craft/system_parsing/` | System YAML parsing |
 | Unit — gems_craft_hybrid | `tests/unittests/gems_craft_hybrid/` | Hybrid GEMS/Antares Simulator schema parsing |
-| Unit — gems_runner / expression | `tests/unittests/gems_runner/expression/` | Solver-output expression evaluation (`dual()`, `reduced_cost()`, `variable()`) |
+| Unit — gems_runner / expression | `tests/unittests/gems_runner/expression/` | Solver-output expression evaluation (`dual()`, `reduced_cost()`, `lower_bound()`, `upper_bound()`, `variable()`) |
 | Unit — gems_runner / simulation | `tests/unittests/gems_runner/simulation/` | Full problem build + solve on small networks |
 | End-to-end — functional | `tests/e2e/functional/` | Cross-cutting tests: library/system combinations, stochastic, investment, scenario builder |
 | End-to-end — models | `tests/e2e/models/` | Model-level tests (andromede-v1 models, operator tests, proof-of-concept models) |

src/gems_craft/expression/copy.py

@@ -23,6 +23,7 @@
     ExpressionNode,
     FloorNode,
     LiteralNode,
+    LowerBoundNode,
     MaxNode,
     MinNode,
     ParameterNode,
@@ -34,6 +35,7 @@
     TimeEvalNode,
     TimeShiftNode,
     TimeSumNode,
+    UpperBoundNode,
     VariableNode,
 )
 from .visitor import ExpressionVisitorOperations, visit
@@ -111,6 +113,12 @@ def dual(self, node: DualNode) -> ExpressionNode:
     def reduced_cost(self, node: ReducedCostNode) -> ExpressionNode:
         return ReducedCostNode(node.variable_id)
 
+    def lower_bound(self, node: LowerBoundNode) -> ExpressionNode:
+        return LowerBoundNode(node.variable_id)
+
+    def upper_bound(self, node: UpperBoundNode) -> ExpressionNode:
+        return UpperBoundNode(node.variable_id)
+
 
 def copy_expression(expression: ExpressionNode) -> ExpressionNode:
     return visit(expression, CopyVisitor())

src/gems_craft/expression/degree.py

@@ -20,6 +20,7 @@
     CeilNode,
     DualNode,
     FloorNode,
+    LowerBoundNode,
     MaxNode,
     MinNode,
     PortFieldAggregatorNode,
@@ -29,6 +30,7 @@
     TimeEvalNode,
     TimeShiftNode,
     TimeSumNode,
+    UpperBoundNode,
 )
 
 from .expression import (
@@ -132,6 +134,12 @@ def dual(self, node: DualNode) -> int | float:
     def reduced_cost(self, node: ReducedCostNode) -> int | float:
         return math.inf
 
+    def lower_bound(self, node: LowerBoundNode) -> int | float:
+        return math.inf
+
+    def upper_bound(self, node: UpperBoundNode) -> int | float:
+        return math.inf
+
 
 def compute_degree(expression: ExpressionNode) -> int | float:
     return visit(expression, ExpressionDegreeVisitor())

src/gems_craft/expression/equality.py

@@ -32,6 +32,7 @@
     CeilNode,
     DualNode,
     FloorNode,
+    LowerBoundNode,
     MaxNode,
     MinNode,
     PortFieldAggregatorNode,
@@ -42,6 +43,7 @@
     TimeEvalNode,
     TimeShiftNode,
     TimeSumNode,
+    UpperBoundNode,
 )
 
 
@@ -115,6 +117,10 @@ def visit(self, left: ExpressionNode, right: ExpressionNode) -> bool:
             return self.dual(left, right)
         if isinstance(left, ReducedCostNode) and isinstance(right, ReducedCostNode):
             return self.reduced_cost(left, right)
+        if isinstance(left, LowerBoundNode) and isinstance(right, LowerBoundNode):
+            return self.lower_bound(left, right)
+        if isinstance(left, UpperBoundNode) and isinstance(right, UpperBoundNode):
+            return self.upper_bound(left, right)
         raise NotImplementedError(f"Equality not implemented for {left.__class__}")
 
     def literal(self, left: LiteralNode, right: LiteralNode) -> bool:
@@ -217,6 +223,12 @@ def dual(self, left: DualNode, right: DualNode) -> bool:
     def reduced_cost(self, left: ReducedCostNode, right: ReducedCostNode) -> bool:
         return left.variable_id == right.variable_id
 
+    def lower_bound(self, left: LowerBoundNode, right: LowerBoundNode) -> bool:
+        return left.variable_id == right.variable_id
+
+    def upper_bound(self, left: UpperBoundNode, right: UpperBoundNode) -> bool:
+        return left.variable_id == right.variable_id
+
 
 def expressions_equal(
     left: ExpressionNode, right: ExpressionNode, abs_tol: float = 0, rel_tol: float = 0

src/gems_craft/expression/expression.py

@@ -357,6 +357,16 @@ class ReducedCostNode(ExpressionNode):
     variable_id: str
 
 
+@dataclass(frozen=True, eq=False)
+class LowerBoundNode(ExpressionNode):
+    variable_id: str
+
+
+@dataclass(frozen=True, eq=False)
+class UpperBoundNode(ExpressionNode):
+    variable_id: str
+
+
 def sum_expressions(expressions: Sequence[ExpressionNode]) -> ExpressionNode:
     if len(expressions) == 0:
         return LiteralNode(0)

src/gems_craft/expression/indexing.py

@@ -27,6 +27,7 @@
     ExpressionNode,
     FloorNode,
     LiteralNode,
+    LowerBoundNode,
     MaxNode,
     MinNode,
     MultiplicationNode,
@@ -40,6 +41,7 @@
     TimeEvalNode,
     TimeShiftNode,
     TimeSumNode,
+    UpperBoundNode,
     VariableNode,
 )
 from .visitor import ExpressionVisitor, T, visit
@@ -156,6 +158,12 @@ def dual(self, node: DualNode) -> IndexingStructure:
     def reduced_cost(self, node: ReducedCostNode) -> IndexingStructure:
         return self.context.get_variable_structure(node.variable_id)
 
+    def lower_bound(self, node: LowerBoundNode) -> IndexingStructure:
+        return self.context.get_variable_structure(node.variable_id)
+
+    def upper_bound(self, node: UpperBoundNode) -> IndexingStructure:
+        return self.context.get_variable_structure(node.variable_id)
+
 
 def compute_indexation(
     expression: ExpressionNode, provider: IndexingStructureProvider

src/gems_craft/expression/parsing/parse_expression.py

@@ -21,9 +21,11 @@
     Comparator,
     ComparisonNode,
     DualNode,
+    LowerBoundNode,
     PortFieldAggregatorNode,
     PortFieldNode,
     ReducedCostNode,
+    UpperBoundNode,
     maximum,
     minimum,
 )
@@ -194,6 +196,22 @@ def _visit_reduced_cost(self, arg_exprs: list) -> ExpressionNode:
             raise ValueError(f"'{vid}' is not a variable of the model.")
         return ReducedCostNode(vid)
 
+    def _visit_lower_bound(self, arg_exprs: list) -> ExpressionNode:
+        if len(arg_exprs) != 1:
+            raise ValueError("lower_bound() requires exactly 1 argument.")
+        vid = arg_exprs[0].getText()  # type: ignore
+        if vid not in self.identifiers.variables:
+            raise ValueError(f"'{vid}' is not a variable of the model.")
+        return LowerBoundNode(vid)
+
+    def _visit_upper_bound(self, arg_exprs: list) -> ExpressionNode:
+        if len(arg_exprs) != 1:
+            raise ValueError("upper_bound() requires exactly 1 argument.")
+        vid = arg_exprs[0].getText()  # type: ignore
+        if vid not in self.identifiers.variables:
+            raise ValueError(f"'{vid}' is not a variable of the model.")
+        return UpperBoundNode(vid)
+
     # Visit a parse tree produced by ExprParser#function.
     def visitFunction(self, ctx: ExprParser.FunctionContext) -> ExpressionNode:
         function_name: str = ctx.IDENTIFIER().getText()  # type: ignore
@@ -204,6 +222,10 @@ def visitFunction(self, ctx: ExprParser.FunctionContext) -> ExpressionNode:
             return self._visit_dual(arg_exprs)
         if function_name == "reduced_cost":
             return self._visit_reduced_cost(arg_exprs)
+        if function_name == "lower_bound":
+            return self._visit_lower_bound(arg_exprs)
+        if function_name == "upper_bound":
+            return self._visit_upper_bound(arg_exprs)
 
         args: list[ExpressionNode] = (
             [expr.accept(self) for expr in arg_exprs]  # type: ignore

src/gems_craft/expression/print.py

@@ -20,6 +20,7 @@
     DualNode,
     ExpressionNode,
     FloorNode,
+    LowerBoundNode,
     MaxNode,
     MinNode,
     PortFieldAggregatorNode,
@@ -29,6 +30,7 @@
     TimeEvalNode,
     TimeShiftNode,
     TimeSumNode,
+    UpperBoundNode,
 )
 
 from .expression import (
@@ -144,6 +146,12 @@ def dual(self, node: DualNode) -> str:
     def reduced_cost(self, node: ReducedCostNode) -> str:
         return f"reduced_cost({node.variable_id})"
 
+    def lower_bound(self, node: LowerBoundNode) -> str:
+        return f"lower_bound({node.variable_id})"
+
+    def upper_bound(self, node: UpperBoundNode) -> str:
+        return f"upper_bound({node.variable_id})"
+
 
 def print_expr(expression: ExpressionNode) -> str:
     return visit(expression, PrinterVisitor())

src/gems_craft/expression/uses_sum_connections_on.py

@@ -21,6 +21,7 @@
     ExpressionNode,
     FloorNode,
     LiteralNode,
+    LowerBoundNode,
     MaxNode,
     MinNode,
     MultiplicationNode,
@@ -34,6 +35,7 @@
     TimeEvalNode,
     TimeShiftNode,
     TimeSumNode,
+    UpperBoundNode,
     VariableNode,
 )
 
@@ -122,6 +124,12 @@ def dual(self, node: DualNode) -> bool:
     def reduced_cost(self, node: ReducedCostNode) -> bool:
         return False
 
+    def lower_bound(self, node: LowerBoundNode) -> bool:
+        return False
+
+    def upper_bound(self, node: UpperBoundNode) -> bool:
+        return False
+
 
 def uses_sum_connections_on(
     expr: ExpressionNode, port_name: str, field_name: str

src/gems_craft/expression/visitor.py

@@ -29,6 +29,7 @@
     ExpressionNode,
     FloorNode,
     LiteralNode,
+    LowerBoundNode,
     MaxNode,
     MinNode,
     MultiplicationNode,
@@ -42,6 +43,7 @@
     TimeEvalNode,
     TimeShiftNode,
     TimeSumNode,
+    UpperBoundNode,
     VariableNode,
 )
 
@@ -126,6 +128,12 @@ def dual(self, node: DualNode) -> T: ...
     @abstractmethod
     def reduced_cost(self, node: ReducedCostNode) -> T: ...
 
+    @abstractmethod
+    def lower_bound(self, node: LowerBoundNode) -> T: ...
+
+    @abstractmethod
+    def upper_bound(self, node: UpperBoundNode) -> T: ...
+
 
 def visit(root: ExpressionNode, visitor: ExpressionVisitor[T]) -> T:
     """
@@ -177,6 +185,10 @@ def visit(root: ExpressionNode, visitor: ExpressionVisitor[T]) -> T:
         return visitor.dual(root)
     elif isinstance(root, ReducedCostNode):
         return visitor.reduced_cost(root)
+    elif isinstance(root, LowerBoundNode):
+        return visitor.lower_bound(root)
+    elif isinstance(root, UpperBoundNode):
+        return visitor.upper_bound(root)
     raise ValueError(f"Unknown expression node type {root.__class__}")
 
 

src/gems_craft/model/port.py

@@ -32,6 +32,7 @@
     CeilNode,
     DualNode,
     FloorNode,
+    LowerBoundNode,
     MaxNode,
     MinNode,
     PortFieldAggregatorNode,
@@ -42,6 +43,7 @@
     TimeEvalNode,
     TimeShiftNode,
     TimeSumNode,
+    UpperBoundNode,
 )
 from gems_craft.expression.visitor import visit
 
@@ -178,6 +180,12 @@ def dual(self, node: DualNode) -> None:
     def reduced_cost(self, node: ReducedCostNode) -> None:
         pass  # reduced_cost() is permitted in port-field definitions
 
+    def lower_bound(self, node: LowerBoundNode) -> None:
+        pass  # lower_bound() is permitted in port-field definitions
+
+    def upper_bound(self, node: UpperBoundNode) -> None:
+        pass  # upper_bound() is permitted in port-field definitions
+
 
 def _validate_port_field_expression(definition: PortFieldDefinition) -> None:
     visit(definition.definition, _PortFieldExpressionChecker())

src/gems_craft/model/resolve_library.py

@@ -23,6 +23,7 @@
     DualNode,
     FloorNode,
     LiteralNode,
+    LowerBoundNode,
     MaxNode,
     MinNode,
     MultiplicationNode,
@@ -36,6 +37,7 @@
     TimeEvalNode,
     TimeShiftNode,
     TimeSumNode,
+    UpperBoundNode,
     VariableNode,
 )
 from gems_craft.expression.indexing_structure import IndexingStructure
@@ -291,6 +293,12 @@ def dual(self, node: DualNode) -> None:
     def reduced_cost(self, node: ReducedCostNode) -> None:
         pass
 
+    def lower_bound(self, node: LowerBoundNode) -> None:
+        pass
+
+    def upper_bound(self, node: UpperBoundNode) -> None:
+        pass
+
 
 def _forbid_bare_port_field(expr: ExpressionNode, context: str) -> None:
     visit(expr, _ForbidBarePortFieldVisitor(context))

src/gems_runner/expression/evaluate.py

@@ -24,6 +24,7 @@
     ExpressionNode,
     FloorNode,
     LiteralNode,
+    LowerBoundNode,
     MaxNode,
     MinNode,
     ParameterNode,
@@ -35,6 +36,7 @@
     TimeEvalNode,
     TimeShiftNode,
     TimeSumNode,
+    UpperBoundNode,
     VariableNode,
 )
 from gems_craft.expression.indexing import IndexingStructureProvider
@@ -139,6 +141,12 @@ def dual(self, node: DualNode) -> float:
     def reduced_cost(self, node: ReducedCostNode) -> float:
         raise NotImplementedError("reduced_cost() is not statically evaluable.")
 
+    def lower_bound(self, node: LowerBoundNode) -> float:
+        raise NotImplementedError("lower_bound() is not statically evaluable.")
+
+    def upper_bound(self, node: UpperBoundNode) -> float:
+        raise NotImplementedError("upper_bound() is not statically evaluable.")
+
 
 def evaluate(expression: ExpressionNode, value_provider: ValueProvider) -> float:
     return visit(expression, EvaluationVisitor(value_provider))