From f9606dc1c21f67bc13eff8aee9795d24e202a34c Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Thu, 2 Oct 2025 16:36:39 -0400 Subject: [PATCH 1/6] initial additions --- .../modeling_topics/singlediode.rst | 115 +++++++++++++++++- 1 file changed, 111 insertions(+), 4 deletions(-) diff --git a/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst b/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst index 085b0b66cc..697f46c802 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst @@ -1,7 +1,114 @@ .. _singlediode: -Single Diode Equation -===================== +Single diode models +=================== + +Single-diode models are a popular means of simulating the electrical output +of a PV module under any given irradiance and temperature conditions. +A single-diode model (SDM) pairs the single-diode equation (SDE) with a set of +auxiliary equations that predict the SDE parameters at any given irradiance +and temperature. All SDMs use the SDE, but their auxiliary equations differ. +For more background on SDMs, see the `PVPMC website +`_. + +Three SDMs are currently available in pvlib: the CEC SDM, the PVsyst SDM, +and the De Soto SDM. pvlib splits these models into two steps. The first +is to compute the auxiliary equations using one of the following functions: + +* CEC SDM: :py:func:`~pvlib.pvsystem.calcparams_cec` +* PVsyst SDM: :py:func:`~pvlib.pvsystem.calcparams_pvsyst` +* De Soto SDM: :py:func:`~pvlib.pvsystem.calcparams_desoto` + +The second step is to use the output of these functions to compute points on +the SDE's I-V curve, as described in the following sections. + +Computing key SDE I-V points +---------------------------- +Three points on the SDE I-V curve are typically of special interest for PV modeling: +the maximum power (MP), open circuit (OC) and short circuit (SC) points. However, +because the SDE is an implicit transcendental equation, it is not possible +to directly calculate these points. Instead, pvlib provides several algorithms +for computing these points. + +The most accurate and convenient function is :py:func:`pvlib.pvsystem.singlediode`. +It provides several methods of computing these points: + ++------------------+------------+-----------+-------------------------+ +| Method | Type | Speed | Guaranteed convergence? | ++==================+============+===========+=========================+ +| ``newton`` | iterative | fast | no | ++------------------+------------+-----------+-------------------------+ +| ``brentq`` | iterative | slow | yes | ++------------------+------------+-----------+-------------------------+ +| ``chandrupatla`` | iterative | fast | yes | ++------------------+------------+-----------+-------------------------+ +| ``lambertw`` | explicit | medium | yes | ++------------------+------------+-----------+-------------------------+ + +If lower accuracy (within ~1%) is allowable, these points can be estimated +much more quickly using :py:func:`pvlib.singlediode.batzelis_keypoints`. + + +Computing full I-V curves +------------------------- + +Full I-V curves with an arbitrary number of points can be computed using +:py:func:`pvlib.pvsystem.i_from_v` and :py:func:`pvlib.pvsystem.v_from_i`, which +calculate either current or voltage from the other. It is often useful to +first compute the key points using :py:func:`pvlib.pvsystem.singlediode` to +determine the open-circuit or short-circuit values, and then compute a range +of voltages/currents from zero to those extreme points. This range can then +be used with the above functions to compute the I-V curve. + + +Special thin film parameters +---------------------------- + +The PVsyst SDM has two additional, optional parameters to better represent +the behavior of CdTe and a-Si modules. As these parameters are not included +in the standard SDE, special methods are needed to account for them. +The functions :py:func:`pvlib.pvsystem.max_power_point`, +:py:func:`pvlib.singlediode.bishop88_i_from_v`, +and :py:func:`pvlib.singlediode.bishop88_v_from_i` +can compute the key points and full I-V curves using these parameters. + + +Reverse bias breakdown +---------------------- + +Although the standard SDE does not account for reverse bias breakdown, the +following functions can optionally include an extra term for modeling it: +:py:func:`pvlib.pvsystem.max_power_point`, +:py:func:`pvlib.singlediode.bishop88_i_from_v`, +and :py:func:`pvlib.singlediode.bishop88_v_from_i`. + + +Model parameter values +---------------------- + +Despite some models having parameters with similar names, parameter values are +specific to the model and thus must be produced with the intended model in mind. +Sometimes sets of parameter values can be read in from external sources, for example: + +* CEC SDM parameter database available from :py:func:`~pvlib.pvsystem.retrieve_sam` +* PAN files, which can be read using :py:func:`~pvlib.iotools.read_panond` + +pvlib also provides a set of functions that can estimate SDM parameter values +from various datasources: + ++---------------------------------------------------------------+---------+--------------------+ +| Function | SDM | Inputs | ++===============================================================+=========+====================+ +| :py:func:`~pvlib.ivtools.sdm.fit_cec_sam` | CEC | datasheet | +| :py:func:`~pvlib.ivtools.sdm.fit_desoto` | De Soto | datasheet | +| :py:func:`~pvlib.ivtools.sdm.fit_desoto_sandia` | De Soto | I-V curves | +| :py:func:`~pvlib.ivtools.sdm.fit_pvsyst_sandia` | PVsyst | I-V curves | +| :py:func:`~pvlib.ivtools.sdm.fit_pvsyst_iec61853_sandia_2025` | PVsyst | IEC 61853-1 matrix | ++---------------------------------------------------------------+---------+--------------------+ + + +Single-diode equation +--------------------- This section reviews the solutions to the single diode equation used in pvlib-python to generate an IV curve of a PV module. @@ -15,7 +122,7 @@ The :func:`pvlib.pvsystem.singlediode` function allows the user to choose the method using the ``method`` keyword. Lambert W-Function ------------------- +****************** When ``method='lambertw'``, the Lambert W-function is used as previously shown by Jain, Kapoor [1, 2] and Hansen [3]. The following algorithm can be found on `Wikipedia: Theory of Solar Cells @@ -50,7 +157,7 @@ Then the module current can be solved using the Lambert W-function, Bishop's Algorithm ------------------- +****************** The function :func:`pvlib.singlediode.bishop88` uses an explicit solution [4] that finds points on the IV curve by first solving for pairs :math:`(V_d, I)` where :math:`V_d` is the diode voltage :math:`V_d = V + I*Rs`. Then the voltage From 241ba2ceffcd46891841d232acec622624cfe45f Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Fri, 3 Oct 2025 10:29:44 -0400 Subject: [PATCH 2/6] fix table --- docs/sphinx/source/user_guide/modeling_topics/singlediode.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst b/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst index 697f46c802..9d904b5f25 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst @@ -100,9 +100,13 @@ from various datasources: | Function | SDM | Inputs | +===============================================================+=========+====================+ | :py:func:`~pvlib.ivtools.sdm.fit_cec_sam` | CEC | datasheet | ++---------------------------------------------------------------+---------+--------------------+ | :py:func:`~pvlib.ivtools.sdm.fit_desoto` | De Soto | datasheet | ++---------------------------------------------------------------+---------+--------------------+ | :py:func:`~pvlib.ivtools.sdm.fit_desoto_sandia` | De Soto | I-V curves | ++---------------------------------------------------------------+---------+--------------------+ | :py:func:`~pvlib.ivtools.sdm.fit_pvsyst_sandia` | PVsyst | I-V curves | ++---------------------------------------------------------------+---------+--------------------+ | :py:func:`~pvlib.ivtools.sdm.fit_pvsyst_iec61853_sandia_2025` | PVsyst | IEC 61853-1 matrix | +---------------------------------------------------------------+---------+--------------------+ From 2be74c2b091f86c048445f69f6af8438e296fe88 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Fri, 3 Oct 2025 10:45:42 -0400 Subject: [PATCH 3/6] revisions --- .../user_guide/modeling_topics/singlediode.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst b/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst index 9d904b5f25..ceb8bcbc82 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst @@ -25,10 +25,9 @@ the SDE's I-V curve, as described in the following sections. Computing key SDE I-V points ---------------------------- Three points on the SDE I-V curve are typically of special interest for PV modeling: -the maximum power (MP), open circuit (OC) and short circuit (SC) points. However, -because the SDE is an implicit transcendental equation, it is not possible -to directly calculate these points. Instead, pvlib provides several algorithms -for computing these points. +the maximum power (MP), open circuit (OC), and short circuit (SC) points. +Unfortunately, computing them is complicated by the SDE being an implicit transcendental +equation. pvlib provides several algorithms for computing these points. The most accurate and convenient function is :py:func:`pvlib.pvsystem.singlediode`. It provides several methods of computing these points: @@ -52,11 +51,11 @@ much more quickly using :py:func:`pvlib.singlediode.batzelis_keypoints`. Computing full I-V curves ------------------------- -Full I-V curves with an arbitrary number of points can be computed using +Full I-V curves can be computed using :py:func:`pvlib.pvsystem.i_from_v` and :py:func:`pvlib.pvsystem.v_from_i`, which calculate either current or voltage from the other. It is often useful to -first compute the key points using :py:func:`pvlib.pvsystem.singlediode` to -determine the open-circuit or short-circuit values, and then compute a range +first compute the open-circuit or short-circuit values using +:py:func:`pvlib.pvsystem.singlediode` and then compute a range of voltages/currents from zero to those extreme points. This range can then be used with the above functions to compute the I-V curve. From 8f529c868135da24d0405148a1fe0f194755ba86 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Fri, 3 Oct 2025 10:54:12 -0400 Subject: [PATCH 4/6] whatsnew --- docs/sphinx/source/whatsnew/v0.13.2.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/sphinx/source/whatsnew/v0.13.2.rst b/docs/sphinx/source/whatsnew/v0.13.2.rst index f649a93fd0..de18e634d5 100644 --- a/docs/sphinx/source/whatsnew/v0.13.2.rst +++ b/docs/sphinx/source/whatsnew/v0.13.2.rst @@ -22,6 +22,7 @@ Enhancements Documentation ~~~~~~~~~~~~~ +* Provide an overview of single-diode modeling functionality in :ref:`singlediode`. (:pull:`2565`) Testing From 4dd10da6e78884c148e23d9afe31db18edb91b4f Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Fri, 3 Oct 2025 13:40:51 -0400 Subject: [PATCH 5/6] Apply suggestions from code review Co-authored-by: Cliff Hansen --- .../modeling_topics/singlediode.rst | 55 +++++++++---------- 1 file changed, 25 insertions(+), 30 deletions(-) diff --git a/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst b/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst index ceb8bcbc82..297cce85d1 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst @@ -20,17 +20,11 @@ is to compute the auxiliary equations using one of the following functions: * De Soto SDM: :py:func:`~pvlib.pvsystem.calcparams_desoto` The second step is to use the output of these functions to compute points on -the SDE's I-V curve, as described in the following sections. - -Computing key SDE I-V points ----------------------------- -Three points on the SDE I-V curve are typically of special interest for PV modeling: -the maximum power (MP), open circuit (OC), and short circuit (SC) points. -Unfortunately, computing them is complicated by the SDE being an implicit transcendental -equation. pvlib provides several algorithms for computing these points. - -The most accurate and convenient function is :py:func:`pvlib.pvsystem.singlediode`. -It provides several methods of computing these points: +the SDE's I-V curve. Three points on the SDE I-V curve are typically of special +interest for PV modeling: the maximum power (MP), open circuit (OC), and +short circuit (SC) points. The most convenient function for computing these +points is :py:func:`pvlib.pvsystem.singlediode`. It provides several methods +for solving the SDE: +------------------+------------+-----------+-------------------------+ | Method | Type | Speed | Guaranteed convergence? | @@ -44,7 +38,7 @@ It provides several methods of computing these points: | ``lambertw`` | explicit | medium | yes | +------------------+------------+-----------+-------------------------+ -If lower accuracy (within ~1%) is allowable, these points can be estimated +If lower accuracy (within ~1%) is allowable, the special points can be estimated much more quickly using :py:func:`pvlib.singlediode.batzelis_keypoints`. @@ -53,43 +47,44 @@ Computing full I-V curves Full I-V curves can be computed using :py:func:`pvlib.pvsystem.i_from_v` and :py:func:`pvlib.pvsystem.v_from_i`, which -calculate either current or voltage from the other. It is often useful to +calculate either current or voltage from the other, with the methods listed +above. It is often useful to first compute the open-circuit or short-circuit values using :py:func:`pvlib.pvsystem.singlediode` and then compute a range of voltages/currents from zero to those extreme points. This range can then be used with the above functions to compute the I-V curve. -Special thin film parameters ----------------------------- +IV curves in reverse bias +------------------------- -The PVsyst SDM has two additional, optional parameters to better represent -the behavior of CdTe and a-Si modules. As these parameters are not included -in the standard SDE, special methods are needed to account for them. -The functions :py:func:`pvlib.pvsystem.max_power_point`, +The standard SDE does not account for diode breakdown at reverse bias. The +following functions can optionally include an extra term for modeling it: +:py:func:`pvlib.pvsystem.max_power_point`, :py:func:`pvlib.singlediode.bishop88_i_from_v`, -and :py:func:`pvlib.singlediode.bishop88_v_from_i` -can compute the key points and full I-V curves using these parameters. +and :py:func:`pvlib.singlediode.bishop88_v_from_i`. -Reverse bias breakdown ----------------------- +Recombination current for thin film cells +----------------------------------------- -Although the standard SDE does not account for reverse bias breakdown, the -following functions can optionally include an extra term for modeling it: +The PVsyst SDM optionally modifies the SDE to better represent recombination +current in CdTe and a-Si modules. The modified SDE requires two additional +parameters. pvlib functions can compute the key points or full I-V curves using +the modified SDE: :py:func:`pvlib.pvsystem.max_power_point`, :py:func:`pvlib.singlediode.bishop88_i_from_v`, -and :py:func:`pvlib.singlediode.bishop88_v_from_i`. - +and :py:func:`pvlib.singlediode.bishop88_v_from_i`. Model parameter values ---------------------- Despite some models having parameters with similar names, parameter values are -specific to the model and thus must be produced with the intended model in mind. -Sometimes sets of parameter values can be read in from external sources, for example: +specific to each model and thus must be produced with the intended model in mind. +For some models, sets of parameter values can be read from external sources, +for example: -* CEC SDM parameter database available from :py:func:`~pvlib.pvsystem.retrieve_sam` +* CEC SDM parameter database can be read using :py:func:`~pvlib.pvsystem.retrieve_sam` * PAN files, which can be read using :py:func:`~pvlib.iotools.read_panond` pvlib also provides a set of functions that can estimate SDM parameter values From d5b80a60059136aae8c13e5f441aa7e1ddcc5d55 Mon Sep 17 00:00:00 2001 From: Kevin Anderson Date: Tue, 7 Oct 2025 14:25:58 -0400 Subject: [PATCH 6/6] Update docs/sphinx/source/user_guide/modeling_topics/singlediode.rst --- docs/sphinx/source/user_guide/modeling_topics/singlediode.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst b/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst index 297cce85d1..0d43966742 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/singlediode.rst @@ -38,8 +38,6 @@ for solving the SDE: | ``lambertw`` | explicit | medium | yes | +------------------+------------+-----------+-------------------------+ -If lower accuracy (within ~1%) is allowable, the special points can be estimated -much more quickly using :py:func:`pvlib.singlediode.batzelis_keypoints`. Computing full I-V curves