Little things

Author: echedey-ls

docs/examples/shading/plot_martinez_shade_loss.py

@@ -1,52 +1,39 @@
 """
-Calculating power loss from partial module shading
-==================================================
+Modelling power loss due to module shading in non-monolithic Si arrays
+======================================================================
 
-Example of modeling cell-to-cell mismatch loss from partial module shading.
+This example demonstrates how to model power loss due to row-to-row shading in
+a PV array comprised of non-monolithic silicon cells.
 """
 
 # %%
-# 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.
+# The example is based on the work of Martinez et al. [1]_.
+# The model is implemented in :py:func:`pvlib.shading.martinez_shade_loss`.
+# This model corrects the beam and circumsolar incident irradiance
+# based on the number of shaded *blocks*. A *block* is defined as a
+# group of cells that are protected by a bypass diode.
+# More information on the *blocks* can be found in the original paper [1]_ and
+# in the function documentation.
+#
+# The following key functions are used in this example:
+# 1. :py:func:`pvlib.shading.martinez_shade_loss` to calculate the adjustment
+# 2. :py:func:`pvlib.shading.shading_factor1d` to calculate the fraction of
+#    shaded surface and the number of shaded *blocks*, due to row-to-row
+#    shading
+# 
+# .. versionadded:: 0.10.5
+# .. sectionauthor:: Echedey Luis <[email protected]>
 
-from pvlib import pvsystem, singlediode
+from pvlib import shading
 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
-
+# TODO: REBASE FROM SHADING_FACTOR1D
 
 # %%
-# Simulating a cell IV curve
+# yolo
 # --------------------------
 #
-# First, calculate IV curves for individual cells.  The process is as follows:
-#
+

pvlib/shading.py

@@ -540,8 +540,14 @@ def shaded_fraction1d(
 
 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
+    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.10.5
+
+    Parameters
+    ----------
     shaded_fraction : numeric
         Surface shaded fraction. Unitless.
     shaded_blocks : numeric
@@ -552,7 +558,7 @@ def martinez_shade_factor(shaded_fraction, N_shaded_blocks, N_total_blocks):
     Returns
     -------
     shading_correction_factor : numeric
-        Multiply unshaded power by this factor.
+        Multiply direct and circumsolar irradiance by this factor.
 
     Notes
     -----
@@ -563,9 +569,9 @@ def martinez_shade_factor(shaded_fraction, N_shaded_blocks, N_total_blocks):
         (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.
+    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
     ^^^^^^^^^^^^^^^^^^
@@ -580,6 +586,16 @@ def martinez_shade_factor(shaded_fraction, N_shaded_blocks, N_total_blocks):
      - whether or not the module is comprised of *half-cut cells*
     The latter two are heavily correlated.
 
+    For example:
+     - A module with 3 bypass diodes and 3 junction boxes is likely to have
+       3 blocks.
+     - A module with 1 bypass diode and 1 junction box is likely to have 1
+       block.
+     - A module with 3 bypass diodes and 1 junction box is likely to have 3
+       blocks.
+     - A module with 1 bypass diode and 3 junction boxes is likely to have 1
+       block.
+
     Examples
     --------
     Minimal example. For a complete example, see
@@ -589,15 +605,18 @@ def martinez_shade_factor(shaded_fraction, N_shaded_blocks, N_total_blocks):
     >>> 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
+            80, 180, 90, 25,
+             collector_width=0.5, row_pitch=1, surface_to_axis_offset=0,
+             cross_axis_slope=5.711, shading_tracker_tilt=50)
         )
     >>> 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
+    shaded_fraction1d : to calculate 1-dimensional shaded fraction
+    linear_shade_loss
 
     References
     ----------