refactor: imrpove naming and documentation

src/ecalc/libraries/libecalc/common/libecalc/core/models/compressor/train/fluid.py

@@ -10,9 +10,12 @@
 
 
 class FluidStream:
-    """Currently just a dataclass with a set composition.
+    """Fluid interface used in eCalc compressor train simulation
 
-    Keep as separate layer until having different initialization options to set composition
+    TODO:
+        - [x] Remove NeqSimFluid as class member
+        - [ ] Remove connections to NeqSimFluid
+        - [ ] Separate init methods based on config. To enable eCalc to be agnostick EoS package backend (NeqSim, ML, thermo(?))
     """
 
     def __init__(
@@ -22,6 +25,14 @@ def __init__(
         temperature_kelvin: float = UnitConstants.STANDARD_TEMPERATURE_KELVIN,
         existing_fluid: Optional[NeqsimFluid] = None,
     ):
+        """
+
+        Args:
+            fluid_model: Describes fluid composition and EoS model
+            pressure_bara: Pressure of fluid [bara]
+            temperature_kelvin: Temperature of fluid [K]
+            existing_fluid: Initialize FluidStream from an existing (NeqSim) fluid. Warning: Be mindful of keeping fluid_model and existing fluid consistent. If not the fluid properties may be incorrect.
+        """
         self.fluid_model = fluid_model
         self.initial_temperature_kelvin = temperature_kelvin
         self.initial_pressure_bare = pressure_bara
@@ -87,10 +98,19 @@ def z(self) -> float:
     def enthalpy_joule_per_kg(self) -> float:
         return self._enthalpy_joule_per_kg
 
-    def standard_to_mass_rate(
+    def standard_rate_to_mass_rate(
         self, standard_rates: Union[NDArray[np.float64], float]
     ) -> Union[NDArray[np.float64], float]:
-        """Sm3/day to kg/h. Standard conditions are 15C at 1atm = 1.01325 bara."""
+        """Convert standard rate [Sm3/day] to mass rate [kg/h].
+
+        Use standard conditions are 15C at 1atm = 1.01325 bara for fluid density.
+
+        Args:
+            standard_rates: List or single rate(s) to convert [Sm3/day]
+
+        Returns:
+            List or single standard rate(s) [kg/h]
+        """
         mass_rate_kg_per_hour = standard_rates * self.standard_conditions_density / UnitConstants.HOURS_PER_DAY
         if isinstance(mass_rate_kg_per_hour, np.ndarray):
             return np.array(mass_rate_kg_per_hour)
@@ -139,7 +159,7 @@ def get_fluid_streams(
 
         Args:
             pressure_bara: array of pressures [bara]
-            temperature_kelvin: array of temperatures [kelvin]
+            temperature_kelvin: array of temperatures [K]
 
         Returns:
             List of fluid streams at set temperatures and pressures
@@ -155,6 +175,19 @@ def get_fluid_streams(
     def set_new_pressure_and_temperature(
         self, new_pressure_bara: float, new_temperature_kelvin: float, remove_liquid: bool = True
     ) -> FluidStream:
+        """Get a new fluid with changed pressure and temperature.
+
+        This is a wrapper of a TP-flash
+
+        Args:
+            new_pressure_bara: Pressure setpoint of new fluid [bara]
+            new_temperature_kelvin: Temperature setpoint of new fluid [K]
+            remove_liquid: If true the new fluid will be forced to be single phase (Gas), defaults to true
+
+        Returns:
+            New fluid stream flashed to a new temperature and pressure setpoint
+
+        """
         fluid_stream = NeqsimFluid.create_thermo_system(
             composition=self.fluid_model.composition,
             temperature_kelvin=self.temperature_kelvin,
@@ -172,6 +205,19 @@ def set_new_pressure_and_temperature(
     def set_new_pressure_and_enthalpy_change(
         self, new_pressure: float, enthalpy_change_joule_per_kg: float, remove_liquid: bool = True
     ) -> FluidStream:
+        """Get a new fluid with changed pressure and changed enthalpy.
+
+        This is a wrapper of a PH-flash
+
+        Args:
+            new_pressure: Pressure setpoint of new fluid [bara]
+            enthalpy_change_joule_per_kg: Change in enthalpy perfomed on new fluid [J/kg]
+            remove_liquid: If true the new fluid will be forced to be single phase (Gas), defaults to true
+
+        Returns:
+            Mew fluid stream flashed to a new pressure and changed enthalpy
+
+        """
         fluid_stream = NeqsimFluid.create_thermo_system(
             composition=self.fluid_model.composition,
             temperature_kelvin=self.temperature_kelvin,

src/ecalc/libraries/libecalc/common/libecalc/core/models/compressor/train/simplified_train.py

@@ -123,7 +123,7 @@ def _evaluate_rate_ps_pd(
             suction_pressure=suction_pressure, discharge_pressure=discharge_pressure
         )
 
-        mass_rate_kg_per_hour = self.fluid.standard_to_mass_rate(standard_rates=rate)
+        mass_rate_kg_per_hour = self.fluid.standard_rate_to_mass_rate(standard_rates=rate)
         compressor_stages_result_per_time_step = []
         inlet_pressure = suction_pressure.copy()
         for stage in self.stages:

src/ecalc/libraries/libecalc/common/libecalc/core/models/compressor/train/single_speed_compressor_train_common_shaft.py

@@ -136,7 +136,7 @@ def _evaluate_rate_ps_pd(
                     f"larger than maximum allowed discharge pressure in single speed compressor model"
                     f" ({self.maximum_discharge_pressure})"
                 )
-        mass_rates_kg_per_hour = self.fluid.standard_to_mass_rate(standard_rates=rate)
+        mass_rates_kg_per_hour = self.fluid.standard_rate_to_mass_rate(standard_rates=rate)
         if self.pressure_control == FixedSpeedPressureControl.DOWNSTREAM_CHOKE:
             train_results = self._evaluate_train_results_and_failure_status_downstream_choking(
                 mass_rates_kg_per_hour=mass_rates_kg_per_hour,

src/ecalc/libraries/libecalc/common/libecalc/core/models/compressor/train/variable_speed_compressor_train_common_shaft.py

@@ -79,7 +79,7 @@ def _evaluate_rate_ps_pd(
         suction_pressure: NDArray[np.float64],
         discharge_pressure: NDArray[np.float64],
     ) -> List[CompressorTrainResultSingleTimeStep]:
-        mass_rate_kg_per_hour = self.fluid.standard_to_mass_rate(standard_rates=rate)
+        mass_rate_kg_per_hour = self.fluid.standard_rate_to_mass_rate(standard_rates=rate)
 
         # Iterate over input points, calculate one by one
         train_results: List[CompressorTrainResultSingleTimeStep] = []

src/ecalc/libraries/libecalc/common/libecalc/core/models/compressor/train/variable_speed_compressor_train_common_shaft_multiple_streams_and_pressures.py

@@ -824,7 +824,9 @@ def calculate_compressor_train_given_rate_ps_speed(
             pressure_bara=inlet_pressure_bara,
             temperature_kelvin=self.stages[0].inlet_temperature_kelvin,
         )
-        mass_rate_this_stage_kg_per_hour = inlet_stream.standard_to_mass_rate(std_rates_std_m3_per_day_per_stream[0])
+        mass_rate_this_stage_kg_per_hour = inlet_stream.standard_rate_to_mass_rate(
+            std_rates_std_m3_per_day_per_stream[0]
+        )
         mass_rate_previous_stage_kg_per_hour = 0
         previous_outlet_stream = None
 
@@ -836,7 +838,7 @@ def calculate_compressor_train_given_rate_ps_speed(
             # assume that volume/mass is always taken out before additional volume/mass is potentially added, no matter
             # what order the streams are defined in in the yaml file
             for stream_number in self.outlet_stream_connected_to_stage.get(stage_number):
-                mass_rate_this_stage_kg_per_hour -= inlet_stream.standard_to_mass_rate(
+                mass_rate_this_stage_kg_per_hour -= inlet_stream.standard_rate_to_mass_rate(
                     std_rates_std_m3_per_day_per_stream[stream_number]
                 )
             for stream_number in self.inlet_stream_connected_to_stage.get(stage_number):
@@ -847,7 +849,7 @@ def calculate_compressor_train_given_rate_ps_speed(
                         pressure_bara=inlet_stream.pressure_bara,
                         temperature_kelvin=inlet_stream.temperature_kelvin,
                     )
-                    mass_rate_additional_inlet_stream_kg_per_hour = additional_inlet_stream.standard_to_mass_rate(
+                    mass_rate_additional_inlet_stream_kg_per_hour = additional_inlet_stream.standard_rate_to_mass_rate(
                         float(std_rates_std_m3_per_day_per_stream[stream_number])
                     )
 
@@ -1098,7 +1100,7 @@ def _update_inlet_fluid_and_std_rates_for_last_subtrain(
             temperature_kelvin=self.stages[0].inlet_temperature_kelvin,
         )
         inlet_std_rate = float(std_rates_std_m3_per_day_per_stream[0])
-        inlet_mass_rate = inlet_stream.standard_to_mass_rate(inlet_std_rate)
+        inlet_mass_rate = inlet_stream.standard_rate_to_mass_rate(inlet_std_rate)
 
         # take mass out before potential mixing with additional ingoing stream
         # assume that volume/mass is always taken out before additional volume/mass is potentially added, no matter
@@ -1112,7 +1114,7 @@ def _update_inlet_fluid_and_std_rates_for_last_subtrain(
                     pressure_bara=inlet_pressure,
                     temperature_kelvin=self.stages[0].inlet_temperature_kelvin,
                 )
-                mass_rate_additional_inlet_stream = additional_inlet_stream.standard_to_mass_rate(
+                mass_rate_additional_inlet_stream = additional_inlet_stream.standard_rate_to_mass_rate(
                     float(std_rates_std_m3_per_day_per_stream[stream_number])
                 )
                 # mix streams to get inlet stream for first compressor stage
@@ -1124,7 +1126,7 @@ def _update_inlet_fluid_and_std_rates_for_last_subtrain(
                     pressure_bara=additional_inlet_stream.pressure_bara,
                 )
                 inlet_std_rate += std_rates_std_m3_per_day_per_stream[stream_number]
-                inlet_mass_rate = inlet_stream.standard_to_mass_rate(inlet_std_rate)
+                inlet_mass_rate = inlet_stream.standard_rate_to_mass_rate(inlet_std_rate)
 
         # update inlet fluid for the subtrain with new composition
         updated_inlet_fluid = FluidStream(fluid_model=inlet_stream.fluid_model)