Merge branch 'main' into intro_text_solar_position_algorithms

Author: IoannisSifnaios

src/solposx/refraction/archer.py

@@ -18,20 +18,20 @@ def archer(elevation):
 
     Returns
     -------
-    refraction_correction : array-like
-        Refraction correction. [degrees]
+    np.array or pd.Series
+        Atmospheric refraction angle. [degrees]
 
     Notes
     -----
     The equation to calculate the refraction correction is given by:
 
     .. math::
 
-        C = \text{cos}(Z) + 0.0083 \cdot \left(\frac{1}{0.955 + (20.267 \cdot \text{cos}(Z))} - 0.047121 \right)
-
-        Z_a = \text{arccos}(C)
-
-        refraction = Z - Z_a
+        \begin{align}
+        & C = \text{cos}(Z) + 0.0083 \cdot \left(\frac{1}{0.955 + (20.267 \cdot \text{cos}(Z))} - 0.047121 \right)\\
+        & Z_a = \text{arccos}(C)\\
+        & refraction = Z - Z_a\\
+        \end{align}
 
     where :math:`Z` is the true solar zenith angle and :math:`Z_a` is the
     aparent zenith angle.

src/solposx/refraction/bennett.py

@@ -14,14 +14,14 @@ def bennett(elevation, pressure=101325., temperature=12.):
     elevation : array-like
         True solar elevation angle (not accounting for refraction). [degrees]
     pressure : numeric, default 101325
-        Local atmospheric pressure. [Pascal]
+        Annual average atmospheric pressure. [Pascal]
     temperature : numeric, default 12
-        Local air temperature. [C]
+        Annaul average air temperature. [C]
 
     Returns
     -------
-    refraction_correction : numeric
-        Refraction correction. [degrees]
+    np.array or pd.Series
+        Atmospheric refraction angle. [degrees]
 
     Notes
     -----

src/solposx/refraction/hughes.py

@@ -19,30 +19,27 @@ def hughes(elevation, pressure=101325., temperature=12.):
     elevation : array-like
         True solar elevation angle (not accounting for refraction). [degrees]
     pressure : numeric, default 101325
-        Local atmospheric pressure. [Pascal]
+        Annual average atmospheric pressure. [Pascal]
     temperature : numeric, default 12
-        Atmospheric temperature. The default in this code deviates from
+        Annual average temperature. The default in this code deviates from
         [1]_, which used 10 C. [C]
 
     Returns
     -------
-    refraction_correction : array-like
-        Refraction correction. [degrees]
+    np.array or pd.Series
+        Atmospheric refraction angle. [degrees]
 
     Notes
     -----
     The equation to calculate the refraction correction is given by:
 
     .. math::
 
-        \text{For }5° < el <= 90°:
-            ref = \frac{58.1}{\text{tan}(el)} - \frac{0.07}{\text{tan}(el)^3} + \frac{8.6\cdot 10^{-5}}{tan(el)^5}
-
-        \text{For }-0.575° < el <= 5°:
-            ref = el \cdot (-518.2 + el \cdot (103.4 + el \cdot (-12.79 + el \cdot 0.711))) + 1735
-
-        \text{For }el <= -0.575°:
-            ref = \frac{-20.774}{\text{tan}(el)}
+        \begin{align}
+        & \frac{58.1}{\text{tan}(el)} - \frac{0.07}{\text{tan}(el)^3} + \frac{8.6\cdot 10^{-5}}{tan(el)^5} \text{ for } 5° < el <= 90°\\
+        & el \cdot (-518.2 + el \cdot (103.4 + el \cdot (-12.79 + el \cdot 0.711))) + 1735 \text{ for } -0.575° < el <= 5°\\
+        & \frac{-20.774}{\text{tan}(el)} \text{ for } el <= -0.575°\\
+        \end{align}
 
     where :math:`el` is the true (unrefracted) solar elevation angle.
 

src/solposx/refraction/michalsky.py

@@ -15,8 +15,8 @@ def michalsky(elevation):
 
     Returns
     -------
-    refraction_correction : numeric
-        Refraction correction. [degrees]
+    np.array or pd.Series
+        Atmospheric refraction angle. [degrees]
 
     Notes
     -----

src/solposx/refraction/sg2.py

@@ -14,27 +14,25 @@ def sg2(elevation, pressure=101325., temperature=12.):
     elevation : array-like
         True solar elevation angle (not accounting for refraction). [degrees]
     pressure : numeric, default 101325
