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

Author: RDaxini

.github/workflows/asv_check.yml

@@ -26,19 +26,7 @@ jobs:
           python-version: '3.9'
 
       - name: Install asv
-        run: pip install asv==0.4.2
-
-      # asv 0.4.2 (and more recent versions as well) creates conda envs
-      # using the --force option, which was removed in conda 24.3.
-      # Since ubuntu-latest now comes with conda 24.3 pre-installed,
-      # using the system's conda will result in error.
-      # To prevent that, we install an older version.
-      # TODO: remove this when we eventually upgrade our asv version.
-      # https://github.com/airspeed-velocity/asv/issues/1396
-      - name: Install Conda
-        uses: conda-incubator/setup-miniconda@v3
-        with:
-          conda-version: 24.1.2
+        run: pip install asv==0.6.4
 
       - name: Run asv benchmarks
         run: |

.github/workflows/pytest-remote-data.yml

@@ -56,7 +56,7 @@ jobs:
     strategy:
       fail-fast: false  # don't cancel other matrix jobs when one fails
       matrix:
-        python-version: [3.9, "3.10", "3.11", "3.12"]
+        python-version: [3.9, "3.10", "3.11", "3.12", "3.13"]
         suffix: ['']  # the alternative to "-min"
         include:
           - python-version: 3.9
@@ -100,7 +100,7 @@ jobs:
           SOLARANYWHERE_API_KEY: ${{ secrets.SOLARANYWHERE_API_KEY }}
           BSRN_FTP_USERNAME: ${{ secrets.BSRN_FTP_USERNAME }}
           BSRN_FTP_PASSWORD: ${{ secrets.BSRN_FTP_PASSWORD }}
-        run: pytest pvlib/tests/iotools --cov=./ --cov-report=xml --remote-data
+        run: pytest tests/iotools --cov=./ --cov-report=xml --remote-data
 
       - name: Upload coverage to Codecov
         if: matrix.python-version == 3.9 && matrix.suffix == ''

.github/workflows/pytest.yml

@@ -12,7 +12,7 @@ jobs:
       fail-fast: false  # don't cancel other matrix jobs when one fails
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: [3.9, "3.10", "3.11", "3.12"]
+        python-version: [3.9, "3.10", "3.11", "3.12", "3.13"]
         environment-type: [conda, bare]
         suffix: ['']  # placeholder as an alternative to "-min"
         include:
@@ -79,7 +79,7 @@ jobs:
         shell: bash -l {0}  # necessary for conda env to be active
         run: |
           # ignore iotools; those tests are run in a separate workflow
-          pytest pvlib --cov=./ --cov-report=xml --ignore=pvlib/tests/iotools
+          pytest tests --cov=./ --cov-report=xml --ignore=tests/iotools
 
       - name: Upload coverage to Codecov
         if: matrix.python-version == 3.9 && matrix.suffix == '' && matrix.os == 'ubuntu-latest' && matrix.environment-type == 'conda'

.gitignore

@@ -81,9 +81,9 @@ coverage.xml
 
 
 # Datafiles
