pvlib 0.10.5__py3-none-any.whl → 0.11.0a1__py3-none-any.whl

pvlib/iam.py

@@ -592,10 +592,10 @@ def marion_diffuse(model, surface_tilt, **kwargs):
     iam : dict
         IAM values for each type of diffuse irradiance:
 
-            * 'sky': radiation from the sky dome (zenith <= 90)
-            * 'horizon': radiation from the region of the sky near the horizon
-              (89.5 <= zenith <= 90)
-            * 'ground': radiation reflected from the ground (zenith >= 90)
+        * 'sky': radiation from the sky dome (zenith <= 90)
+        * 'horizon': radiation from the region of the sky near the horizon
+          (89.5 <= zenith <= 90)
+        * 'ground': radiation reflected from the ground (zenith >= 90)
 
         See [1]_ for a detailed description of each class.
 
@@ -667,10 +667,10 @@ def marion_integrate(function, surface_tilt, region, num=None):
     region : {'sky', 'horizon', 'ground'}
         The region to integrate over. Must be one of:
 
-            * 'sky': radiation from the sky dome (zenith <= 90)
-            * 'horizon': radiation from the region of the sky near the horizon
-              (89.5 <= zenith <= 90)
-            * 'ground': radiation reflected from the ground (zenith >= 90)
+        * 'sky': radiation from the sky dome (zenith <= 90)
+        * 'horizon': radiation from the region of the sky near the horizon
+          (89.5 <= zenith <= 90)
+        * 'ground': radiation reflected from the ground (zenith >= 90)
 
         See [1]_ for a detailed description of each class.
 
@@ -678,8 +678,8 @@ def marion_integrate(function, surface_tilt, region, num=None):
         The number of increments in the zenith integration.
         If not specified, N will follow the values used in [1]_:
 
-            * 'sky' or 'ground': num = 180
-            * 'horizon': num = 1800
+        * 'sky' or 'ground': num = 180
+        * 'horizon': num = 1800
 
     Returns
     -------
