Merge branch 'main' into docstring-guidelines-units-etc

Author: AdamRJensen

docs/sphinx/source/user_guide/nomenclature.rst

@@ -102,20 +102,21 @@ There is a convention on consistent variable names throughout the library:
         Photocurrent
 
     poa_diffuse
-        Total diffuse irradiation in plane. Sum of ground and sky diffuse.
+        Total diffuse irradiance in plane [Wm⁻²]. Sum of ground and sky diffuse
+        components of global irradiance.
 
     poa_direct
-        Direct/beam irradiation in plane
+        Direct/beam irradiance in plane [Wm⁻²].
 
     poa_global
-        Global irradiation in plane. sum of diffuse and beam projection.
+        Global irradiance in plane.  Sum of diffuse and beam projection [Wm⁻²].
 
     poa_ground_diffuse
-        In plane ground reflected irradiation
+        In plane ground reflected irradiance [Wm⁻²].
 
     poa_sky_diffuse
-        Diffuse irradiation in plane from scattered light in the atmosphere
-        (without ground reflected irradiation)
+        Diffuse irradiance in plane from scattered light in the atmosphere
+        (without ground reflected irradiance) [Wm⁻²].
 
     precipitable_water
         Total precipitable water contained in a column of unit cross section
@@ -168,10 +169,6 @@ There is a convention on consistent variable names throughout the library:
     temp_module
         Temperature of the module
 
-    transposition_factor
-        The gain ratio of the radiation on inclined plane to global horizontal
-        irradiation: :math:`\frac{poa\_global}{ghi}`
-
     tz
         Timezone
 

docs/sphinx/source/whatsnew/v0.11.2.rst

@@ -48,6 +48,8 @@ Documentation
 
 * Added a section in the style guide for parameter naming and units best practices.
   See :ref:`documentation-units`. (:issue:`2205`, :pull:`2248`)
+* Added a example to :py:func:`~pvlib.pvsystem.retrieve_sam` docstring to
+  demonstrate how to retrieve a database from the SAM repo. (:pull:`2313`)
 
 Testing
 ~~~~~~~

pvlib/ivtools/sdm.py

@@ -562,27 +562,34 @@ def fit_desoto_sandia(ivcurves, specs, const=None, maxiter=5, eps1=1.e-3):
     -------
     dict
         I_L_ref : float
-            light current at STC [A]
+            Light current at STC [A]
         I_o_ref : float
-            dark current at STC [A]
+            Dark current at STC [A]
         EgRef : float
-            effective band gap at STC [eV]
+            Effective band gap at STC [eV]
         R_s : float
-            series resistance at STC [ohm]
+            Series resistance at STC [ohm]
         R_sh_ref : float
-            shunt resistance at STC [ohm]
+            Shunt resistance at STC [ohm]
         cells_in_series : int
-            number of cells in series
+            Number of cells in series
         iph : array
-            light current for each IV curve [A]
+            Light current for each IV curve [A]
         io : array
-            dark current for each IV curve [A]
+            Dark current for each IV curve [A]
         rs : array
-            series resistance for each IV curve [ohm]
+            Series resistance for each IV curve [ohm]
         rsh : array
-            shunt resistance for each IV curve [ohm]
+            Shunt resistance for each IV curve [ohm]
+        a_ref : float
+            The product of the usual diode ideality factor (n, unitless),
+            number of cells in series (Ns), and cell thermal voltage at
+            reference conditions, in units of V.
+        dEgdT : float
+            The temperature dependence of the energy bandgap (Eg) at reference
+            conditions [1/K].
         u : array
-            boolean for each IV curve indicating that the parameter values
+            Boolean for each IV curve indicating that the parameter values
             are deemed reasonable by the private function ``_filter_params``
 
     Notes

pvlib/pvsystem.py

@@ -1986,10 +1986,10 @@ def retrieve_sam(name=None, path=None):
 
     This function will retrieve either:
 
-        * CEC module database
-        * Sandia Module database
-        * CEC Inverter database
-        * Anton Driesse Inverter database
+    * CEC module database
+    * Sandia Module database
+    * CEC Inverter database
+    * Anton Driesse Inverter database
 
     and return it as a pandas DataFrame.
 
@@ -2002,20 +2002,20 @@ def retrieve_sam(name=None, path=None):
         Use one of the following strings to retrieve a database bundled with
         pvlib:
 
-        * 'CECMod' - returns the CEC module database
-        * 'CECInverter' - returns the CEC Inverter database
-        * 'SandiaInverter' - returns the CEC Inverter database
+        * ``'CECMod'`` - returns the CEC module database
+        * ``'CECInverter'`` - returns the CEC Inverter database
+        * ``'SandiaInverter'`` - returns the CEC Inverter database
           (CEC is only current inverter db available; tag kept for
           backwards compatibility)
