Skip to content

Commit cf4e06e

Browse files
kandersolarcwhanse
kandersolar
and
cwhanse
authored
Add guidance about SDMs to User Guide (#2565)
* initial additions * fix table * revisions * whatsnew * Apply suggestions from code review Co-authored-by: Cliff Hansen <cwhanse@sandia.gov> * Update docs/sphinx/source/user_guide/modeling_topics/singlediode.rst --------- Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>
1 parent 74ded02 commit cf4e06e

File tree

2 files changed

+108
-4
lines changed

2 files changed

+108
-4
lines changed

‎docs/sphinx/source/user_guide/modeling_topics/singlediode.rst‎

Lines changed: 107 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,110 @@
11
.. _singlediode:
22

3-
Single Diode Equation
4-
=====================
3+
Single diode models
4+
===================
5+
6+
Single-diode models are a popular means of simulating the electrical output
7+
of a PV module under any given irradiance and temperature conditions.
8+
A single-diode model (SDM) pairs the single-diode equation (SDE) with a set of
9+
auxiliary equations that predict the SDE parameters at any given irradiance
10+
and temperature. All SDMs use the SDE, but their auxiliary equations differ.
11+
For more background on SDMs, see the `PVPMC website
12+
<https://pvpmc.sandia.gov/modeling-guide/2-dc-module-iv/single-diode-equivalent-circuit-models/>`_.
13+
14+
Three SDMs are currently available in pvlib: the CEC SDM, the PVsyst SDM,
15+
and the De Soto SDM. pvlib splits these models into two steps. The first
16+
is to compute the auxiliary equations using one of the following functions:
17+
18+
* CEC SDM: :py:func:`~pvlib.pvsystem.calcparams_cec`
19+
* PVsyst SDM: :py:func:`~pvlib.pvsystem.calcparams_pvsyst`
20+
* De Soto SDM: :py:func:`~pvlib.pvsystem.calcparams_desoto`
21+
22+
The second step is to use the output of these functions to compute points on
23+
the SDE's I-V curve. Three points on the SDE I-V curve are typically of special
24+
interest for PV modeling: the maximum power (MP), open circuit (OC), and
25+
short circuit (SC) points. The most convenient function for computing these
26+
points is :py:func:`pvlib.pvsystem.singlediode`. It provides several methods
27+
for solving the SDE:
28+
29+
+------------------+------------+-----------+-------------------------+
30+
| Method | Type | Speed | Guaranteed convergence? |
31+
+==================+============+===========+=========================+
32+
| ``newton`` | iterative | fast | no |
33+
+------------------+------------+-----------+-------------------------+
34+
| ``brentq`` | iterative | slow | yes |
35+
+------------------+------------+-----------+-------------------------+
36+
| ``chandrupatla`` | iterative | fast | yes |
37+
+------------------+------------+-----------+-------------------------+
38+
| ``lambertw`` | explicit | medium | yes |
39+
+------------------+------------+-----------+-------------------------+
40+
41+
42+
43+
Computing full I-V curves
44+
-------------------------
45+
46+
Full I-V curves can be computed using
47+
:py:func:`pvlib.pvsystem.i_from_v` and :py:func:`pvlib.pvsystem.v_from_i`, which
48+
calculate either current or voltage from the other, with the methods listed
49+
above. It is often useful to
50+
first compute the open-circuit or short-circuit values using
51+
:py:func:`pvlib.pvsystem.singlediode` and then compute a range
52+
of voltages/currents from zero to those extreme points. This range can then
53+
be used with the above functions to compute the I-V curve.
54+
55+
56+
IV curves in reverse bias
57+
-------------------------
58+
59+
The standard SDE does not account for diode breakdown at reverse bias. The
60+
following functions can optionally include an extra term for modeling it:
61+
:py:func:`pvlib.pvsystem.max_power_point`,
62+
:py:func:`pvlib.singlediode.bishop88_i_from_v`,
63+
and :py:func:`pvlib.singlediode.bishop88_v_from_i`.
64+
65+
66+
Recombination current for thin film cells
67+
-----------------------------------------
68+
69+
The PVsyst SDM optionally modifies the SDE to better represent recombination
70+
current in CdTe and a-Si modules. The modified SDE requires two additional
71+
parameters. pvlib functions can compute the key points or full I-V curves using
72+
the modified SDE:
73+
:py:func:`pvlib.pvsystem.max_power_point`,
74+
:py:func:`pvlib.singlediode.bishop88_i_from_v`,
75+
and :py:func:`pvlib.singlediode.bishop88_v_from_i`.
76+
77+
Model parameter values
78+
----------------------
79+
80+
Despite some models having parameters with similar names, parameter values are
81+
specific to each model and thus must be produced with the intended model in mind.
82+
For some models, sets of parameter values can be read from external sources,
83+
for example:
84+
85+
* CEC SDM parameter database can be read using :py:func:`~pvlib.pvsystem.retrieve_sam`
86+
* PAN files, which can be read using :py:func:`~pvlib.iotools.read_panond`
87+
88+
pvlib also provides a set of functions that can estimate SDM parameter values
89+
from various datasources:
90+
91+
+---------------------------------------------------------------+---------+--------------------+
92+
| Function | SDM | Inputs |
93+
+===============================================================+=========+====================+
94+
| :py:func:`~pvlib.ivtools.sdm.fit_cec_sam` | CEC | datasheet |
95+
+---------------------------------------------------------------+---------+--------------------+
96+
| :py:func:`~pvlib.ivtools.sdm.fit_desoto` | De Soto | datasheet |
97+
+---------------------------------------------------------------+---------+--------------------+
98+
| :py:func:`~pvlib.ivtools.sdm.fit_desoto_sandia` | De Soto | I-V curves |
99+
+---------------------------------------------------------------+---------+--------------------+
100+
| :py:func:`~pvlib.ivtools.sdm.fit_pvsyst_sandia` | PVsyst | I-V curves |
101+
+---------------------------------------------------------------+---------+--------------------+
102+
| :py:func:`~pvlib.ivtools.sdm.fit_pvsyst_iec61853_sandia_2025` | PVsyst | IEC 61853-1 matrix |
103+
+---------------------------------------------------------------+---------+--------------------+
104+
105+
106+
Single-diode equation
107+
---------------------
5108

6109
This section reviews the solutions to the single diode equation used in
7110
pvlib-python to generate an IV curve of a PV module.
@@ -15,7 +118,7 @@ The :func:`pvlib.pvsystem.singlediode` function allows the user to choose the
15118
method using the ``method`` keyword.
16119

17120
Lambert W-Function
18-
------------------
121+
******************
19122
When ``method='lambertw'``, the Lambert W-function is used as previously shown
20123
by Jain, Kapoor [1, 2] and Hansen [3]. The following algorithm can be found on
21124
`Wikipedia: Theory of Solar Cells
@@ -50,7 +153,7 @@ Then the module current can be solved using the Lambert W-function,
50153
51154
52155
Bishop's Algorithm
53-
------------------
156+
******************
54157
The function :func:`pvlib.singlediode.bishop88` uses an explicit solution [4]
55158
that finds points on the IV curve by first solving for pairs :math:`(V_d, I)`
56159
where :math:`V_d` is the diode voltage :math:`V_d = V + I*Rs`. Then the voltage

‎docs/sphinx/source/whatsnew/v0.13.2.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ Enhancements
3232

3333
Documentation
3434
~~~~~~~~~~~~~
35+
* Provide an overview of single-diode modeling functionality in :ref:`singlediode`. (:pull:`2565`)
3536

3637

3738
Testing

0 commit comments

Comments
 (0)