Merge remote-tracking branch 'upstream/main' into irradiance_updates

Author: RDaxini

.github/workflows/asv_check.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Install Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.12'
 
       - name: Install asv
         run: pip install asv==0.6.4

.github/workflows/flake8.yml

@@ -7,10 +7,10 @@ jobs:
     steps:
       - name: Checkout source
         uses: actions/checkout@v4
-      - name: Install Python 3.11
+      - name: Install Python 3.12
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
       - name: Install Flake8 5.0.4 linter
         run: pip install flake8==5.0.4  # use this version for --diff option
       - name: Setup Flake8 output matcher for PR annotations

.github/workflows/publish.yml

@@ -22,7 +22,8 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: 3.9
+        # Python version should be the minimum supported version
+        python-version: "3.9"
 
     - name: Install build tools
       run: |

README.md

@@ -68,7 +68,7 @@ Documentation
 =============
 
 Full documentation can be found at [readthedocs](http://pvlib-python.readthedocs.io/en/stable/),
-including an [FAQ](http://pvlib-python.readthedocs.io/en/stable/user_guide/faq.html) page.
+including an [FAQ](https://pvlib-python.readthedocs.io/en/stable/user_guide/extras/faq.html) page.
 
 Installation
 ============

docs/examples/agrivoltaics/plot_agrivoltaics_ground_irradiance.py

@@ -0,0 +1,163 @@
+"""
+Agrivoltaic system modeling
+===========================
+
+Irradiance at crop level between rows
+"""
+
+# %%
+# This example demonstrates how to calculate power output for a bifacial
+# agriPV plant as well as calculating the irradiance at crop level
+# using pvlib's infinite sheds model.
+# For an overview of agrivPV concepts and performance, the reader
+# is referred to :doi:`10.69766/XAEU5008`.
+#
+# This gallery example is based on an actual AgriPV plant, namely
+# European Energy's `Flakkebjerg AgriPV site
+# <https://europeanenergy.com/2023/12/20/using-the-same-land-twice-at-european-\
+# energys-flakkebjerg-solar-park/>`_.
+#
+# The first steps are to define the plant location and to calculate solar
+# position and clearsky irradiance for a single day as an example.
+#
+# .. figure:: ../../_images/agrivoltaics_system.jpg
+#    :align: center
+#    :width: 75%
+#    :alt: Photo of an agriPV system
+#
+#    Photo of an agriPV system.
+#    *Source: Adam R. Jensen*
+
+import pvlib
+import pandas as pd
+from pvlib.tools import cosd
+import matplotlib.pyplot as plt
+
+# sphinx_gallery_thumbnail_path = '_images/agrivoltaics_system.jpg'
+
+location = pvlib.location.Location(latitude=55, longitude=10)
+
+times = pd.date_range('2020-06-28', periods=24*60, freq='1min', tz='UTC')
+
+solpos = location.get_solarposition(times)
+
+clearsky = location.get_clearsky(times, model='ineichen')
+
+# %%
+# Next, we need to define the plant layout:
+
+height = 2.6  # [m] height of torque above ground
+pitch = 12  # [m] row spacing
+row_width = 2 * 2.384  # [m] two modules in portrait, each 2 m long
+gcr = row_width / pitch  # ground coverage ratio [unitless]
+axis_azimuth = 0  # [degrees] north-south tracking axis
+max_angle = 55  # [degrees] maximum rotation angle
+
+# %%
+# Before running the infinite sheds model, we need to know the orientation
+# of the trackers. For a single-axis tracker, this can be calculated as:
+
+tracking_orientations = pvlib.tracking.singleaxis(
+    apparent_zenith=solpos['apparent_zenith'],
+    apparent_azimuth=solpos['azimuth'],
+    axis_azimuth=axis_azimuth,
+    max_angle=max_angle,
+    backtrack=True,
+    gcr=gcr,
+)
+
+# %%
+# For agrivPV systems, the local albedo is dependent on crop growth and thus
+# changes throughout the seasons. In this example, we only simulate one
+# day and thus use a constant value. Similarly, we will assume a constant
+# air temperature to avoid getting external data. Both albedo and air
+# temperature could be defined as Series with the same index as used for the
+# solar position calculations.
+
+albedo = 0.20  # [unitless]
+temp_air = 18  # [degrees C]
+
+# %%
+# Now, we are ready to calculate the front and rear-side irradiance using
+# the pvlib infinite sheds model.
+
+dni_extra = pvlib.irradiance.get_extra_radiation(times)
+
+irradiance = pvlib.bifacial.infinite_sheds.get_irradiance(
+    surface_tilt=tracking_orientations['surface_tilt'],
+    surface_azimuth=tracking_orientations['surface_azimuth'],
+    solar_zenith=solpos['apparent_zenith'],
+    solar_azimuth=solpos['azimuth'],
+    gcr=gcr,
+    height=height,
+    pitch=pitch,
+    ghi=clearsky['ghi'],
+    dhi=clearsky['dhi'],
+    dni=clearsky['dni'],
+    albedo=albedo,
+    model='haydavies',
+    dni_extra=dni_extra,
+    bifaciality=0.7,  # [unitless] rear-side power relative to front-side
+)
+
+# %%
+# Once the in-plane irradiance is known, we can estimate the PV array power.
+# For simplicity, we use the PVWatts model:
+
+N_modules = 1512  # [unitless] Number of modules
+pdc0_per_module = 660  # [W] STC rating
+pdc0 = pdc0_per_module * N_modules
+
+gamma_pdc = -0.004  # [1/degrees C]
+
+temp_cell = pvlib.temperature.faiman(
+    poa_global=irradiance['poa_global'],
+    temp_air=temp_air,
+)
+
+power_dc = pvlib.pvsystem.pvwatts_dc(
+    effective_irradiance=irradiance['poa_global'],
+    temp_cell=temp_cell,
+    pdc0=pdc0,
+    gamma_pdc=gamma_pdc)
+
+power_dc.divide(1000).plot()
+plt.ylabel('DC power [kW]')
+plt.show()
+
+# %%
+# In addition to the power output of the PV array, we are also interested
+# in how much irradiance reaches the crops under the array. In this case
+# we calculate the average irradiance on the ground between two rows, using
+# the infinite sheds utility functions.
+#
+# This consists of two parts. First we determine the diffuse irradiance on
+# ground and second we calculate the fraction of the ground that is unshaded
+# (i.e., receives DNI).
+
+vf_ground_sky = pvlib.bifacial.utils.vf_ground_sky_2d_integ(
+    surface_tilt=tracking_orientations['surface_tilt'],
+    gcr=gcr,
+    height=height,
+    pitch=pitch,
+)
+
+unshaded_ground_fraction = pvlib.bifacial.utils._unshaded_ground_fraction(
+    surface_tilt=tracking_orientations['surface_tilt'],
+    surface_azimuth=tracking_orientations['surface_azimuth'],
+    solar_zenith=solpos['apparent_zenith'],
+    solar_azimuth=solpos['azimuth'],
+    gcr=gcr,
+)
+
+crop_avg_irradiance = (unshaded_ground_fraction * clearsky['dni']
+                       * cosd(solpos['apparent_zenith'])
+                       + vf_ground_sky * clearsky['dhi'])
+
+fig, ax = plt.subplots()
+clearsky['ghi'].plot(ax=ax, label='Horizontal irradiance above panels')
+crop_avg_irradiance.plot(ax=ax, label='Horizontal irradiance at crop level')
+ax.legend(loc='upper center')
+ax.set_ylabel('Irradiance [W/m$^2$]')
+ax.set_ylim(-10, 1050)
+plt.show()

docs/examples/system-models/plot_oedi_9068.py

@@ -165,7 +165,7 @@
 # module fraction and returns the average irradiance over the total module
 # surface.
 
-solar_position = location.get_solarposition(psm3.index, latitude, longitude)
+solar_position = location.get_solarposition(psm3.index)
 tracker_angles = mount.get_orientation(
     solar_position['apparent_zenith'],
     solar_position['azimuth']

docs/sphinx/source/_images/agrivoltaics_system.jpg

@@ -412,6 +412,41 @@ def setup(app):
 # https://gist.github.com/flying-sheep/b65875c0ce965fbdd1d9e5d0b9851ef1
 
 
+# select correct base URL depending on the build system context
+def get_source_files_base_url():
+    """
+    Get the base URL for the source code to generate links to GitHub source.
+    If the build is on ReadTheDocs and it's a stable version, use the
+    versioned link. If it's a latest version, use the main link.
+
+    For other builds (e.g. pull requests), use the main link.
+    Local builds will also use the main link.
+
+    Resulting base URL should end with a trailing slash.
+
+    See https://docs.readthedocs.com/platform/stable/reference/environment-variables.html
+    """  # noqa: E501
+    repo_url = os.environ.get(
+        "READTHEDOCS_GIT_CLONE_URL",
+        default="https://github.com/pvlib/pvlib-python",
+    )
+    READTHEDOCS_ENV = os.environ.get("READTHEDOCS", None) == "True"
+    READTHEDOCS_VERSION = os.environ.get("READTHEDOCS_VERSION", None)
+    READTHEDOCS_GIT_IDENTIFIER = os.environ.get(
+        "READTHEDOCS_GIT_IDENTIFIER", None
+    )
+    if READTHEDOCS_ENV:  # Building docs on ReadTheDocs
+        if READTHEDOCS_VERSION == "latest":  # latest version, commited to main
+            repo_url += "/blob/main/"
+        elif READTHEDOCS_VERSION == "stable":  # stable version, has a tag
+            repo_url += f"/blob/{READTHEDOCS_GIT_IDENTIFIER}/"
+        else:  # pull request, user and branch are unknown so use main
+            repo_url += "/blob/main/"
+    else:  # Local build
+        repo_url += "/blob/main/"  # can't tell where to point to
+    return repo_url
+
+
 def get_obj_module(qualname):
     """
     Get a module/class/attribute and its original module by qualname.
@@ -456,18 +491,18 @@ def get_linenos(obj):
         return start, start + len(lines) - 1
 
 
+URL_BASE = get_source_files_base_url()  # Edit on GitHub source code links
+
+
 def make_github_url(file_name):
     """
     Generate the appropriate GH link for a given docs page.  This function
     is intended for use in sphinx template files.
 
     The target URL is built differently based on the type of page.  The pydata
     sphinx theme has a built-in `file_name` variable that looks like
-    "/docs/sphinx/source/api.rst" or "generated/pvlib.atmosphere.alt2pres.rst"
+    "docs/sphinx/source/api.rst" or "generated/pvlib.atmosphere.alt2pres.rst"
     """
-
-    URL_BASE = "https://github.com/pvlib/pvlib-python/blob/main/"
-
     # is it a gallery page?
     if any(d in file_name for d in sphinx_gallery_conf['gallery_dirs']):
         example_folder = file_name.split("/")[-2]