@@ -1107,14 +1107,14 @@ def convert(source_name, source_params, target_name, weight=_sin_weight,
     source_params : dict
         A dictionary of parameters for the source model.
 
-            If source model is ``'ashrae'``, the dictionary must contain
-            the key ``'b'``.
+        If source model is ``'ashrae'``, the dictionary must contain
+        the key ``'b'``.
 
-            If source model is ``'martin_ruiz'``, the dictionary must
-            contain the key ``'a_r'``.
+        If source model is ``'martin_ruiz'``, the dictionary must
+        contain the key ``'a_r'``.
 
-            If source model is ``'physical'``, the dictionary must
-            contain the keys ``'n'``, ``'K'``, and ``'L'``.
+        If source model is ``'physical'``, the dictionary must
+        contain the keys ``'n'``, ``'K'``, and ``'L'``.
 
     target_name : str
         Name of the target model. Must be ``'ashrae'``, ``'martin_ruiz'``, or
@@ -1146,14 +1146,14 @@ def convert(source_name, source_params, target_name, weight=_sin_weight,
     dict
         Parameters for the target model.
 
-            If target model is ``'ashrae'``, the dictionary will contain
-            the key ``'b'``.
+        If target model is ``'ashrae'``, the dictionary will contain
+        the key ``'b'``.
 
-            If target model is ``'martin_ruiz'``, the dictionary will
-            contain the key ``'a_r'``.
+        If target model is ``'martin_ruiz'``, the dictionary will
+        contain the key ``'a_r'``.
 
-            If target model is ``'physical'``, the dictionary will
-            contain the keys ``'n'``, ``'K'``, and ``'L'``.
+        If target model is ``'physical'``, the dictionary will
+        contain the keys ``'n'``, ``'K'``, and ``'L'``.
 
     Note
     ----
@@ -1243,14 +1243,14 @@ def fit(measured_aoi, measured_iam, model_name, weight=_sin_weight, xtol=None):
     dict
         Parameters for target model.
 
-            If target model is ``'ashrae'``, the dictionary will contain
-            the key ``'b'``.
+        If target model is ``'ashrae'``, the dictionary will contain
+        the key ``'b'``.
 
-            If target model is ``'martin_ruiz'``, the dictionary will
-            contain the key ``'a_r'``.
+        If target model is ``'martin_ruiz'``, the dictionary will
+        contain the key ``'a_r'``.
 
-            If target model is ``'physical'``, the dictionary will
-            contain the keys ``'n'``, ``'K'``, and ``'L'``.
+        If target model is ``'physical'``, the dictionary will
+        contain the keys ``'n'``, ``'K'``, and ``'L'``.
 
     References
     ----------

pvlib/iotools/__init__.py

@@ -1,7 +1,6 @@
 from pvlib.iotools.tmy import read_tmy2, read_tmy3  # noqa: F401
 from pvlib.iotools.epw import read_epw, parse_epw  # noqa: F401
 from pvlib.iotools.srml import read_srml  # noqa: F401
-from pvlib.iotools.srml import read_srml_month_from_solardat  # noqa: F401
 from pvlib.iotools.srml import get_srml  # noqa: F401
 from pvlib.iotools.surfrad import read_surfrad  # noqa: F401
 from pvlib.iotools.midc import read_midc  # noqa: F401

pvlib/iotools/midc.py

@@ -20,15 +20,21 @@ import pandas as pd
 MIDC_VARIABLE_MAP = {
     'BMS': {
         'Global CMP22 (vent/cor) [W/m^2]': 'ghi',
-        'Direct NIP [W/m^2]': 'dni',
+        'Direct CHP1-1 [W/m^2]': 'dni_chp1',
+        # NIP was mapped to dni for pvlib<=0.10.5
+        'Direct NIP [W/m^2]': 'dni_nip',
         'Diffuse CM22-1 (vent/cor) [W/m^2]': 'dhi',
         'Avg Wind Speed @ 6ft [m/s]': 'wind_speed',
         'Tower Dry Bulb Temp [deg C]': 'temp_air',
         'Tower RH [%]': 'relative_humidity'},
     'UOSMRL': {
         'Global CMP22 [W/m^2]': 'ghi',
-        'Direct NIP [W/m^2]': 'dni',
-        'Diffuse Schenk [W/m^2]': 'dhi',
+        'Direct CHP1 [W/m^2]': 'dni_chp1',
+        'Diffuse [W/m^2]': 'dhi',
+        # NIP was mapped to dni for pvlib<=0.10.5
+        'Direct NIP [W/m^2]': 'dni_nip',
+        # Schenk was mapped to dhi for pvlib<=0.10.5
+        # 'Diffuse Schenk [W/m^2]': 'dhi',
         'Air Temperature [deg C]': 'temp_air',
         'Relative Humidity [%]': 'relative_humidity',
         'Avg Wind Speed @ 10m [m/s]': 'wind_speed'},
@@ -80,18 +86,17 @@ MIDC_VARIABLE_MAP = {
         'Air Temperature [deg C]': 'temp_air',
         'Rel Humidity [%]': 'relative_humidity',
         'Avg Wind Speed @ 3m [m/s]': 'wind_speed'},
-    'VTIF': {
+    'NWTC': {
         'Global Horizontal [W/m^2]': 'ghi',
         'Direct Normal [W/m^2]': 'dni',
         'Diffuse Horizontal [W/m^2]': 'dhi',
-        'Air Temperature [deg C]': 'temp_air',
-        'Avg Wind Speed @ 3m [m/s]': 'wind_speed',
-        'Rel Humidity [%]': 'relative_humidity'},
-    'NWTC': {
-        'Global PSP [W/m^2]': 'ghi',
+        # PSP instrument was removed Feb. 2021
+        # PSP was mapped to ghi for pvlib<=0.10.5
+        # 'Global PSP [W/m^2]': 'ghi',
         'Temperature @ 2m [deg C]': 'temp_air',
         'Avg Wind Speed @ 2m [m/s]': 'wind_speed',
-        'Relative Humidity [%]': 'relative_humidity'}}
+        'Relative Humidity [%]': 'relative_humidity'},
+}
 
 
 # Maps problematic timezones to 'Etc/GMT' for parsing.

pvlib/iotools/psm3.py

@@ -62,8 +62,8 @@ REQUEST_VARIABLE_MAP = {
 
 
 def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
-             attributes=ATTRIBUTES, leap_day=None, full_name=PVLIB_PYTHON,
-             affiliation=PVLIB_PYTHON, map_variables=None, url=None,
+             attributes=ATTRIBUTES, leap_day=True, full_name=PVLIB_PYTHON,
+             affiliation=PVLIB_PYTHON, map_variables=True, url=None,
              timeout=30):
     """
     Retrieve NSRDB PSM3 timeseries weather data from the PSM3 API. The NSRDB
@@ -105,14 +105,14 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
         for lists of available fields. Alternatively, pvlib names may also be
         used (e.g. 'ghi' rather than 'GHI'); see :const:`REQUEST_VARIABLE_MAP`.
         To retrieve all available fields, set ``attributes=[]``.
-    leap_day : boolean, default False
+    leap_day : bool, default : True
         include leap day in the results. Only used for single-year requests
         (i.e., it is ignored for tmy/tgy/tdy requests).
     full_name : str, default 'pvlib python'
         optional
     affiliation : str, default 'pvlib python'
         optional
-    map_variables : boolean, optional
+    map_variables : bool, default True
         When true, renames columns of the Dataframe to pvlib variable names
         where applicable. See variable :const:`VARIABLE_MAP`.
     url : str, optional
@@ -179,14 +179,6 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
     # convert pvlib names in attributes to psm3 convention
     attributes = [REQUEST_VARIABLE_MAP.get(a, a) for a in attributes]
 
-    if (leap_day is None) and (not names.startswith('t')):
-        warnings.warn(
-            'The ``get_psm3`` function will default to leap_day=True '
-            'starting in pvlib 0.11.0. Specify leap_day=True '
-            'to enable this behavior now, or specify leap_day=False '
-            'to hide this warning.', pvlibDeprecationWarning)
-        leap_day = False
-
     # required query-string parameters for request to PSM3 API
     params = {
         'api_key': api_key,
@@ -227,7 +219,7 @@ def get_psm3(latitude, longitude, api_key, email, names='tmy', interval=60,
     return parse_psm3(fbuf, map_variables)
 
 
-def parse_psm3(fbuf, map_variables=None):
+def parse_psm3(fbuf, map_variables=True):
     """
     Parse an NSRDB PSM3 weather file (formatted as SAM CSV). The NSRDB
     is described in [1]_ and the SAM CSV format is described in [2]_.
@@ -241,9 +233,9 @@ def parse_psm3(fbuf, map_variables=None):
     ----------
     fbuf: file-like object
         File-like object containing data to read.
-    map_variables: bool
+    map_variables: bool, default True
         When true, renames columns of the Dataframe to pvlib variable names
-        where applicable. See variable VARIABLE_MAP.
+        where applicable. See variable :const:`VARIABLE_MAP`.
 
     Returns
     -------
@@ -356,13 +348,6 @@ def parse_psm3(fbuf, map_variables=None):
     tz = 'Etc/GMT%+d' % -metadata['Time Zone']
     data.index = pd.DatetimeIndex(dtidx).tz_localize(tz)
 
-    if map_variables is None:
-        warnings.warn(
-            'PSM3 variable names will be renamed to pvlib conventions by '
-            'default starting in pvlib 0.11.0. Specify map_variables=True '
-            'to enable that behavior now, or specify map_variables=False '
-            'to hide this warning.', pvlibDeprecationWarning)
-        map_variables = False
     if map_variables:
         data = data.rename(columns=VARIABLE_MAP)
         metadata['latitude'] = metadata.pop('Latitude')
@@ -372,7 +357,7 @@ def parse_psm3(fbuf, map_variables=None):
     return data, metadata
 
 
-def read_psm3(filename, map_variables=None):
+def read_psm3(filename, map_variables=True):
     """
     Read an NSRDB PSM3 weather file (formatted as SAM CSV). The NSRDB
     is described in [1]_ and the SAM CSV format is described in [2]_.
@@ -386,9 +371,9 @@ def read_psm3(filename, map_variables=None):
     ----------
     filename: str
         Filename of a file containing data to read.
-    map_variables: bool
+    map_variables: bool, default True
         When true, renames columns of the Dataframe to pvlib variable names
-        where applicable. See variable VARIABLE_MAP.
+        where applicable. See variable :const:`VARIABLE_MAP`.
 
     Returns
     -------

pvlib/iotools/srml.py

@@ -6,8 +6,6 @@ import pandas as pd
 import urllib
 import warnings
 
-from pvlib._deprecation import deprecated
-
 # VARIABLE_MAP is a dictionary mapping SRML data element numbers to their
 # pvlib names. For most variables, only the first three digits are used,
 # the fourth indicating the instrument. Spectral data (7xxx) uses all
@@ -172,65 +170,6 @@ def _format_index(df):
     return df
 
 
-@deprecated('0.10.0', alternative='pvlib.iotools.get_srml', removal='0.11.0')
-def read_srml_month_from_solardat(station, year, month, filetype='PO',
-                                  map_variables=True):
-    """
-    Request a month of SRML data and read it into a Dataframe.
-
-    The SRML is described in [1]_.
-
-    Parameters
-    ----------
-    station: str
-        The name of the SRML station to request.
-    year: int
-        Year to request data for
-    month: int
-        Month to request data for.
-    filetype: string
-        SRML file type to gather. See notes for explanation.
-    map_variables: bool, default: True
-        When true, renames columns of the DataFrame to pvlib variable names
-        where applicable. See variable :const:`VARIABLE_MAP`.
-
-    Returns
-    -------
-    data: pd.DataFrame
-        One month of data from SRML.
-
-    Notes
-    -----
-    File types designate the time interval of a file and if it contains
-    raw or processed data. For instance, `RO` designates raw, one minute
-    data and `PO` designates processed one minute data. The availability
-    of file types varies between sites. Below is a table of file types
-    and their time intervals. See [1] for site information.
-
-    ============= ============ ==================
-    time interval raw filetype processed filetype
-    ============= ============ ==================
-    1 minute      RO           PO
-    5 minute      RF           PF
-    15 minute     RQ           PQ
-    hourly        RH           PH
-    ============= ============ ==================
-
-    References
-    ----------
-    .. [1] University of Oregon Solar Radiation Measurement Laboratory
-       http://solardata.uoregon.edu/
-    """
-    file_name = "{station}{filetype}{year:02d}{month:02d}.txt".format(
-        station=station,
-        filetype=filetype,
-        year=year % 100,
-        month=month)
-    url = "http://solardata.uoregon.edu/download/Archive/"
-    data = read_srml(url + file_name, map_variables=map_variables)
-    return data
-
-
 def get_srml(station, start, end, filetype='PO', map_variables=True,
              url="http://solardata.uoregon.edu/download/Archive/"):
     """Request data from UoO SRML and read it into a Dataframe.

pvlib/irradiance.py

@@ -16,22 +16,18 @@ from scipy.optimize import bisect
 from pvlib import atmosphere, solarposition, tools
 import pvlib  # used to avoid dni name collision in complete_irradiance
 
+from pvlib._deprecation import pvlibDeprecationWarning
+import warnings
 
-# see References section of get_ground_diffuse function
-SURFACE_ALBEDOS = {'urban': 0.18,
-                   'grass': 0.20,
-                   'fresh grass': 0.26,
-                   'soil': 0.17,
-                   'sand': 0.40,
-                   'snow': 0.65,
-                   'fresh snow': 0.75,
-                   'asphalt': 0.12,
-                   'concrete': 0.30,
-                   'aluminum': 0.85,
-                   'copper': 0.74,
-                   'fresh steel': 0.35,
-                   'dirty steel': 0.08,
-                   'sea': 0.06}
+
+# Deprecation warning based on https://peps.python.org/pep-0562/
+def __getattr__(attr):
+    if attr == 'SURFACE_ALBEDOS':
+        warnings.warn(f"{attr} has been moved to the albedo module as of "
+                      "v0.11.0. Please use pvlib.albedo.SURFACE_ALBEDOS.",
+                      pvlibDeprecationWarning)
+        return pvlib.albedo.SURFACE_ALBEDOS
+    raise AttributeError(f"module {__name__!r} has no attribute {attr!r}")
 
 
 def get_extra_radiation(datetime_or_doy, solar_constant=1366.1,
@@ -232,48 +228,6 @@ def aoi(surface_tilt, surface_azimuth, solar_zenith, solar_azimuth):
     return aoi_value
 
 
-def poa_horizontal_ratio(surface_tilt, surface_azimuth,
-                         solar_zenith, solar_azimuth):
-    """
-    Calculates the ratio of the beam components of the plane of array
-    irradiance and the horizontal irradiance.
-
-    Input all angles in degrees.
-
-    Parameters
-    ----------
-    surface_tilt : numeric
-        Panel tilt from horizontal.
-    surface_azimuth : numeric
-        Panel azimuth from north.
-    solar_zenith : numeric
-        Solar zenith angle.
-    solar_azimuth : numeric
-        Solar azimuth angle.
-
-    Returns
-    -------
-    ratio : numeric
-        Ratio of the plane of array irradiance to the horizontal plane
-        irradiance
-    """
-
-    cos_poa_zen = aoi_projection(surface_tilt, surface_azimuth,
-                                 solar_zenith, solar_azimuth)
-
-    cos_solar_zenith = tools.cosd(solar_zenith)
-
-    # ratio of tilted and horizontal beam irradiance
-    ratio = cos_poa_zen / cos_solar_zenith
-
-    try:
-        ratio.name = 'poa_ratio'
-    except AttributeError:
-        pass
-
-    return ratio
-
-
 def beam_component(surface_tilt, surface_azimuth, solar_zenith, solar_azimuth,
                    dni):
     """
@@ -450,6 +404,11 @@ def get_sky_diffuse(surface_tilt, surface_azimuth,
     require ``'dni_extra'``. Values can be calculated using
     :py:func:`~pvlib.irradiance.get_extra_radiation`.
 
+    The ``'Perez'`` transposition model features discontinuities in the
+    predicted tilted diffuse irradiance due to relying on discrete input
+    values. For applications that benefit from continuous output, consider
+    using :py:func:`~pvlib.irradiance.perez_driesse`.
+
     The ``'perez'`` and ``'perez-driesse'`` models require relative airmass
     (``airmass``) as input. If ``airmass`` is not provided, it is calculated
     using the defaults in :py:func:`~pvlib.atmosphere.get_relative_airmass`.
@@ -592,7 +551,7 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None):
     Notes
     -----
     Table of albedo values by ``surface_type`` are from [2]_, [3]_, [4]_;
-    see :py:data:`~pvlib.irradiance.SURFACE_ALBEDOS`.
+    see :py:const:`~pvlib.albedo.SURFACE_ALBEDOS`.
 
     References
     ----------
@@ -607,7 +566,7 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None):
     '''
 
     if surface_type is not None:
-        albedo = SURFACE_ALBEDOS[surface_type]
+        albedo = pvlib.albedo.SURFACE_ALBEDOS[surface_type]
 
     diffuse_irrad = ghi * albedo * (1 - np.cos(np.radians(surface_tilt))) * 0.5
 
@@ -896,8 +855,8 @@ def reindl(surface_tilt, surface_azimuth, dhi, dni, ghi, dni_extra,
 
     .. math::
 
-       I_{d} = DHI (A R_b + (1 - A) (\frac{1 + \cos\beta}{2})
-       (1 + \sqrt{\frac{I_{hb}}{I_h}} \sin^3(\beta/2)) )
+       I_{d} = DHI \left(A R_b + (1 - A) \left(\frac{1 + \cos\beta}{2}\right)
+       \left(1 + \sqrt{\frac{I_{hb}}{I_h}} \sin^3(\beta/2)\right) \right)
 
     Reindl's 1990 model determines the diffuse irradiance from the sky
     (ground reflected irradiance is not included in this algorithm) on a
@@ -1050,6 +1009,13 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
     pressure-corrected) airmass. Optionally a selector may be used to
     use any of Perez's model coefficient sets.
 
+    Warning
+    -------
+    The Perez transposition model features discontinuities in the
+    predicted tilted diffuse irradiance due to relying on discrete input
+    values. For applications that benefit from continuous output, consider
+    using :py:func:`~pvlib.irradiance.perez_driesse`.
+
     Parameters
     ----------
     surface_tilt : numeric
@@ -1551,9 +1517,9 @@ def ghi_from_poa_driesse_2023(surface_tilt, surface_azimuth,
         Solar azimuth angle. [degree]
     poa_global : numeric
         Plane-of-array global irradiance, aka global tilted irradiance. [W/m^2]
-    dni_extra : None or numeric, default None
+    dni_extra : numeric, optional
         Extraterrestrial direct normal irradiance. [W/m^2]
-    airmass : None or numeric, default None
+    airmass : numeric, optional
         Relative airmass (not adjusted for pressure). [unitless]
     albedo : numeric, default 0.25
         Ground surface albedo. [unitless]
@@ -2334,10 +2300,10 @@ def gti_dirint(poa_global, aoi, solar_zenith, solar_azimuth, times,
     data : DataFrame
         Contains the following keys/columns:
 
-            * ``ghi``: the modeled global horizontal irradiance in W/m^2.
-            * ``dni``: the modeled direct normal irradiance in W/m^2.
-            * ``dhi``: the modeled diffuse horizontal irradiance in
-              W/m^2.
+        * ``ghi``: the modeled global horizontal irradiance in W/m^2.
+        * ``dni``: the modeled direct normal irradiance in W/m^2.
+        * ``dhi``: the modeled diffuse horizontal irradiance in
+          W/m^2.
 
     References
     ----------
@@ -2484,7 +2450,6 @@ def _gti_dirint_lt_90(poa_global, aoi, aoi_lt_90, solar_zenith, solar_azimuth,
     else:
         # we are here because we ran out of coeffs to loop over and
         # therefore we have exceeded max_iterations
-        import warnings
         failed_points = best_diff[aoi_lt_90][~best_diff_lte_1_lt_90]
         warnings.warn(
             ('%s points failed to converge after %s iterations. best_diff:\n%s'
@@ -2618,11 +2583,11 @@ def erbs(ghi, zenith, datetime_or_doy, min_cos_zenith=0.065, max_zenith=87):
     data : OrderedDict or DataFrame
         Contains the following keys/columns:
 
-            * ``dni``: the modeled direct normal irradiance in W/m^2.
-            * ``dhi``: the modeled diffuse horizontal irradiance in
-              W/m^2.
-            * ``kt``: Ratio of global to extraterrestrial irradiance
-              on a horizontal plane.
+        * ``dni``: the modeled direct normal irradiance in W/m^2.
+        * ``dhi``: the modeled diffuse horizontal irradiance in
+          W/m^2.
+        * ``kt``: Ratio of global to extraterrestrial irradiance
+          on a horizontal plane.
 
     References
     ----------
@@ -2721,11 +2686,11 @@ def erbs_driesse(ghi, zenith, datetime_or_doy=None, dni_extra=None,
     data : OrderedDict or DataFrame
         Contains the following keys/columns:
 
-            * ``dni``: the modeled direct normal irradiance in W/m^2.
-            * ``dhi``: the modeled diffuse horizontal irradiance in
-              W/m^2.
-            * ``kt``: Ratio of global to extraterrestrial irradiance
-              on a horizontal plane.
+        * ``dni``: the modeled direct normal irradiance in W/m^2.
+        * ``dhi``: the modeled diffuse horizontal irradiance in
+          W/m^2.
+        * ``kt``: Ratio of global to extraterrestrial irradiance
+          on a horizontal plane.
 
     Raises
     ------
@@ -2839,17 +2804,17 @@ def orgill_hollands(ghi, zenith, datetime_or_doy, dni_extra=None,
     data : OrderedDict or DataFrame
         Contains the following keys/columns:
 
-            * ``dni``: the modeled direct normal irradiance in W/m^2.
-            * ``dhi``: the modeled diffuse horizontal irradiance in
-              W/m^2.
-            * ``kt``: Ratio of global to extraterrestrial irradiance
-              on a horizontal plane.
+        * ``dni``: the modeled direct normal irradiance in W/m^2.
+        * ``dhi``: the modeled diffuse horizontal irradiance in
+          W/m^2.
+        * ``kt``: Ratio of global to extraterrestrial irradiance
+          on a horizontal plane.
 
     References
     ----------
     .. [1] Orgill, J.F., Hollands, K.G.T., Correlation equation for hourly
-      diffuse radiation on a horizontal surface, Solar Energy 19(4), pp 357–359,
-      1977. Eqs. 3(a), 3(b) and 3(c)
+      diffuse radiation on a horizontal surface, Solar Energy 19(4),
+      pp 357–359, 1977. Eqs. 3(a), 3(b) and 3(c)
       :doi:`10.1016/0038-092X(77)90006-8`
 
     See Also
@@ -2934,11 +2899,11 @@ def boland(ghi, solar_zenith, datetime_or_doy, a_coeff=8.645, b_coeff=0.613,
     data : OrderedDict or DataFrame
         Contains the following keys/columns:
 
-            * ``dni``: the modeled direct normal irradiance in W/m^2.
-            * ``dhi``: the modeled diffuse horizontal irradiance in
-              W/m^2.
-            * ``kt``: Ratio of global to extraterrestrial irradiance
-              on a horizontal plane.
+        * ``dni``: the modeled direct normal irradiance in W/m^2.
+        * ``dhi``: the modeled diffuse horizontal irradiance in
+          W/m^2.
+        * ``kt``: Ratio of global to extraterrestrial irradiance
+          on a horizontal plane.
 
     References
     ----------
@@ -3771,11 +3736,11 @@ def louche(ghi, solar_zenith, datetime_or_doy, max_zenith=90):
     data: OrderedDict or DataFrame
         Contains the following keys/columns:
 
-            * ``dni``: the modeled direct normal irradiance in W/m^2.
-            * ``dhi``: the modeled diffuse horizontal irradiance in
-              W/m^2.
-            * ``kt``: Ratio of global to extraterrestrial irradiance
-              on a horizontal plane.
+        * ``dni``: the modeled direct normal irradiance in W/m^2.
+        * ``dhi``: the modeled diffuse horizontal irradiance in
+          W/m^2.
+        * ``kt``: Ratio of global to extraterrestrial irradiance
+          on a horizontal plane.
 
     References
     -------
@@ -3808,3 +3773,76 @@ def louche(ghi, solar_zenith, datetime_or_doy, max_zenith=90):
         data = pd.DataFrame(data, index=datetime_or_doy)
 
     return data
+
+
+def diffuse_par_spitters(daily_solar_zenith, global_diffuse_fraction):
+    r"""
+    Derive daily diffuse fraction of Photosynthetically Active Radiation (PAR)
+    from daily average solar zenith and diffuse fraction of daily insolation.
+
+    The relationship is based on the work of Spitters et al. (1986) [1]_. The
+    resulting value is the fraction of daily PAR that is diffuse.
+
+    .. note::
+       The diffuse fraction is defined as the ratio of
+       diffuse to global daily insolation, in J m⁻² day⁻¹ or equivalent.
+
+    Parameters
+    ----------
+    daily_solar_zenith : numeric
+        Average daily solar zenith angle. In degrees [°].
+
+    global_diffuse_fraction : numeric
+        Fraction of daily global broadband insolation that is diffuse.
+        Unitless [0, 1].
+
+    Returns
+    -------
+    par_diffuse_fraction : numeric
+        Fraction of daily photosynthetically active radiation (PAR) that is
+        diffuse. Unitless [0, 1].
+
+    Notes
+    -----
+    The relationship is given by equations (9) & (10) in [1]_ and (1) in [2]_:
+
+    .. math::
+
+        k_{diffuse\_PAR}^{model} = \frac{PAR_{diffuse}}{PAR_{total}} =
+        \frac{\left[1 + 0.3 \left(1 - \left(k_d\right) ^2\right)\right]
+        k_d}
+        {1 + \left(1 - \left(k_d\right)^2\right) \cos ^2 (90 - \beta)
+        \cos ^3 \beta}
+
+    where :math:`k_d` is the diffuse fraction of the global insolation, and
+    :math:`\beta` is the daily average of the solar elevation angle in degrees.
+
+    A comparison using different models for the diffuse fraction of
+    the global insolation can be found in [2]_ in the context of Sweden.
+
+    References
+    ----------
+    .. [1] C. J. T. Spitters, H. A. J. M. Toussaint, and J. Goudriaan,
+       'Separating the diffuse and direct component of global radiation and its
+       implications for modeling canopy photosynthesis Part I. Components of
+       incoming radiation', Agricultural and Forest Meteorology, vol. 38,
+       no. 1, pp. 217-229, Oct. 1986, :doi:`10.1016/0168-1923(86)90060-2`.
+    .. [2] S. Ma Lu et al., 'Photosynthetically active radiation decomposition
+       models for agrivoltaic systems applications', Solar Energy, vol. 244,
+       pp. 536-549, Sep. 2022, :doi:`10.1016/j.solener.2022.05.046`.
+    """
+    # notation change:
+    # cosd(90-x) = sind(x) and 90-solar_elevation = solar_zenith
+    cosd_solar_zenith = tools.cosd(daily_solar_zenith)
+    cosd_solar_elevation = tools.sind(daily_solar_zenith)
+    par_diffuse_fraction = (
+        (1 + 0.3 * (1 - global_diffuse_fraction**2))
+        * global_diffuse_fraction
+        / (
+            1
+            + (1 - global_diffuse_fraction**2)
+            * cosd_solar_zenith**2
+            * cosd_solar_elevation**3
+        )
+    )
+    return par_diffuse_fraction