8000 ENH: infinite sheds (#717) · RoyCoding8/pvlib-python@63c36db · GitHub
[go: up one dir, main page]

Skip to content

Commit 63c36db

Browse files
mikofskicwhansekandersolar
authored
ENH: infinite sheds (pvlib#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 <bwana.marko@yahoo.com> * 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 <bwana.marko@yahoo.com> * 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 <bwana.marko@yahoo.com> * 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 <bwana.marko@yahoo.com> * changes solar_zenith, solar_azimuth names * Update pvlib/bifacial/infinite_sheds.py Co-authored-by: Mark Mikofski <bwana.marko@yahoo.com> * 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 <57452607+kanderso-nrel@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Kevin Anderson <57452607+kanderso-nrel@users.noreply.github.com> * remove OrderedDict Co-authored-by: Cliff Hansen <cwhanse@sandia.gov> Co-authored-by: Kevin Anderson <57452607+kanderso-nrel@users.noreply.github.com>
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)
    0