Martinez shading factor

docs/examples/shading/plot_martinez_shade_loss.py

@@ -0,0 +1,240 @@
+"""
+Modelling irradiance loss due to of direct irradiance in modules with bypass diodes
+===================================================================================
+"""  # noqa: E501
+
+# %%
+# This example illustrates how to use the proposed by Martinez et al. [1]_.
+# The model adjusts the incident direct and circumsolar beam irradiance of a
+# PV module based on the number
+# of shaded *blocks*. A *block* is defined as a group of cells protected by a
+# bypass diode. More information on the *blocks* can be found in the original
+# paper [1]_ and in :py:func:`pvlib.shading.direct_martinez`
+# documentation.
+#
+# The following key functions are used in this example:
+#
+# 1. :py:func:`pvlib.shading.direct_martinez` to calculate the adjustment
+#    factor for the output power.
+# 2. :py:func:`pvlib.shading.shaded_fraction1d` to calculate the fraction of
+#    shaded surface and consequently the number of shaded *blocks* due to
+#    row-to-row shading.
+# 3. :py:func:`pvlib.tracking.singleaxis` to calculate the rotation angle of
+#    the trackers.
+#
+# .. sectionauthor:: Echedey Luis <echelual (at) gmail.com>
+#
+# References
+# ----------
+# .. [1] F. Martínez-Moreno, J. Muñoz, and E. Lorenzo, 'Experimental model
+#    to estimate shading losses on PV arrays', Solar Energy Materials and
+#    Solar Cells, vol. 94, no. 12, pp. 2298-2303, Dec. 2010,
+#    :doi:`10.1016/j.solmat.2010.07.029`.
+#
+# Problem description
+# -------------------
+# Let's consider a PV system with the following characteristics:
+#
+# - Two north-south single-axis tracker with 6 modules each one.
+# - The rows have the same true-tracking tilt angles. Let's consider
+#   true-tracking so shade is significant for this example.
+# - Terrain slope is 7 degrees downward to the east.
+# - Rows' axes are horizontal.
+# - The modules are comprised of multiple cells. We will compare these cases:
+#    - modules with one bypass diode
+#    - modules with three bypass diodes
+#    - half-cut cell modules with three bypass diodes on portrait and landscape
+#
+# Setting up the system
+# ----------------------
+# Let's start by defining the system characteristics, location and the time
+# range for the analysis.
+
+import pvlib
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+from matplotlib.dates import ConciseDateFormatter
+
+pitch = 4  # meters
+width = 1.5  # meters
+gcr = width / pitch
+N_modules_per_row = 6
+axis_azimuth = 180  # N-S axis
+axis_tilt = 0  # flat because the axis is perpendicular to the slope
+cross_axis_tilt = -7  # 7 degrees downward to the east
+
+latitude, longitude = 40.2712, -3.7277
+locus = pvlib.location.Location(
+    latitude,
+    longitude,
+    tz="Europe/Madrid",
+    altitude=pvlib.location.lookup_altitude(latitude, longitude),
+)
+
+times = pd.date_range("2001-04-11T04", "2001-04-11T20", freq="10min")
+
+# %%
+# True-tracking algorithm and shaded fraction
+# -------------------------------------------
+# Since this model is about row-to-row shading, we will use the true-tracking
+# algorithm to calculate the trackers rotation. Back-tracking reduces the
+# shading between rows, but since this example is about shading, we will not
+# use it.
+#
+# Then, the next step is to calculate the fraction of shaded surface. This is
+# done using :py:func:`pvlib.shading.shaded_fraction1d`. Using this function is
+# straightforward with the variables we already have defined.
+# Then, we can calculate the number of shaded blocks by rounding up the shaded
+# fraction by the number of blocks along the shaded length.
+
+# Calculate solar position to get single-axis tracker rotation and irradiance
+solar_pos = locus.get_solarposition(times)
+solar_apparent_zenith, solar_azimuth = (
+    solar_pos["apparent_zenith"],
+    solar_pos["azimuth"],
+)  # unpack for better readability
+
+tracking_result = pvlib.tracking.singleaxis(
+    apparent_zenith=solar_apparent_zenith,
+    apparent_azimuth=solar_azimuth,
+    axis_tilt=axis_tilt,
+    axis_azimuth=axis_azimuth,
+    max_angle=(-90 + cross_axis_tilt, 90 + cross_axis_tilt),  # (min, max)
+    backtrack=False,
+    gcr=gcr,
+    cross_axis_tilt=cross_axis_tilt,
+)
+
+tracker_theta, aoi, surface_tilt, surface_azimuth = (
+    tracking_result["tracker_theta"],
+    tracking_result["aoi"],
+    tracking_result["surface_tilt"],
+    tracking_result["surface_azimuth"],
+)  # unpack for better readability
+
+# Calculate the shade fraction
+shaded_fraction = pvlib.shading.shaded_fraction1d(
+    solar_apparent_zenith,
+    solar_azimuth,
+    axis_azimuth,
+    axis_tilt=axis_tilt,
+    shaded_row_rotation=tracker_theta,
+    shading_row_rotation=tracker_theta,
+    collector_width=width,
+    pitch=pitch,
+    cross_axis_slope=cross_axis_tilt,
+)
+
+# %%
+# Number of shaded blocks
+# -----------------------
+# The number of shaded blocks depends on the module configuration and number
+# of bypass diodes. For example,
+# modules with one bypass diode will behave like one block.
+# On the other hand, modules with three bypass diodes will have three blocks,
+# except for the half-cut cell modules, which will have six blocks; 2x3 blocks
+# where the two rows are along the longest side of the module.
+# We can argue that the dimensions of the system changes when you switch from
+# portrait to landscape, but for this example, we will consider it the same.
+#
+# The number of shaded blocks is calculated by rounding up the shaded fraction
+# by the number of blocks along the shaded length. So let's define the number
+# of blocks for each module configuration:
+#
+# - 1 bypass diode: 1 block
+# - 3 bypass diodes: 3 blocks in landscape; 1 in portrait
+# - 3 bypass diodes half-cut cells:
+#   - 2 blocks in portrait
+#   - 3 blocks in landscape
+#
+# .. figure:: ../../_images/PV_module_layout_cesardd.jpg
+#    :align: center
+#    :width: 75%
+#    :alt: Normal and half-cut cells module layouts
+#
+#    Left: common module layout. Right: half-cut cells module layout.
+#    Each module has three bypass diodes. On the left, they connect cell
+#    columns 1-2, 2-3 & 3-4. On the right, they connect cell rows 1-2, 3-4 &
+#    5-6.
+#    *Source: César Domínguez. CC BY-SA 4.0, Wikimedia Commons*
+#
+# In the upper image, each orange U-shaped section of the string is a block.
+# By symmetry, the yellow inverted-U's of the subcircuit are also blocks.
+# For this reason, the half-cut cell modules have 6 blocks in total: two along
+# the longest side and three along the shortest side.
+
+blocks_per_module = {
+    "1 bypass diode": 1,
+    "3 bypass diodes": 3,
+    "3 bypass diodes half-cut, portrait": 2,
+    "3 bypass diodes half-cut, landscape": 3,
+}
+
+# Calculate the number of shaded blocks during the day
+shaded_blocks_per_module = {
+    k: np.ceil(blocks_N * shaded_fraction)
+    for k, blocks_N in blocks_per_module.items()
+}
+
+# %%
+# Results
+# -------
+# Now that we have the number of shaded blocks for each module configuration,
+# we can apply the model and estimate the power loss due to shading.
+#
+# Note this model is not linear with the shaded blocks ratio, so there is a
+# difference between applying it to just a module or a whole row.
+
+shade_factor_per_module = {
+    k: pvlib.shading.direct_martinez(
+        shaded_fraction, module_shaded_blocks, blocks_per_module[k]
+    )
+    for k, module_shaded_blocks in shaded_blocks_per_module.items()
+}
+
+shade_factor_per_row = {
+    k: pvlib.shading.direct_martinez(
+        shaded_fraction,
+        module_shaded_blocks * N_modules_per_row,
+        blocks_per_module[k] * N_modules_per_row,
+    )
+    for k, module_shaded_blocks in shaded_blocks_per_module.items()
+}
+
+fig, (ax1, ax2) = plt.subplots(2, 1, sharex=True)
+fig.suptitle("Martinez power correction factor due to shading")
+for k, shade_factor in shade_factor_per_module.items():
+    linestyle = "--" if k == "3 bypass diodes half-cut, landscape" else "-"
+    ax1.plot(times, shade_factor, label=k, linestyle=linestyle)
+ax1.legend()
+ax1.grid()
+ax1.set_xlabel("Time")
+ax1.xaxis.set_major_formatter(
+    ConciseDateFormatter("%H:%M", tz="Europe/Madrid")
+)
+ax1.set_ylabel("Power correction factor")
+ax1.set_title("Per module")
+
+for k, shade_factor in shade_factor_per_row.items():
+    linestyle = "--" if k == "3 bypass diodes half-cut, landscape" else "-"
+    ax2.plot(times, shade_factor, label=k, linestyle=linestyle)
+ax2.legend()
+ax2.grid()
+ax2.set_xlabel("Time")
+ax2.xaxis.set_major_formatter(
+    ConciseDateFormatter("%H:%M", tz="Europe/Madrid")
+)
+ax2.set_ylabel("Power correction factor")
+ax2.set_title("Per row")
+fig.tight_layout()
+fig.show()
+
+# %%
+# Note how the half-cut cell module in portrait behaves worse that the
+# normal module with three bypass diodes. This is because the number of shaded
+# blocks is less along the shaded length.
+# This is the reason why half-cut cell modules are preferred in portrait
+# orientation.
+
+# %%

