Merge branch 'main' into normalize

Author: cwhanse

docs/examples/irradiance-transposition/use_perez_modelchain.py

@@ -0,0 +1,126 @@
+"""
+Use different Perez coefficients with the ModelChain
+====================================================
+
+This example demonstrates how to customize the ModelChain
+to use site-specific Perez transposition coefficients.
+"""
+
+# %%
+# The :py:class:`pvlib.modelchain.ModelChain` object provides a useful method
+# for easily constructing a PV system model with a simple, unified interface.
+# However, a user may want to customize the steps
+# in the system model in various ways.
+# One such example is during the irradiance transposition step.
+# The Perez model perform very well on field data, but
+# it requires a set of fitted coefficients from various sites.
+# It has been noted that these coefficients can be specific to
+# various climates, so users may see improved model accuracy
+# when using a site-specific set of coefficients.
+# However, the base  :py:class:`~pvlib.modelchain.ModelChain`
+# only supports the default coefficients.
+# This example shows how the  :py:class:`~pvlib.modelchain.ModelChain` can
+# be adjusted to use a different set of Perez coefficients.
+
+import pandas as pd
+from pvlib.pvsystem import PVSystem
+from pvlib.modelchain import ModelChain
+from pvlib.temperature import TEMPERATURE_MODEL_PARAMETERS
+from pvlib import iotools, location, irradiance
+import pvlib
+import os
+import matplotlib.pyplot as plt
+
+# load in TMY weather data from North Carolina included with pvlib
+PVLIB_DIR = pvlib.__path__[0]
+DATA_FILE = os.path.join(PVLIB_DIR, 'data', '723170TYA.CSV')
+
+tmy, metadata = iotools.read_tmy3(DATA_FILE, coerce_year=1990,
+                                  map_variables=True)
+
+weather_data = tmy[['ghi', 'dhi', 'dni', 'temp_air', 'wind_speed']]
+
+loc = location.Location.from_tmy(metadata)
+
+#%%
+# Now, let's set up a standard PV model using the ``ModelChain``
+
+surface_tilt = metadata['latitude']
+surface_azimuth = 180
+
+# define an example module and inverter
+sandia_modules = pvlib.pvsystem.retrieve_sam('SandiaMod')
+cec_inverters = pvlib.pvsystem.retrieve_sam('cecinverter')
+sandia_module = sandia_modules['Canadian_Solar_CS5P_220M___2009_']
+cec_inverter = cec_inverters['ABB__MICRO_0_25_I_OUTD_US_208__208V_']
+
+temp_params = TEMPERATURE_MODEL_PARAMETERS['sapm']['open_rack_glass_glass']
+
+# define the system and ModelChain
+system = PVSystem(arrays=None,
+                  surface_tilt=surface_tilt,
+                  surface_azimuth=surface_azimuth,
+                  module_parameters=sandia_module,
+                  inverter_parameters=cec_inverter,
+                  temperature_model_parameters=temp_params)
+
+mc = ModelChain(system, location=loc)
+
+# %%
+# Now, let's calculate POA irradiance values outside of the ``ModelChain``.
+# We do this for both the default Perez coefficients and the desired
+# alternative Perez coefficients.  This enables comparison at the end.
+
+# Cape Canaveral seems like the most likely match for climate
+model_perez = 'capecanaveral1988'
+
+solar_position = loc.get_solarposition(times=weather_data.index)
+dni_extra = irradiance.get_extra_radiation(weather_data.index)
+
+POA_irradiance = irradiance.get_total_irradiance(
+    surface_tilt=surface_tilt,
+    surface_azimuth=surface_azimuth,
+    dni=weather_data['dni'],
+    ghi=weather_data['ghi'],
+    dhi=weather_data['dhi'],
+    solar_zenith=solar_position['apparent_zenith'],
+    solar_azimuth=solar_position['azimuth'],
+    model='perez',
+    dni_extra=dni_extra)
+
+POA_irradiance_new_perez = irradiance.get_total_irradiance(
+    surface_tilt=surface_tilt,
+    surface_azimuth=surface_azimuth,
+    dni=weather_data['dni'],
+    ghi=weather_data['ghi'],
+    dhi=weather_data['dhi'],
+    solar_zenith=solar_position['apparent_zenith'],
+    solar_azimuth=solar_position['azimuth'],
+    model='perez',
+    model_perez=model_perez,
+    dni_extra=dni_extra)
+
+# %%
+# Now, run the ``ModelChain`` with both sets of irradiance data and compare
+# (note that to use POA irradiance as input to the ModelChain the method
+# `.run_model_from_poa` is used):
+
+mc.run_model_from_poa(POA_irradiance)
+ac_power_default = mc.results.ac
+
+mc.run_model_from_poa(POA_irradiance_new_perez)
+ac_power_new_perez = mc.results.ac
+
+start, stop = '1990-05-05 06:00:00', '1990-05-05 19:00:00'
+plt.plot(ac_power_default.loc[start:stop],
+         label="Default Composite Perez Model")
+plt.plot(ac_power_new_perez.loc[start:stop],
+         label="Cape Canaveral Perez Model")
+plt.xticks(rotation=90)
+plt.ylabel("AC Power ($W$)")
+plt.legend()
+plt.tight_layout()
+plt.show()
+# %%
+# Note that there is a small, but noticeable difference from the default
+# coefficients that may add up over longer periods of time.

