Merge remote-tracking branch 'upstream/main' into irradiance_updates

Author: RDaxini

docs/examples/shading/plot_martinez_shade_loss.py

@@ -47,7 +47,7 @@
 import pandas as pd
 import numpy as np
 import matplotlib.pyplot as plt
-from matplotlib.dates import ConciseDateFormatter
+from matplotlib.dates import DateFormatter
 
 pitch = 4  # meters
 width = 1.5  # meters
@@ -235,10 +235,6 @@
     ax1.plot(times, shade_losses, label=k, linestyle=linestyle)
 ax1.legend(loc="upper center")
 ax1.grid()
-ax1.set_xlabel("Time")
-ax1.xaxis.set_major_formatter(
-    ConciseDateFormatter("%H:%M", tz="Europe/Madrid")
-)
 ax1.set_ylabel(r"$P_{out}$ losses")
 ax1.set_title("Per module")
 
@@ -248,9 +244,7 @@
 ax2.legend(loc="upper center")
 ax2.grid()
 ax2.set_xlabel("Time")
-ax2.xaxis.set_major_formatter(
-    ConciseDateFormatter("%H:%M", tz="Europe/Madrid")
-)
+ax2.xaxis.set_major_formatter(DateFormatter("%H:%M", tz="Europe/Madrid"))
 ax2.set_ylabel(r"$P_{out}$ losses")
 ax2.set_title("Per row")
 fig.tight_layout()

docs/sphinx/source/conf.py

@@ -73,7 +73,9 @@
 
 # Enable hover tooltips
 hoverxref_auto_ref = True
-hoverxref_roles = ["class", "meth", "func", "ref", "term"]
+hoverxref_roles = [
+    "class", "meth", "func", "ref", "term", "obj", "mod", "data"
+]
 hoverxref_role_types = dict.fromkeys(hoverxref_roles, "tooltip")
 hoverxref_domains = ["py"]
 hoverxref_intersphinx = list(intersphinx_mapping.keys())

docs/sphinx/source/contributing/how_to_contribute_new_code.rst

@@ -153,8 +153,7 @@ We strongly recommend using virtual environments for development.
 Virtual environments make it easier to switch between different
 versions of software. This `scientific-python.org guide
 <https://learn.scientific-python.org/development/tutorials/dev-environment/>`_
-is a good reference for virtual environments. The pvlib-python `installation
-user guide <https://pvlib-python.readthedocs.io/en/stable/user_guide/
-installation.html#set-up-a-virtual-environment>`_ also provides instructions on
+is a good reference for virtual environments. The pvlib-python
+:ref:`installation guide <setupenvironment>` also provides instructions on
 setting up a virtual environment. If this is your first pull request, don't
 worry about using a virtual environment.

docs/sphinx/source/contributing/style_guide.rst

@@ -70,6 +70,29 @@ the ``docs/readthedocs.org:pvlib-python`` link within the checks
 status box at the bottom of the pull request.
 
 
+.. _documentation-units:
+
+Parameter names and units
+-------------------------
+
+When specifying parameters and their units, please follow these guidelines:
+
+- Use the recommended parameter name and units listed in the :ref:`nomenclature` where applicable.
+- Enclose units in square brackets after the parameter description, e.g., ``Air temperature. [°C]``.
+- Use unicode superscripts symbols for exponents, e.g. ``m⁻²``.
+
+  - Numbers: ``⁰``, ``¹``, ``²``, ``³``, ``⁴``, ``⁵``, ``⁶``, ``⁷``, ``⁸``, ``⁹``
+  - Negative exponent: ``⁻``
+  - Degree symbol: ``°``
+
+- Link to a brief description in the :ref:`nomenclature` section if it exists, via the sphinx role ``:term:`glossary_term```. For example, to document ``dni`` use:
+
+  .. code-block:: rst
+
+      dni : numeric
+          Direct normal irradiance, see :term:`dni`. [Wm⁻²]
+
+
 .. _reference_style:
 
 References

docs/sphinx/source/reference/airmass_atmospheric.rst

@@ -11,6 +11,8 @@ Airmass and atmospheric models
    atmosphere.get_relative_airmass
    atmosphere.pres2alt
    atmosphere.alt2pres
+   atmosphere.tdew_from_rh
+   atmosphere.rh_from_tdew
    atmosphere.gueymard94_pw
    atmosphere.first_solar_spectral_correction
    atmosphere.bird_hulstrom80_aod_bb

