Merge branch 'main' into get_meteonorm

Author: AdamRJensen

README.md

@@ -74,7 +74,7 @@ Installation
 ============
 
 pvlib-python releases may be installed using the ``pip`` and ``conda`` tools.
-Please see the [Installation page](https://pvlib-python.readthedocs.io/en/stable/user_guide/installation.html) of the documentation for complete instructions.
+Please see the [Installation page](https://pvlib-python.readthedocs.io/en/stable/user_guide/getting_started/installation.html) of the documentation for complete instructions.
 
 
 Contributing

docs/sphinx/source/reference/iotools.rst

@@ -57,6 +57,17 @@ clear-sky irradiance globally.
    iotools.parse_cams
 
 
+NASA POWER
+**********
+
+Satellite-derived irradiance and weather data with global coverage.
+
+.. autosummary::
+   :toctree: generated/
+
+   iotools.get_nasa_power
+
+
 NSRDB
 *****
 

docs/sphinx/source/user_guide/extras/nomenclature.rst

@@ -22,16 +22,24 @@ There is a convention on consistent variable names throughout the library:
 
     aoi
         Angle of incidence. Angle between the surface normal vector and the
-        vector pointing towards the sun’s center
+        vector pointing towards the sun's center. [°]
 
     aoi_projection
-        cos(aoi)
+        cos(aoi). When the sun is behind the surface, the value is negative.
+        For many uses, negative values must be set to zero.
 
     ape
         Average photon energy
 
     apparent_zenith
-        Refraction-corrected solar zenith angle in degrees
+        Refraction-corrected solar zenith angle. The solar
+        zenith angle describes the position of the sun relative to the vertical and is
+        defined as the angle between a vector pointed straight up and a vector pointed
+        at the sun, from the observer. [°]
+
+    apparent_elevation
+        Refraction-corrected solar elevation angle. This is the complement of
+        :term:`apparent_zenith` (90 - apparent_zenith). [°]
 
     bhi
         Beam/direct horizontal irradiance
@@ -87,10 +95,10 @@ There is a convention on consistent variable names throughout the library:
         Sandia Array Performance Model IV curve parameters
 
     latitude
-        Latitude
+        Latitude in decimal degrees. Positive north of equator, negative to south.
 
     longitude
-        Longitude
+        Longitude in decimal degrees. Positive east of prime meridian, negative to west.
 
     pac, ac
         AC power
@@ -141,10 +149,15 @@ There is a convention on consistent variable names throughout the library:
         Diode saturation current
 
     solar_azimuth
-        Azimuth angle of the sun in degrees East of North
+        Azimuth angle of the sun in degrees East of North. The solar azimuth angle
+        describes the sun’s position along the horizon relative to the observer.
+        The pvlib-python convention is defined as degrees East of North, so
+        North = 0°, East = 90°, South = 180°, West = 270°.
 
     solar_zenith
-        Zenith angle of the sun in degrees
+        Zenith angle of the sun in degrees. This is the angle between is between a
+        vector pointed straight up and a vector pointed at the sun, from the observer.
+        This is the complement of solar elevation (90 - elevation). [°]
 
     spectra
     spectra_components
@@ -154,11 +167,16 @@ There is a convention on consistent variable names throughout the library:
         is composed of direct and diffuse components.
 
     surface_azimuth
-        Azimuth angle of the surface
+        Azimuth angle of the surface in degrees East of North. This angle describes the
+        horizontal projection of the normal vector from the surface. The pvlib-python
+        convention is defined as degrees East (clockwise) of North, so North = 0°,
+        East = 90°, South = 180°, West = 270°.
 
     surface_tilt
-        Panel tilt from horizontal [°]. For example, a surface facing up = 0°,
-        surface facing horizon = 90°.
+        Tilt from horizontal [°]. The surface tilt angle 
+        is defined as degrees from the horizontal
+        such that a surface facing up would have a surface tilt of 0°, and one facing
+        the horizon would be 90°.  [°]
 
     temp_air
         Temperature of the air

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

@@ -10,6 +10,7 @@ Breaking Changes
 
 Deprecations
 ~~~~~~~~~~~~
+* Deprecate :py:func:`~pvlib.modelchain.get_orientation`. (:pull:`2495`)
 * Rename parameter name ``aparent_azimuth`` to ``solar_azimuth`` in :py:func:`~pvlib.tracking.singleaxis`.
   (:issue:`2479`, :pull:`2480`)
 
@@ -22,9 +23,15 @@ Enhancements
 * Add iotools functions to retrieve irradiance and weather data from Meteonorm:
   :py:func:`~pvlib.iotools.get_meteonorm` and :py:func:`~pvlib.iotools.get_meteonorm_tmy`.
   (:pull:`2499`)
+* Add :py:func:`pvlib.iotools.get_nasa_power` to retrieve data from NASA POWER free API.
+  (:pull:`2500`)
+* :py:func:`pvlib.spectrum.spectral_factor_firstsolar` no longer emits warnings
+  when airmass and precipitable water values fall out of range. (:pull:`2512`)
 
 Documentation
 ~~~~~~~~~~~~~
+* Substantiate definitions of solar/surface azimuth/zenith and aoi on the
+  :ref:`nomenclature` page. (:issue:`2448`, :pull:`2503`)
 
 
 Testing
@@ -47,3 +54,7 @@ Maintenance
 Contributors
 ~~~~~~~~~~~~
 * Elijah Passmore (:ghuser:`eljpsm`)
+* Ioannis Sifnaios (:ghuser:`IoannisSifnaios`)
+* Rajiv Daxini (:ghuser:`RDaxini`)
+* Omar Bahamida (:ghuser:`OmarBahamida`)
+* Kevin Anderson (:ghuser:`kandersolar`)

pvlib/iotools/__init__.py

@@ -41,3 +41,4 @@
 from pvlib.iotools.solargis import get_solargis  # noqa: F401
 from pvlib.iotools.meteonorm import get_meteonorm  # noqa: F401
 from pvlib.iotools.meteonorm import get_meteonorm_tmy  # noqa: F401
+from pvlib.iotools.nasa_power import get_nasa_power  # noqa: F401

pvlib/iotools/nasa_power.py

@@ -0,0 +1,153 @@
+"""Functions for reading and retrieving data from NASA POWER."""
+
+import pandas as pd
+import requests
+import numpy as np
+
+URL = 'https://power.larc.nasa.gov/api/temporal/hourly/point'
+
+DEFAULT_PARAMETERS = [
+    'dni', 'dhi', 'ghi', 'temp_air', 'wind_speed'
+]
+
+VARIABLE_MAP = {
+    'ALLSKY_SFC_SW_DWN': 'ghi',
+    'ALLSKY_SFC_SW_DIFF': 'dhi',
+    'ALLSKY_SFC_SW_DNI': 'dni',
+    'CLRSKY_SFC_SW_DWN': 'ghi_clear',
+    'T2M': 'temp_air',
+    'WS2M': 'wind_speed_2m',
+    'WS10M': 'wind_speed',
+}
+
+
+def get_nasa_power(latitude, longitude, start, end,
+                   parameters=DEFAULT_PARAMETERS, *, community='re',
+                   elevation=None, wind_height=None, wind_surface=None,
+                   map_variables=True, url=URL):
+    """
+    Retrieve irradiance and weather data from NASA POWER.
+
+    A general description of NASA POWER is given in [1]_ and the API is
+    described in [2]_. A detailed list of the available parameters can be
+    found in [3]_.
+
+    Parameters
+    ----------
+    latitude: float
+        In decimal degrees, north is positive (ISO 19115).
+    longitude: float
+        In decimal degrees, east is positive (ISO 19115).
+    start: datetime like
+        First timestamp of the requested period.
+    end: datetime like
+        Last timestamp of the requested period.
+    parameters: str, list
+        List of parameters. The default parameters are mentioned below; for the
+        full list see [3]_. Note that the pvlib naming conventions can also be
+        used.
+
+        * Global Horizontal Irradiance (GHI) [Wm⁻²]
+        * Diffuse Horizontal Irradiance (DHI) [Wm⁻²]
+        * Direct Normal Irradiance (DNI) [Wm⁻²]
+        * Air temperature at 2 m [C]
+        * Wind speed at 10 m [m/s]
+
+    community: str, default 're'
+        Can be one of the following depending on which parameters are of
+        interest. Note that in many cases this choice
+        might affect the units of the parameter.
+
+        * ``'re'``: renewable energy
+        * ``'sb'``: sustainable buildings
+        * ``'ag'``: agroclimatology
+
+    elevation: float, optional
+        The custom site elevation in meters to produce the corrected
+        atmospheric pressure adjusted for elevation.
+    wind_height: float, optional
+        The custom wind height in meters to produce the wind speed adjusted
+        for height. Has to be between 10 and 300 m; see [4]_.
+    wind_surface: str, optional
+        The definable surface type to adjust the wind speed. For a list of the
+        surface types see [4]_. If you provide a wind surface alias please
+        include a site elevation with the request.
+    map_variables: bool, default True
+        When true, renames columns of the Dataframe to pvlib variable names
+        where applicable. See variable :const:`VARIABLE_MAP`.
+
+    Raises
+    ------
+    requests.HTTPError
+        Raises an error when an incorrect request is made.
+
+    Returns
+    -------
+    data : pd.DataFrame
+        Time series data. The index corresponds to the start (left) of the
+        interval.
+    meta : dict
+        Metadata.
+
+    References
+    ----------
+    .. [1] `NASA Prediction Of Worldwide Energy Resources (POWER)
+       <https://power.larc.nasa.gov/>`_
+    .. [2] `NASA POWER API
+       <https://power.larc.nasa.gov/api/pages/>`_
+    .. [3] `NASA POWER API parameters
+       <https://power.larc.nasa.gov/parameters/>`_
+    .. [4] `NASA POWER corrected wind speed parameters
+       <https://power.larc.nasa.gov/docs/methodology/meteorology/wind/>`_
+    """
+    start = pd.Timestamp(start)
+    end = pd.Timestamp(end)
+
+    # allow the use of pvlib parameter names
+    parameter_dict = {v: k for k, v in VARIABLE_MAP.items()}
+    parameters = [parameter_dict.get(p, p) for p in parameters]
+
+    params = {
+        'latitude': latitude,
+        'longitude': longitude,
+        'start': start.strftime('%Y%m%d'),
+        'end': end.strftime('%Y%m%d'),
+        'community': community,
+        'parameters': ','.join(parameters),  # make parameters in a string
+        'format': 'json',
+        'user': None,
+        'header': True,
+        'time-standard': 'utc',
+        'site-elevation': elevation,
+        'wind-elevation': wind_height,
+        'wind-surface': wind_surface,
+    }
+
+    response = requests.get(url, params=params)
+    if not response.ok:
+        # response.raise_for_status() does not give a useful error message
+        raise requests.HTTPError(response.json())
+
+    # Parse the data to dataframe
+    data = response.json()
+    hourly_data = data['properties']['parameter']
+    df = pd.DataFrame(hourly_data)
+    df.index = pd.to_datetime(df.index, format='%Y%m%d%H').tz_localize('UTC')
+
+    # Create metadata dictionary
+    meta = data['header']
+    meta['times'] = data['times']
+    meta['parameters'] = data['parameters']
+
+    meta['longitude'] = data['geometry']['coordinates'][0]
+    meta['latitude'] = data['geometry']['coordinates'][1]
+    meta['altitude'] = data['geometry']['coordinates'][2]
+
+    # Replace NaN values
+    df = df.replace(meta['fill_value'], np.nan)
+
+    # Rename according to pvlib convention
+    if map_variables:
+        df = df.rename(columns=VARIABLE_MAP)
+
+    return df, meta

pvlib/iotools/pvgis.py

@@ -202,7 +202,7 @@ def get_pvgis_hourly(latitude, longitude, start=None, end=None,
     .. [2] `PVGIS Hourly Radiation
        <https://ec.europa.eu/jrc/en/PVGIS/tools/hourly-radiation>`_
     .. [3] `PVGIS Non-interactive service
-       <https://ec.europa.eu/jrc/en/PVGIS/docs/noninteractive>`_
+       <https://joint-research-centre.ec.europa.eu/photovoltaic-geographical-information-system-pvgis/getting-started-pvgis/api-non-interactive-service_en>`_
     .. [4] `PVGIS horizon profile tool
        <https://ec.europa.eu/jrc/en/PVGIS/tools/horizon>`_
     """  # noqa: E501

pvlib/modelchain.py

@@ -18,6 +18,8 @@
 from pvlib.pvsystem import _DC_MODEL_PARAMS
 from pvlib.tools import _build_kwargs
 
+from pvlib._deprecation import deprecated
+
 # keys that are used to detect input data and assign data to appropriate
 # ModelChain attribute
 # for ModelChain.weather
@@ -59,6 +61,13 @@
 )
 
 
+@deprecated(
+    since="0.13.1",
+    removal="",
+    name="pvlib.modelchain.get_orientation",
+    alternative=None,
+    addendum=None,
+)
 def get_orientation(strategy, **kwargs):
     """
     Determine a PV system's surface tilt and surface azimuth

pvlib/solarposition.py

@@ -285,7 +285,7 @@ def spa_python(time, latitude, longitude,
     Calculate the solar position using a python implementation of the
     NREL SPA algorithm.
 
-    The details of the NREL SPA algorithm are described in [1]_.
+    The details of the NREL SPA algorithm are described in [1]_, [2]_.
 
     If numba is installed, the functions can be compiled to
     machine code and the function can be multithreaded.
@@ -328,25 +328,26 @@ def spa_python(time, latitude, longitude,
     -------
     DataFrame
         The DataFrame will have the following columns:
-        apparent_zenith (degrees),
-        zenith (degrees),
-        apparent_elevation (degrees),
-        elevation (degrees),
-        azimuth (degrees),
-        equation_of_time (minutes).
 
+        - apparent_zenith (degrees),
+        - zenith (degrees),
+        - apparent_elevation (degrees),
+        - elevation (degrees),
+        - azimuth (degrees),
+        - equation_of_time (minutes).
 
     References
     ----------
     .. [1] I. Reda and A. Andreas, Solar position algorithm for solar
        radiation applications. Solar Energy, vol. 76, no. 5, pp. 577-589, 2004.
+       :doi:`10.1016/j.solener.2003.12.003`.
 
     .. [2] I. Reda and A. Andreas, Corrigendum to Solar position algorithm for
        solar radiation applications. Solar Energy, vol. 81, no. 6, p. 838,
-       2007.
+       2007. :doi:`10.1016/j.solener.2007.01.003`.
 
-    .. [3] USNO delta T:
-       https://maia.usno.navy.mil/products/deltaT
+    .. [3] `U.S. Naval Observatory, delta T
+       <https://maia.usno.navy.mil/products/deltaT>`_
 
     See also
     --------