Initial work

Author: echedey-ls

docs/examples/shading/plot_martinez_shade_loss.py

@@ -0,0 +1,52 @@
+"""
+Calculating power loss from partial module shading
+==================================================
+
+Example of modeling cell-to-cell mismatch loss from partial module shading.
+"""
+
+# %%
+# Even though the PV cell is the primary power generation unit, PV modeling is
+# often done at the module level for simplicity because module-level parameters
+# are much more available and it significantly reduces the computational scope
+# of the simulation.  However, module-level simulations are too coarse to be
+# able to model effects like cell to cell mismatch or partial shading.  This
+# example calculates cell-level IV curves and combines them to reconstruct
+# the module-level IV curve.  It uses this approach to find the maximum power
+# under various shading and irradiance conditions.
+#
+# The primary functions used here are:
+#
+# - :py:meth:`pvlib.pvsystem.calcparams_desoto` to estimate the single
+#   diode equation parameters at some specified operating conditions.
+# - :py:meth:`pvlib.singlediode.bishop88` to calculate the full cell IV curve,
+#   including the reverse bias region.
+#
+# .. note::
+#
+#     This example requires the reverse bias functionality added in pvlib 0.7.2
+#
+# .. warning::
+#
+#     Modeling partial module shading is complicated and depends significantly
+#     on the module's electrical topology.  This example makes some simplifying
+#     assumptions that are not generally applicable.  For instance, it assumes
+#     that shading only applies to beam irradiance (*i.e.* all cells receive
+#     the same amount of diffuse irradiance) and cell temperature is uniform
+#     and not affected by cell-level irradiance variation.
+
+from pvlib import pvsystem, singlediode
+import pandas as pd
+import numpy as np
+from scipy.interpolate import interp1d
+import matplotlib.pyplot as plt
+
+from scipy.constants import e as qe, k as kB
+
+
+# %%
+# Simulating a cell IV curve
+# --------------------------
+#
+# First, calculate IV curves for individual cells.  The process is as follows:
+#

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.martinez_shade_factor

pvlib/shading.py

@@ -553,3 +553,77 @@ def shaded_fraction1d(
     )
 
     return np.clip(t_asterisk, 0, 1)
+
+
+def martinez_shade_factor(shaded_fraction, N_shaded_blocks, N_total_blocks):
+    r"""
+    A shading correction factor for the power yield of non-monolithic Silicon
+    modules and arrays with an arbitrary number of bypass diodes.
+    shaded_fraction : numeric
+        Surface shaded fraction. Unitless.
+    shaded_blocks : numeric
+        Number of blocks affected by the shadow. Unitless integer.
+    total_blocks : numeric
+        Number of total blocks. Unitless integer.
+
+    Returns
+    -------
+    shading_correction_factor : numeric
+        Multiply unshaded power 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 unshaded irradiance, :math:`F_{GS}` is the shaded fraction,
+    :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.
+
+    Examples
+    --------
+    Minimal example. For a complete example, see
+    :ref:`this 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
+    >>> Pwr_out_unshaded = 100  # kW
+    >>> shaded_fraction = shading.shaded_fraction1d(
+            TODO copy from linear loss PR
+        )
+    >>> shaded_blocks = np.ceil(total_blocks*shaded_fraction)
+    >>> loss_correction = shading.martinez_shade_factor()
+    >>> Pwr_out_shaded = Pwr_out_unshaded * loss_correction
+
+    See Also
+    --------
+    pvlib.shading.linear_shade_loss for monolithic thin film modules
+
+    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 - N_shaded_blocks / (1 + N_total_blocks))
+    )

pvlib/tests/test_shading.py

@@ -307,3 +307,9 @@ def test_shaded_fraction1d(sf1d_premises_and_expected):
     sf_vec = shading.shaded_fraction1d(**premises)
     assert_allclose(sf_vec, expected_sf_array, atol=1e-6)
     assert isinstance(sf_vec, pd.Series)
+
+
+def test_martinez_shade_factor():
+    """Tests pvlib.shading.martinez_shade_factor"""
+    # TODO
+    pass