Merge branch 'main' into darkmode4myeyes

echedey-ls · echedey-ls · commit 0f8a88de1f1a · 2025-02-21T20:43:22.000Z
diff --git a/.github/workflows/asv_check.yml b/.github/workflows/asv_check.yml
@@ -26,19 +26,7 @@ jobs:
           python-version: '3.9'
 
       - name: Install asv
-        run: pip install asv==0.4.2
-
-      # asv 0.4.2 (and more recent versions as well) creates conda envs
-      # using the --force option, which was removed in conda 24.3.
-      # Since ubuntu-latest now comes with conda 24.3 pre-installed,
-      # using the system's conda will result in error.
-      # To prevent that, we install an older version.
-      # TODO: remove this when we eventually upgrade our asv version.
-      # https://github.com/airspeed-velocity/asv/issues/1396
-      - name: Install Conda
-        uses: conda-incubator/setup-miniconda@v3
-        with:
-          conda-version: 24.1.2
+        run: pip install asv==0.6.4
 
       - name: Run asv benchmarks
         run: |
diff --git a/ci/requirements-py3.12.yml b/ci/requirements-py3.12.yml
@@ -25,4 +25,4 @@ dependencies:
     - statsmodels
     - pip:
         - nrel-pysam>=2.0
-        # - solarfactors  # required shapely<2 isn't available for 3.12
+        - solarfactors
diff --git a/docs/sphinx/source/user_guide/index.rst b/docs/sphinx/source/user_guide/index.rst
@@ -1,20 +1,34 @@
+.. _user_guide:
+
 ==========
 User Guide
 ==========
 
+This user guide is an overview and explains some of the key features of pvlib.
 
 .. toctree::
+   :caption: Getting started
    :maxdepth: 2
-
+   
    package_overview
    installation
    introtutorial
+   
+.. toctree::
+   :caption: Modeling topics
+   :maxdepth: 2
+   
    pvsystem
    modelchain
    timetimezones
-   clearsky
    bifacial
+   clearsky
    weather_data
    singlediode
+
+.. toctree::
+   :caption: Extras
+   :maxdepth: 2
+
    nomenclature
    faq
diff --git a/docs/sphinx/source/user_guide/introtutorial.rst b/docs/sphinx/source/user_guide/introtutorial.rst
@@ -87,7 +87,7 @@ to accomplish our system modeling goal:
             longitude=longitude,
             altitude=altitude,
             temperature=weather["temp_air"],
-            pressure=pvlib.atmosphere.alt2pres(altitude),
+            pressure=weather["pressure"],
         )
         dni_extra = pvlib.irradiance.get_extra_radiation(weather.index)
         airmass = pvlib.atmosphere.get_relative_airmass(solpos['apparent_zenith'])
diff --git a/docs/sphinx/source/whatsnew/v0.11.3.rst b/docs/sphinx/source/whatsnew/v0.11.3.rst
@@ -10,11 +10,18 @@ Deprecations
 
 Enhancements
 ~~~~~~~~~~~~
-
+* :py:func:`~pvlib.irradiance.gti_dirint` now raises an informative message
+  when input data don't include values with AOI<90 (:issue:`1342`, :pull:`2347`)
+* Fix a bug in :py:func:`pvlib.bifacial.get_irradiance_poa` which may have yielded non-zero
+  ground irradiance when the sun was below the horizon. (:issue:`2245`, :pull:`2359`)
+* Fix a bug where :py:func:`pvlib.transformer.simple_efficiency` could only be imported
+  using the `from pvlib.transformer` syntax (:pull:`2388`)
 
 Documentation
 ~~~~~~~~~~~~~
-
+* Fix Procedural and Object Oriented simulation examples having slightly different results, in :ref:`introtutorial`. (:issue:`2366`, :pull:`2367`)
+* Restructure the user guide with subsections (:issue:`2302`, :pull:`2310`)
+* Add references for :py:func:`pvlib.snow.loss_townsend`. (:issue:`2383`, :pull:`2384`)
 
 Testing
 ~~~~~~~
@@ -24,7 +31,20 @@ Requirements
 ~~~~~~~~~~~~
 
 
