Skip to content

Commit 63c36db

Browse files
mikofskicwhansekandersolar
authored
ENH: infinite sheds (#717)
* WIP: ENH: infinite sheds * DOC: add infinite_sheds to api.rst, docstrings form sky_angle * ENH: functions for infinite sheds * add _to_radians and is_rad to convert only if necessary * prefix all functions with get_ * add get_f_sky_pv, get_poa_sky_pv, get_ground_angle_tangent, get_f_gnd_pv, get_f_gnd_pv, get_poa_gnd_pv, etc. * update API ui Signed-off-by: Mark Mikofski <[email protected]> * ENH: clean up docstrings, add 4-quad arctan2, add api docs, more get_irradiance * DOC: fix latex math, use psi_t for top, psi_b for bottom * STY: don't use get_* for standard functions * ENH: create class methods to get irradiance, FIXME: front/back poa not defined * TST: add infinite_sheads test, add infinite_sheds to pvlib-api * TST: ground illumination test * TST: coerce df to float, replace div/0 with nan * TST: set atol to 1e-6 to compare to CSV * TST: test for shade line * TST: fix diffuse fraction NaN and Inf, consolidate front+back = 1 test * TST: add tests for sky angle, psi_top * ENH: STY: fix stickler, ignore binary operator breaks * get_irradiance, output ordered dict or dataframe * finish updating get_poa_global_bifacial to transpose beam and diffuse for each side separately * add fixmes for ground illumination and ground view factor * ENH: BUG: DOC: change "ground-illumination" to "unshaded-ground-fraction" - use tan(zenith) in solar projection math latex - implement gcr_prime and ground-sky-angles calculations - add stub for ground-diffuse view factor Signed-off-by: Mark Mikofski <[email protected]> * ENH: BUG: calculate angles and VF from ground between panels to sky - calculate ground-sky angles to previous and next rows, assuming height is nonzero - calculate limits on ground where it can see the sky - calculate the view factor as a function of z on the ground to the sky - fix places where it still says degrees, bad, no! - add fixme for pv-sky view factor, still has wrong formula - add tests for angles from point z on the ground to tops of current row, and limits of previous and next rows - add a script to make the plot of ground-sky view factor versus z * ENH: BUG: remove gcr_prime from vf calc, not used - add comments, change names x->z - add TODO's to limit number of rows, and set row-type: 'first', 'last', or 'middle' * BUG: fix view factors formulas - was difference of angles, should be difference of cosines - also add TODO's to return VF versus point x on panel, and don't use averages * STY: shorten line in test_infinite_sheds for sum of angles at z1 limit * DOC: update module docstring with process from Marion, et al. - change calc_fx_sky to calc_fz_sky since z is for ground and x is for pv surface - add docstring to calc_fz_sky and for ground_sky_diffuse_view_factor * BUG: revert changes to ground and sky to pv surface view factors * ENH: integrate Fgnd-pv and Fsky-z * change _bigz() to just return bigz * create a test figure of integrated vslue * fix references * update infinite sheds - integrate vf_gnd_sky and apply to poa_ground_diffuse - new vf_ground_sky function - fix iam.ashrae and total_irrad - some cleanup, comment out old bifacialvf stuff - add height, pitch, and npoints args where needed Signed-off-by: Mark Mikofski <[email protected]> * remove discretized angles for fgndsky * don't discretize z * remove maxp, bigz, zuni, and psi_zuni from calc_fgndpv_zsky and just use the integrated value * add more detail re: infinite sheds to module docstring * change f_gnd_sky to f_gnd_beam everywhere * derive how integrated vf_gnd_sky is applied to diffuse reflected light, cite eqn (2) in Marion's paper * clarify what next, prev mean * add ascii sketches to clarify angles to top & bottom of prev or next rows and for current row * clarify what z0 and z1 limits mean * clean up outputs for get_irradiance - and InfiniteSheds.get_irradiance * consolidate solar projection tests * also compare phi and tan_phi * use fraction of pvsurface fx * add test for vf_ground_sky * be quiet stickler * TODO inserts, docstring edits * re-organize * create test files, move two functions to utils * adjust test paths * fix testing * adjustments to sky_angle_tangent * adjustments to get tests to run * move shade_line to shading.shaded_fraction * remove shade_line from infinite_sheds * remove functions that have moved to utils, shading * move several functions to private * move more functions to private * update test_utils.py * linting * tilt to surface_tilt, docstring work * consolidate some functions, docstring work * sky diffuse view factors * finish editing get_irradiance and supporting functions * rework public functions * formatting * remove old test file * add tests for sky_angle functions, remove diffuse_ratio * more tests, fix error in _sky_angle * more tests and docstring work * stickler * remove old test file, test fixes * test fixes * remove axis from linspace usage * documentation * docstrings * height = 0 and surface_tilt = 0 cases * vectorize _vf_ground_sky * overhaul ground to sky view factors, add function to utils * lint, handle floats * improve test fixture, remove unused * loop over rotations in _vf_ground_sky_integ, test get_irradiance_poa * more tests * lint * complete coverage * progress on testing get_irradiance * more testing * whoops * merge upstream * remove local test hack * correction to unshaded_ground_fraction * move pvfactors tests * additional testing * add max_zenith to unshaded_ground_fraction * docstring work * use shading function, extend shading.shaded_fraction * documentation * clarifications, consistent argument order * fix errors * use numeric instead of array-like * docstring sanding * more docstring work, reorder arguments for consistency * edits from review * fix tests * fix test * remove max_rows from public * move shaded_fraction from shading.py to infinite_sheds private * move shading_fraction * repair test, stickler * remove axis_azimuth * redo tests without axis_azimuth, few corrections * trailing spaces * behind the array criteria, return names * changes from review * diffuse fraction when ghi is 0 * clean up * Apply suggestions from code review Co-authored-by: Mark Mikofski <[email protected]> * changes solar_zenith, solar_azimuth names * Update pvlib/bifacial/infinite_sheds.py Co-authored-by: Mark Mikofski <[email protected]> * DOI directive in infinite_sheds.get_irradiance * change back to solar_zenith, solar_azimuth * rename in test_utils * OrderedDict to dict * create bifacial.rst * Update docs/sphinx/source/user_guide/bifacial.rst Co-authored-by: Kevin Anderson <[email protected]> * Apply suggestions from code review Co-authored-by: Kevin Anderson <[email protected]> * remove OrderedDict Co-authored-by: Cliff Hansen <[email protected]> Co-authored-by: Kevin Anderson <[email protected]>
1 parent b8f89b8 commit 63c36db

File tree

12 files changed

+1483
-6
lines changed

12 files changed

+1483
-6
lines changed

docs/sphinx/source/reference/bifacial.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,11 @@
33
Bifacial
44
========
55

6-
Methods for calculating back surface irradiance
6+
Functions for calculating front and back surface irradiance
77

88
.. autosummary::
99
:toctree: generated/
1010

11-
bifacial.pvfactors_timeseries
11+
bifacial.pvfactors.pvfactors_timeseries
12+
bifacial.infinite_sheds.get_irradiance
13+
bifacial.infinite_sheds.get_irradiance_poa
Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
.. _bifacial:
2+
3+
Bifacial modeling
4+
=================
5+
6+
This section reviews the bifacial modeling capabilities of
7+
pvlib-python.
8+
9+
A bifacial module accepts light on both surfaces. Bifacial modules usually have
10+
a front and back surface, with the back surface intended to face away from
11+
the primary source of light. The primary challenge in modeling a PV system
12+
with bifacial modules is estimating the irradiance on the front and back
13+
surfaces.
14+
15+
pvlib-python provides two groups of functions for estimating front and back
16+
irradiance:
17+
18+
1. a wrapper for convenient use of the pvfactors package:
19+
:py:func:`~pvlib.bifacial.pvfactors.pvfactors_timeseries`
20+
21+
2. the infinite sheds bifacial model:
22+
:py:func:`~pvlib.bifacial.infinite_sheds.get_irradiance`
23+
:py:func:`~pvlib.bifacial.infinite_sheds.get_irradiance_poa`
24+
25+
26+
pvfactors
27+
=========
28+
29+
The `pvfactors <https://sunpower.github.io/pvfactors/>`_ package calculates
30+
incident irradiance on the front and back surfaces of an array. pvfactors uses
31+
a 2D geometry which assumes that the array is made up of long, regular rows.
32+
Irradiance is calculated in the middle of a row; end-of-row effects are not
33+
included. pvfactors can model arrays in fixed racking or on single-axis
34+
trackers.
35+
36+
37+
Infinite Sheds
38+
==============
39+
40+
The "infinite sheds" model [1] is a 2-dimensional model of irradiance on the
41+
front and rear surfaces of a PV array. The model assumes that the array
42+
comprises parallel, equally spaced rows (sheds) and calculates irradiance in
43+
the middle of a shed which is far from the front and back rows of the array.
44+
Sheds are assumed to be long enough that end-of-row effects can be
45+
neglected. Rows can be at fixed tilt or on single-axis trackers. The ground
46+
is assumed to be horizontal and level, and the array is mounted at a fixed
47+
height above the ground.
48+
49+
The infinite sheds model accounts for the following effects:
50+
51+
- limited view from the row surfaces to the sky due to blocking of the
52+
sky by nearby rows;
53+
- reduction of irradiance reaching the ground due to shadows cast by
54+
rows and due to blocking of the sky by nearby rows.
55+
56+
The model operates in the following steps:
57+
58+
1. Find the fraction of unshaded ground between rows, ``f_gnd_beam`` where
59+
both direct and diffuse irradiance is received. The model assumes that
60+
there is no direct irradiance in the shaded fraction ``1 - f_gnd_beam``.
61+
2. Calculate the view factor, ``fz_sky``, from the ground to the sky accounting
62+
for the parts of the sky that are blocked from view by the array's rows.
63+
The view factor is multiplied by the sky diffuse irradiance to calculate
64+
the diffuse irradiance reaching the ground. Sky diffuse irradiance is thus
65+
assumed to be isotropic.
66+
3. Calculate the view factor from the row surface to the ground which
67+
determines the fraction of ground-reflected irradiance that reaches the row
68+
surface.
69+
4. Find the fraction of the row surface that is shaded from direct irradiance.
70+
Only sky and ground-reflected irradiance reach the the shaded fraction of
71+
the row surface.
72+
5. For the front and rear surfaces, apply the incidence angle modifier to
73+
the direct irradiance and sum the diffuse sky, diffuse ground, and direct
74+
irradiance to compute the plane-of-array (POA) irradiance on each surface.
75+
6. Apply the bifaciality factor, shade factor and transmission factor to
76+
the rear surface POA irradiance and add the result to the front surface
77+
POA irradiance to calculate the total POA irradiance on the row.
78+
79+
Array geometry is defined by the following:
80+
81+
- ground coverage ratio (GCR), ``gcr``, the ratio of row slant height to
82+
the spacing between rows (pitch).
83+
- height of row center above ground, ``height``.
84+
- tilt of the row from horizontal, ``surface_tilt``.
85+
- azimuth of the row's normal vector, ``surface_azimuth``.
86+
View factors from the ground to the sky are calculated at points spaced along
87+
a one-dimensional axis on the ground, with the origin under the center of a
88+
row and the positive direction toward the right. The positive direction is
89+
considered to be towards the "front" of the array. Array height differs in this
90+
code from the description in [1], where array height is described at the row's
91+
lower edge.
92+
93+
This model is influenced by the 2D model published by Marion, *et al.* in [2].
94+
95+
References
96+
----------
97+
.. [1] Mikofski, M., Darawali, R., Hamer, M., Neubert, A., and Newmiller,
98+
J. "Bifacial Performance Modeling in Large Arrays". 2019 IEEE 46th
99+
Photovoltaic Specialists Conference (PVSC), 2019, pp. 1282-1287.
100+
doi: 10.1109/PVSC40753.2019.8980572.
101+
.. [2] Marion. B., MacAlpine, S., Deline, C., Asgharzadeh, A., Toor, F.,
102+
Riley, D., Stein, J. and Hansen, C. "A Practical Irradiance Model for
103+
Bifacial PV Modules".2017 IEEE 44th Photovoltaic Specialists Conference
104+
(PVSC), 2017, pp. 1537-1543. doi: 10.1109/PVSC.2017.8366263
105+

docs/sphinx/source/user_guide/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ User Guide
1313
modelchain
1414
timetimezones
1515
clearsky
16+
bifacial
1617
forecasts
1718
comparison_pvlib_matlab
1819
variables_style_rules

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ Breaking changes
88

99
Deprecations
1010
~~~~~~~~~~~~
11+
* Moved :py:func:`pvlib.bifacial.pvfactors_timeseries` to
12+
:py:func:`pvlib.bifacial.pvfactors.pvfactors_timeseries`.
13+
:py:module:`pvlib.bifacial` is now a sub-package. (:pull:`717`)
1114
* :py:func:`pvlib.modelchain.basic_chain` is deprecated.
1215
See :py:meth:`pvlib.modelchain.ModelChain.with_pvwatts` and
1316
:py:meth:`pvlib.modelchain.ModelChain.with_sapm` for alternative simplified
@@ -16,6 +19,8 @@ Deprecations
1619

1720
Enhancements
1821
~~~~~~~~~~~~
22+
* Added `pvlib.bifacial.infinite_sheds`, containing a model for irradiance
23+
on front and back surfaces of bifacial arrays. (:pull:`717`)
1924
* Added ``map_variables`` option to :func:`~pvlib.iotools.read_crn` (:pull:`1368`)
2025
* Added :py:func:`pvlib.temperature.prilliman` for modeling cell temperature
2126
at short time steps (:issue:`1081`, :pull:`1391`)

pvlib/bifacial/__init__.py

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
"""
2+
The ``bifacial`` module contains functions to model irradiance for bifacial
3+
modules.
4+
5+
"""
6+
from pvlib._deprecation import deprecated
7+
from pvlib.bifacial import pvfactors, infinite_sheds, utils # noqa: F401
8+
9+
pvfactors_timeseries = deprecated(
10+
since='0.9.1',
11+
name='pvlib.bifacial.pvfactors_timeseries',
12+
alternative='pvlib.bifacial.pvfactors.pvfactors_timeseries'
13+
)(pvfactors.pvfactors_timeseries)

0 commit comments

Comments
 (0)