Rename pvwatts to pvwattsv5 everywhere (#1558)

* v5: extensive renaming and deprecations

* whatsnew

* pr number

* some tests

* use new names in gallery and user's guide

* more tests

* stickler

* update API listing

* fix tests

* stickler

* a bit of cleanup

* bit more cleanup

* fix broken test

* stickler...

* Update docs/sphinx/source/user_guide/modelchain.rst

Co-authored-by: Cliff Hansen <[email protected]>

* switch deprecation removal from 0.10 to 0.11

* a few more 0.10 -> 0.11

Co-authored-by: Cliff Hansen <[email protected]>

Author: kandersolar

docs/examples/bifacial/plot_bifi_model_pvwatts.py

@@ -7,7 +7,7 @@
 
 # %%
 # This example shows how to complete a bifacial modeling example using the
-# :py:func:`pvlib.pvsystem.pvwatts_dc` with the
+# :py:func:`pvlib.pvsystem.pvwattsv5_dc` with the
 # :py:func:`pvlib.bifacial.pvfactors.pvfactors_timeseries` function to
 # transpose GHI data to both front and rear Plane of Array (POA) irradiance.
 
@@ -83,27 +83,27 @@
 temp_cell = temperature.faiman(effective_irrad_bifi, temp_air=25,
                                wind_speed=1)
 
-# using the pvwatts_dc model and parameters detailed above,
+# using the pvwattsv5_dc model and parameters detailed above,
 # set pdc0 and return DC power for both bifacial and monofacial
 pdc0 = 1
 gamma_pdc = -0.0043
-pdc_bifi = pvsystem.pvwatts_dc(effective_irrad_bifi,
-                               temp_cell,
-                               pdc0,
-                               gamma_pdc=gamma_pdc
-                               ).fillna(0)
+pdc_bifi = pvsystem.pvwattsv5_dc(effective_irrad_bifi,
+                                 temp_cell,
+                                 pdc0,
+                                 gamma_pdc=gamma_pdc
+                                 ).fillna(0)
 pdc_bifi.plot(title='Bifacial Simulation on June Solstice', ylabel='DC Power')
 
 # %%
 # For illustration, perform monofacial simulation using pvfactors front-side
 # irradiance (AOI-corrected), and plot along with bifacial results.
 
 effective_irrad_mono = irrad['total_abs_front']
-pdc_mono = pvsystem.pvwatts_dc(effective_irrad_mono,
-                               temp_cell,
-                               pdc0,
-                               gamma_pdc=gamma_pdc
-                               ).fillna(0)
+pdc_mono = pvsystem.pvwattsv5_dc(effective_irrad_mono,
+                                 temp_cell,
+                                 pdc0,
+                                 gamma_pdc=gamma_pdc
+                                 ).fillna(0)
 
 # plot monofacial results
 plt.figure()

docs/sphinx/source/reference/modelchain.rst

@@ -81,9 +81,11 @@ ModelChain model definitions.
    modelchain.ModelChain.desoto
    modelchain.ModelChain.pvsyst
    modelchain.ModelChain.pvwatts_dc
+   modelchain.ModelChain.pvwattsv5_dc
    modelchain.ModelChain.sandia_inverter
    modelchain.ModelChain.adr_inverter
    modelchain.ModelChain.pvwatts_inverter
+   modelchain.ModelChain.pvwattsv5_inverter
    modelchain.ModelChain.ashrae_aoi_loss
    modelchain.ModelChain.physical_aoi_loss
    modelchain.ModelChain.sapm_aoi_loss
@@ -98,6 +100,7 @@ ModelChain model definitions.
    modelchain.ModelChain.dc_ohmic_model
    modelchain.ModelChain.no_dc_ohmic_loss
    modelchain.ModelChain.pvwatts_losses
+   modelchain.ModelChain.pvwattsv5_losses
    modelchain.ModelChain.no_extra_losses
 
 Inference methods

docs/sphinx/source/reference/pv_modeling.rst

@@ -107,7 +107,9 @@ Inverter models (DC to AC conversion)
    inverter.sandia_multi
    inverter.adr
    inverter.pvwatts
+   inverter.pvwattsv5
    inverter.pvwatts_multi
+   inverter.pvwattsv5_multi
 
 Functions for fitting inverter models
 
@@ -152,8 +154,11 @@ PVWatts model
    :toctree: generated/
 
    pvsystem.pvwatts_dc
+   pvsystem.pvwattsv5_dc
    inverter.pvwatts
+   inverter.pvwattsv5
    pvsystem.pvwatts_losses
+   pvsystem.pvwattsv5_losses
 
 Estimating PV model parameters
 ------------------------------

docs/sphinx/source/user_guide/modelchain.rst

@@ -290,25 +290,25 @@ Wrapping methods into a unified API
 Readers may notice that the source code of the :py:meth:`~pvlib.modelchain.ModelChain.run_model`
 method is model-agnostic. :py:meth:`~pvlib.modelchain.ModelChain.run_model` calls generic methods
 such as ``self.dc_model`` rather than a specific model such as
-``pvwatts_dc``. So how does :py:meth:`~pvlib.modelchain.ModelChain.run_model` know what models
+``pvwattsv5_dc``. So how does :py:meth:`~pvlib.modelchain.ModelChain.run_model` know what models
 it’s supposed to run? The answer comes in two parts, and allows us to
 explore more of the ModelChain API along the way.
 
 First, ModelChain has a set of methods that wrap the PVSystem methods
 that perform the calculations (or further wrap the pvsystem.py module’s
 functions). Each of these methods takes the same arguments (``self``)
 and sets the same attributes, thus creating a uniform API. For example,
-the :py:meth:`~pvlib.modelchain.ModelChain.pvwatts_dc` method is shown below. Its only argument is
+the :py:meth:`~pvlib.modelchain.ModelChain.pvwattsv5_dc` method is shown below. Its only argument is
 ``self``, and it sets the ``dc`` attribute.
 
 .. ipython:: python
 
-    mc.pvwatts_dc??
+    mc.pvwattsv5_dc??
 
-The :py:meth:`~pvlib.modelchain.ModelChain.pvwatts_dc` method calls the pvwatts_dc method of the
+The :py:meth:`~pvlib.modelchain.ModelChain.pvwattsv5_dc` method calls the pvwattsv5_dc method of the
 PVSystem object that we supplied when we created the ModelChain instance,
 using data that is stored in the ModelChain ``effective_irradiance`` and
-``cell_temperature`` attributes. The :py:meth:`~pvlib.modelchain.ModelChain.pvwatts_dc` method assigns its
+``cell_temperature`` attributes. The :py:meth:`~pvlib.modelchain.ModelChain.pvwattsv5_dc` method assigns its
 result to the ``dc`` attribute of the ModelChain's ``results`` object. The code
 below shows a simple example of this.
 
@@ -322,21 +322,21 @@ below shows a simple example of this.
     mc = ModelChain(pvwatts_system, location,
                     aoi_model='no_loss', spectral_model='no_loss')
 
-    # manually assign data to the attributes that ModelChain.pvwatts_dc will need.
+    # manually assign data to the attributes that ModelChain.pvwattsv5_dc will need.
     # for standard workflows, run_model would assign these attributes.
     mc.results.effective_irradiance = pd.Series(1000, index=[pd.Timestamp('20170401 1200-0700')])
     mc.results.cell_temperature = pd.Series(50, index=[pd.Timestamp('20170401 1200-0700')])
 
-    # run ModelChain.pvwatts_dc and look at the result
-    mc.pvwatts_dc();
+    # run ModelChain.pvwattsv5_dc and look at the result
+    mc.pvwattsv5_dc();
     mc.results.dc
 
 The :py:meth:`~pvlib.modelchain.ModelChain.sapm` method works in a manner similar
-to the :py:meth:`~pvlib.modelchain.ModelChain.pvwatts_dc`
+to the :py:meth:`~pvlib.modelchain.ModelChain.pvwattsv5_dc`
 method. It calls the :py:meth:`~pvlib.pvsystem.PVSystem.sapm` method using stored data, then
 assigns the result to the ``dc`` attribute of ``ModelChain.results``.
 The :py:meth:`~pvlib.modelchain.ModelChain.sapm` method differs from the
-:py:meth:`~pvlib.modelchain.ModelChain.pvwatts_dc` method in
+:py:meth:`~pvlib.modelchain.ModelChain.pvwattsv5_dc` method in
 a notable way: the PVSystem.sapm method returns a DataFrame with current,
 voltage, and power results, rather than a simple Series
 of power. The ModelChain methods for single diode models (e.g.,
@@ -370,7 +370,7 @@ DC quantities to the output of the full PVSystem.
     mc.sapm();
     mc.results.dc
 
-We’ve established that the ``ModelChain.pvwatts_dc`` and
+We’ve established that the ``ModelChain.pvwattsv5_dc`` and
 ``ModelChain.sapm`` have the same API: they take the same arugments
 (``self``) and they both set the ``dc`` attribute.\* Because the methods
 have the same API, we can call them in the same way. ModelChain includes
@@ -381,7 +381,7 @@ Again, so how does :py:meth:`~pvlib.modelchain.ModelChain.run_model` know which
 models it’s supposed to run?
 
 At object construction, ModelChain assigns the desired model’s method
-(e.g. ``ModelChain.pvwatts_dc``) to the corresponding generic attribute
+(e.g. ``ModelChain.pvwattsv5_dc``) to the corresponding generic attribute
 (e.g. ``ModelChain.dc_model``) either with the value assigned to the ``dc_model``
 parameter at construction, or by inference as described in the next
 section.
@@ -428,15 +428,15 @@ method.
     mc.infer_ac_model??
     pvlib.modelchain._snl_params??
     pvlib.modelchain._adr_params??
-    pvlib.modelchain._pvwatts_params??
+    pvlib.modelchain._pvwattsv5_params??
 
 ModelChain for a PVSystem with multiple Arrays
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The PVSystem can represent a PV system with a single array of modules, or
 with multiple arrays (see :ref:`multiarray`). The same models are applied to
 all ``PVSystem.array`` objects, so each ``Array`` must contain the appropriate model
-parameters. For example, if ``ModelChain.dc_model='pvwatts'``, then each 
+parameters. For example, if ``ModelChain.dc_model='pvwattsv5'``, then each 
 ``Array.module_parameters`` must contain ``'pdc0'``.
 
 When the PVSystem contains multiple arrays, ``ModelChain.results`` attributes

docs/sphinx/source/user_guide/pvsystem.rst

@@ -70,28 +70,28 @@ that describe a PV system's modules and inverter are stored in
 
 
 Extrinsic data is passed to the arguments of PVSystem methods. For example,
-the :py:meth:`~pvlib.pvsystem.PVSystem.pvwatts_dc` method accepts extrinsic
+the :py:meth:`~pvlib.pvsystem.PVSystem.pvwattsv5_dc` method accepts extrinsic
 data irradiance and temperature.
 
 .. ipython:: python
 
-    pdc = system.pvwatts_dc(g_poa_effective=1000, temp_cell=30)
+    pdc = system.pvwattsv5_dc(g_poa_effective=1000, temp_cell=30)
     print(pdc)
 
 Methods attached to a PVSystem object wrap the corresponding functions in
 :py:mod:`~pvlib.pvsystem`. The methods simplify the argument list by
 using data stored in the PVSystem attributes. Compare the
-:py:meth:`~pvlib.pvsystem.PVSystem.pvwatts_dc` method signature to the
-:py:func:`~pvlib.pvsystem.pvwatts_dc` function signature:
+:py:meth:`~pvlib.pvsystem.PVSystem.pvwattsv5_dc` method signature to the
+:py:func:`~pvlib.pvsystem.pvwattsv5_dc` function signature:
 
-    * :py:meth:`PVSystem.pvwatts_dc(g_poa_effective, temp_cell) <pvlib.pvsystem.PVSystem.pvwatts_dc>`
-    * :py:func:`pvwatts_dc(g_poa_effective, temp_cell, pdc0, gamma_pdc, temp_ref=25.) <pvlib.pvsystem.pvwatts_dc>`
+    * :py:meth:`PVSystem.pvwattsv5_dc(g_poa_effective, temp_cell) <pvlib.pvsystem.PVSystem.pvwattsv5_dc>`
+    * :py:func:`pvwattsv5_dc(g_poa_effective, temp_cell, pdc0, gamma_pdc, temp_ref=25.) <pvlib.pvsystem.pvwattsv5_dc>`
 
-How does this work? The :py:meth:`~pvlib.pvsystem.PVSystem.pvwatts_dc`
+How does this work? The :py:meth:`~pvlib.pvsystem.PVSystem.pvwattsv5_dc`
 method looks in `PVSystem.module_parameters` for the `pdc0`, and
-`gamma_pdc` arguments. Then the :py:meth:`PVSystem.pvwatts_dc
-<pvlib.pvsystem.PVSystem.pvwatts_dc>` method calls the
-:py:func:`pvsystem.pvwatts_dc <pvlib.pvsystem.pvwatts_dc>` function with
+`gamma_pdc` arguments. Then the :py:meth:`PVSystem.pvwattsv5_dc
+<pvlib.pvsystem.PVSystem.pvwattsv5_dc>` method calls the
+:py:func:`pvsystem.pvwattsv5_dc <pvlib.pvsystem.pvwattsv5_dc>` function with
 all of the arguments and returns the result to the user. Note that the
 function includes a default value for the parameter `temp_ref`. This
 default value may be overridden by specifying the `temp_ref` key in the
@@ -101,7 +101,7 @@ default value may be overridden by specifying the `temp_ref` key in the
 
     system.arrays[0].module_parameters['temp_ref'] = 0
     # lower temp_ref should lead to lower DC power than calculated above
-    pdc = system.pvwatts_dc(1000, 30)
+    pdc = system.pvwattsv5_dc(1000, 30)
     print(pdc)
 
 Multiple methods may pull data from the same attribute. For example, the
@@ -320,8 +320,8 @@ Losses
 
 The `losses_parameters` attribute contains data that may be used with
 methods that calculate system losses. At present, these methods include
-only :py:meth:`pvlib.pvsystem.PVSystem.pvwatts_losses` and
-:py:func:`pvlib.pvsystem.pvwatts_losses`, but we hope to add more related functions
+only :py:meth:`pvlib.pvsystem.PVSystem.pvwattsv5_losses` and
+:py:func:`pvlib.pvsystem.pvwattsv5_losses`, but we hope to add more related functions
 and methods in the future.
 
 

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

@@ -5,6 +5,29 @@ v0.9.4 (anticipated December 2022)
 
 Deprecations
 ~~~~~~~~~~~~
+* In anticipation of implementing newer versions of the PVWatts model
+  in the future and to clarify the relevant PVWatts model version for
+  existing functionality, several parts of pvlib have been renamed from
+  `pvwatts` to `pvwattsv5`:
+
+    * ``pvlib.inverter.pvwatts`` is now :py:func:`pvlib.inverter.pvwattsv5`
+    * ``pvlib.inverter.pvwatts_multi`` is now :py:func:`pvlib.inverter.pvwattsv5_multi`
+    * ``pvlib.pvsystem.pvwatts_dc`` is now :py:func:`pvlib.pvsystem.pvwattsv5_dc`
+    * ``pvlib.pvsystem.pvwatts_losses`` is now :py:func:`pvlib.pvsystem.pvwattsv5_losses`
+    * ``pvlib.pvsystem.PVSystem.pvwatts_dc`` is now :py:meth:`pvlib.pvsystem.PVSystem.pvwattsv5_dc`
+    * ``pvlib.pvsystem.PVSystem.pvwatts_losses`` is now :py:meth:`pvlib.pvsystem.PVSystem.pvwattsv5_losses`
+    * ``pvlib.modelchain.ModelChain.pvwatts_dc`` is now :py:meth:`pvlib.modelchain.ModelChain.pvwattsv5_dc`
+    * ``pvlib.modelchain.ModelChain.pvwatts_inverter`` is now :py:meth:`pvlib.modelchain.ModelChain.pvwattsv5_inverter`
+    * ``pvlib.modelchain.ModelChain.pvwatts_losses`` is now :py:meth:`pvlib.modelchain.ModelChain.pvwattsv5_losses`
+    
+    * The ``model`` parameter to :py:meth:`pvlib.pvsystem.PVSystem.get_ac` should
+      now be ``'pvwattsv5'`` instead of ``'pvwatts'``.
+    * The ``dc_model``, ``ac_model``, and ``losses_model`` parameters of
+      :py:class:`pvlib.modelchain.ModelChain` should now be ``'pvwattsv5'``
+      instead of ``'pvwatts'``.
+
+  The originals should continue to work for now (emitting a deprecation warning),
+  but will be removed in a future release. (:issue:`1350`, :pull:`1558`)
 
 
 Enhancements

pvlib/inverter.py

@@ -14,6 +14,7 @@
 import pandas as pd
 from numpy.polynomial.polynomial import polyfit  # different than np.polyfit
 
+from pvlib._deprecation import deprecated
 
 def _sandia_eff(v_dc, p_dc, inverter):
     r'''
@@ -330,9 +331,9 @@ def adr(v_dc, p_dc, inverter, vtol=0.10):
     return power_ac
 
 
-def pvwatts(pdc, pdc0, eta_inv_nom=0.96, eta_inv_ref=0.9637):
+def pvwattsv5(pdc, pdc0, eta_inv_nom=0.96, eta_inv_ref=0.9637):
     r"""
-    NREL's PVWatts inverter model.
+    NREL's PVWatts v5 inverter model.
 
     The PVWatts inverter model [1]_ calculates inverter efficiency :math:`\eta`
     as a function of input DC power
@@ -370,14 +371,14 @@ def pvwatts(pdc, pdc0, eta_inv_nom=0.96, eta_inv_ref=0.9637):
     Notes
     -----
     Note that ``pdc0`` is also used as a symbol in
-    :py:func:`pvlib.pvsystem.pvwatts_dc`. ``pdc0`` in this function refers to
+    :py:func:`pvlib.pvsystem.pvwattsv5_dc`. ``pdc0`` in this function refers to
     the DC power input limit of the inverter. ``pdc0`` in
-    :py:func:`pvlib.pvsystem.pvwatts_dc` refers to the DC power of the modules
-    at reference conditions.
+    :py:func:`pvlib.pvsystem.pvwattsv5_dc` refers to the DC power of the
+    modules at reference conditions.
 
     See Also
     --------
-    pvlib.inverter.pvwatts_multi
+    pvlib.inverter.pvwattsv5_multi
 
     References
     ----------
@@ -404,13 +405,19 @@ def pvwatts(pdc, pdc0, eta_inv_nom=0.96, eta_inv_ref=0.9637):
     return power_ac
 
 
-def pvwatts_multi(pdc, pdc0, eta_inv_nom=0.96, eta_inv_ref=0.9637):
+pvwatts = deprecated(since='0.9.4',
+                     name='pvwatts',
+                     alternative='pvwattsv5',
+                     removal='0.11')(pvwattsv5)
+
+
+def pvwattsv5_multi(pdc, pdc0, eta_inv_nom=0.96, eta_inv_ref=0.9637):
     r"""
-    Extend NREL's PVWatts inverter model for multiple MPP inputs.
+    Extend NREL's PVWatts v5 inverter model for multiple MPPT inputs.
 
-    DC input power is summed over MPP inputs to obtain the DC power
-    input to the PVWatts inverter model. See :py:func:`pvlib.inverter.pvwatts`
-    for details.
+    DC input power is summed over MPPT inputs to obtain the DC power
+    input to the PVWatts v5 inverter model.
+    See :py:func:`pvlib.inverter.pvwattsv5` for details.
 
     Parameters
     ----------
@@ -432,9 +439,15 @@ def pvwatts_multi(pdc, pdc0, eta_inv_nom=0.96, eta_inv_ref=0.9637):
 
     See Also
     --------
-    pvlib.inverter.pvwatts
+    pvlib.inverter.pvwattsv5
     """
-    return pvwatts(sum(pdc), pdc0, eta_inv_nom, eta_inv_ref)
+    return pvwattsv5(sum(pdc), pdc0, eta_inv_nom, eta_inv_ref)
+
+
+pvwatts_multi = deprecated(since='0.9.4',
+                           name='pvwatts_multi',
+                           alternative='pvwattsv5_multi',
+                           removal='0.11')(pvwattsv5_multi)
 
 
 def fit_sandia(ac_power, dc_power, dc_voltage, dc_voltage_level, p_ac_0, p_nt):