Implement irradiance.complete_irradiance with component sum equations

docs/sphinx/source/reference/irradiance.rst

@@ -28,6 +28,7 @@ Decomposing and combining irradiance
    irradiance.poa_components
    irradiance.get_ground_diffuse
    irradiance.dni
+   irradiance.component_sum_irradiance
 
 Transposition models
 --------------------

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

@@ -10,12 +10,15 @@ Deprecations
 Enhancements
 ~~~~~~~~~~~~
 * Multiple code style issues fixed that were reported by LGTM analysis. (:issue:`1275`, :pull:`1559`)
+* Added the component sum irradiance function to calculate the component sum value for GHI, DHI, and DNI values
+  :py:func:`~pvlib.irradiance.component_sum_irradiance`
+  (:issue:`1565`, :pull:`1567`)
+
 
 Bug fixes
 ~~~~~~~~~
 
 
-
 Testing
 ~~~~~~~
 
@@ -34,4 +37,5 @@ Requirements
 
 Contributors
 ~~~~~~~~~~~~
-* Christian Orner (:ghuser:`chrisorner`)
+* Kirsten Perry (:ghuser:`kperrynrel`)
+* Christian Orner (:ghuser:`chrisorner`)

pvlib/irradiance.py

@@ -10,8 +10,10 @@
 
 import numpy as np
 import pandas as pd
+import warnings
 
 from pvlib import atmosphere, solarposition, tools
+import pvlib
 
 
 # see References section of get_ground_diffuse function
@@ -2915,3 +2917,68 @@ def dni(ghi, dhi, zenith, clearsky_dni=None, clearsky_tolerance=1.1,
             (zenith < zenith_threshold_for_zero_dni) &
             (dni > max_dni)] = max_dni
     return dni
+
+
+def component_sum_irradiance(solar_zenith,
+                             ghi=None,
+                             dhi=None,
+                             dni=None,
+                             dni_clear=None):
+    """
+    Use the component sum equations to calculate the missing series, using
+    the other available time series. One of the three parameters (ghi, dhi,
+    dni) is passed as None, and the other associated series passed are used to
+    calculate the missing series value.
+
+    The "component sum" or "closure" equation relates the three
+    primary irradiance components as follows:
+
+    .. math::
+
+       GHI = DHI + DNI \cos(\theta_z)
+
+    Parameters
+    ----------
+    solar_zenith : Series
+        Refraction-corrected zenith angles in decimal
+        degrees, with datetime index. Angles must be >=0 and <=180. Must have
+        the same datetime index as ghi, dhi, and dni series, when available.
+    ghi : Series, (optional, default None)
+        Pandas series of dni data, with datetime index. Must have the same
+        datetime index as dni, dhi, and zenith series, when available.
+    dhi : Series, (optional, default None)
+        Pandas series of dni data, with datetime index. Must have the same
+        datetime index as ghi, dni, and zenith series, when available.
+    dni : Series, (optional, default None)
+        Pandas series of dni data, with datetime index. Must have the same
+        datetime index as ghi, dhi, and zenith series, when available.
+    dni_clear : Series, (optional, default None)
+        Pandas series of clearsky dni data, calculated via the
+        get_clearsky function. Must have the same datetime index as ghi, dhi,
+        dni, and zenith series, when available. This is an optional field that
+        is only used when calculating the DNI component sum series.
+
+    Returns
+    -------
+    component_sum_df : Dataframe
+        Pandas series of 'ghi', 'dhi', and 'dni' columns with datetime index
+    """
+    if ghi is not None and dhi is not None and dni is None:
+        dni = pvlib.irradiance.dni(ghi, dhi, solar_zenith,
+                                   clearsky_dni=dni_clear,
+                                   clearsky_tolerance=1.1)
+    elif dni is not None and dhi is not None and ghi is None:
+        ghi = (dhi + dni * tools.cosd(solar_zenith))
+    elif dni is not None and ghi is not None and dhi is None:
+        dhi = (ghi - dni * tools.cosd(solar_zenith))
+    else:
+        err_txt = ("No component sum calculated. Please recheck \n"
+                   "passed ghi, dni, and dhi parameters to check \n"
+                   "exactly one field out of the three is set to None.")
+        raise ValueError(err_txt)
+    # Merge the outputs into a master dataframe containing 'ghi', 'dhi',
+    # and 'dni' columns
+    component_sum_df = pd.DataFrame({'ghi': ghi,
+                                     'dhi': dhi,
+                                     'dni': dni})
+    return component_sum_df