-*.csv
-# Ignore some csv 
-!pvlib/data/*.csv 
+# Do not exclude data directories
+!pvlib/data/**
+!tests/data/**
 
 # vi
 *.swp

ci/requirements-py3.12.yml

@@ -25,4 +25,4 @@ dependencies:
     - statsmodels
     - pip:
         - nrel-pysam>=2.0
-        # - solarfactors  # required shapely<2 isn't available for 3.12
+        - solarfactors

ci/requirements-py3.13.yml

@@ -0,0 +1,28 @@
+name: test_env
+channels:
+    - defaults
+    - conda-forge
+dependencies:
+    - coveralls
+    - cython
+    - ephem
+    - h5py
+    - numba
+    - numpy >= 1.17.3
+    - pandas >= 1.3.0
+    - pip
+    - pytest
+    - pytest-cov
+    - pytest-mock
+    - requests-mock
+    - pytest-timeout
+    - pytest-rerunfailures
+    - conda-forge::pytest-remotedata  # version in default channel is old
+    - python=3.13
+    - pytz
+    - requests
+    - scipy >= 1.6.0
+    - statsmodels
+    - pip:
+        - nrel-pysam>=2.0
+        - solarfactors

codecov.yml

@@ -14,14 +14,15 @@ flags:
   core:
     paths:
       - pvlib/
+      - tests/
       - '!pvlib/iotools/'
-      - '!pvlib/tests/iotools/'
+      - '!tests/iotools/'
     carryforward: false
 
   remote-data:
     paths:
       - pvlib/iotools/
-      - pvlib/tests/iotools
+      - tests/iotools
     carryforward: true  # if not run, use coverage from previous commit
 
 
@@ -47,15 +48,15 @@ coverage:
       tests-core:
         target: 95%
         paths:
-          - 'pvlib/tests/.*'
-          - '!pvlib/tests/iotools/.*'
+          - 'tests/.*'
+          - '!tests/iotools/.*'
         flags:
           - core
 
       tests-remote-data:
         target: 95%
         paths:
-          - 'pvlib/tests/iotools/.*'
+          - 'tests/iotools/.*'
         flags:
           - remote-data
 

docs/sphinx/source/_static/tooltipster_color_theming.css

@@ -0,0 +1,10 @@
+/* Overrides for sphinx-hoverxref since it does not support a native dark theme, see */
+/* https://github.com/readthedocs/sphinx-hoverxref/issues/231 */
+/* Inspired by https://github.com/pybamm-team/PyBaMM/pull/3083 */
+
+/* These will ensure that the tooltip inherits the pydata-sphinx-theme colours */
+
+.tooltipster-sidetip.tooltipster-shadow.tooltipster-shadow-custom .tooltipster-content {
+    background-color: var(--pst-color-background) !important;
+    color: var(--pst-color-text-base) !important;
+}

docs/sphinx/source/conf.py

@@ -66,7 +66,7 @@
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
     'numpy': ('https://numpy.org/doc/stable/', None),
-    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/', None),
     'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None),
     'matplotlib': ('https://matplotlib.org/stable', None),
 }
@@ -282,6 +282,8 @@ def setup(app):
     app.add_css_file("reference_format.css")
     # Add a warning banner at the top of the page if viewing the "latest" docs
     app.add_js_file("version-alert.js")
+    # Match the color theme of tooltips to PyData Sphinx Theme light/dark mode
+    app.add_css_file("tooltipster_color_theming.css")
 
 # -- Options for LaTeX output ---------------------------------------------
 

docs/sphinx/source/contributing/testing.rst

@@ -11,7 +11,7 @@ Overview
 Developers **must** include comprehensive tests for any additions or
 modifications to pvlib. New unit test code should be placed in the
 corresponding test module in the
-`pvlib/tests <https://github.com/pvlib/pvlib-python/tree/main/pvlib/tests>`_
+`tests <https://github.com/pvlib/pvlib-python/tree/main/tests>`_
 directory.
 
 A pull request will automatically run the tests for you on a variety of
@@ -20,26 +20,26 @@ typically more efficient to run and debug the tests in your own local
 environment.
 
 To run the tests locally, install the ``test`` dependencies specified in the
-`setup.py <https://github.com/pvlib/pvlib-python/blob/main/setup.py>`_
+`pyproject.toml <https://github.com/pvlib/pvlib-python/blob/main/pyproject.toml>`_
 file. See :ref:`installation` instructions for more information.
 
 pvlib's unit tests can easily be run by executing ``pytest`` on the
-pvlib directory::
+tests directory::
 
-    pytest pvlib
+    pytest tests
 
 or, for a single module::
 
-    pytest pvlib/tests/test_clearsky.py
+    pytest tests/test_clearsky.py
 
 or, for a single test::
 
-    pytest pvlib/tests/test_clearsky.py::test_ineichen_nans
+    pytest tests/test_clearsky.py::test_ineichen_nans
 
 We suggest using pytest's ``--pdb`` flag to debug test failures rather
 than using ``print`` or ``logging`` calls. For example::
 
