Merge remote-tracking branch 'upstream/main' into scientific_units_test

Author: RDaxini

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/examples/spectrum/plot_spectrl2_fig51A.py

@@ -13,13 +13,6 @@
 # This example recreates an example figure from the SPECTRL2 NREL Technical
 # Report [1]_. The figure shows modeled spectra at hourly intervals across
 # a single morning.
-#
-# References
-# ----------
-# .. [1] Bird, R, and Riordan, C., 1984, "Simple solar spectral model for
-#    direct and diffuse irradiance on horizontal and tilted planes at the
-#    earth's surface for cloudless atmospheres", NREL Technical Report
-#    TR-215-2436 doi:10.2172/5986936.
 
 # %%
 # The SPECTRL2 model has several inputs; some can be calculated with pvlib,
@@ -53,9 +46,10 @@
 
 # %%
 # With all the necessary inputs in hand we can model spectral irradiance using
-# :py:func:`pvlib.spectrum.spectrl2`.  Note that because we are calculating
-# the spectra for more than one set of conditions, we will get back 2-D
-# arrays (one dimension for wavelength, one for time).
+# :py:func:`pvlib.spectrum.spectrl2`. Note that because we are calculating
+# the spectra for more than one set of conditions, the spectral irradiance
+# components will be returned in a dictionary as 2-D arrays, with one dimension
+# for wavelength and one for time.
 
 spectra = spectrum.spectrl2(
     apparent_zenith=solpos.apparent_zenith,
@@ -95,3 +89,11 @@
 # position and the solar position calculation in the technical report does not
 # exactly match the one used here.  However, the differences are minor enough
 # to not materially change the spectra.
+
+# %%
+# References
+# ----------
+# .. [1] Bird, R, and Riordan, C., 1984, "Simple solar spectral model for
+#    direct and diffuse irradiance on horizontal and tilted planes at the
+#    earth's surface for cloudless atmospheres", NREL Technical Report
+#    TR-215-2436 :doi:`10.2172/5986936`

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

@@ -19,6 +19,10 @@ Enhancements
 * 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
@@ -44,6 +48,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
@@ -58,4 +66,11 @@ Contributors
 * Leonardo Micheli (:ghuser:`lmicheli`)
 * Echedey Luis (:ghuser:`echedey-ls`)
 * Rajiv Daxini (:ghuser:`RDaxini`)
+* Mark A. Mikofski (:ghuser:`mikofski`)
+* Ben Pierce (:ghuser:`bgpierc`)
 * Jose Meza (:ghuser:`JoseMezaMendieta`)
+* Luiz Reis (:ghuser:`luizreiscver`)
+* 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/data/variables_style_rules.csv

@@ -10,6 +10,7 @@ bhi;beam/direct horizontal irradiance
 ghi;global horizontal irradiance
 ghi_extra;horizontal irradiance at top of atmosphere (extraterrestrial)
 gri;ground-reflected irradiance
+ape;average photon energy
 aoi;angle of incidence between :math:`90\deg` and :math:`90\deg`
 aoi_projection;cos(aoi)
 airmass;airmass

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