feat(solver): add structured failure events to Solution

Replace bare success=False returns with typed failure events:
- OutsideCapacityEvent: rate above stonewall or below surge, with
  actual and boundary values (m3/h) when available
- TargetNotAchievableEvent: pressure target out of achievable range,
  with achievable and target values (bara)

Author: olelod

src/libecalc/domain/process/entities/process_units/compressor.py

@@ -30,9 +30,15 @@ def get_id(self) -> ProcessUnitId:
     def propagate_stream(self, inlet_stream: FluidStream) -> FluidStream:
         actual_rate = inlet_stream.volumetric_rate_m3_per_hour
         if actual_rate < self.minimum_flow_rate:
-            raise RateTooLowError()
+            raise RateTooLowError(
+                actual_rate=actual_rate,
+                boundary_rate=self.minimum_flow_rate,
+            )
         if actual_rate > self.maximum_flow_rate:
-            raise RateTooHighError()
+            raise RateTooHighError(
+                actual_rate=actual_rate,
+                boundary_rate=self.maximum_flow_rate,
+            )
 
         chart_curve_at_given_speed = self.compressor_chart.get_curve_by_speed(speed=self.speed)
         if chart_curve_at_given_speed is not None:

src/libecalc/domain/process/process_solver/anti_surge/individual_asv.py

@@ -4,7 +4,11 @@
 from libecalc.domain.process.entities.process_units.compressor import Compressor
 from libecalc.domain.process.process_solver.anti_surge.anti_surge_strategy import AntiSurgeStrategy
 from libecalc.domain.process.process_solver.process_runner import Configuration, ProcessRunner
-from libecalc.domain.process.process_solver.solver import Solution
+from libecalc.domain.process.process_solver.solver import (
+    OutsideCapacityEvent,
+    Solution,
+    SolverFailureStatus,
+)
 from libecalc.domain.process.process_solver.solvers.recirculation_solver import RecirculationConfiguration
 from libecalc.domain.process.process_system.process_error import RateTooHighError
 from libecalc.domain.process.process_system.process_system import ProcessSystemId
