pvlib 0.9.5__py3-none-any.whl → 0.10.0__py3-none-any.whl

pvlib/bifacial/utils.py

@@ -5,6 +5,7 @@ modeling.
 import numpy as np
 from pvlib.tools import sind, cosd, tand
 
+
 def _solar_projection_tangent(solar_zenith, solar_azimuth, surface_azimuth):
     """
     Tangent of the angle between the zenith vector and the sun vector
@@ -89,7 +90,7 @@ def _unshaded_ground_fraction(surface_tilt, surface_azimuth, solar_zenith,
     return f_gnd_beam  # 1 - min(1, abs()) < 1 always
 
 
-def _vf_ground_sky_2d(x, rotation, gcr, pitch, height, max_rows=10):
+def vf_ground_sky_2d(rotation, gcr, x, pitch, height, max_rows=10):
     r"""
     Calculate the fraction of the sky dome visible from point x on the ground.
 
@@ -99,15 +100,15 @@ def _vf_ground_sky_2d(x, rotation, gcr, pitch, height, max_rows=10):
 
     Parameters
     ----------
-    x : numeric
-        Position on the ground between two rows, as a fraction of the pitch.
-        x = 0 corresponds to the point on the ground directly below the
-        center point of a row. Positive x is towards the right. [unitless]
     rotation : numeric
         Rotation angle of the row's right edge relative to row center.
         [degree]
     gcr : float
         Ratio of the row slant length to the row spacing (pitch). [unitless]
+    x : numeric
+        Position on the ground between two rows, as a fraction of the pitch.
+        x = 0 corresponds to the point on the ground directly below the
+        center point of a row. Positive x is towards the right. [unitless]
     height : float
         Height of the center point of the row above the ground; must be in the
         same units as ``pitch``.
@@ -169,3 +170,222 @@ def _vf_ground_sky_2d(x, rotation, gcr, pitch, height, max_rows=10):
     np.clip(next_edge, a_min=0., a_max=None, out=next_edge)
     vf = np.sum(next_edge, axis=-1) / 2
     return vf