docs/examples/iv-modeling/plot_singlediode.py

@@ -114,6 +114,8 @@
     # mark the MPP
     plt.plot([v_mp], [i_mp], ls='', marker='o', c='k')
 
+plt.xlim(left=0)
+plt.ylim(bottom=0)
 plt.legend(loc=(1.0, 0))
 plt.xlabel('Module voltage [V]')
 plt.ylabel('Module current [A]')

docs/sphinx/source/reference/effects_on_pv_system_output/spectrum.rst

@@ -18,3 +18,4 @@ Spectrum
    spectrum.spectral_factor_jrc
    spectrum.sr_to_qe
    spectrum.qe_to_sr
+   spectrum.average_photon_energy

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

@@ -10,12 +10,19 @@ Deprecations
 
 Enhancements
 ~~~~~~~~~~~~
+* Add new function to calculate the average photon energy,
+  :py:func:`pvlib.spectrum.average_photon_energy`.
+  (:issue:`2135`, :pull:`2140`)
 * Add new losses function that accounts for non-uniform irradiance on bifacial
   modules, :py:func:`pvlib.bifacial.power_mismatch_deline`.
   (:issue:`2045`, :pull:`2046`)
 * Add new parameters for min/max absolute air mass to
   :py:func:`pvlib.spectrum.spectral_factor_firstsolar`.
   (:issue:`2086`, :pull:`2100`)
+* Add ``roll_utc_offset`` and ``coerce_year`` arguments to
+  :py:func:`pvlib.iotools.get_pvgis_tmy` to allow user to specify time zone,
+  rotate indices of TMY to begin at midnight, and force indices to desired
+  year. (:issue:`2139`, :pull:`2138`)
 * Restructured the pvlib/spectrum folder by breaking up the contents of
   pvlib/spectrum/mismatch.py into pvlib/spectrum/mismatch.py,
   pvlib/spectrum/irradiance.py, and
@@ -42,6 +49,10 @@ Documentation
 * Added gallery example on calculating cell temperature for
   floating PV. (:pull:`2110`)
 
+* Added gallery example demonstrating how to use
+  different Perez coefficients in a ModelChain.
+  (:issue:`2127`, :pull:`2148`)
+
 * Removed unused "times" input from dni_et() function (:issue:`2105`)
 
 Requirements
@@ -57,4 +68,10 @@ Contributors
 * Echedey Luis (:ghuser:`echedey-ls`)
 * Rajiv Daxini (:ghuser:`RDaxini`)
 * Scott Nelson (:ghuser:`scttnlsn`)
+* Mark A. Mikofski (:ghuser:`mikofski`)
+* Ben Pierce (:ghuser:`bgpierc`)
 * Jose Meza (:ghuser:`JoseMezaMendieta`)
+* Carlos Cárdenas-Bravo (:ghuser:`cardenca`)
+* Marcos R. Escudero (:ghuser:`marc-resc`)
+* Bernat Nicolau (:ghuser:`BernatNicolau`)
+* Eduardo Sarquis (:ghuser:`EduardoSarquis`)

pvlib/clearsky.py

