account for major pvwatts changes

[wholmgren]

The SAM Version 2021.12.02 release notes describe major changes to the PVWatts model:

With this release, we have updated SAM's implementation to PVWatts V8 (pvwattsv8 in SSC) with new features listed below. The online PVWatts® Calculator continues to use pvwattsv5 and will be updated later. All versions of PVWatts are available via the SAM Software Development Kit and PySAM. (729)

Reorganize user interface to group advanced inputs into a collapsible panel.
Add snow loss model when weather file includes snow depth data in cm.
Support for bifacial modules.
Internal module and module thermal models based on same model as Detailed PV model.
Internal inverter model based on same model as Detailed PV model.
Inputs for monthly soiling as DC loss.

We should add a note or a warning to pvsystem.pvwatts_dc and inverter.pvwatts. And ModelChain.with_pvwatts is also now ambiguous.

[kandersolar]

Append v5 to the function names? So ModelChain.with_pvwattsv5, etc, and deprecate the originals

[cwhanse]

After thumbing up, second thought: append v5 to base layer functions but add a parameter to ModelChain.with_pvwatts.

[adriesse]

The release note itself seems ambiguous, since the "Detailed PV Model" has several module and inverter options, and incomplete, since the parameters for those options aren't identified. Regardless, I think it's a good idea to create and maintain ways in which pvlib users can run a PVWatts version of their choice and to document what that choice implies technically.

[adriesse]

The following note from the SAM website may also be relevant:

Note: The PVWatts website uses a different version numbering system than the PVWatts model. For example, the website "Version 6" uses the PVWatts Version 5 model.

[adriesse]

Is the overall idea to offer a complete set of functions for each (or at least more than one) pvwatts version?

[kandersolar]

I think there are two independent goals here. For one, to resolve the ambiguity of what models our current "pvwatts_dc" et al. functions implement. For two, to make space for emulating other PVWatts versions, which yes is something I'd like to do for at least v8.

FYI I suspect much of PVWatts v8 is already implemented in pvlib (although called something else, e.g. sam_noct and the CEC models), but I'm waiting until they publish an official description before taking a closer look.

[adriesse]

I support those goals. Assuming that there will be several versions implemented eventually (someone might want to add older ones too) then probably there will be only a few base functions that differ from one version to the next. Would the version suffix refer to the version where the function was introduced? Do any of them them predate v5 currently?

[kandersolar]

Would the version suffix refer to the version where the function was introduced?

That makes sense to me. The docstring could list any newer versions that also use it.

Do any of them them predate v5 currently?

I don't think any pvlib functions with "pvwatts" in the name (currently just the module, inverter, and system loss models) implement pre-v5 models. My understanding is that versions 1 through 4 used the same performance models (the differences were in other aspects like weather data and UI), so it is sufficient to compare the technical reference for Version 1 with that of Version 5.

As an aside, if someone does add the v1 models to pvlib someday, it might be more correct to name them pvform rather than pvwattsv1.