ENH: infinite sheds

docs/sphinx/source/reference/bifacial.rst

@@ -3,9 +3,11 @@
 Bifacial
 ========
 
-Methods for calculating back surface irradiance
+Functions for calculating front and back surface irradiance
 
 .. autosummary::
    :toctree: generated/
 
-   bifacial.pvfactors_timeseries
+   bifacial.pvfactors.pvfactors_timeseries
+   bifacial.infinite_sheds.get_irradiance
+   bifacial.infinite_sheds.get_irradiance_poa

docs/sphinx/source/user_guide/bifacial.rst

@@ -0,0 +1,105 @@
+.. _bifacial:
+
+Bifacial modeling
+=================
+
+This section reviews the bifacial modeling capabilities of
+pvlib-python.
+
+A bifacial module accepts light on both surfaces. Bifacial modules usually have
+a front and back surface, with the back surface intended to face away from
+the primary source of light. The primary challenge in modeling a PV system
+with bifacial modules is estimating the irradiance on the front and back
+surfaces.
+
+pvlib-python provides two groups of functions for estimating front and back
+irradiance:
+
+1. a wrapper for convenient use of the pvfactors package:
+:py:func:`~pvlib.bifacial.pvfactors.pvfactors_timeseries`
+
+2. the infinite sheds bifacial model:
+:py:func:`~pvlib.bifacial.infinite_sheds.get_irradiance`
+:py:func:`~pvlib.bifacial.infinite_sheds.get_irradiance_poa`
+
+
+pvfactors
+=========
+
+The `pvfactors <https://sunpower.github.io/pvfactors/>`_ package calculates
+incident irradiance on the front and back surfaces of an array. pvfactors uses
+a 2D geometry which assumes that the array is made up of long, regular rows.
+Irradiance is calculated in the middle of a row; end-of-row effects are not
+included. pvfactors can model arrays in fixed racking or on single-axis
+trackers.
+
+
+Infinite Sheds
+==============
+
+The "infinite sheds" model [1] is a 2-dimensional model of irradiance on the
+front and rear surfaces of a PV array. The model assumes that the array
+comprises parallel, equally spaced rows (sheds) and calculates irradiance in
+the middle of a shed which is far from the front and back rows of the array.
+Sheds are assumed to be long enough that end-of-row effects can be
+neglected. Rows can be at fixed tilt or on single-axis trackers. The ground
+is assumed to be horizontal and level, and the array is mounted at a fixed
+height above the ground.
+
+The infinite sheds model accounts for the following effects:
+
+    - limited view from the row surfaces to the sky due to blocking of the
+      sky by nearby rows;
+    - reduction of irradiance reaching the ground due to shadows cast by
+      rows and due to blocking of the sky by nearby rows.
+
+The model operates in the following steps:
+
+1. Find the fraction of unshaded ground between rows, ``f_gnd_beam`` where
+   both direct and diffuse irradiance is received. The model assumes that
+   there is no direct irradiance in the shaded fraction ``1 - f_gnd_beam``.
+2. Calculate the view factor, ``fz_sky``, from the ground to the sky accounting
+   for the parts of the sky that are blocked from view by the array's rows.
+   The view factor is multiplied by the sky diffuse irradiance to calculate
+   the diffuse irradiance reaching the ground. Sky diffuse irradiance is thus
+   assumed to be isotropic.
+3. Calculate the view factor from the row surface to the ground which
+   determines the fraction of ground-reflected irradiance that reaches the row
+   surface.
+4. Find the fraction of the row surface that is shaded from direct irradiance.
+   Only sky and ground-reflected irradiance reach the the shaded fraction of
+   the row surface.
+5. For the front and rear surfaces, apply the incidence angle modifier to
+   the direct irradiance and sum the diffuse sky, diffuse ground, and direct
+   irradiance to compute the plane-of-array (POA) irradiance on each surface.
+6. Apply the bifaciality factor, shade factor and transmission factor to
+   the rear surface POA irradiance and add the result to the front surface
+   POA irradiance to calculate the total POA irradiance on the row.
+
+Array geometry is defined by the following:
+
+    - ground coverage ratio (GCR), ``gcr``, the ratio of row slant height to
+      the spacing between rows (pitch).
+    - height of row center above ground, ``height``.
+    - tilt of the row from horizontal, ``surface_tilt``.
+    - azimuth of the row's normal vector, ``surface_azimuth``.
+View factors from the ground to the sky are calculated at points spaced along
+a one-dimensional axis on the ground, with the origin under the center of a
+row and the positive direction toward the right. The positive direction is
+considered to be towards the "front" of the array. Array height differs in this
+code from the description in [1], where array height is described at the row's
+lower edge.
+
+This model is influenced by the 2D model published by Marion, *et al.* in [2].
+
+References
+----------
+.. [1] Mikofski, M., Darawali, R., Hamer, M., Neubert, A., and Newmiller,
+   J. "Bifacial Performance Modeling in Large Arrays". 2019 IEEE 46th
+   Photovoltaic Specialists Conference (PVSC), 2019, pp. 1282-1287.
+   doi: 10.1109/PVSC40753.2019.8980572.
+.. [2] Marion. B., MacAlpine, S., Deline, C., Asgharzadeh, A., Toor, F.,
+   Riley, D., Stein, J. and Hansen, C. "A Practical Irradiance Model for
+   Bifacial PV Modules".2017 IEEE 44th Photovoltaic Specialists Conference
+   (PVSC), 2017, pp. 1537-1543. doi: 10.1109/PVSC.2017.8366263
+

docs/sphinx/source/user_guide/index.rst

@@ -13,6 +13,7 @@ User Guide
    modelchain
    timetimezones
    clearsky
+   bifacial
    forecasts
    comparison_pvlib_matlab
    variables_style_rules

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

@@ -8,6 +8,9 @@ Breaking changes
 
 Deprecations
 ~~~~~~~~~~~~
+* Moved :py:func:`pvlib.bifacial.pvfactors_timeseries` to
+  :py:func:`pvlib.bifacial.pvfactors.pvfactors_timeseries`.
+  :py:module:`pvlib.bifacial` is now a sub-package. (:pull:`717`)
 * :py:func:`pvlib.modelchain.basic_chain` is deprecated.
   See :py:meth:`pvlib.modelchain.ModelChain.with_pvwatts` and
   :py:meth:`pvlib.modelchain.ModelChain.with_sapm` for alternative simplified
@@ -16,6 +19,8 @@ Deprecations
 
 Enhancements
 ~~~~~~~~~~~~
+* Added `pvlib.bifacial.infinite_sheds`, containing a model for irradiance
+  on front and back surfaces of bifacial arrays. (:pull:`717`)
 * Added ``map_variables`` option to :func:`~pvlib.iotools.read_crn` (:pull:`1368`)
 * Added :py:func:`pvlib.temperature.prilliman` for modeling cell temperature
   at short time steps (:issue:`1081`, :pull:`1391`)

pvlib/bifacial/__init__.py

@@ -0,0 +1,13 @@
+"""
+The ``bifacial`` module contains functions to model irradiance for bifacial
+modules.
+
+"""
+from pvlib._deprecation import deprecated
+from pvlib.bifacial import pvfactors, infinite_sheds, utils   # noqa: F401
+
+pvfactors_timeseries = deprecated(
+    since='0.9.1',
+    name='pvlib.bifacial.pvfactors_timeseries',
+    alternative='pvlib.bifacial.pvfactors.pvfactors_timeseries'
+)(pvfactors.pvfactors_timeseries)