Merge branch 'main' into glossary

Author: RDaxini

.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')

.github/workflows/top-ranked-issues.yml

@@ -1,17 +1,17 @@
 name: Update Top Ranked Issues
 
 on:
-  # For testing purposes (can be removed later)
-  pull_request:  
   schedule:
-    # # Runs every day at 3:00 AM UTC
-    # - cron: '0 3 * * *'
-    - cron: '*/10 * * * *'
+    # Runs every day at 00:00 AM UTC
+    - cron: '0 0 * * *'
 
 jobs:
   run-script:
     runs-on: ubuntu-latest
 
+    # Run only if the repository is pvlib/pvlib-python
+    if: ${{ github.repository == 'pvlib/pvlib-python' }}
+
     env:
       GITHUB_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

docs/sphinx/source/_images/example_function_screenshot.png

@@ -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 <https://journals.ieeeauthorcenter.ieee.org/wp-content/uploads/sites/7/IEEE_Reference_Guide.pdf>`_,
+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:
+           <https://pvpmc.sandia.gov/>_
+
+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 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_,
+  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 <admonitions>`_. 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

docs/sphinx/source/contributing/style_guide.rst

@@ -12,14 +12,23 @@ Enhancements
 ~~~~~~~~~~~~
 
 
+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
 ~~~~~~~
@@ -39,6 +48,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`)

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

@@ -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
 
 

pvlib/data/aod550_tcwv_20121101_test.nc

@@ -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}"