docs/sphinx/source/reference/effects_on_pv_system_output/shading.rst

@@ -12,4 +12,4 @@ Shading
    shading.sky_diffuse_passias
    shading.projected_solar_zenith_angle
    shading.shaded_fraction1d
-
+   shading.direct_martinez

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

@@ -32,6 +32,9 @@ Enhancements
   efficiency ([unitless]) and vice versa. The conversion functions are
   :py:func:`pvlib.spectrum.sr_to_qe` and :py:func:`pvlib.spectrum.qe_to_sr`
   respectively. (:issue:`2040`, :pull:`2041`)
+* Added function :py:func:`pvlib.shading.direct_martinez` to calculate
+  shading losses by taking into account the amount of bypass diodes of a module.
+  (:issue:`2063`, :pull:`2070`)
 
 
 Bug fixes

pvlib/shading.py

@@ -553,3 +553,101 @@ def shaded_fraction1d(
     )
 
     return np.clip(t_asterisk, 0, 1)
+
+
+def direct_martinez(shaded_fraction, shaded_blocks, total_blocks):
+    r"""
+    A shading correction factor for the direct and circumsolar incident
+    irradiance of non-monolithic Silicon
+    modules and arrays with an arbitrary number of bypass diodes.
+
+    .. versionadded:: 0.11.0
+
+    Parameters
+    ----------
+    shaded_fraction : numeric
+        Fraction of module surface area that is shaded. Unitless.
+    shaded_blocks : numeric
+        Number of blocks affected by the shadow. Unitless.
+        If a floating point number is provided, it will be rounded up.
+    total_blocks : int
+        Number of total blocks. Unitless.
+
+    Returns
+    -------
+    shading_correction_factor : numeric
+        Multiply direct and circumsolar irradiance by this factor.
+
+    Notes
+    -----
+    The implemented equation is (6) from [1]_:
+
+    .. math::
+
+        (1 - F_{ES}) = (1 - F_{GS}) (1 - \frac{N_{SB}}{N_{TB} + 1})
+
+    Where :math:`(1 - F_{ES})` is the correction factor to be multiplied by
+    the direct and circumsolar irradiance, :math:`F_{GS}` is the shaded
+    fraction of the collector, :math:`N_{SB}` is the number of shaded blocks
+    and :math:`N_{TB}` is the number of total blocks.
+
+    Blocks terminology
+    ^^^^^^^^^^^^^^^^^^
+    [1]_ defines a *block* as a group of solar cells protected by a bypass
+    diode. Also, a *block* is shaded when at least one of its cells is shaded.
+
+    How many blocks and their layout depend on the module(s) used. Many
+    manufacturers don't specify this information explicitly. However, we can
+    infer these values from:
+
+    - the number of bypass diodes
+    - where and how many junction boxes are present on the back of the module
+    - whether or not the module is comprised of *half-cut cells*
+
+    The latter two are heavily correlated.
+
+    For example:
+
+    1. A module with 1 bypass diode behaves as 1 block.
+    2. A module with 3 bypass diodes and 1 junction box is likely to have 3
+       blocks.
+    3. A half-cut module with 3 junction boxes (split junction boxes) is
+       likely to have 3x2 blocks. The number of blocks along the longest
+       side of the module is 2 and along the shortest side is 3.
+    4. A module without bypass diodes doesn't constitute a block, but may be
+       part of one.
+
+    Examples
+    --------
+    Minimal example. For a complete example, see
+    `this gallery example <sphx_glr_gallery_plot_martinez_shade_loss.py>`_.
+
+    >>> import numpy as np
+    >>> from pvlib import shading
+    >>> total_blocks = 3  # blocks along the vertical of the module
+    >>> POA_direct = 600  # W
+    >>> POA_diffuse = 80  # W
+    >>> shaded_fraction = shading.shaded_fraction1d(
+    >>>     80, 180, 90, 25,
+    >>>     collector_width=0.5, pitch=1, surface_to_axis_offset=0,
+    >>>     cross_axis_slope=5.711, shading_row_rotation=50)
+    >>> shaded_blocks = np.ceil(total_blocks*shaded_fraction)
+    >>> loss_correction = shading.direct_martinez(
+    >>>     shaded_fraction, shaded_blocks, total_blocks)
+    >>> POA_total = POA_direct * loss_correction + POA_diffuse
+
+    See Also
+    --------
+    shaded_fraction1d : to calculate 1-dimensional shaded fraction
+
+    References
+    ----------
+    .. [1] F. Martínez-Moreno, J. Muñoz, and E. Lorenzo, 'Experimental model
+        to estimate shading losses on PV arrays', Solar Energy Materials and
+        Solar Cells, vol. 94, no. 12, pp. 2298-2303, Dec. 2010,
+        :doi:`10.1016/j.solmat.2010.07.029`.
+    """  # Contributed by Echedey Luis, 2024
+    return (  # Eq. (6) of [1]
+        (1 - shaded_fraction)
+        * (1 - np.ceil(shaded_blocks) / (1 + total_blocks))
+    )