update class docs

scripts/build_cop_profiles/BaseCopApproximator.py

@@ -14,6 +14,24 @@ class BaseCopApproximator(ABC):
     """
     Abstract class for approximating the coefficient of performance (COP) of a
     heat pump.
+
+    Attributes:
+    ----------
+    forward_temperature_celsius : Union[xr.DataArray, np.array]
+        The forward temperature in Celsius.
+    source_inlet_temperature_celsius : Union[xr.DataArray, np.array]
+        The source inlet temperature in Celsius.
+
+    Methods:
+    -------
+    __init__(self, forward_temperature_celsius, source_inlet_temperature_celsius)
+        Initialize CopApproximator.
+    approximate_cop(self)
+        Approximate heat pump coefficient of performance (COP).
+    celsius_to_kelvin(t_celsius)
+        Convert temperature from Celsius to Kelvin.
+    logarithmic_mean(t_hot, t_cold)
+        Calculate the logarithmic mean temperature difference.
     """
 
     def __init__(
@@ -28,8 +46,8 @@ class BaseCopApproximator(ABC):
         ----------
         forward_temperature_celsius : Union[xr.DataArray, np.array]
             The forward temperature in Celsius.
-        return_temperature_celsius : Union[xr.DataArray, np.array]
+        source_inlet_temperature_celsius : Union[xr.DataArray, np.array]
-            The return temperature in Celsius.
+            The source inlet temperature in Celsius.
         """
         pass
 
@@ -49,6 +67,19 @@ class BaseCopApproximator(ABC):
     def celsius_to_kelvin(
         t_celsius: Union[float, xr.DataArray, np.array]
     ) -> Union[float, xr.DataArray, np.array]:
+        """
+        Convert temperature from Celsius to Kelvin.
+
+        Parameters:
+        ----------
+        t_celsius : Union[float, xr.DataArray, np.array]
+            Temperature in Celsius.
+
+        Returns:
+        -------
+        Union[float, xr.DataArray, np.array]
+            Temperature in Kelvin.
+        """
         if (np.asarray(t_celsius) > 200).any():
             raise ValueError(
                 "t_celsius > 200. Are you sure you are using the right units?"
@@ -60,6 +91,21 @@ class BaseCopApproximator(ABC):
         t_hot: Union[float, xr.DataArray, np.ndarray],
         t_cold: Union[float, xr.DataArray, np.ndarray],
     ) -> Union[float, xr.DataArray, np.ndarray]:
+        """
+        Calculate the logarithmic mean temperature difference.
+
+        Parameters:
+        ----------
+        t_hot : Union[float, xr.DataArray, np.ndarray]
+            Hot temperature.
+        t_cold : Union[float, xr.DataArray, np.ndarray]
+            Cold temperature.
+
+        Returns:
+        -------
+        Union[float, xr.DataArray, np.ndarray]
+            Logarithmic mean temperature difference.
+        """
         if (np.asarray(t_hot <= t_cold)).any():
             raise ValueError("t_hot must be greater than t_cold")
         return (t_hot - t_cold) / np.log(t_hot / t_cold)

scripts/build_cop_profiles/CentralHeatingCopApproximator.py

@@ -20,8 +20,77 @@ class CentralHeatingCopApproximator(BaseCopApproximator):
     default parameters from Pieper et al. (2020). The method is based on
     a thermodynamic heat pump model with some hard-to-know parameters
     being approximated.
-    """
 
+    Attributes:
+    ----------
+    forward_temperature_celsius : Union[xr.DataArray, np.array]
+        The forward temperature in Celsius.
+    return_temperature_celsius : Union[xr.DataArray, np.array]
+        The return temperature in Celsius.
+    source_inlet_temperature_celsius : Union[xr.DataArray, np.array]
+        The source inlet temperature in Celsius.
+    source_outlet_temperature_celsius : Union[xr.DataArray, np.array]
+        The source outlet temperature in Celsius.
+    delta_t_pinch_point : float, optional
+        The pinch point temperature difference, by default 5.
+    isentropic_compressor_efficiency : float, optional
+        The isentropic compressor efficiency, by default 0.8.
+    heat_loss : float, optional
+        The heat loss, by default 0.0.
+
+    Methods:
+    -------
+    __init__(
+        forward_temperature_celsius: Union[xr.DataArray, np.array],
+        source_inlet_temperature_celsius: Union[xr.DataArray, np.array],
+        return_temperature_celsius: Union[xr.DataArray, np.array],
+        source_outlet_temperature_celsius: Union[xr.DataArray, np.array],
+        delta_t_pinch_point: float = 5,
+        isentropic_compressor_efficiency: float = 0.8,
+        heat_loss: float = 0.0,
+    ) -> None:
+        Initializes the CentralHeatingCopApproximator object.
+
+    approximate_cop(self) -> Union[xr.DataArray, np.array]:
+        Calculate the coefficient of performance (COP) for the system.
+
+    _approximate_delta_t_refrigerant_source(
+        self, delta_t_source: Union[xr.DataArray, np.array]
+    ) -> Union[xr.DataArray, np.array]:
+        Approximates the temperature difference between the refrigerant and the source.
+
+    _approximate_delta_t_refrigerant_sink(
+        self,
+        refrigerant: str = "ammonia",
+        a: float = {"ammonia": 0.2, "isobutane": -0.0011},
+        b: float = {"ammonia": 0.2, "isobutane": 0.3},
+        c: float = {"ammonia": 0.016, "isobutane": 2.4},
+    ) -> Union[xr.DataArray, np.array]:
+        Approximates the temperature difference between the refrigerant and heat sink.
+
+    _ratio_evaporation_compression_work_approximation(
+        self,
+        refrigerant: str = "ammonia",
+        a: float = {"ammonia": 0.0014, "isobutane": 0.0035},
+    ) -> Union[xr.DataArray, np.array]:
+        Calculate the ratio of evaporation to compression work based on approximation.
+
+    _approximate_delta_t_refrigerant_sink(
+        self,
+        refrigerant: str = "ammonia",
+        a: float = {"ammonia": 0.2, "isobutane": -0.0011},
+        b: float = {"ammonia": 0.2, "isobutane": 0.3},
+        c: float = {"ammonia": 0.016, "isobutane": 2.4},
+    ) -> Union[xr.DataArray, np.array]:
+        Approximates the temperature difference between the refrigerant and heat sink.
+
+    _ratio_evaporation_compression_work_approximation(
+        self,
+        refrigerant: str = "ammonia",
+        a: float = {"ammonia": 0.0014, "isobutane": 0.0035},
+    ) -> Union[xr.DataArray, np.array]:
+        Calculate the ratio of evaporation to compression work based on approximation.
+    """
     def __init__(
         self,
         forward_temperature_celsius: Union[xr.DataArray, np.array],
@@ -33,6 +102,7 @@ class CentralHeatingCopApproximator(BaseCopApproximator):
         heat_loss: float = 0.0,
     ) -> None:
         """
+        Initializes the CentralHeatingCopApproximator object.
 
         Parameters:
         ----------
@@ -74,6 +144,7 @@ class CentralHeatingCopApproximator(BaseCopApproximator):
         Calculate the coefficient of performance (COP) for the system.
 
         Returns:
+        --------
             Union[xr.DataArray, np.array]: The calculated COP values.
         """
         return (

scripts/build_cop_profiles/DecentralHeatingCopApproximator.py

@@ -16,7 +16,27 @@ class DecentralHeatingCopApproximator(BaseCopApproximator):
     Approximate the coefficient of performance (COP) for a heat pump in a
     decentral heating system (individual/household heating).
 
-    Uses a quadratic regression on the temperature difference between the source and sink based on empirical data proposed by Staffell et al. 2012 .
+    Uses a quadratic regression on the temperature difference between the source and sink based on empirical data proposed by Staffell et al. 2012.
+
+    Attributes
+    ----------
+    forward_temperature_celsius : Union[xr.DataArray, np.array]
+        The forward temperature in Celsius.
+    source_inlet_temperature_celsius : Union[xr.DataArray, np.array]
+        The source inlet temperature in Celsius.
+    source_type : str
+        The source of the heat pump. Must be either 'air' or 'ground'.
+
+    Methods
+    -------
+    __init__(forward_temperature_celsius, source_inlet_temperature_celsius, source_type)
+        Initialize the DecentralHeatingCopApproximator object.
+    approximate_cop()
+        Compute the COP values using quadratic regression for air-/ground-source heat pumps.
+    _approximate_cop_air_source()
+        Evaluate quadratic regression for an air-sourced heat pump.
+    _approximate_cop_ground_source()
+        Evaluate quadratic regression for a ground-sourced heat pump.
 
     References
     ----------
@@ -30,30 +50,32 @@ class DecentralHeatingCopApproximator(BaseCopApproximator):
         source_type: str,
     ):
         """
-        Initialize the COPProfileBuilder object.
+        Initialize the DecentralHeatingCopApproximator object.
 
-        Parameters:
+        Parameters
         ----------
         forward_temperature_celsius : Union[xr.DataArray, np.array]
             The forward temperature in Celsius.
-        return_temperature_celsius : Union[xr.DataArray, np.array]
+        source_inlet_temperature_celsius : Union[xr.DataArray, np.array]
-            The return temperature in Celsius.
+            The source inlet temperature in Celsius.
-        source: str
+        source_type : str
-            The source of the heat pump. Must be either 'air' or 'ground'
+            The source of the heat pump. Must be either 'air' or 'ground'.
         """
 
         self.delta_t = forward_temperature_celsius - source_inlet_temperature_celsius
         if source_type not in ["air", "ground"]:
-            raise ValueError("'source' must be one of ['air', 'ground']")
+            raise ValueError("'source_type' must be one of ['air', 'ground']")
         else:
             self.source_type = source_type
 
     def approximate_cop(self) -> Union[xr.DataArray, np.array]:
         """
-        Compute output of quadratic regression for air-/ground-source heat
+        Compute the COP values using quadratic regression for air-/ground-source heat pumps.
-        pumps.
 
-        Calls the appropriate method depending on `source`.
+        Returns
+        -------
+        Union[xr.DataArray, np.array]
+            The calculated COP values.
         """
         if self.source_type == "air":
             return self._approximate_cop_air_source()