@@ -61,12 +65,27 @@ def apply(self, inlet_stream: FluidStream) -> Solution[Sequence[Configuration[Re
         for loop_id, compressor in zip(self._recirculation_loop_ids, self._compressors, strict=True):
             try:
                 inlet_stream_compressor = self._simulator.run(inlet_stream=inlet_stream, to_id=compressor.get_id())
-            except RateTooHighError:
-                return Solution(success=False, configuration=configurations)
-            if inlet_stream_compressor.standard_rate_sm3_per_day > compressor.get_maximum_standard_rate(
-                inlet_stream_compressor
-            ):
-                return Solution(success=False, configuration=configurations)
+            except RateTooHighError as e:
+                return Solution(
+                    success=False,
+                    configuration=configurations,
+                    failure_event=OutsideCapacityEvent(
+                        status=SolverFailureStatus.ABOVE_MAXIMUM_FLOW_RATE,
+                        actual_value=e.actual_rate,
+                        boundary_value=e.boundary_rate,
+                    ),
+                )
+            max_actual_rate = compressor.maximum_flow_rate
+            if inlet_stream_compressor.volumetric_rate_m3_per_hour > max_actual_rate:
+                return Solution(
+                    success=False,
+                    configuration=configurations,
+                    failure_event=OutsideCapacityEvent(
+                        status=SolverFailureStatus.ABOVE_MAXIMUM_FLOW_RATE,
+                        actual_value=inlet_stream_compressor.volumetric_rate_m3_per_hour,
+                        boundary_value=max_actual_rate,
+                    ),
+                )
             boundary = compressor.get_recirculation_range(inlet_stream=inlet_stream_compressor)
             configuration: Configuration[RecirculationConfiguration] = Configuration(
                 simulation_unit_id=loop_id,

src/libecalc/domain/process/process_solver/outlet_pressure_solver.py

@@ -9,7 +9,11 @@
 from libecalc.domain.process.process_solver.pressure_control.pressure_control_strategy import PressureControlStrategy
 from libecalc.domain.process.process_solver.process_runner import Configuration, ProcessRunner
 from libecalc.domain.process.process_solver.search_strategies import BinarySearchStrategy, RootFindingStrategy
-from libecalc.domain.process.process_solver.solver import Solution
+from libecalc.domain.process.process_solver.solver import (
+    Solution,
+    SolverFailureStatus,
+    TargetNotAchievableEvent,
+)
 from libecalc.domain.process.process_solver.solvers.recirculation_solver import (
     RecirculationConfiguration,
 )
@@ -121,7 +125,11 @@ def find_solution(
             )
 
         if not self._anti_surge_solution.success:
-            return Solution(success=False, configuration=list(configurations.values()))
+            return Solution(
+                success=False,
+                configuration=list(configurations.values()),
+                failure_event=self._anti_surge_solution.failure_event,
+            )
 
         outlet_at_chosen_speed = self._get_outlet_stream(
             inlet_stream=inlet_stream,
@@ -132,6 +140,11 @@ def find_solution(
             return Solution(
                 success=False,
                 configuration=list(configurations.values()),
+                failure_event=TargetNotAchievableEvent(
+                    status=SolverFailureStatus.MAXIMUM_ACHIEVABLE_DISCHARGE_PRESSURE_BELOW_TARGET,
+                    achievable_value=outlet_at_chosen_speed.pressure_bara,
+                    target_value=pressure_constraint.value,
+                ),
             )
 
         pressure_control_solution = self._pressure_control_strategy.apply(

src/libecalc/domain/process/process_solver/pressure_control/common_asv.py

@@ -5,7 +5,11 @@
 from libecalc.domain.process.process_solver.pressure_control.pressure_control_strategy import PressureControlStrategy
 from libecalc.domain.process.process_solver.process_runner import Configuration, ProcessRunner
 from libecalc.domain.process.process_solver.search_strategies import BinarySearchStrategy, RootFindingStrategy
-from libecalc.domain.process.process_solver.solver import Solution
+from libecalc.domain.process.process_solver.solver import (
+    Solution,
+    SolverFailureStatus,
+    TargetNotAchievableEvent,
+)
 from libecalc.domain.process.process_solver.solvers.downstream_choke_solver import ChokeConfiguration
 from libecalc.domain.process.process_solver.solvers.recirculation_solver import (
     RecirculationConfiguration,
@@ -60,6 +64,11 @@ def recirculation_func(config: RecirculationConfiguration) -> FluidStream:
                         value=min_configuration,
                     )
                 ],
+                failure_event=TargetNotAchievableEvent(
+                    status=SolverFailureStatus.MINIMUM_ACHIEVABLE_DISCHARGE_PRESSURE_ABOVE_TARGET,
+                    achievable_value=min_pressure_stream.pressure_bara,
+                    target_value=target_pressure.value,
+                ),
             )
 
         solver = RecirculationSolver(

src/libecalc/domain/process/process_solver/pressure_control/individual_asv.py

@@ -6,7 +6,11 @@
 from libecalc.domain.process.process_solver.pressure_control.pressure_control_strategy import PressureControlStrategy
 from libecalc.domain.process.process_solver.process_runner import Configuration, ProcessRunner
 from libecalc.domain.process.process_solver.search_strategies import BinarySearchStrategy, RootFindingStrategy
-from libecalc.domain.process.process_solver.solver import Solution
+from libecalc.domain.process.process_solver.solver import (
+    Solution,
+    SolverFailureStatus,
+    TargetNotAchievableEvent,
+)
 from libecalc.domain.process.process_solver.solvers.downstream_choke_solver import ChokeConfiguration
 from libecalc.domain.process.process_solver.solvers.recirculation_solver import (
     RecirculationConfiguration,
@@ -56,6 +60,11 @@ def apply(
             return Solution(
                 success=False,
                 configuration=minimum_achievable_pressure_configurations,
+                failure_event=TargetNotAchievableEvent(
+                    status=SolverFailureStatus.MINIMUM_ACHIEVABLE_DISCHARGE_PRESSURE_ABOVE_TARGET,
+                    achievable_value=minimum_achievable_pressure_stream.pressure_bara,
+                    target_value=target_pressure.value,
+                ),
             )
 
         n_stages = len(self._recirculation_loop_ids)
@@ -99,6 +108,7 @@ def recirculation_func(config: RecirculationConfiguration):
                 return Solution(
                     success=False,
                     configuration=configurations,
+                    failure_event=solution.failure_event,
                 )
 
         self._simulator.apply_configurations(configurations)
@@ -173,6 +183,11 @@ def apply(
             return Solution(
                 success=False,
                 configuration=minimum_achievable_pressure_configurations,
+                failure_event=TargetNotAchievableEvent(
+                    status=SolverFailureStatus.MINIMUM_ACHIEVABLE_DISCHARGE_PRESSURE_ABOVE_TARGET,
+                    achievable_value=minimum_achievable_pressure_stream.pressure_bara,
+                    target_value=target_pressure.value,
+                ),
             )
 
         def get_outlet_stream(rate_fraction: float) -> FluidStream:

src/libecalc/domain/process/process_solver/solver.py

@@ -1,17 +1,43 @@
 import abc
 from collections.abc import Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from enum import Enum
 from typing import Generic, TypeVar
 
 from libecalc.domain.process.value_objects.fluid_stream import FluidStream
 
 TConfiguration = TypeVar("TConfiguration")
 
 
+class SolverFailureStatus(str, Enum):
+    ABOVE_MAXIMUM_FLOW_RATE = "ABOVE_MAXIMUM_FLOW_RATE"
+    BELOW_MINIMUM_FLOW_RATE = "BELOW_MINIMUM_FLOW_RATE"
+    MAXIMUM_ACHIEVABLE_DISCHARGE_PRESSURE_BELOW_TARGET = "MAXIMUM_ACHIEVABLE_DISCHARGE_PRESSURE_BELOW_TARGET"
+    MINIMUM_ACHIEVABLE_DISCHARGE_PRESSURE_ABOVE_TARGET = "MINIMUM_ACHIEVABLE_DISCHARGE_PRESSURE_ABOVE_TARGET"
+
+
+@dataclass
+class OutsideCapacityEvent:
+    status: SolverFailureStatus
+    actual_value: float | None = None
+    boundary_value: float | None = None
+
+
+@dataclass
+class TargetNotAchievableEvent:
+    status: SolverFailureStatus
+    achievable_value: float
+    target_value: float
+
+
+SolverFailureEvent = OutsideCapacityEvent | TargetNotAchievableEvent
+
+
 @dataclass
 class Solution(Generic[TConfiguration]):
     success: bool
     configuration: TConfiguration
+    failure_event: SolverFailureEvent | None = field(default=None)
 
 
 class Solver(abc.ABC, Generic[TConfiguration]):

src/libecalc/domain/process/process_solver/solvers/recirculation_solver.py

@@ -5,7 +5,13 @@
 from libecalc.domain.process.process_solver.boundary import Boundary
 from libecalc.domain.process.process_solver.float_constraint import FloatConstraint
 from libecalc.domain.process.process_solver.search_strategies import RootFindingStrategy, SearchStrategy
-from libecalc.domain.process.process_solver.solver import Solution, Solver
+from libecalc.domain.process.process_solver.solver import (
+    OutsideCapacityEvent,
+    Solution,
+    Solver,
+    SolverFailureStatus,
+    TargetNotAchievableEvent,
+)
 from libecalc.domain.process.process_system.process_error import RateTooHighError, RateTooLowError
 from libecalc.domain.process.value_objects.fluid_stream import FluidStream
 
@@ -58,9 +64,17 @@ def bool_func(x: float, mode: Literal["minimize", "maximize"]) -> tuple[bool, bo
                 boundary=self._recirculation_rate_boundary,
                 func=lambda x: bool_func(x, mode="minimize"),
             )
-        except RateTooHighError:
+        except RateTooHighError as e:
             # Flow is above stonewall at zero recirculation; adding recirculation cannot help.
-            return Solution(success=False, configuration=RecirculationConfiguration(recirculation_rate=minimum_rate))
+            return Solution(
+                success=False,
+                configuration=RecirculationConfiguration(recirculation_rate=minimum_rate),
+                failure_event=OutsideCapacityEvent(
+                    status=SolverFailureStatus.ABOVE_MAXIMUM_FLOW_RATE,
+                    actual_value=e.actual_rate,
+                    boundary_value=e.boundary_rate,
+                ),
+            )
 
         target_pressure = self._target_pressure
         if target_pressure is None:
@@ -81,16 +95,32 @@ def bool_func(x: float, mode: Literal["minimize", "maximize"]) -> tuple[bool, bo
         minimum_outlet_stream = func(RecirculationConfiguration(recirculation_rate=minimum_rate))
         if minimum_outlet_stream.pressure_bara <= target_pressure:
             # Highest possible pressure is too low
+            is_success = minimum_outlet_stream.pressure_bara == target_pressure
             return Solution(
-                success=minimum_outlet_stream.pressure_bara == target_pressure,
+                success=is_success,
                 configuration=RecirculationConfiguration(recirculation_rate=minimum_rate),
+                failure_event=None
+                if is_success
+                else TargetNotAchievableEvent(
+                    status=SolverFailureStatus.MAXIMUM_ACHIEVABLE_DISCHARGE_PRESSURE_BELOW_TARGET,
+                    achievable_value=minimum_outlet_stream.pressure_bara,
+                    target_value=target_pressure.value,
+                ),
             )
         maximum_outlet_stream = func(RecirculationConfiguration(recirculation_rate=maximum_rate))
         if maximum_outlet_stream.pressure_bara >= target_pressure:
             # Lowest possible pressure is too high
+            is_success = maximum_outlet_stream.pressure_bara == self._target_pressure
             return Solution(
-                success=maximum_outlet_stream.pressure_bara == self._target_pressure,
+                success=is_success,
                 configuration=RecirculationConfiguration(recirculation_rate=maximum_rate),
+                failure_event=None
+                if is_success
+                else TargetNotAchievableEvent(
+                    status=SolverFailureStatus.MINIMUM_ACHIEVABLE_DISCHARGE_PRESSURE_ABOVE_TARGET,
+                    achievable_value=maximum_outlet_stream.pressure_bara,
+                    target_value=target_pressure.value,
+                ),
             )
 
         recirculation_rate = self._root_finding_strategy.find_root(

src/libecalc/domain/process/process_solver/solvers/speed_solver.py

@@ -4,8 +4,14 @@
 
 from libecalc.domain.process.process_solver.boundary import Boundary
 from libecalc.domain.process.process_solver.search_strategies import RootFindingStrategy, SearchStrategy
-from libecalc.domain.process.process_solver.solver import Solution, Solver
-from libecalc.domain.process.process_system.process_error import ProcessError, RateTooHighError, RateTooLowError
+from libecalc.domain.process.process_solver.solver import (
+    OutsideCapacityEvent,
+    Solution,
+    Solver,
+    SolverFailureStatus,
+    TargetNotAchievableEvent,
+)
+from libecalc.domain.process.process_system.process_error import RateTooHighError, RateTooLowError
 from libecalc.domain.process.value_objects.fluid_stream import FluidStream
 
 logger = logging.getLogger(__name__)
@@ -36,15 +42,39 @@ def get_outlet_stream(speed: float) -> FluidStream:
         max_speed_configuration = SpeedConfiguration(speed=self._boundary.max)
         try:
             maximum_speed_outlet_stream = func(max_speed_configuration)
-        except ProcessError as e:
+        except RateTooHighError as e:
+            logger.debug(f"No solution found for maximum speed: {max_speed_configuration}", exc_info=e)
+            return Solution(
+                success=False,
+                configuration=max_speed_configuration,
+                failure_event=OutsideCapacityEvent(
+                    status=SolverFailureStatus.ABOVE_MAXIMUM_FLOW_RATE,
+                    actual_value=e.actual_rate,
+                    boundary_value=e.boundary_rate,
+                ),
+            )
+        except RateTooLowError as e:
             logger.debug(f"No solution found for maximum speed: {max_speed_configuration}", exc_info=e)
             return Solution(
                 success=False,
                 configuration=max_speed_configuration,
+                failure_event=OutsideCapacityEvent(
+                    status=SolverFailureStatus.BELOW_MINIMUM_FLOW_RATE,
+                    actual_value=e.actual_rate,
+                    boundary_value=e.boundary_rate,
+                ),
             )
 
         if maximum_speed_outlet_stream.pressure_bara < self._target_pressure:
-            return Solution(success=False, configuration=SpeedConfiguration(self._boundary.max))
+            return Solution(
+                success=False,
+                configuration=SpeedConfiguration(self._boundary.max),
+                failure_event=TargetNotAchievableEvent(
+                    status=SolverFailureStatus.MAXIMUM_ACHIEVABLE_DISCHARGE_PRESSURE_BELOW_TARGET,
+                    achievable_value=maximum_speed_outlet_stream.pressure_bara,
+                    target_value=self._target_pressure,
+                ),
+            )
 
         try:
             minimum_speed_configuration = SpeedConfiguration(speed=self._boundary.min)
@@ -71,7 +101,15 @@ def bool_speed_func(x: float):
 
         if minimum_speed_outlet_stream.pressure_bara > self._target_pressure:
             # Solution 2, target pressure is too low
-            return Solution(success=False, configuration=minimum_speed_configuration)
+            return Solution(
+                success=False,
+                configuration=minimum_speed_configuration,
+                failure_event=TargetNotAchievableEvent(
+                    status=SolverFailureStatus.MINIMUM_ACHIEVABLE_DISCHARGE_PRESSURE_ABOVE_TARGET,
+                    achievable_value=minimum_speed_outlet_stream.pressure_bara,
+                    target_value=self._target_pressure,
+                ),
+            )
 
         assert (
             minimum_speed_outlet_stream.pressure_bara

src/libecalc/domain/process/process_solver/solvers/upstream_choke_solver.py

@@ -2,7 +2,12 @@
 
 from libecalc.domain.process.process_solver.boundary import Boundary
 from libecalc.domain.process.process_solver.search_strategies import RootFindingStrategy
-from libecalc.domain.process.process_solver.solver import Solution, Solver
+from libecalc.domain.process.process_solver.solver import (
+    Solution,
+    Solver,
+    SolverFailureStatus,
+    TargetNotAchievableEvent,
+)
 from libecalc.domain.process.process_system.process_error import RateTooHighError
 from libecalc.domain.process.value_objects.fluid_stream import FluidStream
 
@@ -45,9 +50,18 @@ def outlet_pressure(config: ChokeConfiguration) -> float:
 
         # Evaluate outlet pressure at maximum allowed upstream ΔP (within boundary).
         max_cfg = ChokeConfiguration(delta_pressure=self._delta_pressure_boundary.max)
-        if outlet_pressure(max_cfg) > self._target_pressure:
+        max_cfg_pressure = outlet_pressure(max_cfg)
+        if max_cfg_pressure > self._target_pressure:
             # If we are still above target even at max choking, then no solution exists within the boundary.
-            return Solution(success=False, configuration=max_cfg)
+            return Solution(
+                success=False,
+                configuration=max_cfg,
+                failure_event=TargetNotAchievableEvent(
+                    status=SolverFailureStatus.MINIMUM_ACHIEVABLE_DISCHARGE_PRESSURE_ABOVE_TARGET,
+                    achievable_value=max_cfg_pressure,
+                    target_value=self._target_pressure,
+                ),
+            )
 
         pressure_change = self._root_finding_strategy.find_root(
             boundary=self._delta_pressure_boundary,