-        * 'SandiaMod' - returns the Sandia Module database
-        * 'ADRInverter' - returns the ADR Inverter database
+        * ``'SandiaMod'`` - returns the Sandia Module database
+        * ``'ADRInverter'`` - returns the ADR Inverter database
 
     path : string, optional
         Path to a CSV file or a URL.
 
     Returns
     -------
-    samfile : DataFrame
+    DataFrame
         A DataFrame containing all the elements of the desired database.
         Each column represents a module or inverter, and a specific
         dataset can be retrieved by the command
@@ -2033,14 +2033,13 @@ def retrieve_sam(name=None, path=None):
     -----
     Files available at
         https://github.com/NREL/SAM/tree/develop/deploy/libraries
-    Documentation for module and inverter data sets:
-        https://sam.nrel.gov/photovoltaic/pv-sub-page-2.html
 
     Examples
     --------
+    Using a database bundled with pvlib:
 
     >>> from pvlib import pvsystem
-    >>> invdb = pvsystem.retrieve_sam('CECInverter')
+    >>> invdb = pvsystem.retrieve_sam(name='CECInverter')
     >>> inverter = invdb.AE_Solar_Energy__AE6_0__277V_
     >>> inverter
     Vac                          277
@@ -2060,7 +2059,15 @@ def retrieve_sam(name=None, path=None):
     CEC_Date                     NaN
     CEC_Type     Utility Interactive
     Name: AE_Solar_Energy__AE6_0__277V_, dtype: object
-    """
+
+    Using a remote database, via URL:
+
+    >>> url = "https://raw.githubusercontent.com/NREL/SAM/refs/heads/develop/deploy/libraries/CEC%20Inverters.csv"
+    >>> inv_db = pvsystem.retrieve_sam(path=url)
+    >>> inv_db.keys()
+    Index(['ABB__PVI_3_0_OUTD_S_US_A__208V_', 'ABB__PVI_3_0_OUTD_S_US_A__240V_', ...],
+          dtype='object', length=...)
+    """  # noqa: E501
     # error: path was previously silently ignored if name was given GH#2018
     if name is not None and path is not None:
         raise ValueError("Please provide either 'name' or 'path', not both.")

pvlib/solarposition.py

@@ -30,7 +30,7 @@
 def get_solarposition(time, latitude, longitude,
                       altitude=None, pressure=None,
                       method='nrel_numpy',
-                      temperature=12, **kwargs):
+                      temperature=12.0, **kwargs):
     """
     A convenience wrapper for the solar position calculators.
 
@@ -125,8 +125,8 @@ def get_solarposition(time, latitude, longitude,
     return ephem_df
 
 
-def spa_c(time, latitude, longitude, pressure=101325, altitude=0,
-          temperature=12, delta_t=67.0,
+def spa_c(time, latitude, longitude, pressure=101325., altitude=0.,
+          temperature=12., delta_t=67.0,
           raw_spa_output=False):
     r"""
     Calculate the solar position using the C implementation of the NREL