-Contributors
-~~~~~~~~~~~~
+Maintenance
+~~~~~~~~~~~
+* Fix ReadTheDocs builds by upgrading `readthedocs.yml` configuration
+  (:issue:`2357`, :pull:`2358`)
+* asv 0.4.2 upgraded to asv 0.6.4 to fix CI failure due to pinned older conda.
+  (:pull:`2352`)
 
 
+Contributors
+~~~~~~~~~~~~
+* Rajiv Daxini (:ghuser:`RDaxini`)
+* Mark Campanelli (:ghuser:`markcampanelli`)
+* Cliff Hansen (:ghuser:`cwhanse`)
+* Jason Lun Leung (:ghuser:`jason-rpkt`)
+* Manoj K S (:ghuser:`manojks1999`)
+* Kurt Rhee (:ghuser:`kurt-rhee`)
+* Ayush jariyal (:ghuser:`ayushjariyal`)
diff --git a/pvlib/__init__.py b/pvlib/__init__.py
@@ -27,4 +27,5 @@
     temperature,
     tools,
     tracking,
+    transformer,
 )
diff --git a/pvlib/bifacial/infinite_sheds.py b/pvlib/bifacial/infinite_sheds.py
@@ -260,8 +260,9 @@ def get_irradiance_poa(surface_tilt, surface_azimuth, solar_zenith,
     Returns
     -------
     output : dict or DataFrame
-        Output is a DataFrame when input ghi is a Series. See Notes for
-        descriptions of content.
+        Output is a ``pandas.DataFrame`` when ``ghi`` is a Series.
+        Otherwise it is a dict of ``numpy.ndarray``
+        See Notes for descriptions of content.
 
     Notes
     -----
@@ -372,7 +373,7 @@ def get_irradiance_poa(surface_tilt, surface_azimuth, solar_zenith,
         'poa_global': poa_global, 'poa_direct': poa_direct,
         'poa_diffuse': poa_diffuse, 'poa_ground_diffuse': poa_gnd_pv,
         'poa_sky_diffuse': poa_sky_pv, 'shaded_fraction': f_x}
-    if isinstance(poa_global, pd.Series):
+    if isinstance(ghi, pd.Series):
         output = pd.DataFrame(output)
     return output
 
diff --git a/pvlib/bifacial/utils.py b/pvlib/bifacial/utils.py
@@ -87,7 +87,8 @@ def _unshaded_ground_fraction(surface_tilt, surface_azimuth, solar_zenith,
                                         surface_azimuth)
     f_gnd_beam = 1.0 - np.minimum(
         1.0, gcr * np.abs(cosd(surface_tilt) + sind(surface_tilt) * tan_phi))
-    np.where(solar_zenith > max_zenith, 0., f_gnd_beam)  # [1], Eq. 4
+    # [1], Eq. 4
+    f_gnd_beam = np.where(solar_zenith > max_zenith, 0., f_gnd_beam)
     return f_gnd_beam  # 1 - min(1, abs()) < 1 always
 
 
diff --git a/pvlib/iotools/psm3.py b/pvlib/iotools/psm3.py
@@ -49,7 +49,7 @@
     'ghi_clear': 'clearsky_ghi',
     'dhi_clear': 'clearsky_dhi',
     'dni_clear': 'clearsky_dni',
-    'zenith': 'solar_zenith_angle',
+    'solar_zenith': 'solar_zenith_angle',
     'temp_air': 'air_temperature',
     'temp_dew': 'dew_point',
     'relative_humidity': 'relative_humidity',
diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py
@@ -2368,6 +2368,9 @@ def gti_dirint(poa_global, aoi, solar_zenith, solar_azimuth, times,
            irradiance, Solar Energy 122, 1037-1046.
            :doi:`10.1016/j.solener.2015.10.024`
     """
+    # check input data and raise Exceptions where data will cause the
+    # algorithm to fail
+    _gti_dirint_check_input(aoi)
 
     aoi_lt_90 = aoi < 90
 
@@ -2399,6 +2402,17 @@ def gti_dirint(poa_global, aoi, solar_zenith, solar_azimuth, times,
     return output
 
 
+def _gti_dirint_check_input(aoi):
+    r"""
+    Helper for gti_dirint
+
+    Raises Exceptions from input data that cause the algorithm to fail.
+    """
+    if not (aoi < 90).any():
+        raise ValueError("There are no times with AOI < 90. "
+                         "gti_dirint requires some data with AOI < 90.")
+
+
 def _gti_dirint_lt_90(poa_global, aoi, aoi_lt_90, solar_zenith, solar_azimuth,
                       times, surface_tilt, surface_azimuth, pressure=101325.,
                       use_delta_kt_prime=True, temp_dew=None, albedo=.25,
diff --git a/pvlib/snow.py b/pvlib/snow.py
@@ -278,16 +278,23 @@ def loss_townsend(snow_total, snow_events, surface_tilt, relative_humidity,
     axis to the module edge.
 
     The parameter `string_factor` is an enhancement added to the model after
-    publication of [1]_ per private communication with the model's author. The
-    definition for snow events documented above is also based on private
-    communication with the model's author.
+    publication of [1]_, as described in [2]_.
+    The definition for snow events documented above is based on [3]_.
 
     References
     ----------
     .. [1] Townsend, Tim & Powers, Loren. (2011). Photovoltaics and snow: An
        update from two winters of measurements in the SIERRA. 37th IEEE
        Photovoltaic Specialists Conference, Seattle, WA, USA.
        :doi:`10.1109/PVSC.2011.6186627`
+    .. [2] Townsend, T. and Previtali, J. (2023). A Fresh Dusting: Current
+        Uses of the Townsend Snow Model. In "Photovoltaic Reliability
+        Workshop (PVRW) 2023 Proceedings: Posters.", ed. Silverman,
+        T. J. Dec. 2023. NREL/CP-5900-87918.
+        Available at: https://www.nrel.gov/docs/fy25osti/90585.pdf
+    .. [3] Townsend, T. (2013). Predicting PV Energy Loss Caused by Snow.
+        Solar Power International, Chicago IL.
+        :doi:`10.13140/RG.2.2.14299.68647`
     '''
 
     # unit conversions from cm and m to in, from C to K, and from % to fraction
diff --git a/pvlib/tests/bifacial/test_infinite_sheds.py b/pvlib/tests/bifacial/test_infinite_sheds.py
@@ -130,6 +130,7 @@ def test_get_irradiance_poa():
     # series inputs
     surface_tilt = pd.Series(surface_tilt)
     surface_azimuth = pd.Series(data=surface_azimuth, index=surface_tilt.index)
+    ghi = pd.Series(data=ghi, index=surface_tilt.index)
     solar_zenith = pd.Series(solar_zenith, index=surface_tilt.index)
     solar_azimuth = pd.Series(data=solar_azimuth, index=surface_tilt.index)
     expected_diffuse = pd.Series(
diff --git a/pvlib/tests/test_irradiance.py b/pvlib/tests/test_irradiance.py
@@ -928,6 +928,23 @@ def test_gti_dirint():
     assert_frame_equal(output, expected)
 
 
+def test_gti_dirint_data_error():
+    times = pd.DatetimeIndex(
+        ['2014-06-24T06-0700', '2014-06-24T09-0700', '2014-06-24T12-0700'])
+    poa_global = np.array([20, 300, 1000])
+    zenith = np.array([80, 45, 20])
+    azimuth = np.array([90, 135, 180])
+    surface_tilt = 30
+    surface_azimuth = 180
+
+    aoi = np.array([100, 170, 110])
+    with pytest.raises(
+            ValueError, match="There are no times with AOI < 90"):
+        irradiance.gti_dirint(
+            poa_global, aoi, zenith, azimuth, times, surface_tilt,
+            surface_azimuth)
+
+
 def test_erbs():
     index = pd.DatetimeIndex(['20190101']*3 + ['20190620'])
     ghi = pd.Series([0, 50, 1000, 1000], index=index)
diff --git a/readthedocs.yml b/readthedocs.yml
@@ -5,6 +5,9 @@
 # Required
 version: 2
 
+sphinx:
+    configuration: docs/sphinx/source/conf.py
+
 build:
    os: ubuntu-lts-latest
    tools:

Original file line number	Diff line number	Diff line change
`@@ -87,7 +87,7 @@ to accomplish our system modeling goal:`
`87`	`87`	`longitude=longitude,`
`88`	`88`	`altitude=altitude,`
`89`	`89`	`temperature=weather["temp_air"],`
`90`		`- pressure=pvlib.atmosphere.alt2pres(altitude),`
	`90`	`+ pressure=weather["pressure"],`
`91`	`91`	`)`
`92`	`92`	`dni_extra = pvlib.irradiance.get_extra_radiation(weather.index)`
`93`	`93`	`airmass = pvlib.atmosphere.get_relative_airmass(solpos['apparent_zenith'])`
Original file line number	Diff line number	Diff line change
`@@ -27,4 +27,5 @@`
`27`	`27`	`temperature,`
`28`	`28`	`tools,`
`29`	`29`	`tracking,`
	`30`	`+ transformer,`
`30`	`31`	`)`