Merge remote-tracking branch 'upstream/master'

Author: AdamRJensen

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2013-2020, Sandia National Laboratories and pvlib python Development Team
+Copyright (c) 2013-2021, Sandia National Laboratories and pvlib python Development Team
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

docs/sphinx/source/api.rst

@@ -292,6 +292,7 @@ Inverter models (DC to AC conversion)
 .. autosummary::
    :toctree: generated/
 
+   pvsystem.PVSystem.get_ac
    inverter.sandia
    inverter.sandia_multi
    inverter.adr
@@ -630,8 +631,8 @@ ModelChain model definitions.
    modelchain.ModelChain.desoto
    modelchain.ModelChain.pvsyst
    modelchain.ModelChain.pvwatts_dc
-   modelchain.ModelChain.snlinverter
-   modelchain.ModelChain.adrinverter
+   modelchain.ModelChain.sandia_inverter
+   modelchain.ModelChain.adr_inverter
    modelchain.ModelChain.pvwatts_inverter
    modelchain.ModelChain.ashrae_aoi_loss
    modelchain.ModelChain.physical_aoi_loss

docs/sphinx/source/introtutorial.rst

@@ -27,19 +27,17 @@ configuration at a handful of sites listed below.
 
 .. ipython:: python
 
+    import pvlib
     import pandas as pd
     import matplotlib.pyplot as plt
 
-    naive_times = pd.date_range(start='2015', end='2016', freq='1h')
-
-    # very approximate
     # latitude, longitude, name, altitude, timezone
-    coordinates = [(30, -110, 'Tucson', 700, 'Etc/GMT+7'),
-                   (35, -105, 'Albuquerque', 1500, 'Etc/GMT+7'),
-                   (40, -120, 'San Francisco', 10, 'Etc/GMT+8'),
-                   (50, 10, 'Berlin', 34, 'Etc/GMT-1')]
-
-    import pvlib
+    coordinates = [
+        (32.2, -111.0, 'Tucson', 700, 'Etc/GMT+7'),
+        (35.1, -106.6, 'Albuquerque', 1500, 'Etc/GMT+7'),
+        (37.8, -122.4, 'San Francisco', 10, 'Etc/GMT+8'),
+        (52.5, 13.4, 'Berlin', 34, 'Etc/GMT-1'),
+    ]
 
     # get the module and inverter specifications from SAM
     sandia_modules = pvlib.pvsystem.retrieve_sam('SandiaMod')
@@ -48,9 +46,32 @@ configuration at a handful of sites listed below.
     inverter = sapm_inverters['ABB__MICRO_0_25_I_OUTD_US_208__208V_']
     temperature_model_parameters = pvlib.temperature.TEMPERATURE_MODEL_PARAMETERS['sapm']['open_rack_glass_glass']
 
-    # specify constant ambient air temp and wind for simplicity
-    temp_air = 20
-    wind_speed = 0
+
+In order to retrieve meteorological data for the simulation, we can make use of
+the :ref:`iotools` module. In this example we will be using PVGIS, one of the
+data sources available, to retrieve a Typical Meteorological Year (TMY) which
+includes irradiation, temperature and wind speed.
+
+.. note:: PVGIS uses different naming conventions, so it is required to rename
+   the weather data variables before using them. Data is already UTC-localized,
+   so conversion to local timezone is optional.
+
+.. ipython:: python
+
+    variables_translation = {
+        "Gb(n)": "dni",
+        "G(h)": "ghi",
+        "Gd(h)": "dhi",
+        "T2m": "temp_air",
+        "WS10m": "wind_speed",
+    }
+    tmys = []
+    for location in coordinates:
+        latitude, longitude, name, altitude, timezone = location
+        weather = pvlib.iotools.get_pvgis_tmy(latitude, longitude)[0]
+        weather = weather.rename(columns=variables_translation)
+        weather.index.name = "utc_time"
+        tmys.append(weather)
 
 
 Procedural
@@ -69,41 +90,60 @@ to accomplish our system modeling goal:
 
     energies = {}
 
-    for latitude, longitude, name, altitude, timezone in coordinates:
-        times = naive_times.tz_localize(timezone)
+    for location, weather in zip(coordinates, tmys):
+        latitude, longitude, name, altitude, timezone = location
         system['surface_tilt'] = latitude
-        solpos = pvlib.solarposition.get_solarposition(times, latitude, longitude)
-        dni_extra = pvlib.irradiance.get_extra_radiation(times)
+        solpos = pvlib.solarposition.get_solarposition(
+            time=weather.index,
+            latitude=latitude,
+            longitude=longitude,
+            altitude=altitude,
+            temperature=weather["temp_air"],
+            pressure=pvlib.atmosphere.alt2pres(altitude),
+        )
+        dni_extra = pvlib.irradiance.get_extra_radiation(weather.index)
         airmass = pvlib.atmosphere.get_relative_airmass(solpos['apparent_zenith'])
         pressure = pvlib.atmosphere.alt2pres(altitude)
         am_abs = pvlib.atmosphere.get_absolute_airmass(airmass, pressure)
