update class docs

2024-07-31 17:01:27 +02:00 · 2024-07-31 17:01:27 +02:00 · caa260fddb
commit caa260fddb
parent 4362300dce
3 changed files with 153 additions and 14 deletions
--- a/scripts/build_cop_profiles/BaseCopApproximator.py
+++ b/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]
-            The return temperature in Celsius.
+        source_inlet_temperature_celsius : Union[xr.DataArray, np.array]
+            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)
--- a/scripts/build_cop_profiles/CentralHeatingCopApproximator.py
+++ b/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 (
--- a/scripts/build_cop_profiles/DecentralHeatingCopApproximator.py
+++ b/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]
-            The return temperature in Celsius.
-        source: str
-            The source of the heat pump. Must be either 'air' or 'ground'
+        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'.
        """

        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
-        pumps.
+        Compute the COP values using quadratic regression for air-/ground-source heat 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()