diff --git a/docs/sphinx/source/user_guide/index.rst b/docs/sphinx/source/user_guide/index.rst index f8da3b6b44..af2a4cbb92 100644 --- a/docs/sphinx/source/user_guide/index.rst +++ b/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 diff --git a/docs/sphinx/source/user_guide/modeling_topics/iam.rst b/docs/sphinx/source/user_guide/modeling_topics/iam.rst new file mode 100644 index 0000000000..ecd591133e --- /dev/null +++ b/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 `) 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`. diff --git a/docs/sphinx/source/whatsnew/v0.15.1.rst b/docs/sphinx/source/whatsnew/v0.15.1.rst index 5cd4131c85..9955df7473 100644 --- a/docs/sphinx/source/whatsnew/v0.15.1.rst +++ b/docs/sphinx/source/whatsnew/v0.15.1.rst @@ -24,6 +24,7 @@ Enhancements Documentation ~~~~~~~~~~~~~ +* Provide an overview of IAM modeling functionality in :ref:`iam`. (:pull:`2683`) Testing @@ -45,4 +46,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`)