+
+
+def vf_ground_sky_2d_integ(surface_tilt, gcr, height, pitch, max_rows=10,
+                           npoints=100, vectorize=False):
+    """
+    Integrated view factor to the sky from the ground underneath
+    interior rows of the array.
+
+    Parameters
+    ----------
+    surface_tilt : numeric
+        Surface tilt angle in degrees from horizontal, e.g., surface facing up
+        = 0, surface facing horizon = 90. [degree]
+    gcr : float
+        Ratio of row slant length to row spacing (pitch). [unitless]
+    height : float
+        Height of the center point of the row above the ground; must be in the
+        same units as ``pitch``.
+    pitch : float
+        Distance between two rows. Must be in the same units as ``height``.
+    max_rows : int, default 10
+        Maximum number of rows to consider in front and behind the current row.
+    npoints : int, default 100
+        Number of points used to discretize distance along the ground.
+    vectorize : bool, default False
+        If True, vectorize the view factor calculation across ``surface_tilt``.
+        This increases speed with the cost of increased memory usage.
+
+    Returns
+    -------
+    fgnd_sky : numeric
+        Integration of view factor over the length between adjacent, interior
+        rows.  Shape matches that of ``surface_tilt``. [unitless]
+    """
+    # Abuse vf_ground_sky_2d by supplying surface_tilt in place
+    # of a signed rotation. This is OK because
+    # 1) z span the full distance between 2 rows, and
+    # 2) max_rows is set to be large upstream, and
+    # 3) _vf_ground_sky_2d considers [-max_rows, +max_rows]
+    # The VFs to the sky will thus be symmetric around z=0.5
+    z = np.linspace(0, 1, npoints)
+    rotation = np.atleast_1d(surface_tilt)
+    if vectorize:
+        fz_sky = vf_ground_sky_2d(rotation, gcr, z, pitch, height, max_rows)
+    else:
+        fz_sky = np.zeros((npoints, len(rotation)))
+        for k, r in enumerate(rotation):
+            vf = vf_ground_sky_2d(r, gcr, z, pitch, height, max_rows)
+            fz_sky[:, k] = vf[:, 0]  # remove spurious rotation dimension
+    # calculate the integrated view factor for all of the ground between rows
+    return np.trapz(fz_sky, z, axis=0)
+
+
+def _vf_poly(surface_tilt, gcr, x, delta):
+    r'''
+    A term common to many 2D view factor calculations
+
+    Parameters
+    ----------
+    surface_tilt : numeric
+        Surface tilt angle in degrees from horizontal, e.g., surface facing up
+        = 0, surface facing horizon = 90. [degree]
+    gcr : numeric
+        Ratio of the row slant length to the row spacing (pitch). [unitless]
+    x : numeric
+        Position on the row's slant length, as a fraction of the slant length.
+        x=0 corresponds to the bottom of the row. [unitless]
+    delta : -1 or +1
+        A sign indicator for the linear term of the polynomial
+
+    Returns
+    -------
+    numeric
+    '''
+    a = 1 / gcr
+    c = cosd(surface_tilt)
+    return np.sqrt(a*a + 2*delta*a*c*x + x*x)
+
+
+def vf_row_sky_2d(surface_tilt, gcr, x):
+    r'''
+    Calculate the view factor to the sky from a point x on a row surface.
+
+    Assumes a PV system of infinitely long rows with uniform pitch on
+    horizontal ground. The view to the sky is restricted by the row's surface
+    tilt and the top of the adjacent row.
+
+    Parameters
+    ----------
+    surface_tilt : numeric
+        Surface tilt angle in degrees from horizontal, e.g., surface facing up
+        = 0, surface facing horizon = 90. [degree]
+    gcr : numeric
+        Ratio of the row slant length to the row spacing (pitch). [unitless]
+    x : numeric
+        Position on the row's slant length, as a fraction of the slant length.
+        x=0 corresponds to the bottom of the row. [unitless]
+
+    Returns
+    -------
+    vf : numeric
+        Fraction of the sky dome visible from the point x. [unitless]
+
+    '''
+    p = _vf_poly(surface_tilt, gcr, 1 - x, -1)
+    return 0.5*(1 + (1/gcr * cosd(surface_tilt) - (1 - x)) / p)
+
+
+def vf_row_sky_2d_integ(surface_tilt, gcr, x0=0, x1=1):
+    r'''
+    Calculate the average view factor to the sky from a segment of the row
+    surface between x0 and x1.
+
+    Assumes a PV system of infinitely long rows with uniform pitch on
+    horizontal ground. The view to the sky is restricted by the row's surface
+    tilt and the top of the adjacent row.
+
+    Parameters
+    ----------
+    surface_tilt : numeric
+        Surface tilt angle in degrees from horizontal, e.g., surface facing up
+        = 0, surface facing horizon = 90. [degree]
+    gcr : numeric
+        Ratio of the row slant length to the row spacing (pitch). [unitless]
+    x0 : numeric, default 0
+        Position on the row's slant length, as a fraction of the slant length.
+        x0=0 corresponds to the bottom of the row. x0 should be less than x1.
+        [unitless]
+    x1 : numeric, default 1
+        Position on the row's slant length, as a fraction of the slant length.
+        x1 should be greater than x0. [unitless]
+
+    Returns
+    -------
+    vf : numeric
+        Average fraction of the sky dome visible from points in the segment
+        from x0 to x1. [unitless]
+
+    '''
+    u = np.abs(x1 - x0)
+    p0 = _vf_poly(surface_tilt, gcr, 1 - x0, -1)
+    p1 = _vf_poly(surface_tilt, gcr, 1 - x1, -1)
+    with np.errstate(divide='ignore'):
+        result = np.where(u < 1e-6,
+                          vf_row_sky_2d(surface_tilt, gcr, x0),
+                          0.5*(1 + 1/u * (p1 - p0))
+                          )
+    return result
+
+
+def vf_row_ground_2d(surface_tilt, gcr, x):
+    r'''
+    Calculate the view factor to the ground from a point x on a row surface.
+
+    Assumes a PV system of infinitely long rows with uniform pitch on
+    horizontal ground. The view to the ground is restricted by the row's
+    tilt and the bottom of the facing row.
+
+    Parameters
+    ----------
+    surface_tilt : numeric
+        Surface tilt angle in degrees from horizontal, e.g., surface facing up
+        = 0, surface facing horizon = 90. [degree]
+    gcr : numeric
+        Ratio of the row slant length to the row spacing (pitch). [unitless]
+    x : numeric
+        Position on the row's slant length, as a fraction of the slant length.
+        x=0 corresponds to the bottom of the row. [unitless]
+
+    Returns
+    -------
+    vf : numeric
+        View factor to the visible ground from the point x. [unitless]
+
+    '''
+    p = _vf_poly(surface_tilt, gcr, x, 1)
+    return 0.5 * (1 - (1/gcr * cosd(surface_tilt) + x)/p)
+
+
+def vf_row_ground_2d_integ(surface_tilt, gcr, x0=0, x1=1):
+    r'''
+    Calculate the average view factor to the ground from a segment of the row
+    surface between x0 and x1.
+
+    Assumes a PV system of infinitely long rows with uniform pitch on
+    horizontal ground. The view to the ground is restricted by the row's
+    tilt and the bottom of the facing row.
+
+    Parameters
+    ----------
+    surface_tilt : numeric
+        Surface tilt angle in degrees from horizontal, e.g., surface facing up
+        = 0, surface facing horizon = 90. [degree]
+    gcr : numeric
+        Ratio of the row slant length to the row spacing (pitch). [unitless]
+    x0 : numeric, default 0.
+        Position on the row's slant length, as a fraction of the slant length.
+        x0=0 corresponds to the bottom of the row. x0 should be less than x1.
+        [unitless]
+    x1 : numeric, default 1.
+        Position on the row's slant length, as a fraction of the slant length.
+        x1 should be greater than x0. [unitless]
+
+    Returns
+    -------
+    vf : numeric
+        Integrated view factor to the visible ground on the interval (x0, x1).
+        [unitless]
+
+    '''
+    u = np.abs(x1 - x0)
+    p0 = _vf_poly(surface_tilt, gcr, x0, 1)
+    p1 = _vf_poly(surface_tilt, gcr, x1, 1)
+    with np.errstate(divide='ignore'):
+        result = np.where(u < 1e-6,
+                          vf_row_ground_2d(surface_tilt, gcr, x0),
+                          0.5*(1 - 1/u * (p1 - p0))
+                          )
+    return result