feat(libecalc): handle unachievable outlet fluid states

Compressor catches CompressorThermodynamicCalculationError and wraps it as
OutletFluidNotAchievableError with operating-point context. ShaftSpeedFinder
and PipelineSectionSolver handle the new failure type.

Author: olelod

src/libecalc/process/process_pipeline/process_error.py

@@ -1,7 +1,21 @@
+from dataclasses import dataclass
+
 from libecalc.common.errors.exceptions import EcalcError
 from libecalc.process.process_pipeline.process_unit import ProcessUnitId
 
 
+@dataclass(frozen=True)
+class CompressorOperatingPoint:
+    """Context about the compressor state when a failure occurred."""
+
+    inlet_pressure_bara: float
+    inlet_temperature_kelvin: float
+    actual_rate_m3_per_hour: float
+    polytropic_head_joule_per_kg: float
+    polytropic_efficiency: float
+    speed: float
+
+
 class ProcessError(EcalcError):
     def __init__(self, reason: str | None = None):
         self.reason = reason
@@ -92,3 +106,21 @@ def __init__(
             f"Inlet pressure {inlet_pressure_bara:.3f} bara is insufficient for required pressure drop "
             f"{required_delta_pressure_bara:.3f} bara."
         )
+
+
+class OutletFluidNotAchievableError(ProcessError):
+    """The compressor's EOS calculation could not produce a valid outlet stream.
+
+    This occurs when the thermodynamic flash at the computed outlet conditions
+    fails to converge, indicating a physically unachievable state.
+    """
+
+    def __init__(
+        self,
+        process_unit_id: ProcessUnitId,
+        unachievable_operating_point: CompressorOperatingPoint,
+        reason: str = "Outlet fluid state is not achievable.",
+    ):
+        self.process_unit_id = process_unit_id
+        self.unachievable_operating_point = unachievable_operating_point
+        super().__init__(reason)

src/libecalc/process/process_solver/finders/shaft_speed_finder.py

@@ -3,14 +3,19 @@
 
 from libecalc.domain.process.compressor.core.exceptions import CompressorThermodynamicCalculationError
 from libecalc.process.fluid_stream.fluid_stream import FluidStream