@@ -149,11 +149,11 @@ def spa_c(time, latitude, longitude, pressure=101325, altitude=0,
     longitude : float
         Longitude in decimal degrees. Positive east of prime meridian,
         negative to west.
-    pressure : float, default 101325
+    pressure : float, default 101325.0
         Pressure in Pascals
-    altitude : float, default 0
+    altitude : float, default 0.0
         Height above sea level. [m]
-    temperature : float, default 12
+    temperature : float, default 12.0
         Temperature in C
     delta_t : float, default 67.0
         Difference between terrestrial time and UT1.
@@ -279,7 +279,7 @@ def _datetime_to_unixtime(dtindex):
 
 
 def spa_python(time, latitude, longitude,
-               altitude=0, pressure=101325, temperature=12, delta_t=67.0,
+               altitude=0., pressure=101325., temperature=12., delta_t=67.0,
                atmos_refract=None, how='numpy', numthreads=4):
     """
     Calculate the solar position using a python implementation of the
@@ -302,11 +302,11 @@ def spa_python(time, latitude, longitude,
     longitude : float
         Longitude in decimal degrees. Positive east of prime meridian,
         negative to west.
-    altitude : float, default 0
+    altitude : float, default 0.0
         Distance above sea level.
-    pressure : int or float, optional, default 101325
+    pressure : int or float, optional, default 101325.0
         avg. yearly air pressure in Pascals.
-    temperature : int or float, optional, default 12
+    temperature : int or float, optional, default 12.0
         avg. yearly air temperature in degrees C.
     delta_t : float or array, optional, default 67.0
         Difference between terrestrial time and UT1.
@@ -507,9 +507,9 @@ def _ephem_setup(latitude, longitude, altitude, pressure, temperature,
 
 def sun_rise_set_transit_ephem(times, latitude, longitude,
                                next_or_previous='next',
-                               altitude=0,
-                               pressure=101325,
-                               temperature=12, horizon='0:00'):
+                               altitude=0.,
+                               pressure=101325.,
+                               temperature=12., horizon='0:00'):
     """
     Calculate the next sunrise and sunset times using the PyEphem package.
 
@@ -523,11 +523,11 @@ def sun_rise_set_transit_ephem(times, latitude, longitude,
         Longitude in degrees, positive east of prime meridian, negative to west
     next_or_previous : str
         'next' or 'previous' sunrise and sunset relative to time
-    altitude : float, default 0
+    altitude : float, default 0.0
         distance above sea level in meters.
-    pressure : int or float, optional, default 101325
+    pressure : int or float, optional, default 101325.0
         air pressure in Pascals.
-    temperature : int or float, optional, default 12
+    temperature : int or float, optional, default 12.0
         air temperature in degrees C.
     horizon : string, format +/-X:YY
         arc degrees:arc minutes from geometrical horizon for sunrise and
@@ -590,8 +590,8 @@ def sun_rise_set_transit_ephem(times, latitude, longitude,
                                            'transit': trans})
 
 
-def pyephem(time, latitude, longitude, altitude=0, pressure=101325,
-            temperature=12, horizon='+0:00'):
+def pyephem(time, latitude, longitude, altitude=0., pressure=101325.,
+            temperature=12., horizon='+0:00'):
     """
     Calculate the solar position using the PyEphem package.
 
@@ -605,11 +605,11 @@ def pyephem(time, latitude, longitude, altitude=0, pressure=101325,
     longitude : float
         Longitude in decimal degrees. Positive east of prime meridian,
         negative to west.
-    altitude : float, default 0
+    altitude : float, default 0.0
         Height above sea level in meters. [m]
-    pressure : int or float, optional, default 101325
+    pressure : int or float, optional, default 101325.0
         air pressure in Pascals.
-    temperature : int or float, optional, default 12
+    temperature : int or float, optional, default 12.0
         air temperature in degrees C.
     horizon : string, optional, default '+0:00'
         arc degrees:arc minutes from geometrical horizon for sunrise and
@@ -679,7 +679,7 @@ def pyephem(time, latitude, longitude, altitude=0, pressure=101325,
     return sun_coords
 
 
-def ephemeris(time, latitude, longitude, pressure=101325, temperature=12):
+def ephemeris(time, latitude, longitude, pressure=101325.0, temperature=12.0):
     """
     Python-native solar position calculator.
     The accuracy of this code is not guaranteed.
@@ -695,9 +695,9 @@ def ephemeris(time, latitude, longitude, pressure=101325, temperature=12):
     longitude : float
         Longitude in decimal degrees. Positive east of prime meridian,
         negative to west.
-    pressure : float or Series, default 101325
+    pressure : float or Series, default 101325.0
         Ambient pressure (Pascals)
-    temperature : float or Series, default 12
+    temperature : float or Series, default 12.0
         Ambient temperature (C)
 
     Returns
@@ -856,8 +856,8 @@ def ephemeris(time, latitude, longitude, pressure=101325, temperature=12):
 
 
 def calc_time(lower_bound, upper_bound, latitude, longitude, attribute, value,
-              altitude=0, pressure=101325, temperature=12, horizon='+0:00',
-              xtol=1.0e-12):
+              altitude=0.0, pressure=101325.0, temperature=12.0,
+              horizon='+0:00', xtol=1.0e-12):
     """
     Calculate the time between lower_bound and upper_bound
     where the attribute is equal to value. Uses PyEphem for
@@ -879,12 +879,12 @@ def calc_time(lower_bound, upper_bound, latitude, longitude, attribute, value,
         and 'az' (which must be given in radians).
     value : int or float
         The value of the attribute to solve for
-    altitude : float, default 0
+    altitude : float, default 0.0
         Distance above sea level.
-    pressure : int or float, optional, default 101325
+    pressure : int or float, optional, default 101325.0
         Air pressure in Pascals. Set to 0 for no
         atmospheric correction.
-    temperature : int or float, optional, default 12
+    temperature : int or float, optional, default 12.0
         Air temperature in degrees C.
     horizon : string, optional, default '+0:00'
         arc degrees:arc minutes from geometrical horizon for sunrise and