-        tl = pvlib.clearsky.lookup_linke_turbidity(times, latitude, longitude)
-        cs = pvlib.clearsky.ineichen(solpos['apparent_zenith'], am_abs, tl,
-                                     dni_extra=dni_extra, altitude=altitude)
-        aoi = pvlib.irradiance.aoi(system['surface_tilt'], system['surface_azimuth'],
-                                   solpos['apparent_zenith'], solpos['azimuth'])
-        total_irrad = pvlib.irradiance.get_total_irradiance(system['surface_tilt'],
-                                                            system['surface_azimuth'],
-                                                            solpos['apparent_zenith'],
-                                                            solpos['azimuth'],
-                                                            cs['dni'], cs['ghi'], cs['dhi'],
-                                                            dni_extra=dni_extra,
-                                                            model='haydavies')
-        tcell = pvlib.temperature.sapm_cell(total_irrad['poa_global'],
-                                            temp_air, wind_speed,
-                                            **temperature_model_parameters)
+        aoi = pvlib.irradiance.aoi(
+            system['surface_tilt'],
+            system['surface_azimuth'],
+            solpos["apparent_zenith"],
+            solpos["azimuth"],
+        )
+        total_irradiance = pvlib.irradiance.get_total_irradiance(
+            system['surface_tilt'],
+            system['surface_azimuth'],
+            solpos['apparent_zenith'],
+            solpos['azimuth'],
+            weather['dni'],
+            weather['ghi'],
+            weather['dhi'],
+            dni_extra=dni_extra,
+            model='haydavies',
+        )
+        cell_temperature = pvlib.temperature.sapm_cell(
+            total_irradiance['poa_global'],
+            weather["temp_air"],
+            weather["wind_speed"],
+            **temperature_model_parameters,
+        )
         effective_irradiance = pvlib.pvsystem.sapm_effective_irradiance(
-            total_irrad['poa_direct'], total_irrad['poa_diffuse'],
-            am_abs, aoi, module)
-        dc = pvlib.pvsystem.sapm(effective_irradiance, tcell, module)
+            total_irradiance['poa_direct'],
+            total_irradiance['poa_diffuse'],
+            am_abs,
+            aoi,
+            module,
+        )
+        dc = pvlib.pvsystem.sapm(effective_irradiance, cell_temperature, module)
         ac = pvlib.inverter.sandia(dc['v_mp'], dc['p_mp'], inverter)
         annual_energy = ac.sum()
         energies[name] = annual_energy
 
     energies = pd.Series(energies)
 
     # based on the parameters specified above, these are in W*hrs
-    print(energies.round(0))
+    print(energies)
 
     energies.plot(kind='bar', rot=0)
     @savefig proc-energies.png width=6in
@@ -150,28 +190,35 @@ by examining the parameters defined for the module.
     from pvlib.location import Location
     from pvlib.modelchain import ModelChain
 
-    system = PVSystem(module_parameters=module,
-                      inverter_parameters=inverter,
-                      temperature_model_parameters=temperature_model_parameters)
+    system = PVSystem(
+        module_parameters=module,
+        inverter_parameters=inverter,
+        temperature_model_parameters=temperature_model_parameters,
+    )
 
     energies = {}
-    for latitude, longitude, name, altitude, timezone in coordinates:
-        times = naive_times.tz_localize(timezone)
-        location = Location(latitude, longitude, name=name, altitude=altitude,
-                            tz=timezone)
-        weather = location.get_clearsky(times)
-        mc = ModelChain(system, location,
-                        orientation_strategy='south_at_latitude_tilt')
-        # model results (ac, dc) and intermediates (aoi, temps, etc.)
-        # assigned as mc object attributes
-        mc.run_model(weather)
-        annual_energy = mc.results.ac.sum()
+    for location, weather in zip(coordinates, tmys):
+        latitude, longitude, name, altitude, timezone = location
+        location = Location(
+            latitude,
+            longitude,
+            name=name,
+            altitude=altitude,
+            tz=timezone,
+        )
+        mc = ModelChain(
+            system,
+            location,
+            orientation_strategy='south_at_latitude_tilt',
+        )
+        results = mc.run_model(weather)
+        annual_energy = results.ac.sum()
         energies[name] = annual_energy
 
     energies = pd.Series(energies)
 
     # based on the parameters specified above, these are in W*hrs
-    print(energies.round(0))
+    print(energies)
 
     energies.plot(kind='bar', rot=0)
     @savefig modelchain-energies.png width=6in

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

@@ -36,6 +36,10 @@ Breaking changes
 * ``irradiance.liujordan`` and ``ForecastModel.cloud_cover_to_irradiance_liujordan``
   have been removed. (:pull:`1136`)
 