-from libecalc.process.process_pipeline.process_error import CompressorStonewallError, CompressorSurgeError
+from libecalc.process.process_pipeline.process_error import (
+    CompressorStonewallError,
+    CompressorSurgeError,
+    OutletFluidNotAchievableError,
+)
 from libecalc.process.process_solver.boundary import Boundary
 from libecalc.process.process_solver.configuration import SpeedConfiguration
 from libecalc.process.process_solver.finder import Finder, Finding
 from libecalc.process.process_solver.search_strategies import Bisect, BisectResult, RootFindingStrategy
 from libecalc.process.process_solver.solver import (
     CompressorStonewallFailure,
     CompressorSurgeFailure,
+    OutletFluidNotAchievableFailure,
     TargetDirection,
     TargetPressureUnreachableFailure,
     ThermodynamicCalculationFailure,
@@ -60,6 +65,23 @@ def find(self, func: Callable[[SpeedConfiguration], FluidStream]) -> Finding[Spe
                 boundary=Boundary(min=self._boundary.min, max=valid_max),
                 target_pressure=self._target_pressure,
             ).find(func)
+        except OutletFluidNotAchievableError as e:
+            logger.debug(
+                "Outlet fluid not achievable at max speed %.1f rpm; searching for highest valid speed.",
+                self._boundary.max,
+            )
+            valid_max = self._search_strategy.highest_true(self._boundary, lambda speed: self._eos_ok(func, speed))
+            if valid_max is None:
+                return Finding(
+                    configuration=max_speed_configuration,
+                    failure=OutletFluidNotAchievableFailure.from_error(e),
+                )
+            return ShaftSpeedFinder(
+                search_strategy=self._search_strategy,
+                root_finding_strategy=self._root_finding_strategy,
+                boundary=Boundary(min=self._boundary.min, max=valid_max),
+                target_pressure=self._target_pressure,
+            ).find(func)
 
         if maximum_speed_outlet_stream.pressure_bara < self._target_pressure:
             return Finding(
@@ -116,30 +138,39 @@ def _eos_ok(func: Callable[[SpeedConfiguration], FluidStream], speed: float) ->
         try:
             func(SpeedConfiguration(speed=speed))
             return True
-        except (CompressorThermodynamicCalculationError, CompressorStonewallError, CompressorSurgeError):
+        except (
+            CompressorThermodynamicCalculationError,
+            OutletFluidNotAchievableError,
+            CompressorStonewallError,
+            CompressorSurgeError,
+        ):
             return False
 
     def _find_min_within_capacity_speed(
         self, func: Callable[[SpeedConfiguration], FluidStream]
     ) -> tuple[SpeedConfiguration, FluidStream]:
         """Return the lowest speed configuration within flow capacity, and its outlet stream.
 
-        ``CompressorStonewallError`` and ``CompressorThermodynamicCalculationError`` at the boundary
-        minimum are recoverable: higher speed raises the stonewall limit or enters the valid
-        EOS range; search upward.
+        ``CompressorStonewallError``, ``OutletFluidNotAchievableError``, and
+        ``CompressorThermodynamicCalculationError`` at the boundary minimum are recoverable:
+        higher speed raises the stonewall limit or enters the valid EOS range; search upward.
         """
         minimum_speed_configuration = SpeedConfiguration(speed=self._boundary.min)
         try:
             minimum_result = func(minimum_speed_configuration)
             return minimum_speed_configuration, minimum_result
-        except (CompressorStonewallError, CompressorThermodynamicCalculationError) as e:
+        except (CompressorStonewallError, CompressorThermodynamicCalculationError, OutletFluidNotAchievableError) as e:
             logger.debug(f"No solution found for minimum speed: {self._boundary.min}", exc_info=e)
 
             def bool_speed_func(x: float) -> BisectResult:
                 try:
                     func(SpeedConfiguration(speed=x))
                     return BisectResult(higher=False, accepted=True)
-                except (CompressorStonewallError, CompressorThermodynamicCalculationError):
+                except (
+                    CompressorStonewallError,
+                    CompressorThermodynamicCalculationError,
+                    OutletFluidNotAchievableError,
+                ):
                     return BisectResult(higher=True, accepted=False)
                 except CompressorSurgeError:
                     return BisectResult(higher=False, accepted=False)

src/libecalc/process/process_solver/pipeline_section_solver.py

@@ -18,6 +18,7 @@
     CompressorStonewallFailure,
     CompressorSurgeFailure,
     ConvergenceFailure,
+    OutletFluidNotAchievableFailure,
     Solution,
     TargetDirection,
     TargetPressureUnreachableFailure,
@@ -112,7 +113,13 @@ def _find_solution(
         )
 
         if isinstance(
-            speed_finding.failure, (CompressorStonewallFailure, CompressorSurgeFailure, ThermodynamicCalculationFailure)
+            speed_finding.failure,
+            (
+                CompressorStonewallFailure,
+                CompressorSurgeFailure,
+                ThermodynamicCalculationFailure,
+                OutletFluidNotAchievableFailure,
+            ),
         ):
             return Solution(configuration=[shaft_config], failure=speed_finding.failure)
 

src/libecalc/process/process_solver/solver.py

@@ -10,11 +10,13 @@
 from libecalc.domain.process.compressor.core.exceptions import CompressorThermodynamicCalculationError
 from libecalc.process.fluid_stream.fluid_stream import FluidStream
 from libecalc.process.process_pipeline.process_error import (
+    CompressorOperatingPoint,
     CompressorStonewallError,
     CompressorSurgeError,
     InsufficientInletPressureError,
     LiquidAtInletError,
     OfftakeExceedsInletError,
+    OutletFluidNotAchievableError,
     ProcessError,
 )
 from libecalc.process.process_pipeline.process_pipeline import ProcessPipelineId, ProcessPipelineSectionId
@@ -74,6 +76,21 @@ class ThermodynamicCalculationFailure(SolverFailure):
     reason: str = ""
 
 
+@dataclass
+class OutletFluidNotAchievableFailure(SolverFailure):
+    """The compressor EOS calculation could not produce a valid outlet stream."""
+
+    process_unit_id: ProcessUnitId | None = None
+    operating_point: CompressorOperatingPoint | None = None
+
+    @classmethod
+    def from_error(cls, e: OutletFluidNotAchievableError) -> Self:
+        return cls(
+            process_unit_id=e.process_unit_id,
+            operating_point=e.unachievable_operating_point,
+        )
+
+
 @dataclass
 class ConvergenceFailure(SolverFailure):
     reason: str = ""
@@ -136,6 +153,8 @@ def process_error_to_failure(e: ProcessError) -> SolverFailure:
             inlet_pressure_bara=e.inlet_pressure_bara,
             required_delta_pressure_bara=e.required_delta_pressure_bara,
         )
+    if isinstance(e, OutletFluidNotAchievableError):
+        return OutletFluidNotAchievableFailure.from_error(e)
     if isinstance(e, CompressorThermodynamicCalculationError):
         return ThermodynamicCalculationFailure(reason=str(e))
     if isinstance(e, CompressorStonewallError):

src/libecalc/process/process_units/compressor.py

@@ -1,6 +1,7 @@
 from typing import Final
 
 from libecalc.common.ddd import value_object
+from libecalc.domain.process.compressor.core.exceptions import CompressorThermodynamicCalculationError
 from libecalc.domain.process.compressor.core.train.utils.common import (
     RECIRCULATION_BOUNDARY_TOLERANCE,
     calculate_outlet_pressure_and_stream,
@@ -11,9 +12,11 @@
 from libecalc.process.fluid_stream.fluid_service import FluidService
 from libecalc.process.fluid_stream.fluid_stream import FluidStream
 from libecalc.process.process_pipeline.process_error import (
+    CompressorOperatingPoint,
     CompressorStonewallError,
     CompressorSurgeError,
     LiquidAtInletError,
+    OutletFluidNotAchievableError,
 )
 from libecalc.process.process_pipeline.process_unit import ProcessUnit, ProcessUnitId
 from libecalc.process.process_solver.boundary import Boundary
@@ -63,12 +66,25 @@ def propagate_stream(self, inlet_stream: FluidStream) -> FluidStream:
 
         operational_point: OperationalPoint = self.get_operational_point(inlet_stream=inlet_stream)
 
-        return calculate_outlet_pressure_and_stream(
-            polytropic_efficiency=operational_point.polytropic_efficiency,
-            polytropic_head_joule_per_kg=operational_point.polytropic_head_joule_per_kg,
-            inlet_stream=inlet_stream,
-            fluid_service=self._fluid_service,
-        )
+        try:
+            return calculate_outlet_pressure_and_stream(
+                polytropic_efficiency=operational_point.polytropic_efficiency,
+                polytropic_head_joule_per_kg=operational_point.polytropic_head_joule_per_kg,
+                inlet_stream=inlet_stream,
+                fluid_service=self._fluid_service,
+            )
+        except CompressorThermodynamicCalculationError as exc:
+            raise OutletFluidNotAchievableError(
+                process_unit_id=self._id,
+                unachievable_operating_point=CompressorOperatingPoint(
+                    inlet_pressure_bara=inlet_stream.pressure_bara,
+                    inlet_temperature_kelvin=inlet_stream.temperature_kelvin,
+                    actual_rate_m3_per_hour=operational_point.actual_rate_am3_h,
+                    polytropic_head_joule_per_kg=operational_point.polytropic_head_joule_per_kg,
+                    polytropic_efficiency=operational_point.polytropic_efficiency,
+                    speed=self.speed,
+                ),
+            ) from exc
 
     def get_operational_point(self, inlet_stream: FluidStream) -> OperationalPoint:
         """

tests/libecalc/process/process_units/test_compressor.py

@@ -105,3 +105,31 @@ def test_recirculation_range_min_positive_when_below_surge(self, stream_factory,
         )
         boundary = compressor.get_recirculation_range(inlet_stream=inlet)
         assert boundary.min > 0.0
+
+
+class TestCompressorEOSFailure:
+    def test_raises_outlet_fluid_not_achievable_on_eos_failure(self, stream_factory, compressor, shaft):
+        """When the EOS cannot compute an outlet stream, OutletFluidNotAchievableError is raised
+        with the operating-point context attached."""
+        from unittest.mock import patch
+
+        from libecalc.domain.process.compressor.core.exceptions import CompressorThermodynamicCalculationError
+        from libecalc.process.process_pipeline.process_error import OutletFluidNotAchievableError
+
+        speed = (shaft.get_speed_boundary().min + shaft.get_speed_boundary().max) / 2
+        shaft.set_speed(speed)
+        inlet = _inlet_at_midpoint(stream_factory, compressor)
+
+        with patch(
+            "libecalc.process.process_units.compressor.calculate_outlet_pressure_and_stream",
+            side_effect=CompressorThermodynamicCalculationError(operation="flash", reason="flash failed"),
+        ):
+            with pytest.raises(OutletFluidNotAchievableError) as exc_info:
+                compressor.propagate_stream(inlet_stream=inlet)
+
+            error = exc_info.value
+            assert error.process_unit_id == compressor.get_id()
+            op = error.unachievable_operating_point
+            assert op.inlet_pressure_bara == inlet.pressure_bara
+            assert op.speed == speed
+            assert op.actual_rate_m3_per_hour > 0