refactor sapm to be consistent with matlab (#218)

* refactor sapm to be consistent with matlab

* add pvsystem tests

* update modelchain to work with new sapm api

* update docs

* add upper limit to sapm_aoi_loss

* update tests for clipped aoi losses

* and upper keyword argument, roll back mc tests

* update whatsnew

Author: wholmgren

docs/sphinx/source/package_overview.rst

@@ -104,9 +104,10 @@ to accomplish our system modeling goal:
                                                    model='haydavies')
         temps = pvlib.pvsystem.sapm_celltemp(total_irrad['poa_global'],
                                              wind_speed, temp_air)
-        dc = pvlib.pvsystem.sapm(module, total_irrad['poa_direct'],
-                                 total_irrad['poa_diffuse'], temps['temp_cell'],
-                                 am_abs, aoi)
+        effective_irradiance = pvlib.pvsystem.sapm_effective_irradiance(
+            module, total_irrad['poa_direct'], total_irrad['poa_diffuse'],
+            am_abs, aoi)
+        dc = pvlib.pvsystem.sapm(module, effective_irradiance, temps['temp_cell'])
         ac = pvlib.pvsystem.snlinverter(inverter, dc['v_mp'], dc['p_mp'])
         annual_energy = ac.sum()
         energies[name] = annual_energy
@@ -240,11 +241,10 @@ object to accomplish our modeling goal:
         aoi = localized_system.get_aoi(solar_position['apparent_zenith'],
                                        solar_position['azimuth'])
         airmass = localized_system.get_airmass(solar_position=solar_position)
-        dc = localized_system.sapm(total_irrad['poa_direct'],
-                                   total_irrad['poa_diffuse'],
-                                   temps['temp_cell'],
-                                   airmass['airmass_absolute'],
-                                   aoi)
+        effective_irradiance = localized_system.sapm_effective_irradiance(
+            total_irrad['poa_direct'], total_irrad['poa_diffuse'],
+            airmass['airmass_absolute'], aoi)
+        dc = localized_system.sapm(effective_irradiance, temps['temp_cell'])
         ac = localized_system.snlinverter(dc['v_mp'], dc['p_mp'])
         annual_energy = ac.sum()
         energies[name] = annual_energy

docs/sphinx/source/whatsnew/v0.4.0.txt

@@ -3,9 +3,10 @@
 v0.4.0 (July xx, 2016)
 -----------------------
 
-This is a major release from 0.3.3.
-We recommend that all users upgrade to this version after reviewing
-the API changes.
+This is a major release from 0.3.3. We recommend that all users upgrade
+to this version after reviewing the API Changes. Please see the Bug
+Fixes for changes that will result in slightly different modeling
+results.
 
 
 API Changes
@@ -18,6 +19,14 @@ API Changes
   in addition to arrays and Series. Furthermore, these functions no
   longer promote scalar or array input to Series output.
   Also applies to atmosphere.relativeairmass. (:issue:`201`, :issue:`214`)
+* Updated to pvsystem.sapm to be consistent with the PVLIB MATLAB API.
+  pvsystem.sapm now takes an effective irradiance argument instead of
+  POA irradiances, airmass, and AOI. Implements closely related
+  sapm_spectral_loss, sapm_aoi_loss, and sapm_effective_irradiance
+  functions, as well as PVSystem methods. The sapm_aoi_loss function
+  includes an optional argument to apply an upper limit to the output
+  (output can be ~1% larger than 1 for AOI of ~30 degrees).
+  (:issue:`198`, :issue:`205`, :issue:`218`)
 
 
 Enhancements

pvlib/modelchain.py

@@ -169,11 +169,12 @@ def basic_chain(times, latitude, longitude,
                                    weather['wind_speed'],
                                    weather['temp_air'])
 
-    dc = pvsystem.sapm(module_parameters, total_irrad['poa_direct'],
-                       total_irrad['poa_diffuse'],
-                       temps['temp_cell'],
-                       airmass,
-                       aoi)
+    effective_irradiance = pvsystem.sapm_effective_irradiance(
+        module_parameters, total_irrad['poa_direct'],
+        total_irrad['poa_diffuse'], airmass, aoi)
+
+    dc = pvsystem.sapm(module_parameters, effective_irradiance,
+                       temps['temp_cell'])
 
     ac = pvsystem.snlinverter(inverter_parameters, dc['v_mp'], dc['p_mp'])
 
@@ -365,6 +366,9 @@ def run_model(self, times, irradiance=None, weather=None):
             model=self.transposition_model,
             airmass=self.airmass['airmass_relative'])
 
+        self.aoi = self.system.get_aoi(self.solar_position['apparent_zenith'],
+                                       self.solar_position['azimuth'])
+
         if weather is None:
             weather = {'wind_speed': 0, 'temp_air': 20}
         self.weather = weather
@@ -373,14 +377,14 @@ def run_model(self, times, irradiance=None, weather=None):
                                                self.weather['wind_speed'],
                                                self.weather['temp_air'])
 
-        self.aoi = self.system.get_aoi(self.solar_position['apparent_zenith'],
-                                       self.solar_position['azimuth'])
+        self.effective_irradiance = self.system.sapm_effective_irradiance(
+            self.total_irrad['poa_direct'],
+            self.total_irrad['poa_diffuse'],
+            self.airmass['airmass_absolute'],
+            self.aoi)
 
-        self.dc = self.system.sapm(self.total_irrad['poa_direct'],
-                                   self.total_irrad['poa_diffuse'],
-                                   self.temps['temp_cell'],
-                                   self.airmass['airmass_absolute'],
-                                   self.aoi)
+        self.dc = self.system.sapm(self.effective_irradiance,
+                                   self.temps['temp_cell'])
 
         self.dc = self.system.scale_voltage_current_power(self.dc)