+* ``ModelChain.snlinverter`` changed to ``ModelChain.sandia_inverter``.
+  ``ModelChain.adrinverter`` changed to ``ModelChain.adr_inverter``.
+  (:pull:`1150`)
+
 
 Deprecations
 ~~~~~~~~~~~~
@@ -78,9 +82,9 @@ Enhancements
 * Support for :py:func:`~pvlib.inverter.sandia_multi` and
   :py:func:`~pvlib.inverter.pvwatts_multi` added to
   :py:class:`~pvlib.pvsystem.PVSystem` and
-  :py:class:`~pvlib.modelchain.ModelChain` (as ``ac_model='sandia_multi'``
-  and  ``ac_model='pvwatts_multi'``).
-  (:pull:`1076`, :issue:`1067`, :pull:`1132`, :issue:`1117`)
+  :py:class:`~pvlib.modelchain.ModelChain` (as ``ac_model='sandia'``
+  and ``ac_model='pvwatts'``).
+  (:pull:`1076`, :issue:`1067`, :pull:`1132`, :issue:`1117`, :pull:`1150`)
 * :py:class:`~pvlib.modelchain.ModelChain` 'run_model' methods now
   automatically switch to using ``'effective_irradiance'`` (if available) for
   cell temperature models, when ``'poa_global'`` is not provided in input
@@ -89,19 +93,28 @@ Enhancements
   by ``pvsystem.PVSystem.modules_per_strings`` and
   ``pvsystem.PVSystem.strings_per_inverter``. Note that both attributes still
   default to 1. (:pull:`1138`)
+* :py:meth:`~pvlib.pvsystem.PVSystem.get_ac` is added to calculate AC power
+  from DC power. Use parameter ``model`` to specify which inverter model to use.
+  (:pull:`1147`, :issue:`998`, :pull:`1150`)
 
 Bug fixes
 ~~~~~~~~~
 * Pass weather data to solar position calculations in
-  :ref:meth:`~pvlib.modelchain.ModelChain.prepare_inputs_from_poa`.
+  :py:meth:`~pvlib.modelchain.ModelChain.prepare_inputs_from_poa`.
   (:issue:`1065`, :pull:`1140`)
+* Reindl model fixed to generate sky_diffuse=0 when GHI=0.
+  (:issue:`1153`, :pull:`1154`)
 
 Testing
 ~~~~~~~
 
 Documentation
 ~~~~~~~~~~~~~
 
+* Update intro tutorial to highlight the use of historical meteorological data
+  and to make the procedural and object oriented results match exactly.
+* Update documentation links in :py:func:`pvlib.iotools.get_psm3`
+
 Requirements
 ~~~~~~~~~~~~
 * ``dataclasses`` is required for python 3.6
@@ -116,3 +129,5 @@ Contributors
 * Nate Croft (:ghuser:`ncroft-b4`)
 * Kevin Anderson (:ghuser:`kanderso-nrel`)
 * Adam R. Jensen (:ghuser:`AdamRJensen`)
+* Joshua Stein (:ghuser:`jsstein`)
+* Tony Lorenzo (:ghuser:`alorenzo175`)

pvlib/iotools/psm3.py

@@ -112,9 +112,9 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
     .. [1] `NREL National Solar Radiation Database (NSRDB)
        <https://nsrdb.nrel.gov/>`_
     .. [2] `Physical Solar Model (PSM) v3
-       <https://developer.nrel.gov/docs/solar/nsrdb/psm3_data_download/>`_
+       <https://developer.nrel.gov/docs/solar/nsrdb/psm3-download/>`_
     .. [3] `Physical Solar Model (PSM) v3 TMY
-       <https://developer.nrel.gov/docs/solar/nsrdb/psm3_tmy_data_download/>`_
+       <https://developer.nrel.gov/docs/solar/nsrdb/psm3-tmy-download/>`_
     .. [4] `Physical Solar Model (PSM) v3 - Five Minute Temporal Resolution
        <https://developer.nrel.gov/docs/solar/nsrdb/psm3-5min-download/>`_
     """

pvlib/irradiance.py

@@ -886,8 +886,9 @@ def reindl(surface_tilt, surface_azimuth, dhi, dni, ghi, dni_extra,
     # these are the () and [] sub-terms of the second term of eqn 8
     term1 = 1 - AI
     term2 = 0.5 * (1 + tools.cosd(surface_tilt))
-    term3 = 1 + np.sqrt(HB / ghi) * (tools.sind(0.5 * surface_tilt) ** 3)
-
+    with np.errstate(invalid='ignore', divide='ignore'):
+        hb_to_ghi = np.where(ghi == 0, 0, np.divide(HB, ghi))
+    term3 = 1 + np.sqrt(hb_to_ghi) * (tools.sind(0.5 * surface_tilt)**3)
     sky_diffuse = dhi * (AI * Rb + term1 * term2 * term3)
     sky_diffuse = np.maximum(sky_diffuse, 0)