docs: add and update old documentation, type hinting

cosipy/cpkernel/cosipy_core.py

@@ -16,15 +16,33 @@
 from cosipy.modules.surfaceTemperature import update_surface_temperature
 
 
-def init_empty_array_1d(nt: int):
+def init_nan_array_1d(nt: int) -> np.ndarray:
+    """Initialise and fill an array with NaNs.
+    
+    Args:
+        nt: Array size (time dimension).
+
+    Returns:
+        NaN array.
+    """
     if not Config.WRF_X_CSPY:
         x = np.full(nt, np.nan)
     else:
         x = None
 
     return x
 
-def init_empty_array_2d(nt: int, max_layers:int):
+
+def init_nan_array_2d(nt: int, max_layers: int) -> np.ndarray:
+    """Initialise and fill an array with NaNs.
+    
+    Args:
+        nt: Array's temporal resolution.
+        max_layers: Array's spatial resolution.
+
+    Returns:
+        2D NaN array.
+    """
     if not Config.WRF_X_CSPY and Config.full_field:
         x = np.full((nt, max_layers), np.nan)
     else:
@@ -72,57 +90,61 @@ def cosipy_core(DATA, indY, indX, GRID_RESTART=None, stake_names=None, stake_dat
     WRF_X_CSPY = Config.WRF_X_CSPY
 
     # Replace values from constants.py if coupled
+    # TODO: This only affects the current module scope instead of global.
     if WRF_X_CSPY:
         dt = int(DATA.DT.values)
         max_layers = int(DATA.max_layers.values)
         z = float(DATA.ZLVL.values)
 
 
-    nt = len(DATA.time.values)         #accessing DATA is expensive
-    # Local variables -- bypass local array creation for WRF_X_CSPY until more elegant solution is implemented
+    nt = len(DATA.time.values)  # accessing DATA is expensive
+    """
+    Local variables bypass local array creation for WRF_X_CSPY
+    TODO: Implement more elegant solution.
+    """
     if not WRF_X_CSPY:
-        _RRR = init_empty_array_1d(nt)
-        _RAIN = init_empty_array_1d(nt)
-        _SNOWFALL = init_empty_array_1d(nt)
-        _LWin = init_empty_array_1d(nt)
-        _LWout = init_empty_array_1d(nt)
-        _H = init_empty_array_1d(nt)
-        _LE = init_empty_array_1d(nt)
-        _B = init_empty_array_1d(nt)
-        _QRR = init_empty_array_1d(nt)
-        _MB = init_empty_array_1d(nt)
-        _surfMB = init_empty_array_1d(nt)
-        _MB = init_empty_array_1d(nt)
-        _Q = init_empty_array_1d(nt)
-        _SNOWHEIGHT = init_empty_array_1d(nt)
-        _TOTALHEIGHT = init_empty_array_1d(nt)
-        _TS = init_empty_array_1d(nt)
-        _ALBEDO = init_empty_array_1d(nt)
-        _ME = init_empty_array_1d(nt)
-        _intMB = init_empty_array_1d(nt)
-        _EVAPORATION = init_empty_array_1d(nt)
-        _SUBLIMATION = init_empty_array_1d(nt)
-        _CONDENSATION = init_empty_array_1d(nt)
-        _DEPOSITION = init_empty_array_1d(nt)
-        _REFREEZE = init_empty_array_1d(nt)
-        _NLAYERS = init_empty_array_1d(nt)
-        _subM = init_empty_array_1d(nt)
-        _Z0 = init_empty_array_1d(nt)
-        _surfM = init_empty_array_1d(nt)
-        _MOL = init_empty_array_1d(nt)
-        _new_snow_height = init_empty_array_1d(nt)
-        _new_snow_timestamp = init_empty_array_1d(nt)
-        _old_snow_timestamp = init_empty_array_1d(nt)
-
-        _LAYER_HEIGHT = init_empty_array_2d(nt, max_layers)
-        _LAYER_RHO = init_empty_array_2d(nt, max_layers)
-        _LAYER_T = init_empty_array_2d(nt, max_layers)
-        _LAYER_LWC = init_empty_array_2d(nt, max_layers)
-        _LAYER_CC = init_empty_array_2d(nt, max_layers)
-        _LAYER_POROSITY = init_empty_array_2d(nt, max_layers)
-        _LAYER_ICE_FRACTION = init_empty_array_2d(nt, max_layers)
-        _LAYER_IRREDUCIBLE_WATER = init_empty_array_2d(nt, max_layers)
-        _LAYER_REFREEZE = init_empty_array_2d(nt, max_layers)
+        _RRR = init_nan_array_1d(nt)
+        _RAIN = init_nan_array_1d(nt)
+        _SNOWFALL = init_nan_array_1d(nt)
+        _LWin = init_nan_array_1d(nt)
+        _LWout = init_nan_array_1d(nt)
+        _H = init_nan_array_1d(nt)
+        _LE = init_nan_array_1d(nt)
+        _B = init_nan_array_1d(nt)
+        _QRR = init_nan_array_1d(nt)
+        _MB = init_nan_array_1d(nt)
+        _surfMB = init_nan_array_1d(nt)
+        _MB = init_nan_array_1d(nt)
+        _Q = init_nan_array_1d(nt)
+        _SNOWHEIGHT = init_nan_array_1d(nt)
+        _TOTALHEIGHT = init_nan_array_1d(nt)
+        _TS = init_nan_array_1d(nt)
+        _ALBEDO = init_nan_array_1d(nt)
+        _ME = init_nan_array_1d(nt)
+        _intMB = init_nan_array_1d(nt)
+        _EVAPORATION = init_nan_array_1d(nt)
+        _SUBLIMATION = init_nan_array_1d(nt)
+        _CONDENSATION = init_nan_array_1d(nt)
+        _DEPOSITION = init_nan_array_1d(nt)
+        _REFREEZE = init_nan_array_1d(nt)
+        _NLAYERS = init_nan_array_1d(nt)
+        _subM = init_nan_array_1d(nt)
+        _Z0 = init_nan_array_1d(nt)
+        _surfM = init_nan_array_1d(nt)
+        _MOL = init_nan_array_1d(nt)
+        _new_snow_height = init_nan_array_1d(nt)
+        _new_snow_timestamp = init_nan_array_1d(nt)
+        _old_snow_timestamp = init_nan_array_1d(nt)
+
+        _LAYER_HEIGHT = init_nan_array_2d(nt, max_layers)
+        _LAYER_RHO = init_nan_array_2d(nt, max_layers)
+        _LAYER_T = init_nan_array_2d(nt, max_layers)
+        _LAYER_LWC = init_nan_array_2d(nt, max_layers)
+        _LAYER_CC = init_nan_array_2d(nt, max_layers)
+        _LAYER_POROSITY = init_nan_array_2d(nt, max_layers)
+        _LAYER_ICE_FRACTION = init_nan_array_2d(nt, max_layers)
+        _LAYER_IRREDUCIBLE_WATER = init_nan_array_2d(nt, max_layers)
+        _LAYER_REFREEZE = init_nan_array_2d(nt, max_layers)
 
 
     #--------------------------------------------

cosipy/cpkernel/grid.py

@@ -692,7 +692,7 @@ def set_fresh_snow_props_update_time(self, seconds: float):
         """Update the timestamp of the snow properties.
 
         Args:
-            seconds : seconds without snowfall [s].
+            seconds: seconds without snowfall [s].
         """
         self.old_snow_timestamp = self.old_snow_timestamp + seconds
         # Set the timestamp to zero
@@ -706,11 +706,16 @@ def set_fresh_snow_props_height(self, height: float):
         """
         self.new_snow_height = height
 
-    def get_fresh_snow_props(self):
+    def get_fresh_snow_props(self) -> tuple:
         """Get the first snow layer's properties.
 
         This is used internally to track the albedo properties of the
         first snow layer.
+
+        Returns:
+            First snow layer's updated height, time elapsed since the
+            last snowfall, and the time elapsed between the last and
+            penultimate snowfall.
         """
         return (
             self.new_snow_height,
@@ -776,7 +781,7 @@ def set_refreeze(self, refreeze: np.ndarray):
         for idx in range(self.number_nodes):
             self.grid[idx].set_layer_refreeze(refreeze[idx])
 
-    def get_temperature(self):
+    def get_temperature(self) -> list:
         """Get the temperature profile."""
         return [
             self.grid[idx].get_layer_temperature()
@@ -787,7 +792,7 @@ def get_node_temperature(self, idx: int):
         """Get a node's temperature."""
         return self.grid[idx].get_layer_temperature()
 
-    def get_specific_heat(self):
+    def get_specific_heat(self) -> list:
         """Get the specific heat capacity profile (air+water+ice)."""
         return [
             self.grid[idx].get_layer_specific_heat()
@@ -798,21 +803,21 @@ def get_node_specific_heat(self, idx: int):
         """Get a node's specific heat capacity (air+water+ice)."""
         return self.grid[idx].get_layer_specific_heat()
 
-    def get_height(self):
+    def get_height(self) -> list:
         """Get the heights of all the layers."""
         return [
             self.grid[idx].get_layer_height()
             for idx in range(self.number_nodes)
         ]
 
-    def get_snow_heights(self):
+    def get_snow_heights(self) -> list:
         """Get the heights of the snow layers."""
         return [
             self.grid[idx].get_layer_height()
             for idx in range(self.get_number_snow_layers())
         ]
 
-    def get_ice_heights(self):
+    def get_ice_heights(self) -> list:
         """Get the heights of the ice layers."""
         return [
             self.grid[idx].get_layer_height()
@@ -828,7 +833,7 @@ def get_node_density(self, idx: int):
         """Get a node's density."""
         return self.grid[idx].get_layer_density()
 
-    def get_density(self):
+    def get_density(self) -> list:
         """Get the density profile."""
         return [
             self.grid[idx].get_layer_density()
@@ -839,7 +844,7 @@ def get_node_liquid_water_content(self, idx: int):
         """Get a node's liquid water content."""
         return self.grid[idx].get_layer_liquid_water_content()
 
-    def get_liquid_water_content(self):
+    def get_liquid_water_content(self) -> list:
         """Get a profile of the liquid water content."""
         return [
             self.grid[idx].get_layer_liquid_water_content()
@@ -850,7 +855,7 @@ def get_node_ice_fraction(self, idx: int):
         """Get a node's ice fraction."""
         return self.grid[idx].get_layer_ice_fraction()
 
-    def get_ice_fraction(self):
+    def get_ice_fraction(self) -> list:
         """Get a profile of the ice fraction."""
         return [
             self.grid[idx].get_layer_ice_fraction()
@@ -861,7 +866,7 @@ def get_node_irreducible_water_content(self, idx: int):
         """Get a node's irreducible water content."""
         return self.grid[idx].get_layer_irreducible_water_content()
 
-    def get_irreducible_water_content(self):
+    def get_irreducible_water_content(self) -> list:
         """Get a profile of the irreducible water content."""
         return [
             self.grid[idx].get_layer_irreducible_water_content()
@@ -872,7 +877,7 @@ def get_node_cold_content(self, idx: int):
         """Get a node's cold content."""
         return self.grid[idx].get_layer_cold_content()
 
-    def get_cold_content(self):
+    def get_cold_content(self) -> list:
         """Get the cold content profile."""
         return [
             self.grid[idx].get_layer_cold_content()
@@ -883,7 +888,7 @@ def get_node_porosity(self, idx: int):
         """Get a node's porosity."""
         return self.grid[idx].get_layer_porosity()
 
-    def get_porosity(self):
+    def get_porosity(self) -> list:
         """Get the porosity profile."""
         return [
             self.grid[idx].get_layer_porosity()
@@ -894,7 +899,7 @@ def get_node_thermal_conductivity(self, idx: int):
         """Get a node's thermal conductivity."""
         return self.grid[idx].get_layer_thermal_conductivity()
 
-    def get_thermal_conductivity(self):
+    def get_thermal_conductivity(self) -> list:
         """Get the thermal conductivity profile."""
         return [
             self.grid[idx].get_layer_thermal_conductivity()
@@ -905,7 +910,7 @@ def get_node_thermal_diffusivity(self, idx: int):
         """Get a node's thermal diffusivity."""
         return self.grid[idx].get_layer_thermal_diffusivity()
 
-    def get_thermal_diffusivity(self):
+    def get_thermal_diffusivity(self) -> list:
         """Get the thermal diffusivity profile."""
         return [
             self.grid[idx].get_layer_thermal_diffusivity()
@@ -916,7 +921,7 @@ def get_node_refreeze(self, idx: int):
         """Get the amount of refrozen water in a node."""
         return self.grid[idx].get_layer_refreeze()
 
-    def get_refreeze(self):
+    def get_refreeze(self) -> list:
         """Get the profile of refrozen water."""
         return [
             self.grid[idx].get_layer_refreeze()
@@ -931,7 +936,7 @@ def get_node_depth(self, idx: int):
                 d = d + self.get_node_height(i)
         return d
 
-    def get_depth(self):
+    def get_depth(self) -> list:
         """Get a depth profile."""
         h = np.array(self.get_height())
         z = np.empty_like(h)  # faster than copy

cosipy/cpkernel/init.py

@@ -8,6 +8,9 @@
 def init_snowpack(DATA):
     """Initialise the snowpack.
 
+    Args:
+        DATA (xarray.Dataset): Glacier data for a single grid point.
+
     Returns:
         Grid: Initialised glacier data structure with snowpack.
     """
@@ -155,7 +158,11 @@ def create_grid_jitted(
     new_snow_timestamp: float,
     old_snow_timestamp: float,
 ):
-    """Create Grid with JIT."""
+    """Create Grid with JIT.
+    
+    Returns:
+        Grid: Glacier data structure.
+    """
 
     GRID = Grid(
         layer_heights,