Started revising simplified heat tranfer methods.

src/topupheat/pipes/system.py

@@ -319,9 +319,6 @@ class SupplyReturnPipeSystem:
     # TODO: make it possible for the maximum specific pressure loss to be
     # expressed as a function of the fluid speed
     
-    # a) constant maximum specific pressure loss
-    # b) the maximum specific pressure loss as a function of the fluid speed
-    
     def rated_heat_capacity(self, recalculate: bool = False, **kwargs):
         if not hasattr(self, 'rhc') or recalculate or len(kwargs) != 0:
             if self.pipes_are_different:
@@ -561,33 +558,76 @@ class SupplyReturnPipeSystem:
         raise NotImplementedError
         
     # *************************************************************************
-        
+    # TODO: test all 3 modes (single input, list, list of lists,)
     def simplified_specific_heat_transfer_surroundings(
             self,
             specific_heat_transfer_coefficient: float or list,
             temperature_surroundings: float or list,
             unit_conversion_factor: float = 1.0
             ):
+        """
+        Calculates the specific heat transfer with the surroundings using a 
+        constant specific heat transfer coefficient.
 
-        # specific_heat_transfer_coefficient >> options
-        # temperature_surroundings >> temporal
+        Parameters
+        ----------
+        specific_heat_transfer_coefficient : float or list
+            The heat transfer coefficient per unit length. For non-vector mode,
+            it must be supplied a float or as a list with one value per time 
+            interval. For vector mode, it can be supplied as a list with one
+            value per option or, as a list with one list per option, each with
+            one value per time interval.
+        temperature_surroundings : float or list
+            The temperature of the surroundings, submitted per time interval.
+            If it concerns multiple time intervals, it must be submitted as a
+            list whose size is compatible with the other inputs.
+        unit_conversion_factor : float, optional
+            A factor to adjust the final units. The default is 1.0.
+
+        Raises
+        ------
+        TypeError
+            This error is raised if the combination of inputs is incompatible.
+
+        Returns
+        -------
+        out : float, list or list of lists
+            The specific heat transfer rate(s) based on the inputs.
+
+        """
         # determine if the inputs are for temporal vector/normal mode
         if isinstance(temperature_surroundings, Real):
+            # single u value: non-temporal vector mode
             temporal_vector_mode = False
         elif (type(temperature_surroundings) == list or 
               type(temperature_surroundings) == tuple):
+            # u values submitted a a list/tuple: temporal vector mode
             temporal_vector_mode = True
         else:
             raise ValueError('Incompatible inputs.')
             
-        # confirm inputs are consistent with vector/normal mode
+        # u:
+        # 1) non-vector mode, float = 1 option, 1 time interval
+        # 2) non-vector mode, list = 1 option, multiple time intervals
+        # 3) vector mode, list (options) = 
+        # 4) vector mode, list of lists = 
+        
+        # rule out impossible combinations
+        # 1) non-vector mode and inconsistent u/temperature types
+        # 2) non-vector mode and u values in a list that does not match the size of the temperature list
+        # 3) vector mode and size of list with u values does not match the number of options
+        # 4) vector mode and the number of u values per list does not match the number of time intervals
+        
         if ((not self.vector_mode and 
-             not isinstance(specific_heat_transfer_coefficient, Real)) or
-            (self.vector_mode and 
-             len(self.supply_temperature) < 1 or
-             len(specific_heat_transfer_coefficient) != self.number_options()
+             (type(specific_heat_transfer_coefficient) != type(temperature_surroundings) or 
+              len(specific_heat_transfer_coefficient) != len(temperature_surroundings))) or
+            (self.vector_mode and len(specific_heat_transfer_coefficient) != 0 and
+             (len(specific_heat_transfer_coefficient) != self.number_options() or
+              (type(specific_heat_transfer_coefficient[0]) == type(temperature_surroundings) and
+               len(specific_heat_transfer_coefficient[0]) != len(temperature_surroundings)))
              )
             ):
+            # all the aforementioned cases lead here
             raise TypeError('Inconsistent inputs.')
         
         if self.vector_mode:
@@ -655,6 +695,7 @@ class SupplyReturnPipeSystem:
             time_interval_duration: float or list,
             unit_conversion_factor: float = 1.0
             ):
+        
         """
         Calculates the heat transfer with the surroundings using a constant
         specific heat transfer coefficient.