pvlib/modelchain.py

@@ -1289,13 +1289,13 @@ def complete_irradiance(self, weather):
         self._assign_times()
         self.results.solar_position = self.location.get_solarposition(
             self.results.times, method=self.solar_position_method)
-
+        # Calculate the irradiance using the component sum equations,
+        # if needed
         if isinstance(weather, tuple):
             for w in self.results.weather:
                 self._complete_irradiance(w)
         else:
             self._complete_irradiance(self.results.weather)
-
         return self
 
     def _complete_irradiance(self, weather):
@@ -1304,26 +1304,31 @@ def _complete_irradiance(self, weather):
                    "Results can be too high or negative.\n" +
                    "Help to improve this function on github:\n" +
                    "https://github.com/pvlib/pvlib-python \n")
-
+        warnings.warn(wrn_txt, UserWarning)
         if {'ghi', 'dhi'} <= icolumns and 'dni' not in icolumns:
             clearsky = self.location.get_clearsky(
                 weather.index, solar_position=self.results.solar_position)
-            weather.loc[:, 'dni'] = pvlib.irradiance.dni(
-                weather.loc[:, 'ghi'], weather.loc[:, 'dhi'],
-                self.results.solar_position.zenith,
-                clearsky_dni=clearsky['dni'],
-                clearsky_tolerance=1.1)
+            component_sum_df = pvlib.irradiance.component_sum_irradiance(
+                solar_zenith=self.results.solar_position.apparent_zenith,
+                ghi=weather.ghi,
+                dhi=weather.dhi,
+                dni=None,
+                dni_clear=clearsky.dni)
+            weather.loc[:, 'dni'] = component_sum_df.dni
         elif {'dni', 'dhi'} <= icolumns and 'ghi' not in icolumns:
-            warnings.warn(wrn_txt, UserWarning)
-            weather.loc[:, 'ghi'] = (
-                weather.dhi + weather.dni *
-                tools.cosd(self.results.solar_position.zenith)
-            )
+            component_sum_df = pvlib.irradiance.component_sum_irradiance(
+                solar_zenith=self.results.solar_position.apparent_zenith,
+                ghi=None,
+                dhi=weather.dhi,
+                dni=weather.dni)
+            weather.loc[:, 'ghi'] = component_sum_df.ghi
         elif {'dni', 'ghi'} <= icolumns and 'dhi' not in icolumns:
