Merge branch 'main' into add-examples-poa-irrad

Author: Chirag3841

docs/sphinx/source/user_guide/index.rst

@@ -27,6 +27,7 @@ This user guide is an overview and explains some of the key features of pvlib.
    modeling_topics/weather_data
    modeling_topics/singlediode
    modeling_topics/temperature
+   modeling_topics/iam
 
 .. toctree::
    :maxdepth: 2

docs/sphinx/source/user_guide/modeling_topics/iam.rst

@@ -0,0 +1,100 @@
+.. _iam:
+
+
+Incidence angle modifier
+========================
+
+Some fraction of the light incident on a PV module surface is reflected away or
+absorbed before it reaches the PV cell.  This irradiance reduction depends
+on the angle at which the light strikes the module (the angle of incidence,
+:term:`AOI <aoi>`) and the optical properties of the module.
+
+Some reduction occurs at all angles of incidence, even normal incidence.
+However, because PV modules are rated with irradiance at normal incidence,
+the reduction at normal incidence is implicit in the PV module's power rating
+and does not need to be accounted for separately in a performance model.
+Therefore, only the extra reduction at non-normal incidence should be modeled.
+
+This is done using incidence angle modififer (:term:`IAM`) models.
+Conceptually, IAM is the fraction of incident light that is
+transmitted to the PV cell, normalized to the fraction transmitted at normal incidence:
+
+.. math::
+
+   IAM(\theta) = \frac{T(\theta)}{T(0)},
+
+where :math:`T(\theta)` represents the transmitted light fraction at AOI :math:`\theta`.
+IAM equals (by definition) 1.0 when AOI is zero and typically approaches zero
+as AOI approaches 90°.  The shape of the IAM profile at intermediate AOI
+is nonlinear and depends on the module's optical properties.
+
+IAM may also depend on the wavelength of the light, the polarization of the light,
+and which side of the module the light comes from.  However, IAM models usually
+neglect these minor effects.
+
+IAM functions in pvlib take an input angle in degrees and return a unitless ratio
+in the range 0–1.
+
+
+Types of models
+---------------
+
+Because total in-plane irradiance is the combination of light from many
+directions, IAM values are computed for each component separately:
+
+- *direct IAM*: IAM computed for the AOI of direct irradiance
+- *circumsolar IAM*: typically approximated as equal to the direct IAM
+- *diffuse IAM*: IAM integrated across the ranges of AOI spanning the sky and/or
+  ground surfaces
+
+Because diffuse light can be thought of as a field of many small beams of
+direct light, diffuse IAM can then be understood as the IAM averaged across
+those individual beams.  This averaging can be done explicitly or empirically.
+
+In principle, IAM should be applied to all components of incident irradiance.
+In practice, IAM is sometimes applied only to the direct component of in-plane
+irradiance, as the direct component is often the largest contributor to total
+in-plane irradiance and has a highly variable AOI across the day and year.
+
+The IAM models currently available in pvlib are summarized in the
+following table:
+
++-------------------------------------------+---------+-------------------------------------------+
+| Model                                     | Type    | Notes                                     |
++===========================================+=========+===========================================+
+| :py:func:`~pvlib.iam.ashrae`              | direct  | Once common, now less used                |
++-------------------------------------------+---------+-------------------------------------------+
+| :py:func:`~pvlib.iam.martin_ruiz`         | direct  | Used in the IEC 61853 standard            |
++-------------------------------------------+---------+-------------------------------------------+
+| :py:func:`~pvlib.iam.martin_ruiz_diffuse` | diffuse | Used in the IEC 61853 standard            |
++-------------------------------------------+---------+-------------------------------------------+
+| :py:func:`~pvlib.iam.physical`            | direct  | Physics-based; optional AR coating        |
++-------------------------------------------+---------+-------------------------------------------+
+| :py:func:`~pvlib.iam.sapm`                | direct  | Can be non-monotonic and exceed 1.0       |
++-------------------------------------------+---------+-------------------------------------------+
+| :py:func:`~pvlib.iam.schlick`             | direct  | Does not take module-specific parameters  |
++-------------------------------------------+---------+-------------------------------------------+
+| :py:func:`~pvlib.iam.schlick_diffuse`     | diffuse | Does not take module-specific parmaeters  |
++-------------------------------------------+---------+-------------------------------------------+
+
+In addition to the core models above, pvlib provides several other functions
+for IAM modeling:
+
+- :py:func:`~pvlib.iam.interp`: interpolate between points on a measured IAM profile 
+- :py:func:`~pvlib.iam.marion_diffuse` and :py:func:`~pvlib.iam.marion_integrate`:
+  numerically integrate any IAM model across AOI to compute sky, horizon, and ground IAMs
+
+
+Model parameters
+----------------
+
+Some IAM model functions provide default values for their parameters.
+However, these generic values may not be suitable for all PV modules.
+It should be noted that using the default parameter values for each 
+model generally leads to different IAM profiles.
+
+Module-specific values can be obtained via testing.  For example, IEC 61853-2
+testing produces measured IAM values across the range of AOI and a corresponding
+parameter value for the Martin-Ruiz model.  Parameter values for other models can
+be determined using :py:func:`pvlib.iam.fit`.  Parameter values can also be approximately
+converted between models using :py:func:`pvlib.iam.convert`.

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