@@ -941,7 +941,7 @@ def bird(zenith, airmass_relative, aod380, aod500, precipitable_water,
     zenith is never explicitly defined in the report, since the purpose
     was to compare existing clear sky models with "rigorous radiative
     transfer models" (RTM) it is possible that apparent zenith was
-    obtained as output from the RTM. However, the implentation presented
+    obtained as output from the RTM. However, the implementation presented
     in PVLIB is tested against the NREL Excel implementation by Daryl
     Myers which uses an analytical expression for solar zenith instead
     of apparent zenith.

pvlib/iotools/pvgis.py

@@ -18,10 +18,10 @@
 import json
 from pathlib import Path
 import requests
+import numpy as np
 import pandas as pd
+import pytz
 from pvlib.iotools import read_epw, parse_epw
-import warnings
-from pvlib._deprecation import pvlibDeprecationWarning
 
 URL = 'https://re.jrc.ec.europa.eu/api/'
 
@@ -390,9 +390,33 @@ def read_pvgis_hourly(filename, pvgis_format=None, map_variables=True):
     raise ValueError(err_msg)
 
 
+def _coerce_and_roll_tmy(tmy_data, tz, year):
+    """
+    Assumes ``tmy_data`` input is UTC, converts from UTC to ``tz``, rolls
+    dataframe so timeseries starts at midnight, and forces all indices to
+    ``year``. Only works for integer ``tz``, but ``None`` and ``False`` are
+    re-interpreted as zero / UTC.
+    """
+    if tz:
+        tzname = pytz.timezone(f'Etc/GMT{-tz:+d}')
+    else:
+        tz = 0
+        tzname = pytz.timezone('UTC')
+    new_index = pd.DatetimeIndex([
+        timestamp.replace(year=year, tzinfo=tzname)
+        for timestamp in tmy_data.index],
+        name=f'time({tzname})')
+    new_tmy_data = pd.DataFrame(
+        np.roll(tmy_data, tz, axis=0),
+        columns=tmy_data.columns,
+        index=new_index)
+    return new_tmy_data
+
+
 def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
                   userhorizon=None, startyear=None, endyear=None,
-                  map_variables=True, url=URL, timeout=30):
+                  map_variables=True, url=URL, timeout=30,
+                  roll_utc_offset=None, coerce_year=None):
     """
     Get TMY data from PVGIS.
 
@@ -424,6 +448,13 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
         base url of PVGIS API, append ``tmy`` to get TMY endpoint
     timeout : int, default 30
         time in seconds to wait for server response before timeout
+    roll_utc_offset: int, optional
+        Use to specify a time zone other than the default UTC zero and roll
+        dataframe by ``roll_utc_offset`` so it starts at midnight on January
+        1st. Ignored if ``None``, otherwise will force year to ``coerce_year``.
+    coerce_year: int, optional
+        Use to force indices to desired year. Will default to 1990 if
+        ``coerce_year`` is not specified, but ``roll_utc_offset`` is specified.
 
     Returns
     -------
@@ -510,6 +541,11 @@ def get_pvgis_tmy(latitude, longitude, outputformat='json', usehorizon=True,
     if map_variables:
         data = data.rename(columns=VARIABLE_MAP)
 
+    if not (roll_utc_offset is None and coerce_year is None):
+        # roll_utc_offset is specified, but coerce_year isn't
+        coerce_year = coerce_year or 1990
+        data = _coerce_and_roll_tmy(data, roll_utc_offset, coerce_year)
+
     return data, months_selected, inputs, meta
 
 

pvlib/irradiance.py

@@ -395,8 +395,8 @@ def get_sky_diffuse(surface_tilt, surface_azimuth,
     Raises
     ------
     ValueError
-        If model is one of ``'haydavies'``, ``'reindl'``, or ``'perez'`` and
-        ``dni_extra`` is not specified.
+        If model is one of ``'haydavies'``, ``'reindl'``, ``'perez'``,  or
+        ``'perez_driesse'`` and ``dni_extra`` is not specified.
 
     Notes
     -----

pvlib/modelchain.py

@@ -1474,7 +1474,7 @@ def prepare_inputs_from_poa(self, data):
         data : DataFrame, or tuple or list of DataFrame
             Contains plane-of-array irradiance data. Required column names
             include ``'poa_global'``, ``'poa_direct'`` and ``'poa_diffuse'``.
-            Columns with weather-related data are ssigned to the
+            Columns with weather-related data are assigned to the
             ``weather`` attribute.  If columns for ``'temp_air'`` and
             ``'wind_speed'`` are not provided, air temperature of 20 C and wind
             speed of 0 m/s are assumed.

pvlib/pvsystem.py

@@ -841,7 +841,7 @@ def scale_voltage_current_power(self, data):
     @_unwrap_single_value
     def pvwatts_dc(self, g_poa_effective, temp_cell):
         """
-        Calcuates DC power according to the PVWatts model using
+        Calculates DC power according to the PVWatts model using
         :py:func:`pvlib.pvsystem.pvwatts_dc`, `self.module_parameters['pdc0']`,
         and `self.module_parameters['gamma_pdc']`.
 
@@ -1550,7 +1550,7 @@ def calcparams_desoto(effective_irradiance, temp_cell,
         Light-generated current in amperes
 
     saturation_current : numeric
-        Diode saturation curent in amperes
+        Diode saturation current in amperes
 
     resistance_series : numeric
         Series resistance in ohms

pvlib/solarposition.py

@@ -717,11 +717,11 @@ def ephemeris(time, latitude, longitude, pressure=101325, temperature=12):
 
         * apparent_elevation : apparent sun elevation accounting for
           atmospheric refraction.
+          This is the complement of the apparent zenith angle.
         * elevation : actual elevation (not accounting for refraction)
           of the sun in decimal degrees, 0 = on horizon.
           The complement of the zenith angle.
         * azimuth : Azimuth of the sun in decimal degrees East of North.
-          This is the complement of the apparent zenith angle.
         * apparent_zenith : apparent sun zenith accounting for atmospheric
           refraction.
         * zenith : Solar zenith angle