docs/sphinx/source/reference/tracking.rst

@@ -3,9 +3,6 @@
 Tracking
 ========
 
-Functions
----------
-
 .. autosummary::
    :toctree: generated/
 

docs/sphinx/source/reference/transformer.rst

@@ -3,7 +3,7 @@
 Transformer losses
 ==================
 
-Methods to account for losses in transformers
+Functions to account for losses in transformers
 
 .. autosummary::
    :toctree: generated/

docs/sphinx/source/user_guide/nomenclature.rst

@@ -102,20 +102,21 @@ There is a convention on consistent variable names throughout the library:
         Photocurrent
 
     poa_diffuse
-        Total diffuse irradiation in plane. Sum of ground and sky diffuse.
+        Total diffuse irradiance in plane [Wm⁻²]. Sum of ground and sky diffuse
+        components of global irradiance.
 
     poa_direct
-        Direct/beam irradiation in plane
+        Direct/beam irradiance in plane [Wm⁻²].
 
     poa_global
-        Global irradiation in plane. sum of diffuse and beam projection.
+        Global irradiance in plane.  Sum of diffuse and beam projection [Wm⁻²].
 
     poa_ground_diffuse
-        In plane ground reflected irradiation
+        In plane ground reflected irradiance [Wm⁻²].
 
     poa_sky_diffuse
-        Diffuse irradiation in plane from scattered light in the atmosphere
-        (without ground reflected irradiation)
+        Diffuse irradiance in plane from scattered light in the atmosphere
+        (without ground reflected irradiance) [Wm⁻²].
 
     precipitable_water
         Total precipitable water contained in a column of unit cross section
@@ -168,10 +169,6 @@ There is a convention on consistent variable names throughout the library:
     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
 

docs/sphinx/source/whatsnew.rst

@@ -6,6 +6,7 @@ What's New
 
 These are new features and improvements of note in each release.
 
+.. include:: whatsnew/v0.11.3.rst
 .. include:: whatsnew/v0.11.2.rst
 .. include:: whatsnew/v0.11.1.rst
 .. include:: whatsnew/v0.11.0.rst

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

@@ -1,63 +1,73 @@
 .. _whatsnew_01120:
 
 
-v0.11.2 (Anticipated December, 2024)
-------------------------------------
+v0.11.2 (December 16, 2024)
+---------------------------
 
 Deprecations
 ~~~~~~~~~~~~
-
+* Deprecate terms ``dni_clearsky`` and ``clearsky_dni``, replace with ``dni_clear`` and ``ghi_clear``.
+  Affected functions are :py:func:`~pvlib.irradiance.dirindex`, :py:func:`~pvlib.irradiance.dni`
+  and :py:func:`~pvlib.irradiance.clearsky_index`.
 
 Enhancements
 ~~~~~~~~~~~~
+* Add :py:func:`~pvlib.atmosphere.rh_from_tdew` and :py:func:`~pvlib.atmosphere.tdew_from_rh`.
+  (:issue:`1744`, :pull:`2286`)
 * :py:func:`~pvlib.ivtools.sdm.fit_desoto` now allows input of initial
   parameter guesses. (:issue:`1014`, :pull:`2291`)
 
 Bug Fixes
 ~~~~~~~~~
 * :py:meth:`~pvlib.pvsystem.PVSystem.get_irradiance` accepts float inputs.
   (:issue:`1338`, :pull:`2227`)
