From ac2755b1a93f8a69fd6cb17b0ba4a2ff36bccfc5 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Thu, 26 Sep 2024 15:39:11 -0700 Subject: [PATCH 1/5] revise dc_ohmic_loss and dc_ohms_from_percent docstrings --- pvlib/pvsystem.py | 62 ++++++++++++++++++++++++++--------------------- 1 file changed, 34 insertions(+), 28 deletions(-) diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 926da5548f..e5d43365d8 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -2872,45 +2872,45 @@ def dc_ohms_from_percent(vmp_ref, imp_ref, dc_ohmic_percent, modules_per_string=1, strings=1): """ - Calculates the equivalent resistance of the wires from a percent - ohmic loss at STC. - - Equivalent resistance is calculated with the function: - - .. math:: - Rw = (L_{stc} / 100) * (Varray / Iarray) - - :math:`Rw` is the equivalent resistance in ohms - :math:`Varray` is the Vmp of the modules times modules per string - :math:`Iarray` is the Imp of the modules times strings per array - :math:`L_{stc}` is the input dc loss percent + Calculates the equivalent resistance of the conductors from a percent + ohmic loss of an array at reference conditions. Parameters ---------- vmp_ref: numeric - Voltage at maximum power in reference conditions [V] + Maximum power voltage of one module at reference conditions. [V] imp_ref: numeric - Current at maximum power in reference conditions [V] - dc_ohmic_percent: numeric, default 0 - input dc loss as a percent, e.g. 1.5% loss is input as 1.5 + Maximum power current of one module at reference conditions. [A] + dc_ohmic_percent: numeric + Array DC loss as a percent, e.g. 1.5% loss is input as 1.5. modules_per_string: int, default 1 - Number of modules per string in the array. + Number of series-connected modules per string in the array. strings: int, default 1 Number of parallel strings in the array. Returns ---------- Rw: numeric - Equivalent resistance [ohm] + Equivalent resistance. [ohm] See Also -------- pvlib.pvsystem.dc_ohmic_losses - References - ---------- - .. [1] PVsyst 7 Help. "Array ohmic wiring loss". - https://www.pvsyst.com/help/ohmic_loss.htm + Notes + ----- + Equivalent resistance is calculated as: + + .. math:: + Rw = (L_{stc} / 100) * (Varray / Iarray) + + :math:`Rw` is the equivalent resistance in ohms. + :math:`Varray` is the array voltage, equal to ``vmp_ref`` times + ``modules_per_string``. + :math:`Iarray` is the array current, equal to ``imp_ref`` times + ``strings``. + :math:`L_{stc}` is the input DC loss percent at reference conditions. + """ vmp = modules_per_string * vmp_ref @@ -2929,9 +2929,9 @@ def dc_ohmic_losses(resistance, current): Parameters ---------- resistance: numeric - Equivalent resistance of wires [ohm] + Equivalent resistance of wires. [ohm] current: numeric, float or array-like - Operating current [A] + Operating current. [A] Returns ---------- @@ -2942,10 +2942,16 @@ def dc_ohmic_losses(resistance, current): -------- pvlib.pvsystem.dc_ohms_from_percent - References - ---------- - .. [1] PVsyst 7 Help. "Array ohmic wiring loss". - https://www.pvsyst.com/help/ohmic_loss.htm + Notes + ----- + Ohmic (also termed joule or heat) loss is the power lost due to current + flowing through a conductor. Ohmic loss :math:`L` is computed as + + .. math:: + L = I \times R^2 + + where :math:`I` is the current (A) and :math:`R` is the resistance of the + conductor (ohms). """ return resistance * current * current From 8592fab7e18c7a0c67dcf7260bfd1decce129296 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Thu, 26 Sep 2024 16:57:15 -0700 Subject: [PATCH 2/5] edits --- pvlib/pvsystem.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index e5d43365d8..dfac0236e4 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -2872,7 +2872,7 @@ def dc_ohms_from_percent(vmp_ref, imp_ref, dc_ohmic_percent, modules_per_string=1, strings=1): """ - Calculates the equivalent resistance of the conductors from a percent + Calculate the equivalent resistance of the conductors from the percent ohmic loss of an array at reference conditions. Parameters @@ -2882,7 +2882,8 @@ def dc_ohms_from_percent(vmp_ref, imp_ref, dc_ohmic_percent, imp_ref: numeric Maximum power current of one module at reference conditions. [A] dc_ohmic_percent: numeric - Array DC loss as a percent, e.g. 1.5% loss is input as 1.5. + Array DC power loss as a percent of DC power loss at reference + conditions. In percent, e.g. 1.5% loss is input as 1.5. modules_per_string: int, default 1 Number of series-connected modules per string in the array. strings: int, default 1 @@ -2902,7 +2903,8 @@ def dc_ohms_from_percent(vmp_ref, imp_ref, dc_ohmic_percent, Equivalent resistance is calculated as: .. math:: - Rw = (L_{stc} / 100) * (Varray / Iarray) + + Rw = (L_{stc} / 100) \times (Varray / Iarray) :math:`Rw` is the equivalent resistance in ohms. :math:`Varray` is the array voltage, equal to ``vmp_ref`` times @@ -2936,7 +2938,7 @@ def dc_ohmic_losses(resistance, current): Returns ---------- loss: numeric - Power Loss [W] + Power loss. [W] See Also -------- @@ -2948,6 +2950,7 @@ def dc_ohmic_losses(resistance, current): flowing through a conductor. Ohmic loss :math:`L` is computed as .. math:: + L = I \times R^2 where :math:`I` is the current (A) and :math:`R` is the resistance of the From b1c6cf96ef3d740b42649d7a64ffc86c4fb3b8e3 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Fri, 27 Sep 2024 08:15:52 -0700 Subject: [PATCH 3/5] Apply suggestions from code review Thanks @RDaxini Co-authored-by: RDaxini <143435106+RDaxini@users.noreply.github.com> --- pvlib/pvsystem.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index dfac0236e4..897e3b0f96 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -2871,7 +2871,7 @@ def pvwatts_losses(soiling=2, shading=3, snow=0, mismatch=2, wiring=2, def dc_ohms_from_percent(vmp_ref, imp_ref, dc_ohmic_percent, modules_per_string=1, strings=1): - """ + r""" Calculate the equivalent resistance of the conductors from the percent ohmic loss of an array at reference conditions. @@ -2904,12 +2904,13 @@ def dc_ohms_from_percent(vmp_ref, imp_ref, dc_ohmic_percent, .. math:: - Rw = (L_{stc} / 100) \times (Varray / Iarray) + R_w = \left(\frac{L_{stc}}{100}\right) \times \left(\frac{ + V_{array}}{I_{array}}\right) - :math:`Rw` is the equivalent resistance in ohms. - :math:`Varray` is the array voltage, equal to ``vmp_ref`` times + :math:`R_w` is the equivalent resistance in ohms. + :math:`V_{array}` is the array voltage, equal to ``vmp_ref`` times ``modules_per_string``. - :math:`Iarray` is the array current, equal to ``imp_ref`` times + :math:`I_{array}` is the array current, equal to ``imp_ref`` times ``strings``. :math:`L_{stc}` is the input DC loss percent at reference conditions. @@ -2947,7 +2948,7 @@ def dc_ohmic_losses(resistance, current): Notes ----- Ohmic (also termed joule or heat) loss is the power lost due to current - flowing through a conductor. Ohmic loss :math:`L` is computed as + flowing through a conductor. Ohmic loss, :math:`L`, is computed as .. math:: From 4779c4405cce536bedabec5f9f767865cad7efe5 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Fri, 27 Sep 2024 08:17:00 -0700 Subject: [PATCH 4/5] raw docstring --- pvlib/pvsystem.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 897e3b0f96..57752dff7e 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -2925,7 +2925,7 @@ def dc_ohms_from_percent(vmp_ref, imp_ref, dc_ohmic_percent, def dc_ohmic_losses(resistance, current): - """ + r""" Returns ohmic losses in units of power from the equivalent resistance of the wires and the operating current. From c5ac6d0679050d3622036afeefe88f6e014442b7 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Fri, 27 Sep 2024 08:25:41 -0700 Subject: [PATCH 5/5] whatsnew --- docs/sphinx/source/whatsnew/v0.11.2.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/source/whatsnew/v0.11.2.rst b/docs/sphinx/source/whatsnew/v0.11.2.rst index 3965101174..9d7129d50d 100644 --- a/docs/sphinx/source/whatsnew/v0.11.2.rst +++ b/docs/sphinx/source/whatsnew/v0.11.2.rst @@ -14,6 +14,8 @@ Enhancements Documentation ~~~~~~~~~~~~~ +* Edited docstrings for :py:func:`~pvlib.pvsystem.dc_ohms_from_percent` and + :py:func:`~pvlib.pvsystem.dc_ohmic_loss` for clarity. (:issue:`1601`, :pull:`2229`) Testing @@ -26,5 +28,5 @@ Requirements Contributors ~~~~~~~~~~~~ - +* Cliff Hansen (:ghuser:`cwhanse`)