-            warnings.warn(wrn_txt, UserWarning)
-            weather.loc[:, 'dhi'] = (
-                weather.ghi - weather.dni *
-                tools.cosd(self.results.solar_position.zenith))
+            component_sum_df = pvlib.irradiance.component_sum_irradiance(
+                solar_zenith=self.results.solar_position.apparent_zenith,
+                ghi=weather.ghi,
+                dhi=None,
+                dni=weather.dni)
+            weather.loc[:, 'dhi'] = component_sum_df.dhi
 
     def _prep_inputs_solar_pos(self, weather):
         """

pvlib/tests/test_irradiance.py

@@ -7,8 +7,10 @@
 import pandas as pd
 
 import pytest
-from numpy.testing import assert_almost_equal, assert_allclose
-
+from numpy.testing import (assert_almost_equal,
+                           assert_allclose,
+                           assert_warns,
+                           assert_raises)
 from pvlib import irradiance
 
 from .conftest import (
@@ -1082,3 +1084,71 @@ def test_clearness_index_zenith_independent(airmass_kt):
                                                         airmass)
     expected = pd.Series([np.nan, 0.553744437562], index=times)
     assert_series_equal(out, expected)
+
+
+def test_component_sum_irradiance():
+    # Generate dataframe to test on
+    times = pd.date_range('2010-07-05 7:00:00-0700', periods=2, freq='H')
+    i = pd.DataFrame({'ghi': [372.103976116, 497.087579068],
+                      'dhi': [356.543700, 465.44400],
+                      'dni': [49.63565561689957, 62.10624908037814]},
+                     index=times)
+    # Define the solar position and clearsky dataframes
+    solar_position = pd.DataFrame({'apparent_zenith': [71.7303262449161,
+                                                       59.369],
+                                   'zenith': [71.7764, 59.395]},
+                                  index=pd.DatetimeIndex([
+                                      '2010-07-05 07:00:00-0700',
+                                      '2010-07-05 08:00:00-0700']))
+    clearsky = pd.DataFrame({'dni': [625.5254880160008, 778.7766443075865],
+                             'ghi': [246.3508023804681, 469.461381740857],
+                             'dhi': [50.25488725346631, 72.66909939636372]},
+                            index=pd.DatetimeIndex([
+                                      '2010-07-05 07:00:00-0700',
+                                      '2010-07-05 08:00:00-0700']))
+    # Test scenario where DNI is generated via component sum equation
+    component_sum_df = irradiance.component_sum_irradiance(
+        solar_position.apparent_zenith,
+        ghi=i.ghi,
+        dhi=i.dhi,
+        dni=None,
+        dni_clear=clearsky.dni)
+    # Assert that the ghi, dhi, and dni series match the original dataframe
+    # values
+    assert_frame_equal(component_sum_df, i)
+    # Test scenario where GHI is generated via component sum equation
+    component_sum_df = irradiance.component_sum_irradiance(
+        solar_position.apparent_zenith,
+        ghi=None,
+        dhi=i.dhi,
+        dni=i.dni,
+        dni_clear=clearsky.dni)
+    # Assert that the ghi, dhi, and dni series match the original dataframe
+    # values
+    assert_frame_equal(component_sum_df, i)
+    # Test scenario where DHI is generated via component sum equation
+    component_sum_df = irradiance.component_sum_irradiance(
+        solar_position.apparent_zenith,
+        ghi=i.ghi,
+        dhi=None,
+        dni=i.dni,
+        dni_clear=clearsky.dni)
+    # Assert that the ghi, dhi, and dni series match the original dataframe
+    # values
+    assert_frame_equal(component_sum_df, i)
+    # Test scenario where all parameters are passed (throw error)
+    component_sum_df = assert_raises(ValueError,
+                                     irradiance.component_sum_irradiance,
+                                     solar_position.apparent_zenith,
+                                     ghi=i.ghi,
+                                     dhi=i.dhi,
+                                     dni=i.dni,
+                                     dni_clear=clearsky.dni)
+    # Test scenario where only one parameter is passed (throw error)
+    component_sum_df = assert_raises(ValueError,
+                                     irradiance.component_sum_irradiance,
+                                     solar_position.apparent_zenith,
+                                     ghi=None,
+                                     dhi=None,
+                                     dni=i.dni,
+                                     dni_clear=clearsky.dni)

pvlib/tests/test_modelchain.py

@@ -1886,7 +1886,7 @@ def test_complete_irradiance(sapm_dc_snl_ac_system, location):
     """Check calculations"""
     mc = ModelChain(sapm_dc_snl_ac_system, location)
     times = pd.date_range('2010-07-05 7:00:00-0700', periods=2, freq='H')
-    i = pd.DataFrame({'dni': [49.756966, 62.153947],
+    i = pd.DataFrame({'dni': [49.63565561689957, 62.10624908037814],
                       'ghi': [372.103976116, 497.087579068],
                       'dhi': [356.543700, 465.44400]}, index=times)
 
@@ -1904,7 +1904,7 @@ def test_complete_irradiance(sapm_dc_snl_ac_system, location):
 
     mc.complete_irradiance(i[['dhi', 'ghi']])
     assert_series_equal(mc.results.weather['dni'],
-                        pd.Series([49.756966, 62.153947],
+                        pd.Series([49.63565561689957, 62.10624908037814],
                                   index=times, name='dni'))