Merge pull request #10 from gregory-halverson/main

type-hints

Author: gregory-halverson

pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools>=60", "setuptools-scm>=8.0", "wheel"]
 
 [project]
 name = "sun_angles"
-version = "1.1.4"
+version = "1.2.0"
 description = "calculates solar zenith and azimuth and daylight hours"
 readme = "README.md"
 authors = [

sun_angles/SHA.py

@@ -1,19 +1,21 @@
+from typing import Union
 import warnings
 import numpy as np
+from rasters import Raster
 
 from .day_angle import day_angle_rad_from_DOY
 from .declination import solar_dec_deg_from_day_angle_rad
 
-def SHA_deg_from_DOY_lat(DOY: np.ndarray, latitude: np.ndarray) -> np.ndarray:
+def SHA_deg_from_DOY_lat(DOY: Union[Raster, np.ndarray], latitude: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
     """
     Calculate the sunrise hour angle in degrees from the latitude in degrees and the day of the year.
 
     Parameters:
-    DOY (np.ndarray): A numpy array containing day of the year values (integers between 1 and 365).
-    latitude (np.ndarray): A numpy array containing latitude values in degrees.
+    DOY (Union[Raster, np.ndarray]): A Raster or numpy array containing day of the year values (integers between 1 and 365).
+    latitude (Union[Raster, np.ndarray]): A Raster or numpy array containing latitude values in degrees.
 
     Returns:
-    np.ndarray: A numpy array containing the corresponding sunrise hour angles in degrees.
+    Union[Raster, np.ndarray]: A Raster or numpy array containing the corresponding sunrise hour angles in degrees.
 
     The function performs the following steps:
     1. Calculate the day angle in radians from the day of the year using the function `day_angle_rad_from_DOY`.
@@ -58,5 +60,4 @@ def SHA_deg_from_DOY_lat(DOY: np.ndarray, latitude: np.ndarray) -> np.ndarray:
     sunrise_deg = np.where(sunrise_cos >= 1, 0, sunrise_deg)
     sunrise_deg = np.where(sunrise_cos <= -1, 180, sunrise_deg)
 
-    return sunrise_deg
-
+    return sunrise_deg

sun_angles/SZA.py

@@ -2,17 +2,17 @@
 from datetime import datetime
 
 import numpy as np
-from rasters import Raster
+from rasters import Raster, CoordinateArray
 
-from solar_apparent_time import solar_day_of_year_for_longitude
+from solar_apparent_time import solar_day_of_year_for_longitude, solar_hour_of_day_for_area
 
 from .day_angle import day_angle_rad_from_DOY
 from .declination import solar_dec_deg_from_day_angle_rad
 
 def SZA_deg_from_lat_dec_hour(
-        latitude: np.ndarray, 
+        latitude: Union[Raster, np.ndarray], 
         solar_dec_deg: Union[Raster, np.ndarray], 
-        hour: Union[Raster, np.ndarray]) -> np.ndarray:
+        hour: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
     """
     This function calculates the solar zenith angle (SZA) given the latitude, solar declination, and solar time. 
     The SZA is the angle between the zenith and the center of the sun's disc. The zenith is the point on the celestial 
@@ -95,8 +95,7 @@ def calculate_SZA_from_datetime(time_UTC: datetime, lat: float, lon: float):
     # Calculate the day of year based on the UTC time and longitude
     doy = solar_day_of_year_for_longitude(time_UTC, lon)
     # Calculate the hour of the day based on the UTC time and longitude
-    # FIXME missing `hour_of_day` implementation
-    hour = hour_of_day(time_UTC, lon)
+    hour = solar_hour_of_day_for_area(time_UTC=time_UTC, geometry=CoordinateArray(x=lon, y=lat))
     # Calculate the solar zenith angle in degrees based on the latitude, solar declination angle, and hour of the day
     SZA = calculate_SZA_from_DOY_and_hour(lat, lon, doy, hour)
 

sun_angles/azimuth.py

@@ -1,17 +1,22 @@
+from typing import Union
 import warnings
 import numpy as np
+from rasters import Raster
 
-def calculate_solar_azimuth(solar_dec_deg: np.ndarray, SZA_deg: np.ndarray, hour: np.ndarray) -> np.ndarray:
+def calculate_solar_azimuth(
+        solar_dec_deg: Union[Raster, np.ndarray], 
+        SZA_deg: Union[Raster, np.ndarray], 
+        hour: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
     """
     Calculate the solar azimuth angle based on the solar declination, solar zenith angle, and hour of the day.
     
     Parameters:
-    solar_dec_deg (np.ndarray): Solar declination in degrees.
-    SZA_deg (np.ndarray): Solar zenith angle in degrees.
-    hour (np.ndarray): Hour of the day, where 0 corresponds to 00:00 and 23 corresponds to 23:00.
+    solar_dec_deg (Union[Raster, np.ndarray]): Solar declination in degrees.
+    SZA_deg (Union[Raster, np.ndarray]): Solar zenith angle in degrees.
+    hour (Union[Raster, np.ndarray]): Hour of the day, where 0 corresponds to 00:00 and 23 corresponds to 23:00.
     
     Returns:
-    np.ndarray: Solar azimuth angle in degrees.
+    Union[Raster, np.ndarray]: Solar azimuth angle in degrees.
     
     Note:
     This function ignores any warnings that might be generated during the calculations.
@@ -36,4 +41,4 @@ def calculate_solar_azimuth(solar_dec_deg: np.ndarray, SZA_deg: np.ndarray, hour
         # Convert the solar azimuth from radians to degrees
         solar_azimuth_deg = np.degrees(solar_azimuth_rad)
 
-    return solar_azimuth_deg
+    return solar_azimuth_deg

sun_angles/day_angle.py

@@ -1,14 +1,18 @@
+from typing import Union
 import numpy as np
+from rasters import Raster
 
-def day_angle_rad_from_DOY(DOY: np.ndarray) -> np.ndarray:
+def day_angle_rad_from_DOY(DOY: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
     """
     Calculate the day angle in radians from the day of the year.
 
     Parameters:
-    DOY (np.ndarray): A numpy array containing day of the year values (integers between 1 and 365).
+    DOY (Union[Raster, np.ndarray]): A Raster object or a numpy array containing 
+    day of the year values (integers between 1 and 365).
 
     Returns:
-    np.ndarray: A numpy array containing the corresponding day angles in radians.
+    Union[Raster, np.ndarray]: A Raster object or a numpy array containing the 
+    corresponding day angles in radians.
 
     The day angle is calculated using the formula:
     day_angle = (2 * π * (DOY - 1)) / 365
@@ -20,4 +24,4 @@ def day_angle_rad_from_DOY(DOY: np.ndarray) -> np.ndarray:
     Reference:
     Duffie, J. A., & Beckman, W. A. (2013). Solar Engineering of Thermal Processes (4th ed.). Wiley.
     """
-    return (2 * np.pi * (DOY - 1)) / 365
+    return (2 * np.pi * (DOY - 1)) / 365

sun_angles/daylight.py

@@ -1,9 +1,11 @@
+from typing import Union
 import numpy as np
+from rasters import Raster
 
-def daylight_from_SHA(SHA_deg: np.ndarray) -> np.ndarray:
+def daylight_from_SHA(SHA_deg: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
     """
-    This function calculates daylight hours from the sunrise hour angle (SHA) in degrees.
-    
+    Calculates daylight hours from the sunrise hour angle (SHA) in degrees.
+
     The calculation is based on the formula:
     
     $$ daylight = \frac{2}{15} * SHA $$
@@ -16,17 +18,17 @@ def daylight_from_SHA(SHA_deg: np.ndarray) -> np.ndarray:
     
     Parameters
     ----------
-    SHA_deg : np.ndarray
-        Sunrise hour angle in degrees. Must be a numpy array.
+    SHA_deg : Union[Raster, np.ndarray]
+        Sunrise hour angle in degrees. Can be a `Raster` object or a numpy array.
         
     Returns
     -------
-    np.ndarray
-        Daylight hours. Returns a numpy array of the same shape as `SHA_deg`.
+    Union[Raster, np.ndarray]
+        Daylight hours. Returns a `Raster` object or a numpy array of the same shape as `SHA_deg`.
         
     References
     ----------
     - Allen, R.G., Pereira, L.S., Raes, D., Smith, M., 1998. Crop evapotranspiration-Guidelines for computing crop water requirements-FAO Irrigation and drainage paper 56. FAO, Rome, 300(9).
     - Duffie, J. A., & Beckman, W. A. (2013). Solar Engineering of Thermal Processes (4th ed.). Wiley.
     """
-    return (2.0 / 15.0) * SHA_deg
+    return (2.0 / 15.0) * SHA_deg

sun_angles/declination.py

@@ -1,14 +1,16 @@
+from typing import Union
 import numpy as np
+from rasters import Raster
 
-def solar_dec_deg_from_day_angle_rad(day_angle_rad: np.ndarray) -> np.ndarray:
+def solar_dec_deg_from_day_angle_rad(day_angle_rad: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
     """
     Calculate solar declination in degrees from the day angle in radians.
 
     Parameters:
-    day_angle_rad (np.ndarray): A numpy array containing day angles in radians.
+    day_angle_rad (Union[Raster, np.ndarray]): A Raster or numpy array containing day angles in radians.
 
     Returns:
-    np.ndarray: A numpy array containing the corresponding solar declination angles in degrees.
+    Union[Raster, np.ndarray]: A Raster or numpy array containing the corresponding solar declination angles in degrees.
 
     The solar declination is calculated using the following formula:
     solar_declination = 0.006918 - 0.399912 * cos(day_angle_rad) + 0.070257 * sin(day_angle_rad)
@@ -23,4 +25,4 @@ def solar_dec_deg_from_day_angle_rad(day_angle_rad: np.ndarray) -> np.ndarray:
     """
     return (0.006918 - 0.399912 * np.cos(day_angle_rad) + 0.070257 * np.sin(day_angle_rad) 
             - 0.006758 * np.cos(2 * day_angle_rad) + 0.000907 * np.sin(2 * day_angle_rad) 
-            - 0.002697 * np.cos(3 * day_angle_rad) + 0.00148 * np.sin(3 * day_angle_rad)) * (180 / np.pi)
+            - 0.002697 * np.cos(3 * day_angle_rad) + 0.00148 * np.sin(3 * day_angle_rad)) * (180 / np.pi)

sun_angles/sunrise.py

@@ -1,20 +1,25 @@
+from typing import Union
 import numpy as np
+from rasters import Raster
 
-def sunrise_from_SHA(SHA_deg: np.ndarray) -> np.ndarray:
+def sunrise_from_SHA(SHA_deg: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
     """
     Calculate the sunrise hour from the sunrise hour angle (SHA) in degrees.
 
-    This function takes an array of sunrise hour angles (SHA) in degrees and 
-    converts it to the corresponding sunrise hours. The conversion is based on 
-    the fact that the Earth rotates 15 degrees per hour.
+    This function takes a `Raster` or `numpy.ndarray` of sunrise hour angles (SHA) 
+    in degrees and converts it to the corresponding sunrise hours. The conversion 
+    is based on the fact that the Earth rotates 15 degrees per hour.
 
     Parameters:
-    SHA_deg (np.ndarray): Array of sunrise hour angles in degrees.
+    SHA_deg (Union[Raster, np.ndarray]): A `Raster` or `numpy.ndarray` containing 
+                                         sunrise hour angles in degrees.
 
     Returns:
-    np.ndarray: Array of calculated sunrise hours.
+    Union[Raster, np.ndarray]: A `Raster` or `numpy.ndarray` containing the 
+                               calculated sunrise hours.
 
     Example:
+    >>> import numpy as np
     >>> SHA_deg = np.array([0, 15, 30, 45])
     >>> sunrise_from_SHA(SHA_deg)
     array([12., 11., 10.,  9.])
@@ -26,4 +31,4 @@ def sunrise_from_SHA(SHA_deg: np.ndarray) -> np.ndarray:
     [1] Duffie, J.A., & Beckman, W.A. (2013). Solar Engineering of Thermal Processes. 
     John Wiley & Sons. 
     """
-    return 12.0 - (SHA_deg / 15.0)
+    return 12.0 - (SHA_deg / 15.0)

sun_angles/version.txt

@@ -1 +1 @@
-1.1.4
+1.2.0