-
-Bug fixes
-~~~~~~~~~
+* Handle DST transitions that happen at midnight in :py:func:`pvlib.solarposition.hour_angle`
+  (:issue:`2132` :pull:`2133`)
+* Change ``dni_extra`` to a required parameter in :py:func:`pvlib.irradiance.ghi_from_poa_driesse_2023`
+  (:issue:`2279` :pull:`2331`)
 * :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`)
+* Correct sign of temperature coefficient ``dEgdT`` in :py:func:`~pvlib.ivtools.sdm.fit_desoto_sandia`.
+  Results may differ slightly from previous versions. (:issue:`2311`, :pull:`2322`)
 
 Documentation
 ~~~~~~~~~~~~~
-* Edited docstrings for :py:func:`~pvlib.pvsystem.dc_ohms_from_percent` and
+* Edit 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 'freestanding' and 'insulated' `racking_model` options for cell
-  temperature calculation in :py:class:`~pvlib.pvsystem.PVSystem`
+* Add 'freestanding' and 'insulated' `racking_model` options for cell
+  temperature calculation in :py:class:`~pvlib.pvsystem.PVSystem`,
   :py:class:`~pvlib.pvsystem.SingleAxisTrackerMount`, and
   :py:class:`~pvlib.pvsystem.FixedMount` docstrings. Various formatting edits
   for clarity. (:issue:`1942`, :pull:`2232`)
-* Added a new citation style guide (:ref:`reference_style`) to the contributing
-  page. (:issue:`2202`, :pull:`2226`)
-* Updated :py:func:`~pvlib.irradiance.reindl` to include definitions of terms
+* Update :py:func:`~pvlib.irradiance.reindl` to include definitions of terms
   and a new "notes" section (:issue:`2183`, :pull:`2193`)
-* Clarified the error message in :py:func:`~pvlib.clearsky.detect_clearsky` when
+* Clarify the error message in :py:func:`~pvlib.clearsky.detect_clearsky` when
   windows contain fewer than three data points (:issue:`2005`, :pull:`2281`)
-* Added a new :ref:`nomenclature` page, in place of the Variables and Symbols
+* Clarify mounting cases for parameters for :py:func:`~pvlib.temperature.sapm_module`,
+  :py:func:`~pvlib.temperature.sapm_cell` and :py:func:`~pvlib.temperature.pvsyst_cell`.
+  (:issue:`1323`, :pull:`2293`)
+* Add an example to :py:func:`~pvlib.pvsystem.retrieve_sam` docstring to
+  demonstrate how to retrieve a database from the SAM repo. (:pull:`2313`)
+* Add a new citation style guide (:ref:`reference_style`) to the contributing
+  page. (:issue:`2202`, :pull:`2226`)
+* Explain how to write docstrings for new functions in :ref:`example-docstring`
+  (:discuss:`2081`, :pull:`2254`)
+* Add a section in the style guide for parameter naming and units best practices.
+  See :ref:`documentation-units`. (:issue:`2205`, :pull:`2248`)
+* Add 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`)
-* Added the following variables to the :ref:`nomenclature` page:
+* Add the following variables to the :ref:`nomenclature` page:
 
   - `spectra` and `spectra_components` (:issue:`2150`, :pull:`2264`)
 
 
 Testing
 ~~~~~~~
-
-
-Requirements
-~~~~~~~~~~~~
-
+* Update test files to track new PVGIS 5.3 data. (:pull:`2305`)
 
 Maintenance
 ~~~~~~~~~~~
-* Added a decorator to deprecate renamed keyword arguments in functions,
+* Add a decorator to deprecate renamed keyword arguments in functions,
   :py:func:`pvlib._deprecation.renamed_kwarg_warning`. (:pull:`2237`)
 
 
@@ -68,5 +78,22 @@ Contributors
 * Dave Pitts (:ghuser:`dgapitts`)
 * Kurt Rhee (:ghuser:`kurt-rhee`)
 * Mark Mikofski (:ghuser:`mikofski`)
-* matsuobasho (:ghuser:`matsuobasho`)
+* Roma Koulikov (:ghuser:`matsuobasho`)
 * Echedey Luis (:ghuser:`echedey-ls`)
+* Kevin Anderson (:ghuser:`kandersolar`)
+* Scott Nelson (:ghuser:`scttnlsn`)
+* Ioannis Sifnaios (:ghuser:`IoannisSifnaios`)
+* Adam R. Jensen (:ghuser:`AdamRJensen`)
+* Anton Driesse (:ghuser:`adriesse`)
+* Will Holmgren (:ghuser:`wholmgren`)
+* Umay Akkoseoglu (:ghuser:`uakkoseo`)
+* Mark Campanelli (:ghuser:`markcampanelli`)
+* :ghuser:`iblasi`
+* Hiromasa Ihara (:ghuser:`miettal`)
+* Yunho Kee (:ghuser:`yhkee0404`)
+* Hamilton Kibbe (:ghuser:`hamiltonkibbe`)
+* Felix Korbelius (:ghuser:`FelixKoTU`)
+* Michael Deceglie (:ghuser:`mdeceglie`)
+* Will Hobbs (:ghuser:`williamhobbs`)
+* Todd Karin (:ghuser:`toddkarin`)
+* Lucas Schneeberger (:ghuser:`lucasschn`)