-        Local atmospheric pressure. [Pascal]
+        Annual average atmospheric pressure. [Pascal]
     temperature : numeric, default 12
-        Local air temperature. [C]
+        Annual average air temperature. [C]
 
     Returns
     -------
-    refraction_correction : array-like
-        Refraction correction. [degrees]
+    np.array or pd.Series
+        Atmospheric refraction angle. [degrees]
 
     Notes
     -----
     The equation to calculate the refraction correction is given by:
 
     .. math::
 
-       \begin{cases}
-
-       \frac{P}{1010} \cdot \frac{283}{273+T} \cdot \frac{2.96706 \cdot 10^{-4}}{\text{tan}(el+0.0031376 \cdot (el+0.089186)^{-1})} & \text{for } el > -0.01 \text{ [rad]}
-
-       -\frac{P}{1010} \cdot \frac{283}{273+T} \cdot \frac{1.005516 \cdot 10^{-4}}{\text{tan}(el)} & \text{for } el < -0.01 \text{ [rad]}
-       \end{cases}
+       \begin{align}
+       & \frac{P}{1010} \cdot \frac{283}{273+T} \cdot \frac{2.96706 \cdot 10^{-4}}{\text{tan}(el+0.0031376 \cdot (el+0.089186)^{-1})} & \text{ for } el > -0.01 \text{ [rad]}\\
+       & -\frac{P}{1010} \cdot \frac{283}{273+T} \cdot \frac{1.005516 \cdot 10^{-4}}{\text{tan}(el)} & \text{ for } el < -0.01 \text{ [rad]}
+       \end{align}
 
     where :math:`el` is the true solar elevation angle, :math:`P` is the local
     air pressure, :math:`T` is the local air temperature.

src/solposx/refraction/spa.py

@@ -25,8 +25,8 @@ def spa(elevation, pressure=101325., temperature=12., refraction_limit=-0.5667):
 
     Returns
     -------
-    refraction_correction : numeric
-        Refraction correction. [degrees]
+    np.array or pd.Series
+        Atmospheric refraction angle. [degrees]
 
     Notes
     -----

src/solposx/solarposition/noaa.py

@@ -30,7 +30,7 @@ def noaa(times, latitude, longitude, delta_t=67.0):
     longitude : float
         Longitude in decimal degrees. Positive east of prime meridian,
         negative to west. [degrees]
-    delta_t : float or array, default 67.0
+    delta_t : numeric, default 67.0
         Difference between terrestrial time and UT1.
         If delta_t is None, uses spa.calculate_deltat
         using time.year and time.month from pandas.DatetimeIndex.

src/solposx/solarposition/usno.py

@@ -22,15 +22,15 @@ def usno(times, latitude, longitude, delta_t=67.0, gmst_option=1):
     longitude : float
         Longitude in decimal degrees. Positive east of prime meridian,
         negative to west. [degrees]
-    delta_t : float or array, default 67.0
+    delta_t : numeric, default 67.0
         Difference between terrestrial time and UT1.
         If delta_t is None, uses spa.calculate_deltat
         using time.year and time.month from pandas.DatetimeIndex.
         For most simulations the default delta_t is sufficient.
         The USNO has historical and forecasted delta_t [2]_. [seconds]
-    gmst_option : numeric, default 1
-        Different ways of calculating the Greenwich mean sidereal time. See
-        [1]_.
+    gmst_option : int, default 1
+        Different ways of calculating the Greenwich mean sidereal time.
+        `gmst_option` needs to be either 1, 2, or 3. See [1]_.
 
     Returns
     -------

tests/test_solarposition.py

@@ -489,3 +489,17 @@ def test_noaa_refraction_85_degrees():
         latitude=0, longitude=0,
     )
     assert angles['elevation'].iloc[0] == angles['apparent_elevation'].iloc[0]
+
+
+def test_delta_t_array_input():
+    # test that delta_t can be specified as either an array or float
+    times = pd.date_range('2020-03-23 12', periods=10, tz='UTC')
+    delta_t = np.ones(len(times)) * 67.0
+    # test noaa
+    noaa_array = noaa(times, 50, 10, delta_t=delta_t)
+    noaa_float = noaa(times, 50, 10, delta_t=67.0)
+    pd.testing.assert_frame_equal(noaa_array, noaa_float)
+    # test usno
+    usno_array = usno(times, 50, 10, delta_t=delta_t)
+    usno_float = usno(times, 50, 10, delta_t=67.0)
+    pd.testing.assert_frame_equal(usno_array, usno_float)