@@ -27,6 +27,7 @@ Documentation
 * Add examples for run_model_from_poa() and run_model_from_effective_irradiance()
   (:issue:`1043`, :pull:`2621`)
 
+* Provide an overview of IAM modeling functionality in :ref:`iam`. (:pull:`2683`)
 
 
 Testing
@@ -48,4 +49,9 @@ Maintenance
 Contributors
 ~~~~~~~~~~~~
 * Aman Srivastava (:ghuser:`aman-coder03`)
+* Rajiv Daxini (:ghuser:`RDaxini`)
+* Echedey Luis (:ghuser:`echedey-ls`)
+* Cliff Hansen (:ghuser:`cwhanse`)
+* Anton Driesse (:ghuser:`adriesse`)
+* Kevin Anderson (:ghuser:`kandersolar`)
 

pvlib/tools.py

@@ -471,14 +471,14 @@ def _degrees_to_index(degrees, coordinate):
         inputmax = 180
         outputmax = 4320
     else:
-        raise IndexError("coordinate must be 'latitude' or 'longitude'.")
+        raise ValueError("coordinate must be 'latitude' or 'longitude'.")
 
     inputrange = inputmax - inputmin
     scale = outputmax/inputrange  # number of indices per degree
     center = inputmin + 1 / scale / 2  # shift to center of index
     outputmax -= 1  # shift index to zero indexing
     index = (degrees - center) * scale
-    err = IndexError('Input, %g, is out of range (%g, %g).' %
+    err = ValueError('Input, %g, is out of range (%g, %g).' %
                      (degrees, inputmin, inputmax))
 
     # If the index is still out of bounds after rounding, raise an error.

tests/test_clearsky.py

@@ -505,13 +505,13 @@ def monthly_lt_nointerp(lat, lon, time=months):
         monthly_lt_nointerp(-90, 180),
         [1.35, 1.7, 1.35, 1.35, 1.35, 1.35, 1.35, 1.35, 1.35, 1.35, 1.35, 1.7])
     # test out of range exceptions at corners
-    with pytest.raises(IndexError):
+    with pytest.raises(ValueError, match="out of range"):
         monthly_lt_nointerp(91, -122)  # exceeds max latitude
-    with pytest.raises(IndexError):
+    with pytest.raises(ValueError, match="out of range"):
         monthly_lt_nointerp(38.2, 181)  # exceeds max longitude
-    with pytest.raises(IndexError):
+    with pytest.raises(ValueError, match="out of range"):
         monthly_lt_nointerp(-91, -122)  # exceeds min latitude
-    with pytest.raises(IndexError):
+    with pytest.raises(ValueError, match="out of range"):
         monthly_lt_nointerp(38.2, -181)  # exceeds min longitude
 
 

tests/test_tools.py

@@ -102,7 +102,8 @@ def test__golden_sect_DataFrame_nans():
 def test_degrees_to_index_1():
     """Test that _degrees_to_index raises an error when something other than
     'latitude' or 'longitude' is passed."""
-    with pytest.raises(IndexError):  # invalid value for coordinate argument
+    # invalid value for coordinate argument
+    with pytest.raises(ValueError, match="coordinate must be"):
         tools._degrees_to_index(degrees=22.0, coordinate='width')