diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 80d6b61470..b8901ef6c3 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -33,9 +33,21 @@ jobs: - name: Build packages run: python -m build + - name: List distribution file sizes + run: du -h dist/* + - name: Check metadata verification run: python -m twine check --strict dist/* + - name: Ensure that the wheel installs successfully + run: | + mkdir ./tmp + pip install $(find dist -type f -name "*.whl") --target=./tmp + + - name: List installed file sizes + run: du -h pvlib + working-directory: ./tmp + # only publish distribution to PyPI for tagged commits - name: Publish distribution to PyPI if: startsWith(github.ref, 'refs/tags/v') diff --git a/docs/sphinx/source/_images/example_function_screenshot.png b/docs/sphinx/source/_images/example_function_screenshot.png new file mode 100644 index 0000000000..f4728bd9e2 Binary files /dev/null and b/docs/sphinx/source/_images/example_function_screenshot.png differ diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 58faa59a98..5a874f0f51 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/docs/sphinx/source/contributing/style_guide.rst @@ -13,7 +13,7 @@ pvlib python generally follows the `PEP 8 -- Style Guide for Python Code is 79 characters. pvlib python uses a mix of full and abbreviated variable names. See -:ref:`variables_style_rules`. We could be better about consistency. +:ref:`nomenclature`. Prefer full names for new contributions. This is especially important for the API. Abbreviations can be used within a function to improve the readability of formulae. @@ -70,6 +70,81 @@ the ``docs/readthedocs.org:pvlib-python`` link within the checks status box at the bottom of the pull request. +.. _references: + +References +---------- +pvlib-python is transitioning to the `IEEE reference style `_, +which should be used in all new contributions. At minimum, a reference should +include: + +* Author list (for more than six authors, list only the first with et al.) +* Publication title +* Publisher (journal title, laboratory name, etc.) +* Year of publication +* DOI (if available) + +The recommended citation style for several media types is as follows: + +**Journal article**: + + Author initials and surname, "Title of article," abbreviated journal + title, vol. number, issue number, page numbers, Abbreviated Month Year. + +**Book**: + + Author initials. Author Surname, "Chapter title" in Book Title, xth ed. + City of Publisher, (only U.S. State), Country: Abbrev. of Publisher, year, + ch. x, sec. x, pp. xxx–xxx. + +**Technical report**: + + Author initials. Author Surname, "Report title" Abbrev. publisher name, + City of publisher, Abbrev. State, Country, Rep. xxx, year + +The example below shows how to cite material and generate a reference list +using the IEEE style in a docstring:: + + This is the recommended citation for the pvlib-python project [1]_. There + are also some conference papers linked to pvlib, for example [2]_. + + Other types of reference you may find in the pvlib-python documentation + include books [3]_, technical reports [4]_, and websites [5]_. + + References + ---------- + .. [1] K. Anderson, C. Hansen, W. Holmgren, A. Jensen, M. Mikofski, + and A Driesse. "pvlib python: 2023 project update." J. Open Source + Softw. vol. 8, no. 92, pp. 5994, Dec 2023, + :doi:`10.21105/joss.05994`. + + .. [2] J. S. Stein, "The Photovoltaic Performance Modeling Collaborative + (PVPMC)," In Proc. 38th IEEE Photovoltaic Specialists Conference + (PVSC), Austin, TX, USA, 2012, pp. 3048-3052, + :doi:`10.1109/PVSC.2012.6318225`. + + .. [3] J. A. Duffie and W. A. Beckman, "Solar Radiation" in Solar + Engineering of Thermal Processes, 3rd ed, New York, USA, J. Wiley + and Sons, 2006, ch. 1, sec. 1.5, pp.9-11. + + .. [4] R. Bird and C. Riordan, "Simple solar spectral model for direct and + diffuse irradiance on horizontal and tilted planes at the earth’s + surface for cloudless atmospheres", NREL, Golden, CO, USA, Technical + Report TR-215-2436, 1984, :doi:`10.2172/5986936`. + + .. [5] "PVPMC Home." Sandia National Laboratories PV Performance Modeling + Collaborative. Accessed: Oct. 17, 2024. [Online.] Available: + _ + +Things to note: + +* In-text numeric citations are a number inside square brackets, followed + by an underscore, e.g. ``[1]_``. +* To include a DOI, you can use pvlib's custom ``:doi:`` + `Sphinx role `_, + followed by the DOI inside a set of backticks. + + .. _building-the-documentation: Building the documentation @@ -88,7 +163,7 @@ An easy way to do this is with:: Note: Anaconda users may have trouble using the above command to update an older version of docutils. If that happens, you can update it with ``conda`` -(e.g. ``conda install docutils=0.15.2``) and run the above command again. +(e.g. ``conda install docutils=0.21``) and run the above command again. Once the ``doc`` dependencies are installed, navigate to ``/docs/sphinx`` and execute:: @@ -107,6 +182,116 @@ Note that Windows users need not have the ``make`` utility installed as pvlib includes a ``make.bat`` batch file that emulates its interface. +.. _example-docstring: + +Example Docstring +----------------- + +Here is a template for a function docstring that encapsulates the main +features that may be used in any docstring. Note that not all sections are +required for every function. + +.. code-block:: python + + def example_function(poa_global, exponents, degree_symbol, time_ref='UT', + optional_arg=None): + r""" + One-sentence summary of the function (no citations). + + A longer description of the function. This can include citations + (references) to literature [1]_, websites [2]_, and other code elements + such as functions (:py:func:`pvlib.location.lookup_altitude`) and + classes (:py:class:`pvlib.location.Location`). + + .. versionadded:: 0.0.1 + There are many more purpose-specific directives, admonitions and such + available at `this link `_. E.g.: ``.. versionchanged::``, + ``.. deprecated::``, ``.. note::`` and ``.. warning::``. + + .. _admonitions: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#admonitions-messages-and-warnings + + Parameters + ---------- + poa_global : numeric + Plane-of-array global irradiance, see :term:`poa_global`. [Wm⁻²]. + exponents : array-like + A list of exponents. [x⁰¹²³⁴⁵⁶⁷⁸⁹⁻]. + degree_symbol : pandas.Series or pandas.DataFrame + It's different from superscript zero. [°]. + time_ref : ``'UT'`` or ``'TST'``, default: ``'UT'`` + ``'UT'`` (universal time) or ``'TST'`` (True Solar Time). + optional_arg : integer, optional + A description of ``optional_arg``. [Unitless]. + + Specify a suitable datatype for each parameter. Other common + data types include ``str``, ``bool``, ``float``, ``numeric`` + and ``pandas.DatetimeIndex``. + + Returns + ------- + name : numeric + A description of the return value. + + Raises + ------ + ValueError + If ``poa_global`` is negative. + KeyError + If ``time_ref`` does not exist. + + Notes + ----- + This section can include additional information about the function. + + For example, an equation using LaTeX markup: + + .. math:: + + a = \left(\frac{b}{c}\right)^2 + + where :math:`a` is the result of the equation, and :math:`b` and :math:`c` + are inputs. + + Or a figure with a caption: + + .. figure:: ../../_images/pvlib_logo_horiz.png + :scale: 10% + :alt: alternate text + :align: center + + Figure caption. + + See Also + -------- + pvlib.location.lookup_altitude, pvlib.location.Location + + Examples + -------- + >>> example_function(1, 1, pd.Series([1]), "TST", 2) + 'Something' + + References + ---------- + A IEEE citation to a relevant reference. You may use an automatic + citation generator to format the citation correctly. + + .. [1] Anderson, K., Hansen, C., Holmgren, W., Jensen, A., Mikofski, M., + and Driesse, A. "pvlib python: 2023 project update." Journal of Open + Source Software, 8(92), 5994, (2023). :doi:`10.21105/joss.05994`. + .. [2] J. Smith and J. Doe. "Obama inaugurated as President." CNN.com. + Accessed: Feb. 1, 2009. [Online.] + Available: http://www.cnn.com/POLITICS/01/21/obama_inaugurated/index.html + """ + a = "Some" + b = "thing" + return a + b + +A preview of how this docstring would render in the documentation can be seen in the +following file: :download:`Example docstring<../_images/example_function_screenshot.png>`. + +Remember that to show the docstring in the documentation, you must list +the function in the appropriate ``.rst`` file in the ``docs/sphinx/source/reference`` folder. + .. _example-gallery: Example Gallery diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index ce62c56e28..20e776bf2f 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -26,7 +26,7 @@ pvlib python that-use-pvlib-python>`_ page for inspiration and listing of your application. -There is a :ref:`variable naming convention ` to +There is a :ref:`variable naming convention ` to ensure consistency throughout the library. diff --git a/docs/sphinx/source/user_guide/index.rst b/docs/sphinx/source/user_guide/index.rst index 416cc0b260..8ce48515c9 100644 --- a/docs/sphinx/source/user_guide/index.rst +++ b/docs/sphinx/source/user_guide/index.rst @@ -15,6 +15,6 @@ User Guide clearsky bifacial weather_data - variables_style_rules singlediode + nomenclature faq diff --git a/docs/sphinx/source/user_guide/nomenclature.rst b/docs/sphinx/source/user_guide/nomenclature.rst new file mode 100644 index 0000000000..a89da06cbf --- /dev/null +++ b/docs/sphinx/source/user_guide/nomenclature.rst @@ -0,0 +1,192 @@ +.. _nomenclature: + +Nomenclature +============ + +There is a convention on consistent variable names throughout the library: + +.. glossary:: + + airmass + Airmass + + airmass_absolute + Absolute airmass + + airmass_relative + Relative airmass + + albedo + Ratio of reflected solar irradiance to global horizontal irradiance + [unitless] + + aoi + Angle of incidence. Angle between the surface normal vector and the + vector pointing towards the sun’s center + + aoi_projection + cos(aoi) + + ape + Average photon energy + + apparent_zenith + Refraction-corrected solar zenith angle in degrees + + bhi + Beam/direct horizontal irradiance + + dhi + Diffuse horizontal irradiance + + dni + Direct normal irradiance [Wm⁻²]. Irradiance received per unit area by a + surface perpendicular (normal) to the sun's rays that propagate in a + straight line from the sun. + + dni_clear + Clear sky direct normal irradiance + + dni_extra + Direct normal irradiance at top of atmosphere (extraterrestrial) + + effective_irradiance + Effective irradiance + + eta_inv + Inverter efficiency + + eta_inv_nom + Nominal inverter efficiency + + eta_inv_ref + Reference inverter efficiency + + g_poa_effective + Broadband plane of array effective irradiance + + gamma_pdc + Module temperature coefficient. Typically in units of 1/C. + + ghi + Global horizontal irradiance + + ghi_extra + Horizontal irradiance at top of atmosphere (extraterrestrial) + + gri + Ground-reflected irradiance + + i_sc + Short circuit module current + + i_x, i_xx + Sandia Array Performance Model IV curve parameters + + latitude + Latitude + + longitude + Longitude + + pac, ac + AC power + + pdc, dc + DC power + + pdc0 + Nameplate DC rating + + photocurrent + Photocurrent + + poa_diffuse + Total diffuse irradiation in plane. Sum of ground and sky diffuse. + + poa_direct + Direct/beam irradiation in plane + + poa_global + Global irradiation in plane. sum of diffuse and beam projection. + + poa_ground_diffuse + In plane ground reflected irradiation + + poa_sky_diffuse + Diffuse irradiation in plane from scattered light in the atmosphere + (without ground reflected irradiation) + + precipitable_water + Total precipitable water contained in a column of unit cross section + from earth to top of atmosphere + + pressure + Atmospheric pressure + + relative_humidity + Relative humidity + + resistance_series + Series resistance + + resistance_shunt + Shunt resistance + + saturation_current + Diode saturation current + + solar_azimuth + Azimuth angle of the sun in degrees East of North + + solar_zenith + Zenith angle of the sun in degrees + + surface_azimuth + Azimuth angle of the surface + + surface_tilt + Panel tilt from horizontal [°]. For example, a surface facing up = 0°, + surface facing horizon = 90°. + + temp_air + Temperature of the air + + temp_cell + Temperature of the cell + + temp_dew + Dewpoint temperature + + temp_module + Temperature of the module + + transposition_factor + The gain ratio of the radiation on inclined plane to global horizontal + irradiation: :math:`\frac{poa\_global}{ghi}` + + tz + Timezone + + v_mp, i_mp, p_mp + Module voltage, current, power at the maximum power point + + v_oc + Open circuit module voltage + + wind_direction + Wind direction + + wind_speed + Wind speed + + +For further explanation of the variables, common symbols, and +units, refer to the following sources from `SoDa Service `_: + + * `Acronyms, Terminology and Units `_ + * `Plane orientations and radiation components `_ + * `Time references `_ + +.. note:: These further references might not use the same terminology as + *pvlib*. But the physical process referred to is the same. diff --git a/docs/sphinx/source/user_guide/variables_style_rules.rst b/docs/sphinx/source/user_guide/variables_style_rules.rst deleted file mode 100644 index 4d3574ab4b..0000000000 --- a/docs/sphinx/source/user_guide/variables_style_rules.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _variables_style_rules: - -Variables and Symbols -===================== - -There is a convention on consistent variable names throughout the library: - -.. csv-table:: List of used Variables and Parameters - :file: ../../../../pvlib/data/variables_style_rules.csv - :delim: ; - :header-rows: 1 - :widths: 5, 5 - :stub-columns: 1 - -For a definition and further explanation on the variables, common symbols and units refer to the following sources: - - -* `IEC 61724-1:2017 -- Photovoltaic system performance - Part 1: Monitoring `_ section: 3 -- Terms and definitions; the Indian Standard referencing the withdrawn earlier global IEC standard IEC 61724:1998 is available online: `IS/IEC 61724 (1998) `_ and can provide relevant contents. -* Explanation of Solar irradiation and solar geometry by `SoDa Service `_ - - * `Acronyms, Terminology and Units `_ - * `Plane orientations and radiation components `_ - * `Time references `_ - -.. note:: These further references might not use the same terminology as *pvlib*. But the physical process referred to is the same. diff --git a/docs/sphinx/source/user_guide/weather_data.rst b/docs/sphinx/source/user_guide/weather_data.rst index 06e54d2296..9f983cf335 100644 --- a/docs/sphinx/source/user_guide/weather_data.rst +++ b/docs/sphinx/source/user_guide/weather_data.rst @@ -83,7 +83,7 @@ a :py:class:`pandas.DataFrame` of the actual dataset, plus a metadata dictionary. Most :py:mod:`pvlib.iotools` functions also have a ``map_variables`` parameter to automatically translate the column names used in the data file (which vary widely from dataset to dataset) -into standard pvlib names (see :ref:`variables_style_rules`). +into standard pvlib names (see :ref:`nomenclature`). Typical usage looks something like this: diff --git a/docs/sphinx/source/whatsnew/v0.11.2.rst b/docs/sphinx/source/whatsnew/v0.11.2.rst index f168922554..0827899be2 100644 --- a/docs/sphinx/source/whatsnew/v0.11.2.rst +++ b/docs/sphinx/source/whatsnew/v0.11.2.rst @@ -15,12 +15,28 @@ Enhancements the previous size. (:issue:`2271`, :pull:`2277`) +Bug Fixes +~~~~~~~~~ +* :py:meth:`~pvlib.pvsystem.PVSystem.get_irradiance` accepts float inputs. + (:issue:`1338`, :pull:`2227`) + +Bug fixes +~~~~~~~~~ +* :py:func:`~pvlib.spa.julian_day_dt` now accounts for the 10 day difference + between Julian and Gregorian calendars prior to the year 1582. (:issue:`2077`, :pull:`2249`) + Documentation ~~~~~~~~~~~~~ * Edited docstrings for :py:func:`~pvlib.pvsystem.dc_ohms_from_percent` and :py:func:`~pvlib.pvsystem.dc_ohmic_losses` for clarity. (:issue:`1601`, :pull:`2229`) +* Added a new citation style guide (:ref:`references`) to the contributing + page. (:issue:`2202`, :pull:`2226`) * Updated :py:func:`~pvlib.irradiance.reindl` to include definitions of terms and a new "notes" section (:issue:`2183`, :pull:`2193`) +* Added a new :ref:`nomenclature` page, in place of the Variables and Symbols + page, using the sphinx glossary directive. (:issue:`1421`, :pull:`2234`) +* Explained how to write docstrings for new functions in :ref:`example-docstring` + (:discussion:`2081`, :pull:`2254`) Testing ~~~~~~~ @@ -41,6 +57,8 @@ Contributors ~~~~~~~~~~~~ * Cliff Hansen (:ghuser:`cwhanse`) * Rajiv Daxini (:ghuser:`RDaxini`) +* Dave Pitts (:ghuser:`dgapitts`) +* Kurt Rhee (:ghuser:`kurt-rhee`) * Mark Mikofski (:ghuser:`mikofski`) * matsuobasho (:ghuser:`matsuobasho`) * Echedey Luis (:ghuser:`echedey-ls`) diff --git a/docs/sphinx/source/whatsnew/v0.3.0.txt b/docs/sphinx/source/whatsnew/v0.3.0.txt index 62cc9839f7..36db1b3b90 100644 --- a/docs/sphinx/source/whatsnew/v0.3.0.txt +++ b/docs/sphinx/source/whatsnew/v0.3.0.txt @@ -47,7 +47,7 @@ Enhancements * :ref:`installation` (:issue:`135`) * :ref:`contributing` (:issue:`46`) * :ref:`timetimezones` (:issue:`47`) - * :ref:`variables_style_rules` (:issue:`102`) + * Variables and Symbols (:issue:`102`) * Classes (:issue:`93`) (Moved to :ref:`api` in :issue:`258`) * Adds support for Appveyor, a Windows continuous integration service. diff --git a/pvlib/data/aod550_tcwv_20121101_test.nc b/pvlib/data/aod550_tcwv_20121101_test.nc deleted file mode 100644 index c65d1fb941..0000000000 Binary files a/pvlib/data/aod550_tcwv_20121101_test.nc and /dev/null differ diff --git a/pvlib/data/variables_style_rules.csv b/pvlib/data/variables_style_rules.csv deleted file mode 100644 index f7930bd445..0000000000 --- a/pvlib/data/variables_style_rules.csv +++ /dev/null @@ -1,56 +0,0 @@ -variable;description -tz;timezone -latitude;latitude -longitude;longitude -dni;direct normal irradiance -dni_extra;direct normal irradiance at top of atmosphere (extraterrestrial) -dni_clear;clear sky direct normal irradiance -dhi;diffuse horizontal irradiance -bhi;beam/direct horizontal irradiance -ghi;global horizontal irradiance -ghi_extra;horizontal irradiance at top of atmosphere (extraterrestrial) -gri;ground-reflected irradiance -ape;average photon energy -aoi;angle of incidence. Angle between the surface normal vector and the vector pointing towards the sun's center -aoi_projection;cos(aoi) -airmass;airmass -airmass_relative;relative airmass -airmass_absolute;absolute airmass -poa_ground_diffuse;in plane ground reflected irradiation -poa_direct;direct/beam irradiation in plane -poa_diffuse;total diffuse irradiation in plane. sum of ground and sky diffuse. -poa_global;global irradiation in plane. sum of diffuse and beam projection. -poa_sky_diffuse;diffuse irradiation in plane from scattered light in the atmosphere (without ground reflected irradiation) -g_poa_effective;broadband plane of array effective irradiance. -surface_tilt;tilt angle of the surface -surface_azimuth;azimuth angle of the surface -solar_zenith;zenith angle of the sun in degrees -apparent_zenith;refraction-corrected solar zenith angle in degrees -solar_azimuth;azimuth angle of the sun in degrees East of North -temp_cell;temperature of the cell -temp_module;temperature of the module -temp_air;temperature of the air -temp_dew;dewpoint temperature -relative_humidity;relative humidity -wind_speed;wind speed -wind_direction;wind direction -pressure;atmospheric pressure -albedo;ratio of reflected solar irradiance to global horizontal irradiance, unitless -precipitable_water;total precipitable water contained in a column of unit cross section from earth to top of atmosphere -v_mp, i_mp, p_mp;module voltage, current, power at the maximum power point -v_oc;open circuit module voltage -i_sc;short circuit module current -i_x, i_xx;Sandia Array Performance Model IV curve parameters -effective_irradiance;effective irradiance -photocurrent;photocurrent -saturation_current;diode saturation current -resistance_series;series resistance -resistance_shunt;shunt resistance -transposition_factor; the gain ratio of the radiation on inclined plane to global horizontal irradiation: :math:`\frac{poa\_global}{ghi}` -pdc0; nameplate DC rating -pdc, dc; dc power -gamma_pdc; module temperature coefficient. Typically in units of 1/C. -pac, ac; ac power -eta_inv; inverter efficiency -eta_inv_ref; reference inverter efficiency -eta_inv_nom; nominal inverter efficiency diff --git a/pvlib/iotools/midc.py b/pvlib/iotools/midc.py index 99b6f20680..c0dfd370eb 100644 --- a/pvlib/iotools/midc.py +++ b/pvlib/iotools/midc.py @@ -193,7 +193,7 @@ def read_midc(filename, variable_map={}, raw_data=False, **kwargs): See the MIDC_VARIABLE_MAP for collection of mappings by site. For a full list of pvlib variable names see the - :ref:`variables_style_rules`. + :ref:`nomenclature`. Be sure to check the units for the variables you will use on the `MIDC site `_. diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index d1854cfb6c..1a3ac5e71e 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -734,16 +734,14 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra, The Hay and Davies model determines the diffuse irradiance from the sky (ground reflected irradiance is not included in this algorithm) on a tilted surface using the surface tilt angle, surface - azimuth angle, diffuse horizontal irradiance, direct normal - irradiance, extraterrestrial irradiance, sun zenith angle, and sun - azimuth angle. + azimuth angle, diffuse horizontal irradiance, direct normal irradiance, + extraterrestrial irradiance, sun zenith angle, and sun azimuth angle. Parameters ---------- surface_tilt : numeric - Surface tilt angles in decimal degrees. The tilt angle is - defined as degrees from horizontal (e.g. surface facing up = 0, - surface facing horizon = 90) + Panel tilt from the horizontal, in decimal degrees, see + :term:`surface_tilt`. surface_azimuth : numeric Surface azimuth angles in decimal degrees. The azimuth @@ -754,7 +752,7 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra, Diffuse horizontal irradiance. [Wm⁻²] dni : numeric - Direct normal irradiance. [Wm⁻²] + Direct normal irradiance, see :term:`dni`. [Wm⁻²] dni_extra : numeric Extraterrestrial normal irradiance. [Wm⁻²] diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 02a1ac0664..76872248a4 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -312,7 +312,7 @@ def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi, dni_extra=None, airmass=None, albedo=None, model='haydavies', **kwargs): """ - Uses the :py:func:`irradiance.get_total_irradiance` function to + Uses :py:func:`pvlib.irradiance.get_total_irradiance` to calculate the plane of array irradiance components on the tilted surfaces defined by each array's ``surface_tilt`` and ``surface_azimuth``. @@ -323,11 +323,11 @@ def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi, Solar zenith angle. solar_azimuth : float or Series Solar azimuth angle. - dni : float or Series or tuple of float or Series + dni : float, Series, or tuple of float or Series Direct Normal Irradiance. [W/m2] - ghi : float or Series or tuple of float or Series + ghi : float, Series, or tuple of float or Series Global horizontal irradiance. [W/m2] - dhi : float or Series or tuple of float or Series + dhi : float, Series, or tuple of float or Series Diffuse horizontal irradiance. [W/m2] dni_extra : float, Series or tuple of float or Series, optional Extraterrestrial direct normal irradiance. [W/m2] @@ -339,15 +339,22 @@ def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi, Irradiance model. kwargs - Extra parameters passed to :func:`irradiance.get_total_irradiance`. + Extra parameters passed to + :py:func:`pvlib.irradiance.get_total_irradiance`. Notes ----- - Each of `dni`, `ghi`, and `dni` parameters may be passed as a tuple - to provide different irradiance for each array in the system. If not - passed as a tuple then the same value is used for input to each Array. - If passed as a tuple the length must be the same as the number of - Arrays. + Each of ``dni``, ``ghi``, and ``dni`` may be passed as a float, Series, + or tuple of float or Series. If passed as a float or Series, these + values are used for all Arrays. If passed as a tuple, the tuple length + must be the same as the number of Arrays. The first tuple element is + used for the first Array, the second tuple element for the second + Array, and so forth. + + Some sky irradiance models require ``dni_extra``. For these models, + if ``dni_extra`` is not provided and ``solar_zenith`` has a + ``DatetimeIndex``, then ``dni_extra`` is calculated. + Otherwise, ``dni_extra=1367`` is assumed. Returns ------- @@ -1077,7 +1084,7 @@ def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi, """ Get plane of array irradiance components. - Uses the :py:func:`pvlib.irradiance.get_total_irradiance` function to + Uses :py:func:`pvlib.irradiance.get_total_irradiance` to calculate the plane of array irradiance components for a surface defined by ``self.surface_tilt`` and ``self.surface_azimuth``. @@ -1112,6 +1119,13 @@ def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi, Column names are: ``'poa_global', 'poa_direct', 'poa_diffuse', 'poa_sky_diffuse', 'poa_ground_diffuse'``. + Notes + ----- + Some sky irradiance models require ``dni_extra``. For these models, + if ``dni_extra`` is not provided and ``solar_zenith`` has a + ``DatetimeIndex``, then ``dni_extra`` is calculated. + Otherwise, ``dni_extra=1367`` is assumed. + See also -------- :py:func:`pvlib.irradiance.get_total_irradiance` @@ -1119,9 +1133,16 @@ def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi, if albedo is None: albedo = self.albedo - # not needed for all models, but this is easier + # dni_extra is not needed for all models, but this is easier if dni_extra is None: - dni_extra = irradiance.get_extra_radiation(solar_zenith.index) + if (hasattr(solar_zenith, 'index') and + isinstance(solar_zenith.index, pd.DatetimeIndex)): + # calculate extraterrestrial irradiance + dni_extra = irradiance.get_extra_radiation( + solar_zenith.index) + else: + # use the solar constant + dni_extra = 1367.0 if airmass is None: airmass = atmosphere.get_relative_airmass(solar_zenith) diff --git a/pvlib/spa.py b/pvlib/spa.py index 23c0d42ed4..d4181aaa49 100644 --- a/pvlib/spa.py +++ b/pvlib/spa.py @@ -413,8 +413,10 @@ def julian_day_dt(year, month, day, hour, minute, second, microsecond): frac_of_day = (microsecond / 1e6 + (second + minute * 60 + hour * 3600) ) * 1.0 / (3600*24) d = day + frac_of_day - jd = (int(365.25 * (year + 4716)) + int(30.6001 * (month + 1)) + d + - b - 1524.5) + jd = int(365.25 * (year + 4716)) + int(30.6001 * (month + 1)) + d - 1524.5 + if jd > 2299160.0: + jd += b + return jd diff --git a/pvlib/tests/test_pvsystem.py b/pvlib/tests/test_pvsystem.py index c98c201af4..fd482c5127 100644 --- a/pvlib/tests/test_pvsystem.py +++ b/pvlib/tests/test_pvsystem.py @@ -1870,7 +1870,6 @@ def test_PVSystem_get_irradiance(solar_pos): irrads['dni'], irrads['ghi'], irrads['dhi']) - expected = pd.DataFrame(data=np.array( [[883.65494055, 745.86141676, 137.79352379, 126.397131, 11.39639279], [0., -0., 0., 0., 0.]]), @@ -1881,6 +1880,23 @@ def test_PVSystem_get_irradiance(solar_pos): assert_frame_equal(irradiance, expected, check_less_precise=2) +def test_PVSystem_get_irradiance_float(): + system = pvsystem.PVSystem(surface_tilt=32, surface_azimuth=135) + irrads = {'dni': 900., 'ghi': 600., 'dhi': 100.} + zenith = 55.366831 + azimuth = 172.320038 + irradiance = system.get_irradiance(zenith, + azimuth, + irrads['dni'], + irrads['ghi'], + irrads['dhi']) + expected = {'poa_global': 884.80903423, 'poa_direct': 745.84258835, + 'poa_diffuse': 138.96644588, 'poa_sky_diffuse': 127.57005309, + 'poa_ground_diffuse': 11.39639279} + for k, v in irradiance.items(): + assert np.isclose(v, expected[k], rtol=1e-6) + + def test_PVSystem_get_irradiance_albedo(solar_pos): system = pvsystem.PVSystem(surface_tilt=32, surface_azimuth=135) irrads = pd.DataFrame({'dni': [900, 0], 'ghi': [600, 0], 'dhi': [100, 0], diff --git a/pvlib/tests/test_spa.py b/pvlib/tests/test_spa.py index f4b6dec03d..67cab4cbdb 100644 --- a/pvlib/tests/test_spa.py +++ b/pvlib/tests/test_spa.py @@ -1,6 +1,8 @@ import os import datetime as dt import warnings +import pytest +import pvlib try: from importlib import reload @@ -423,3 +425,30 @@ def test_solar_position_multithreaded(self): nresult, self.spa.solar_position( times, lat, lon, elev, pressure, temp, delta_t, atmos_refract, numthreads=3, sst=True)[:3], 5) + + +# Define extra test cases for issue #2077 +test_cases_issue_2207 = [ + ((2000, 1, 1, 12, 0, 0), 2451545.0), + ((1999, 1, 1, 0, 0, 0), 2451179.5), + ((1987, 1, 27, 0, 0, 0), 2446822.5), + ((1987, 6, 19, 12, 0, 0), 2446966.0), + ((1988, 1, 27, 0, 0, 0), 2447187.5), + ((1988, 6, 19, 12, 0, 0), 2447332.0), + ((1900, 1, 1, 0, 0, 0), 2415020.5), + ((1600, 1, 1, 0, 0, 0), 2305447.5), + ((1600, 12, 31, 0, 0, 0), 2305812.5), + ((837, 4, 10, 7, 12, 0), 2026871.8), + ((-123, 12, 31, 0, 0, 0), 1676496.5), + ((-122, 1, 1, 0, 0, 0), 1676497.5), + ((-1000, 7, 12, 12, 0, 0), 1356001.0), + ((-1000, 2, 29, 0, 0, 0), 1355866.5), + ((-1001, 8, 17, 21, 36, 0), 1355671.4), + ((-4712, 1, 1, 12, 0, 0), 0.0), +] + + +@pytest.mark.parametrize("inputs, expected", test_cases_issue_2207) +def test_julian_day_issue_2207(inputs, expected): + result = pvlib.spa.julian_day_dt(*inputs, microsecond=0) + assert result == expected, f"Failed for inputs {inputs}"