-    pytest pvlib --pdb
+    pytest tests --pdb
 
 will drop you into the
 `pdb debugger <https://docs.python.org/3/library/pdb.html>`_ at the
@@ -50,7 +50,7 @@ to the test suite (with rare exceptions).
 To include all network-dependent tests, include the ``--remote-data`` flag to
 your ``pytest`` call::
 
-    pytest pvlib --remote-data
+    pytest tests --remote-data
 
 And consider adding ``@pytest.mark.remote_data`` to any network dependent test
 you submit for a PR.

docs/sphinx/source/reference/airmass_atmospheric.rst

@@ -14,7 +14,6 @@ Airmass and atmospheric models
    atmosphere.tdew_from_rh
    atmosphere.rh_from_tdew
    atmosphere.gueymard94_pw
-   atmosphere.first_solar_spectral_correction
    atmosphere.bird_hulstrom80_aod_bb
    atmosphere.kasten96_lt
    atmosphere.angstrom_aod_at_lambda

docs/sphinx/source/reference/effects_on_pv_system_output/spectrum.rst

@@ -8,7 +8,6 @@ Spectrum
 
    spectrum.spectrl2
    spectrum.get_example_spectral_response
-   spectrum.get_am15g
    spectrum.get_reference_spectra
    spectrum.calc_spectral_mismatch_field
    spectrum.spectral_factor_caballero

docs/sphinx/source/reference/iotools.rst

@@ -26,6 +26,12 @@ of sources and file formats relevant to solar energy modeling.
    iotools.read_crn
    iotools.read_solrad
    iotools.get_solrad
+   iotools.get_nsrdb_psm4_aggregated
+   iotools.get_nsrdb_psm4_tmy
+   iotools.get_nsrdb_psm4_conus
+   iotools.get_nsrdb_psm4_full_disc
+   iotools.read_nsrdb_psm4
+   iotools.parse_nsrdb_psm4
    iotools.get_psm3
    iotools.read_psm3
    iotools.parse_psm3

docs/sphinx/source/reference/modelchain.rst

@@ -112,7 +112,6 @@ on the information in the associated :py:class:`~pvsystem.PVSystem` object.
    modelchain.ModelChain.infer_dc_model
    modelchain.ModelChain.infer_ac_model
    modelchain.ModelChain.infer_aoi_model
-   modelchain.ModelChain.infer_spectral_model
    modelchain.ModelChain.infer_temperature_model
    modelchain.ModelChain.infer_losses_model
 

docs/sphinx/source/reference/pv_modeling/parameters.rst

@@ -12,6 +12,7 @@ Functions for fitting single diode models
     ivtools.sdm.fit_cec_sam
     ivtools.sdm.fit_desoto
     ivtools.sdm.fit_pvsyst_sandia
+    ivtools.sdm.fit_pvsyst_iec61853_sandia_2025
     ivtools.sdm.fit_desoto_sandia
 
 Functions for fitting the single diode equation

docs/sphinx/source/reference/pv_modeling/system_models.rst

@@ -12,7 +12,6 @@ Sandia array performance model (SAPM)
 
    pvsystem.sapm
    pvsystem.sapm_effective_irradiance
-   pvsystem.sapm_spectral_loss
    spectrum.spectral_factor_sapm
    inverter.sandia
    temperature.sapm_cell

docs/sphinx/source/user_guide/faq.rst renamed to docs/sphinx/source/user_guide/extras/faq.rst

@@ -71,6 +71,9 @@ There is a convention on consistent variable names throughout the library:
     ghi
         Global horizontal irradiance
 
+    ghi_clear
+        Clearsky global horizontal irradiance [Wm⁻²]
+
     ghi_extra
         Horizontal irradiance at top of atmosphere (extraterrestrial)
 

docs/sphinx/source/user_guide/nomenclature.rst renamed to docs/sphinx/source/user_guide/extras/nomenclature.rst

@@ -133,7 +133,7 @@ Follow these steps to obtain the library using git/GitHub:
    This button is circled in the image below. Remember the system path that
    you clone the library to.
 
-.. image:: ../_images/clonebutton.png
+.. image:: ../../_images/clonebutton.png
 
 Please see GitHub's
 `Forking Projects <https://guides.github.com/activities/forking/>`_,

docs/sphinx/source/user_guide/installation.rst renamed to docs/sphinx/source/user_guide/getting_started/installation.rst

@@ -87,7 +87,7 @@ to accomplish our system modeling goal:
             longitude=longitude,
             altitude=altitude,
             temperature=weather["temp_air"],
-            pressure=pvlib.atmosphere.alt2pres(altitude),
+            pressure=weather["pressure"],
         )
         dni_extra = pvlib.irradiance.get_extra_radiation(weather.index)
         airmass = pvlib.atmosphere.get_relative_airmass(solpos['apparent_zenith'])

docs/sphinx/source/user_guide/introtutorial.rst renamed to docs/sphinx/source/user_guide/getting_started/introtutorial.rst

@@ -1,20 +1,34 @@
+.. _user_guide:
+
 ==========
 User Guide
 ==========
 
+This user guide is an overview and explains some of the key features of pvlib.
+
+.. toctree::
+   :caption: Getting started
+   :maxdepth: 2
+
+   getting_started/package_overview
+   getting_started/installation
+   getting_started/introtutorial
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Modeling topics
+
+   modeling_topics/pvsystem
+   modeling_topics/modelchain
+   modeling_topics/timetimezones
+   modeling_topics/bifacial
+   modeling_topics/clearsky
+   modeling_topics/weather_data
+   modeling_topics/singlediode
 
 .. toctree::
    :maxdepth: 2
+   :caption: Extras
 
-   package_overview
-   installation
-   introtutorial
-   pvsystem
-   modelchain
-   timetimezones
-   clearsky
-   bifacial
-   weather_data
-   singlediode
-   nomenclature
-   faq
+   extras/nomenclature
+   extras/faq

docs/sphinx/source/user_guide/package_overview.rst renamed to docs/sphinx/source/user_guide/getting_started/package_overview.rst

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

docs/sphinx/source/user_guide/index.rst

@@ -53,9 +53,9 @@ Deprecations
   deprecated. Use :py:func:`pvlib.pvsystem.v_from_i` and
   :py:func:`pvlib.pvsystem.i_from_v` instead. (:issue:`1626`, :pull:`1743`)
 * Functions for calculating spectral modifiers have been moved to :py:mod:`pvlib.spectrum`:
-  :py:func:`pvlib.atmosphere.first_solar_spectral_correction` is deprecated and
+  :py:func:`!pvlib.atmosphere.first_solar_spectral_correction` is deprecated and
   replaced by :py:func:`~pvlib.spectrum.spectral_factor_firstsolar`, and
-  :py:func:`pvlib.pvsystem.sapm_spectral_loss` is deprecated and replaced by
+  :py:func:`!pvlib.pvsystem.sapm_spectral_loss` is deprecated and replaced by
   :py:func:`~pvlib.spectrum.spectral_factor_sapm`. (:pull:`1628`)
 * Removed the ``get_ecmwf_macc`` and ``read_ecmwf_macc`` iotools functions as the
   MACC dataset has been `removed by ECMWF <https://confluence.ecmwf.int/display/DAC/Decommissioning+of+ECMWF+Public+Datasets+Service>`_

docs/sphinx/source/user_guide/bifacial.rst renamed to docs/sphinx/source/user_guide/modeling_topics/bifacial.rst

@@ -28,7 +28,7 @@ Deprecations
 ~~~~~~~~~~~~
 * The ``pvlib.irradiance.SURFACE_ALBEDOS`` dictionary has been moved to
   :py:const:`pvlib.albedo.SURFACE_ALBEDOS`. (:pull:`2095`)
-* Function :py:func:`pvlib.spectrum.get_am15g` has been deprecated in favor
+* Function :py:func:`!pvlib.spectrum.get_am15g` has been deprecated in favor
   of the new function :py:func:`pvlib.spectrum.get_reference_spectra`. Use
   ``pvlib.spectrum.get_reference_spectra(standard="ASTM G173-03")["global"]``
   instead. (:pull:`2039`)