From b73efcd630ee7b0e3b9a827cb9e46c0de2b19fe9 Mon Sep 17 00:00:00 2001 From: WhatIsAPM1989 Date: Wed, 28 Oct 2026 22:30:52 +0000 Subject: [PATCH 1/3] DOC: add missing reference callouts and enable footnote warnings Connect existing references to the descriptions of the corresponding models, correct spectral model citations, and remove the global suppression of unreferenced-footnote warnings. No calculation code changes. Assisted-by: Codex (GPT-6) --- .../adr-pvarray/plot_fit_to_matrix.py | 2 ++ .../adr-pvarray/plot_simulate_fast.py | 2 ++ .../adr-pvarray/plot_simulate_system.py | 2 ++ .../reflections/plot_convert_iam_models.py | 5 ++-- docs/sphinx/source/conf.py | 4 --- .../user_guide/modeling_topics/spectrum.rst | 11 ++++---- docs/sphinx/source/whatsnew/v0.16.2.rst | 4 +++ pvlib/atmosphere.py | 22 +++++++++------ pvlib/bifacial/ants2d.py | 6 +++- pvlib/bifacial/infinite_sheds.py | 6 ++-- pvlib/bifacial/utils.py | 16 +++++++++++ pvlib/clearsky.py | 10 ++++--- pvlib/iam.py | 16 +++++++---- pvlib/iotools/acis.py | 4 ++- pvlib/iotools/pvgis.py | 2 +- pvlib/irradiance.py | 22 +++++++++------ .../ivtools/sdm/_fit_desoto_pvsyst_sandia.py | 9 ++++++ pvlib/ivtools/utils.py | 4 +-- pvlib/location.py | 3 +- pvlib/pvarray.py | 2 +- pvlib/pvsystem.py | 17 ++++++----- pvlib/scaling.py | 10 ++++--- pvlib/singlediode.py | 2 +- pvlib/soiling.py | 2 +- pvlib/solarposition.py | 28 +++++++++++++------ pvlib/spectrum/response.py | 4 +-- pvlib/temperature.py | 4 ++- pvlib/tracking.py | 2 +- 28 files changed, 148 insertions(+), 73 deletions(-) diff --git a/docs/examples/adr-pvarray/plot_fit_to_matrix.py b/docs/examples/adr-pvarray/plot_fit_to_matrix.py index 9fec2d5e3c..1d194b4c05 100644 --- a/docs/examples/adr-pvarray/plot_fit_to_matrix.py +++ b/docs/examples/adr-pvarray/plot_fit_to_matrix.py @@ -12,6 +12,8 @@ parameters can be determined with just a few lines of code using functions in pvlib-python. +The ADR efficiency model is described in [1]_ and [2]_. + Author: Anton Driesse """ diff --git a/docs/examples/adr-pvarray/plot_simulate_fast.py b/docs/examples/adr-pvarray/plot_simulate_fast.py index 380744f626..1dd27f9613 100644 --- a/docs/examples/adr-pvarray/plot_simulate_fast.py +++ b/docs/examples/adr-pvarray/plot_simulate_fast.py @@ -13,6 +13,8 @@ To compare simulation speed, we run them using ``timeit``. +The ADR efficiency model is described in [1]_ and [2]_. + Author: Anton Driesse """ diff --git a/docs/examples/adr-pvarray/plot_simulate_system.py b/docs/examples/adr-pvarray/plot_simulate_system.py index b0abede934..5bde4c5adb 100644 --- a/docs/examples/adr-pvarray/plot_simulate_system.py +++ b/docs/examples/adr-pvarray/plot_simulate_system.py @@ -9,6 +9,8 @@ Efficiency is independent of system size, so adjusting the system capacity is just a matter of setting the desired value, e.g. P_STC = 5000. +The ADR efficiency model is described in [1]_ and [2]_. + Author: Anton Driesse """ diff --git a/docs/examples/reflections/plot_convert_iam_models.py b/docs/examples/reflections/plot_convert_iam_models.py index 6b0ec78ab3..cc5db4c049 100644 --- a/docs/examples/reflections/plot_convert_iam_models.py +++ b/docs/examples/reflections/plot_convert_iam_models.py @@ -17,8 +17,9 @@ # # Here, we show how to use # :py:func:`~pvlib.iam.convert` to estimate parameters for a desired target -# IAM model from a source IAM model. Model conversion uses a weight -# function that can assign more influence to some AOI values than others. +# IAM model from a source IAM model using the method in [1]_. +# Model conversion uses a weight function that can assign more influence to +# some AOI values than others. # We illustrate how to provide a custom weight function to # :py:func:`~pvlib.iam.convert`. diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 90c2f0a3a5..6da08efd22 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -380,10 +380,6 @@ def setup(app): ipython_warning_is_error = False -# suppress "WARNING: Footnote [1] is not referenced." messages -# https://github.com/pvlib/pvlib-python/issues/837 -suppress_warnings = ['ref.footnote'] - os_re_sep = re.escape(os.path.sep) # settings for sphinx-gallery sphinx_gallery_conf = { diff --git a/docs/sphinx/source/user_guide/modeling_topics/spectrum.rst b/docs/sphinx/source/user_guide/modeling_topics/spectrum.rst index 1ff5fa1df4..ceb7208b94 100644 --- a/docs/sphinx/source/user_guide/modeling_topics/spectrum.rst +++ b/docs/sphinx/source/user_guide/modeling_topics/spectrum.rst @@ -23,6 +23,7 @@ given spectrum to its response under a reference spectrum, typically the AM1.5G spectrum. It represents the relative difference in the performance of a PV device under a spectrum different from the reference spectrum, and can be used to correct the measured power output of a PV system for spectral effects. +The spectral mismatch correction for device measurements is standardized in [9]_. pvlib-python contains several models to estimate the spectral mismatch factor using atmospheric variables such as air mass, or calculate it exactly using @@ -49,16 +50,16 @@ Reference [2]_. +=====================================================+=============================+=========+=========+======+======+======+============+===========+ | :py:func:`Caballero ` | :term:`airmass_absolute`, | | | | | | | | | +-----------------------------+ | | | | | | | -| |:term:`precipitable_water`, | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | [2]_ | +| |:term:`precipitable_water`, | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | [3]_ | | +-----------------------------+ | | | | | | | | | :term:`aod` | | | | | | | | +-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+ | :py:func:`First Solar ` | :term:`airmass_absolute`, | | | | | | | | -| +-----------------------------+ | ✓ | ✓ | | | | [3]_ | +| +-----------------------------+ | ✓ | ✓ | | | | [7]_ | | | :term:`precipitable_water` | | | | | | | | +-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+ | :py:func:`JRC ` | :term:`airmass_relative`, | | | | | | | | -| +-----------------------------+ | ✓ | ✓ | | | + [4]_ | +| +-----------------------------+ | ✓ | ✓ | | | + [8]_ | | | :term:`clearsky_index` | | | | | | | | +-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+ | :py:func:`Polo ` | :term:`precipitable_water`, | | | | | | | | @@ -72,10 +73,10 @@ Reference [2]_. | | :term:`pressure` | | | | | | | | +-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+ | :py:func:`PVSPEC ` | :term:`airmass_absolute`, | | | | | | | | -| +-----------------------------+ ✓ | ✓ | ✓ | ✓ | ✓ | | [6]_ | +| +-----------------------------+ ✓ | ✓ | ✓ | ✓ | ✓ | | [4]_ | | | clearsky_index | | | | | | | | +-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+ -| :py:func:`SAPM ` | :term:`airmass_absolute` | | | | | | | [7]_ | +| :py:func:`SAPM ` | :term:`airmass_absolute` | | | | | | | [6]_ | +-----------------------------------------------------+-----------------------------+---------+---------+------+------+------+------------+-----------+ diff --git a/docs/sphinx/source/whatsnew/v0.16.2.rst b/docs/sphinx/source/whatsnew/v0.16.2.rst index 67e908862a..ef92ed2a7c 100644 --- a/docs/sphinx/source/whatsnew/v0.16.2.rst +++ b/docs/sphinx/source/whatsnew/v0.16.2.rst @@ -31,6 +31,9 @@ Enhancements Documentation ~~~~~~~~~~~~~ +* Add missing reference callouts in docstrings and documentation, correct + spectral model citations, and enable Sphinx warnings for unreferenced + footnotes. (:issue:`837`) * Add :py:func:`pvlib.spa.transit_sunrise_sunset` to the API reference. (:issue:`2255`, :pull:`2873`) * Clarified in :py:func:`pvlib.tracking.singleaxis` that the tracker @@ -78,3 +81,4 @@ Contributors * :ghuser:`bfs2021` * :ghuser:`xiajiahang` * Jakub Krasuski (:ghuser:`Blizzeq`) +* :ghuser:`WhatIsAPM1989` diff --git a/pvlib/atmosphere.py b/pvlib/atmosphere.py index 95401ff3ba..6cf4f27e7f 100644 --- a/pvlib/atmosphere.py +++ b/pvlib/atmosphere.py @@ -29,7 +29,7 @@ def pres2alt(pressure): Notes ------ - The following assumptions are made + The following assumptions are made in the derivation in [1]_ ============================ ================ Parameter Value @@ -69,7 +69,7 @@ def alt2pres(altitude): Notes ------ - The following assumptions are made + The following assumptions are made in the derivation in [1]_ ============================ ================ Parameter Value @@ -98,7 +98,7 @@ def get_absolute_airmass(airmass_relative, pressure=101325.): Determine absolute (pressure-adjusted) airmass from relative airmass and pressure. - The calculation for absolute airmass (:math:`AM_a`) is + The calculation for absolute airmass (:math:`AM_a`) is given by [1]_ .. math:: AM_a = AM_r \frac{P}{101325} @@ -267,7 +267,8 @@ def gueymard94_pw(temp_air, relative_humidity): accuracy of this method is approximately 20% for moderate PW (1-3 cm) and less accurate otherwise. - The model was developed by expanding Eq. 1 in [2]_: + The model is described in [1]_ and was developed by expanding Eq. 1 + in [2]_: .. math:: @@ -439,7 +440,7 @@ def bird_hulstrom80_aod_bb(aod380, aod500): Approximate broadband aerosol optical depth. Bird and Hulstrom developed a correlation for broadband aerosol optical - depth (AOD) using two wavelengths, 380 nm and 500 nm. + depth (AOD) using two wavelengths, 380 nm and 500 nm [1]_ [2]_. Parameters ---------- @@ -473,10 +474,14 @@ def bird_hulstrom80_aod_bb(aod380, aod500): def kasten96_lt(airmass_absolute, precipitable_water, aod_bb): """ - Calculate Linke turbidity using Kasten pyrheliometric formula. + Calculate Linke turbidity using the Kasten pyrheliometric formula. + + The Linke turbidity factor [1]_ is calculated using the Kasten + formulations [2]_ [3]_ and the conversion in [5]_. An airmass-independent + formulation is discussed in [6]_. Note that broadband aerosol optical depth (AOD) can be approximated by AOD - measured at 700 nm according to Molineaux [4] . Bird and Hulstrom offer an + measured at 700 nm according to Molineaux [4]_. Bird and Hulstrom offer an alternate approximation using AOD measured at 380 nm and 500 nm. Based on original implementation by Armel Oumbe. @@ -561,7 +566,8 @@ def kasten96_lt(airmass_absolute, precipitable_water, aod_bb): def angstrom_aod_at_lambda(aod0, lambda0, alpha=1.14, lambda1=700.0): r""" - Get AOD at specified wavelength using Angstrom turbidity model. + Get AOD at specified wavelength using the Angstrom turbidity model + [1]_ [2]_. Parameters ---------- diff --git a/pvlib/bifacial/ants2d.py b/pvlib/bifacial/ants2d.py index 1aac0651d3..12b98b9f5d 100644 --- a/pvlib/bifacial/ants2d.py +++ b/pvlib/bifacial/ants2d.py @@ -51,6 +51,10 @@ def _shaded_fraction(tracker_rotation, phi, gcr, x0=0, x1=1): Fraction of row slant height from the bottom that is shaded from direct irradiance. + Notes + ----- + The shading geometry is described in [1]_. + References ---------- .. [1] Kevin Anderson and Mark Mikofski, "Slope-Aware Backtracking for @@ -93,7 +97,7 @@ def _ants2d_singleside(tracker_rotation, cos_aoi, phi, gcr, height, pitch, max_rows): r""" Calculate plane-of-array irradiance components on one side of a row - of modules. + of modules using the view factor model in [1]_. Parameters ---------- diff --git a/pvlib/bifacial/infinite_sheds.py b/pvlib/bifacial/infinite_sheds.py index 48f455f38d..7a445c5090 100644 --- a/pvlib/bifacial/infinite_sheds.py +++ b/pvlib/bifacial/infinite_sheds.py @@ -112,7 +112,7 @@ def _shaded_fraction(solar_zenith, solar_azimuth, surface_tilt, Calculate fraction (from the bottom) of row slant height that is shaded from direct irradiance by the row in front toward the sun. - See [1], Eq. 14 and also [2], Eq. 32. + See [1]_, Eq. 14 and also [2]_, Eq. 32. .. math:: F_x = \\max \\left( 0, \\min \\left(\\frac{\\text{GCR} \\cos \\theta @@ -173,7 +173,7 @@ def get_irradiance_poa(surface_tilt, surface_azimuth, solar_zenith, r""" Calculate plane-of-array (POA) irradiance on one side of a row of modules. - The infinite sheds model [1] assumes the PV system comprises parallel, + The infinite sheds model [1]_ assumes the PV system comprises parallel, evenly spaced rows on a level, horizontal surface. Rows can be on fixed racking or single axis trackers. The model calculates irradiance at a location far from the ends of any rows, in effect, assuming that the @@ -381,7 +381,7 @@ def get_irradiance(surface_tilt, surface_azimuth, solar_zenith, solar_azimuth, """ Get front and rear irradiance using the infinite sheds model. - The infinite sheds model [1] assumes the PV system comprises parallel, + The infinite sheds model [1]_ assumes the PV system comprises parallel, evenly spaced rows on a level, horizontal surface. Rows can be on fixed racking or single axis trackers. The model calculates irradiance at a location far from the ends of any rows, in effect, assuming that the diff --git a/pvlib/bifacial/utils.py b/pvlib/bifacial/utils.py index df10a8e113..a6b06439b3 100644 --- a/pvlib/bifacial/utils.py +++ b/pvlib/bifacial/utils.py @@ -85,6 +85,10 @@ def _unshaded_ground_fraction(tracker_rotation, phi, gcr, height=None, Fraction of distance betwen rows (pitch) with direct irradiance (unshaded). [unitless] + Notes + ----- + The geometry and derivation are described in [1]_. + References ---------- .. [1] K. S. Anderson, A. R. Jensen, and C. W. Hansen, "A Bifacial View @@ -291,6 +295,10 @@ def vf_ground_sky_2d_integ(tracker_rotation, gcr, height, pitch, max_rows=10, Integration of view factor over the length between adjacent, interior rows. Shape matches that of ``tracker_rotation``. [unitless] + Notes + ----- + The geometry and derivation are described in [1]_. + References ---------- .. [1] K. S. Anderson, A. R. Jensen, and C. W. Hansen, "A Bifacial View @@ -454,6 +462,10 @@ def vf_row_sky_2d_integ(surface_tilt, gcr, x0=0, x1=1): Average fraction of the sky dome visible from points in the segment from x0 to x1. [unitless] + Notes + ----- + The geometry and derivation are described in [1]_. + References ---------- .. [1] K. S. Anderson, A. R. Jensen, and C. W. Hansen, "A Bifacial View @@ -567,6 +579,10 @@ def vf_row_ground_2d_integ(surface_tilt, gcr, height=None, pitch=None, Integrated view factor to the visible ground on the interval (x0, x1). [unitless] + Notes + ----- + The geometry and derivation are described in [1]_. + References ---------- .. [1] K. S. Anderson, A. R. Jensen, and C. W. Hansen, "A Bifacial View diff --git a/pvlib/clearsky.py b/pvlib/clearsky.py index 3af86fa771..0666fcec4a 100644 --- a/pvlib/clearsky.py +++ b/pvlib/clearsky.py @@ -283,10 +283,10 @@ def haurwitz(apparent_zenith): Determine clear sky GHI using the Haurwitz model. Implements the Haurwitz clear sky model for global horizontal - irradiance (GHI) as presented in [1, 2]. A report on clear + irradiance (GHI) as presented in [1]_ [2]_. A report on clear sky models found the Haurwitz model to have the best performance in terms of average monthly error among models which require only - zenith angle [3]. + zenith angle [3]_. Parameters ---------- @@ -638,7 +638,7 @@ def _clear_sample_index(clear_windows, samples_per_window, align, H): def _clearsky_get_threshold(sample_interval): """ Returns threshold values for kwargs in detect_clearsky. See - Table 1 in [1]. + Table 1 in [1]_. References ---------- @@ -930,7 +930,9 @@ def bird(zenith, airmass_relative, aod380, aod500, precipitable_water, """ Bird Simple Clear Sky Broadband Solar Radiation Model - Based on NLR Excel implementation by Daryl R. Myers [1, 2]. + Based on the NLR Excel implementation [3]_ by Daryl R. Myers [2]_ + of the Bird and Hulstrom model [1]_ [4]_. Corrections to the model + are documented in the error reports [5]_. Bird and Hulstrom define the zenith as the "angle between a line to the sun and the local zenith". There is no distinction in the paper diff --git a/pvlib/iam.py b/pvlib/iam.py index cc9c8daae8..2e41bdba0b 100644 --- a/pvlib/iam.py +++ b/pvlib/iam.py @@ -103,7 +103,7 @@ def physical(aoi, n=1.526, K=4.0, L=0.002, *, n_ar=None): ``iam.physical`` calculates the incidence angle modifier as described in [1]_, Section 3, with additional support of an anti-reflective coating. The calculation is based on a physical model of reflections, absorption, - and transmission through a transparent cover. + and transmission through a transparent cover, as described in [2]_. Parameters ---------- @@ -117,7 +117,7 @@ def physical(aoi, n=1.526, K=4.0, L=0.002, *, n_ar=None): K : numeric, default 4.0 The glazing extinction coefficient in units of 1/meters. - Reference [1] indicates that a value of 4 is reasonable for + Reference [1]_ indicates that a value of 4 is reasonable for "water white" glass. L : numeric, default 0.002 @@ -319,8 +319,9 @@ def martin_ruiz_diffuse(surface_tilt, a_r=0.16, c1=0.4244, c2=None): Determine the incidence angle modifiers (IAM) for sky diffuse and ground-reflected irradiance using the Martin and Ruiz incident angle model. - As described in [1]_, the IAMs result from integrals that assume the - incoming sky diffuse and ground-reflected irradiance are isotropic. + As described in [1]_ and corrected in [2]_, the IAMs result from integrals + that assume the incoming sky diffuse and ground-reflected irradiance + are isotropic. Parameters ---------- @@ -524,6 +525,9 @@ def sapm(aoi, module, upper=None): r""" Determine the incidence angle modifier (IAM) using the SAPM model. + Procedures for determining the model coefficients are described in [2]_, + with angle of incidence measurement techniques discussed in [3]_. + Parameters ---------- aoi : numeric @@ -1127,7 +1131,7 @@ def _process_return(target_name, optimize_result): def convert(source_name, source_params, target_name, weight=_sin_weight, fix_n=True, xtol=None): """ - Convert a source IAM model to a target IAM model. + Convert a source IAM model to a target IAM model using the method in [1]_. Parameters ---------- @@ -1246,7 +1250,7 @@ def residual_function(target_param): def fit(measured_aoi, measured_iam, model_name, weight=_sin_weight, xtol=None): """ - Find model parameters that best fit the data. + Find model parameters that best fit the data using the method in [1]_. Parameters ---------- diff --git a/pvlib/iotools/acis.py b/pvlib/iotools/acis.py index 634af07933..6603d08dc7 100644 --- a/pvlib/iotools/acis.py +++ b/pvlib/iotools/acis.py @@ -425,7 +425,9 @@ def get_acis_available_stations(latitude_range, longitude_range, **kwargs): """ List weather stations in a given area available from the - Applied Climate Information System (ACIS). + Applied Climate Information System (ACIS) [1]_. + + Station metadata fields are described in [2]_. The ``sids`` returned by this function can be used with :py:func:`get_acis_station_data` to retrieve weather measurements diff --git a/pvlib/iotools/pvgis.py b/pvlib/iotools/pvgis.py index 74b044abad..5f5a15cefb 100644 --- a/pvlib/iotools/pvgis.py +++ b/pvlib/iotools/pvgis.py @@ -719,7 +719,7 @@ def read_pvgis_tmy(filename, pvgis_format=None, map_variables=True): def get_pvgis_horizon(latitude, longitude, url=URL, **kwargs): - """Get horizon data from PVGIS. + """Get horizon data from PVGIS [1]_. Parameters ---------- diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index 5436ed235c..b6385cad1f 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -581,7 +581,7 @@ def get_ground_diffuse(surface_tilt, ghi, albedo=.25, surface_type=None): r''' Estimate diffuse irradiance on a tilted surface from ground reflections. - Ground diffuse irradiance is calculated as + Ground diffuse irradiance is calculated as in [1]_ .. math:: @@ -653,6 +653,8 @@ def isotropic(surface_tilt, dhi, return_components=False): Determine diffuse irradiance from the sky on a tilted surface using the isotropic sky model. + The isotropic sky diffuse irradiance is calculated as in [1]_: + .. math:: I_{d} = DHI \frac{1 + \cos\beta}{2} @@ -1169,7 +1171,9 @@ def perez(surface_tilt, surface_azimuth, dhi, dni, dni_extra, horizontal irradiance, direct normal irradiance, extraterrestrial irradiance, sun zenith angle, sun azimuth angle, and relative (not pressure-corrected) airmass. Optionally a selector may be used to - use any of Perez's model coefficient sets. + use any of Perez's model coefficient sets [2]_ [3]_ [4]_. + + An empirical validation of the model is provided in [1]_. Warning ------- @@ -2062,9 +2066,9 @@ def dirint(ghi, solar_zenith, times, pressure=101325., use_delta_kt_prime=True, Determine DNI from GHI using the DIRINT modification of the DISC model. - Implements the modified DISC model known as "DIRINT" introduced in - [1]_. DIRINT predicts direct normal irradiance (DNI) from measured - global horizontal irradiance (GHI). DIRINT improves upon the DISC + Implements the modification of the DISC model [2]_ known as "DIRINT", + introduced in [1]_. DIRINT predicts direct normal irradiance (DNI) from + measured global horizontal irradiance (GHI). DIRINT improves upon the DISC model by using time-series GHI data and dew point temperature information. The effectiveness of the DIRINT model improves with each piece of information provided. @@ -3183,7 +3187,7 @@ def campbell_norman(zenith, transmittance, pressure=101325.0, dni_extra=1367.0): ''' Determine DNI, DHI, GHI from extraterrestrial flux, transmittance, - and atmospheric pressure. + and atmospheric pressure using the model in [1]_. Parameters ---------- @@ -3235,7 +3239,9 @@ def campbell_norman(zenith, transmittance, pressure=101325.0, def _get_perez_coefficients(perezmodel): ''' - Find coefficients for the Perez model + Find coefficients for the Perez models in [2]_ [3]_ [4]_. + + An empirical validation of the model is provided in [1]_. Parameters ---------- @@ -3884,7 +3890,7 @@ def complete_irradiance(solar_zenith, def louche(ghi, solar_zenith, datetime_or_doy, max_zenith=90): """ - Determine DNI and DHI from GHI using the Louche model. + Determine DNI and DHI from GHI using the Louche model [1]_. Parameters ---------- diff --git a/pvlib/ivtools/sdm/_fit_desoto_pvsyst_sandia.py b/pvlib/ivtools/sdm/_fit_desoto_pvsyst_sandia.py index b0b7c6fa3e..cc26212a58 100644 --- a/pvlib/ivtools/sdm/_fit_desoto_pvsyst_sandia.py +++ b/pvlib/ivtools/sdm/_fit_desoto_pvsyst_sandia.py @@ -238,6 +238,9 @@ def _update_io(voc, iph, io, rs, rsh, nnsvth): """ Adjusts Io to match Voc using other parameter values. + The method follows the MATLAB implementation [1]_ and the + descriptions in [2]_ [3]_. + Helper function for fit_pvsyst_sandia, fit_desoto_sandia Description @@ -429,6 +432,9 @@ def _update_rsh_fixed_pt(vmp, imp, iph, io, rs, rsh, nnsvth): """ Adjust Rsh to match Vmp using other parameter values + The method follows the MATLAB implementation [1]_ and the + descriptions in [2]_. + Helper function for fit_pvsyst_sandia, fit_desoto_sandia Description @@ -478,6 +484,9 @@ def _calc_theta_phi_exact(vmp, imp, iph, io, rs, rsh, nnsvth): _calc_theta_phi_exact computes Lambert W values appearing in the analytic solutions to the single diode equation for the max power point. + The method follows the MATLAB implementation [1]_ and the + descriptions in [2]_ [3]_. + Helper function for fit_pvsyst_sandia Parameters diff --git a/pvlib/ivtools/utils.py b/pvlib/ivtools/utils.py index 0d0ef1382a..d5f1989c8d 100644 --- a/pvlib/ivtools/utils.py +++ b/pvlib/ivtools/utils.py @@ -429,8 +429,8 @@ def _schumaker_qspline(x, y): def astm_e1036(v, i, imax_limits=(0.75, 1.15), vmax_limits=(0.75, 1.15), voc_points=3, isc_points=3, mp_fit_order=4): ''' - Extract photovoltaic IV parameters according to ASTM E1036. Assumes that - the power producing portion of the curve is in the first quadrant. + Extract photovoltaic IV parameters according to ASTM E1036 [1]_. Assumes + that the power producing portion of the curve is in the first quadrant. Parameters ---------- diff --git a/pvlib/location.py b/pvlib/location.py index e339e752f0..5065c02349 100644 --- a/pvlib/location.py +++ b/pvlib/location.py @@ -426,7 +426,8 @@ def lookup_altitude(latitude, longitude): """ Look up location altitude from low-resolution altitude map supplied with pvlib. The data for this map comes from multiple open data - sources with varying resolutions aggregated by Mapzen. + sources with varying resolutions aggregated by Mapzen [1]_ using + Joerd [2]_ and distributed as Terrain Tiles [3]_. More details can be found here https://github.com/tilezen/joerd/blob/master/docs/data-sources.md diff --git a/pvlib/pvarray.py b/pvlib/pvarray.py index 9fd5d0efd2..65804578b8 100644 --- a/pvlib/pvarray.py +++ b/pvlib/pvarray.py @@ -21,7 +21,7 @@ def pvefficiency_adr(effective_irradiance, temp_cell, Calculate PV module efficiency using the ADR model. The efficiency varies with irradiance and operating temperature - and is determined by 5 model parameters as described in [1]_. + and is determined by 5 model parameters as described in [1]_ and [2]_. Parameters ---------- diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 79d8a58d11..f3dba7aff8 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -1787,11 +1787,11 @@ def calcparams_desoto(effective_irradiance, temp_cell, ----- If the reference parameters in the ModuleParameters struct are read from a database or library of parameters (e.g. System Advisor - Model), it is important to use the same EgRef and dEgdT values that + Model [2]_), it is important to use the same EgRef and dEgdT values that were used to generate the reference parameters, regardless of the actual bandgap characteristics of the semiconductor. For example, in the case of the System Advisor Model library, created as described - in [3], EgRef and dEgdT for all modules were 1.121 and -0.0002677, + in [3]_, EgRef and dEgdT for all modules were 1.121 and -0.0002677, respectively. This table of reference bandgap energies (EgRef), bandgap energy @@ -1810,7 +1810,7 @@ def calcparams_desoto(effective_irradiance, temp_cell, >>> M = np.polyval([-1.26E-4, 2.816E-3, -0.024459, 0.086257, 0.9181], ... AMa) # doctest: +SKIP - Source: [1] + Source: [1]_ Cadmium Telluride (CdTe): * EgRef = 1.475 @@ -1819,7 +1819,7 @@ def calcparams_desoto(effective_irradiance, temp_cell, >>> M = np.polyval([-2.46E-5, 9.607E-4, -0.0134, 0.0716, 0.9196], ... AMa) # doctest: +SKIP - Source: [4] + Source: [4]_ Copper Indium diSelenide (CIS): * EgRef = 1.010 @@ -1828,7 +1828,7 @@ def calcparams_desoto(effective_irradiance, temp_cell, >>> M = np.polyval([-3.74E-5, 0.00125, -0.01462, 0.0718, 0.9210], ... AMa) # doctest: +SKIP - Source: [4] + Source: [4]_ Copper Indium Gallium diSelenide (CIGS): * EgRef = 1.15 @@ -1844,7 +1844,7 @@ def calcparams_desoto(effective_irradiance, temp_cell, * dEgdT = -0.000433 * M = unknown - Source: [4] + Source: [4]_ ''' # Boltzmann constant in eV/K, 8.617332478e-05 @@ -1904,6 +1904,7 @@ def calcparams_cec(effective_irradiance, temp_cell, model. The CEC model [1]_ differs from the De soto et al. model [3]_ by the parameter Adjust. The five values returned by calcparams_cec can be used by singlediode to calculate an IV curve. + The CEC model is used in the System Advisor Model [2]_. Parameters ---------- @@ -2370,7 +2371,7 @@ def sapm(effective_irradiance, temp_cell, module, *, temperature_ref=25, ''' The Sandia PV Array Performance Model (SAPM) generates 5 points on a PV module's I-V curve (Voc, Isc, Ix, Ixx, Vmp/Imp) according to - SAND2004-3535. Assumes a reference cell temperature of 25°C. + SAND2004-3535 [1]_. Assumes a reference cell temperature of 25°C. Parameters ---------- @@ -2698,6 +2699,8 @@ def singlediode(photocurrent, saturation_current, resistance_series, implicit diode equation utilizes the Lambert W function to obtain an explicit function of :math:`V=f(I)` and :math:`I=f(V)` as shown in [2]_. + The numerical methods use the approach of Bishop [4]_. + If the method is ``'newton'`` then the root-finding Newton-Raphson method is used. It should be safe for well-behaved IV curves, otherwise the ``'chandrupatla``` or ``'brentq'`` methods are recommended for reliability. diff --git a/pvlib/scaling.py b/pvlib/scaling.py index 67d10f17e5..e407379753 100644 --- a/pvlib/scaling.py +++ b/pvlib/scaling.py @@ -89,7 +89,7 @@ def wvm(clearsky_index, positions, cloud_speed, dt=None): def _compute_vr(positions, cloud_speed, tmscales): """ Compute the variability reduction factors for each wavelet mode for the - Wavelet Variability Model [1-3]. + Wavelet Variability Model [1]_ [2]_, following the MATLAB code [3]_. Parameters ---------- @@ -159,12 +159,13 @@ def latlon_to_xy(coordinates): Convert latitude and longitude in degrees to a coordinate system measured in meters from zero deg latitude, zero deg longitude. - This is a convenience method to support inputs to wvm. Note that the + This is a convenience method to support inputs to wvm [3]_, using + an earth radius from [1]_. Note that the methodology used is only suitable for short distances. For conversions of longer distances, users should consider use of Universal Transverse Mercator (UTM) or other suitable cartographic projection. Consider packages built for cartographic projection such as pyproj (e.g. - pyproj.transform()) [2]. + pyproj.transform()) [2]_. Parameters ---------- @@ -217,7 +218,8 @@ def _compute_wavelet(clearsky_index, dt=None): centered moving averages. Smallest scale (filter size of 2) is a degenerate case that resembles a Haar wavelet. Returns one level of approximation coefficient (CAn) and n levels of detail coefficients (CD1, CD2, ..., - CDn-1, CDn). + CDn-1, CDn). The transform follows the Wavelet Variability Model [1]_ + and its MATLAB implementation [2]_. Parameters ---------- diff --git a/pvlib/singlediode.py b/pvlib/singlediode.py index a511f9ebf4..dfc43e19b8 100644 --- a/pvlib/singlediode.py +++ b/pvlib/singlediode.py @@ -44,7 +44,7 @@ def estimate_voc(photocurrent, saturation_current, nNsVth): ----- Calculating the open circuit voltage, :math:`V_{oc}`, of an ideal device with infinite shunt resistance, :math:`R_{sh} \\to \\infty`, and zero - series resistance, :math:`R_s = 0`, yields the following equation [1]. As + series resistance, :math:`R_s = 0`, yields the following equation [1]_. As an estimate of :math:`V_{oc}` it is useful as an upper bound for the bisection method. diff --git a/pvlib/soiling.py b/pvlib/soiling.py index 6fdad506e6..448c661f5d 100644 --- a/pvlib/soiling.py +++ b/pvlib/soiling.py @@ -69,7 +69,7 @@ def hsu(rainfall, cleaning_threshold, surface_tilt, pm2_5, pm10, As recommended by [1]_, the default values of ``depo_veloc`` are the settling velocities of particulates, i.e., only the gravitational - movement of particles. + movement of particles, as described in [2]_. References ----------- diff --git a/pvlib/solarposition.py b/pvlib/solarposition.py index eb3bcdc81d..219ed041dd 100644 --- a/pvlib/solarposition.py +++ b/pvlib/solarposition.py @@ -34,6 +34,8 @@ def get_solarposition(time, latitude, longitude, """ A convenience wrapper for the solar position calculators. + The default method uses the NLR SPA algorithm [1]_ [2]_ [3]_. + Parameters ---------- time : pandas.DatetimeIndex @@ -130,7 +132,7 @@ def spa_c(time, latitude, longitude, pressure=101325., altitude=0., raw_spa_output=False): r""" Calculate the solar position using the NLR C implementation of the - NREL SPA. + NREL SPA [1]_. The source files for this code are located in './spa_c_files/', along with a README file which describes how the C code is wrapped in Python. @@ -156,7 +158,7 @@ def spa_c(time, latitude, longitude, pressure=101325., altitude=0., temperature : float, default 12.0 Temperature in C delta_t : float, default 67.0 - Difference between terrestrial time and UT1. + Difference between terrestrial time and UT1 [2]_. USNO has previous values and predictions [3]_. raw_spa_output : bool, default False If true, returns the raw SPA output. @@ -695,7 +697,7 @@ def pyephem(time, latitude, longitude, altitude=0., pressure=101325., def ephemeris(time, latitude, longitude, pressure=101325.0, temperature=12.0): """ - Python-native solar position calculator. + Python-native solar position calculator based on [1]_. The accuracy of this code is not guaranteed. Consider using the built-in spa_c code or the PyEphem library. @@ -1120,6 +1122,8 @@ def equation_of_time_pvcdrom(dayofyear): """ Equation of time from PVCDROM. + The equation is also described in [1]_. + `PVCDROM`_ is a website by Solar Power Lab at Arizona State University (ASU) @@ -1153,9 +1157,9 @@ def equation_of_time_pvcdrom(dayofyear): def declination_spencer71(dayofyear): """ Solar declination from Duffie & Beckman and attributed to - Spencer (1971) and Iqbal (1983). + Spencer (1971) [2]_ and Iqbal (1983). - See [1]_ for details. + See [1]_ and [3]_ for details. .. warning:: Return units are radians, not degrees. @@ -1198,7 +1202,7 @@ def declination_cooper69(dayofyear): """ Solar declination from Duffie & Beckman and attributed to Cooper (1969). - See [1]_ for details. + See [1]_, [2]_, and [3]_ for details. .. warning:: Return units are radians, not degrees. @@ -1244,7 +1248,9 @@ def declination_cooper69(dayofyear): def solar_azimuth_analytical(latitude, hourangle, declination, zenith): """ Analytical expression of solar azimuth angle based on spherical - trigonometry. + trigonometry [1]_ [2]_. + + See also the online descriptions in [3]_ and [4]_. Parameters ---------- @@ -1314,7 +1320,9 @@ def solar_azimuth_analytical(latitude, hourangle, declination, zenith): def solar_zenith_analytical(latitude, hourangle, declination): """ Analytical expression of solar zenith angle based on spherical - trigonometry. + trigonometry [1]_ [2]_ [3]_. + + See also the online descriptions in [4]_ and [5]_. .. warning:: The analytic form neglects the effect of atmospheric refraction. @@ -1367,6 +1375,8 @@ def hour_angle(times, longitude, equation_of_time): """ Hour angle in local solar time. Zero at local solar noon. + The calculation is described in [1]_, [2]_, and [3]_. + Parameters ---------- times : :class:`pandas.DatetimeIndex` @@ -1469,7 +1479,7 @@ def _times_to_hours_after_local_midnight(times): def sun_rise_set_transit_geometric(times, latitude, longitude, declination, equation_of_time): """ - Geometric calculation of solar sunrise, sunset, and transit. + Geometric calculation of solar sunrise, sunset, and transit [1]_ [2]_. .. warning:: The geometric calculation assumes a circular earth orbit with the sun as a point source at its center, and neglects the effect of diff --git a/pvlib/spectrum/response.py b/pvlib/spectrum/response.py index 906c156ed2..e6a30ae689 100644 --- a/pvlib/spectrum/response.py +++ b/pvlib/spectrum/response.py @@ -89,7 +89,7 @@ def sr_to_qe(sr, wavelength=None, normalize=False): Provide wavelengths in nanometers, [nm]. - Conversion is described in [1]_. + Conversion is described in [1]_ and [2]_. .. versionadded:: 0.11.0 @@ -188,7 +188,7 @@ def qe_to_sr(qe, wavelength=None, normalize=False): Provide wavelengths in nanometers, [nm]. - Conversion is described in [1]_. + Conversion is described in [1]_ and [2]_. .. versionadded:: 0.11.0 diff --git a/pvlib/temperature.py b/pvlib/temperature.py index 55222c0fb1..54aaeba531 100644 --- a/pvlib/temperature.py +++ b/pvlib/temperature.py @@ -371,7 +371,9 @@ def pvsyst_cell(poa_global, temp_air, wind_speed=1.0, u_c=29.0, u_v=0.0, Notes ----- - The Pvsyst model for cell temperature :math:`T_{C}` is given by + The PVsyst model [1]_ has the same form as the Faiman model [2]_, + with the added influence of module efficiency and absorption. + The cell temperature :math:`T_{C}` is given by .. math:: :label: pvsyst diff --git a/pvlib/tracking.py b/pvlib/tracking.py index a3cd6456a9..0d4ba808a2 100644 --- a/pvlib/tracking.py +++ b/pvlib/tracking.py @@ -261,7 +261,7 @@ def _unit_normal(axis_azimuth, axis_tilt, theta): def calc_surface_orientation(tracker_theta, axis_tilt=0, axis_azimuth=0): """ - Calculate the surface tilt and azimuth angles for a given tracker rotation. + Calculate surface tilt and azimuth for a tracker rotation using [1]_. Parameters ---------- From 1758c8b83b3d7ef222a1af7ea1eaec4c3b02ef79 Mon Sep 17 00:00:00 2001 From: WhatIsAPM1989 Date: Wed, 28 Oct 2026 22:33:26 +0000 Subject: [PATCH 2/3] DOC: keep citations out of autosummary descriptions Move callouts into extended descriptions so autosummary tables retain citation-free summaries and do not produce unknown-target errors. Assisted-by: Codex (GPT-6) --- pvlib/atmosphere.py | 5 +++-- pvlib/bifacial/ants2d.py | 4 +++- pvlib/clearsky.py | 5 +++-- pvlib/iam.py | 8 ++++++-- pvlib/iotools/acis.py | 5 +++-- pvlib/iotools/pvgis.py | 4 +++- pvlib/irradiance.py | 12 +++++++++--- pvlib/ivtools/utils.py | 6 ++++-- pvlib/location.py | 4 +++- pvlib/pvsystem.py | 10 +++++++--- pvlib/scaling.py | 13 ++++++++----- pvlib/solarposition.py | 28 ++++++++++++++++++---------- pvlib/tracking.py | 4 +++- 13 files changed, 73 insertions(+), 35 deletions(-) diff --git a/pvlib/atmosphere.py b/pvlib/atmosphere.py index 6cf4f27e7f..a2318684fa 100644 --- a/pvlib/atmosphere.py +++ b/pvlib/atmosphere.py @@ -566,8 +566,9 @@ def kasten96_lt(airmass_absolute, precipitable_water, aod_bb): def angstrom_aod_at_lambda(aod0, lambda0, alpha=1.14, lambda1=700.0): r""" - Get AOD at specified wavelength using the Angstrom turbidity model - [1]_ [2]_. + Get AOD at specified wavelength using Angstrom turbidity model. + + The model is described in [1]_ and [2]_. Parameters ---------- diff --git a/pvlib/bifacial/ants2d.py b/pvlib/bifacial/ants2d.py index 12b98b9f5d..f7eb9404a9 100644 --- a/pvlib/bifacial/ants2d.py +++ b/pvlib/bifacial/ants2d.py @@ -97,7 +97,9 @@ def _ants2d_singleside(tracker_rotation, cos_aoi, phi, gcr, height, pitch, max_rows): r""" Calculate plane-of-array irradiance components on one side of a row - of modules using the view factor model in [1]_. + of modules. + + The view factor model is described in [1]_. Parameters ---------- diff --git a/pvlib/clearsky.py b/pvlib/clearsky.py index 0666fcec4a..40f05b5d40 100644 --- a/pvlib/clearsky.py +++ b/pvlib/clearsky.py @@ -637,8 +637,9 @@ def _clear_sample_index(clear_windows, samples_per_window, align, H): def _clearsky_get_threshold(sample_interval): """ - Returns threshold values for kwargs in detect_clearsky. See - Table 1 in [1]_. + Returns threshold values for kwargs in detect_clearsky. + + See Table 1 in [1]_. References ---------- diff --git a/pvlib/iam.py b/pvlib/iam.py index 2e41bdba0b..cbf9c25cb1 100644 --- a/pvlib/iam.py +++ b/pvlib/iam.py @@ -1131,7 +1131,9 @@ def _process_return(target_name, optimize_result): def convert(source_name, source_params, target_name, weight=_sin_weight, fix_n=True, xtol=None): """ - Convert a source IAM model to a target IAM model using the method in [1]_. + Convert a source IAM model to a target IAM model. + + The conversion method is described in [1]_. Parameters ---------- @@ -1250,7 +1252,9 @@ def residual_function(target_param): def fit(measured_aoi, measured_iam, model_name, weight=_sin_weight, xtol=None): """ - Find model parameters that best fit the data using the method in [1]_. + Find model parameters that best fit the data. + + The fitting method is described in [1]_. Parameters ---------- diff --git a/pvlib/iotools/acis.py b/pvlib/iotools/acis.py index 6603d08dc7..1339123e0c 100644 --- a/pvlib/iotools/acis.py +++ b/pvlib/iotools/acis.py @@ -425,9 +425,10 @@ def get_acis_available_stations(latitude_range, longitude_range, **kwargs): """ List weather stations in a given area available from the - Applied Climate Information System (ACIS) [1]_. + Applied Climate Information System (ACIS). - Station metadata fields are described in [2]_. + The service API is described in [1]_ and the station metadata fields + are described in [2]_. The ``sids`` returned by this function can be used with :py:func:`get_acis_station_data` to retrieve weather measurements diff --git a/pvlib/iotools/pvgis.py b/pvlib/iotools/pvgis.py index 5f5a15cefb..9592461116 100644 --- a/pvlib/iotools/pvgis.py +++ b/pvlib/iotools/pvgis.py @@ -719,7 +719,9 @@ def read_pvgis_tmy(filename, pvgis_format=None, map_variables=True): def get_pvgis_horizon(latitude, longitude, url=URL, **kwargs): - """Get horizon data from PVGIS [1]_. + """Get horizon data from PVGIS. + + The horizon profile tool is described in [1]_. Parameters ---------- diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index b6385cad1f..96051c2b25 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -3187,7 +3187,9 @@ def campbell_norman(zenith, transmittance, pressure=101325.0, dni_extra=1367.0): ''' Determine DNI, DHI, GHI from extraterrestrial flux, transmittance, - and atmospheric pressure using the model in [1]_. + and atmospheric pressure. + + The model is described in [1]_. Parameters ---------- @@ -3239,7 +3241,9 @@ def campbell_norman(zenith, transmittance, pressure=101325.0, def _get_perez_coefficients(perezmodel): ''' - Find coefficients for the Perez models in [2]_ [3]_ [4]_. + Find coefficients for the Perez model. + + The model coefficient sets are described in [2]_, [3]_, and [4]_. An empirical validation of the model is provided in [1]_. @@ -3890,7 +3894,9 @@ def complete_irradiance(solar_zenith, def louche(ghi, solar_zenith, datetime_or_doy, max_zenith=90): """ - Determine DNI and DHI from GHI using the Louche model [1]_. + Determine DNI and DHI from GHI using the Louche model. + + The model is described in [1]_. Parameters ---------- diff --git a/pvlib/ivtools/utils.py b/pvlib/ivtools/utils.py index d5f1989c8d..16e05f0d29 100644 --- a/pvlib/ivtools/utils.py +++ b/pvlib/ivtools/utils.py @@ -429,8 +429,10 @@ def _schumaker_qspline(x, y): def astm_e1036(v, i, imax_limits=(0.75, 1.15), vmax_limits=(0.75, 1.15), voc_points=3, isc_points=3, mp_fit_order=4): ''' - Extract photovoltaic IV parameters according to ASTM E1036 [1]_. Assumes - that the power producing portion of the curve is in the first quadrant. + Extract photovoltaic IV parameters according to ASTM E1036. + + The extraction procedure is described in [1]_. Assumes that the power + producing portion of the curve is in the first quadrant. Parameters ---------- diff --git a/pvlib/location.py b/pvlib/location.py index 5065c02349..72ba35dc24 100644 --- a/pvlib/location.py +++ b/pvlib/location.py @@ -425,7 +425,9 @@ def get_sun_rise_set_transit(self, times, method='spa', **kwargs): def lookup_altitude(latitude, longitude): """ Look up location altitude from low-resolution altitude map - supplied with pvlib. The data for this map comes from multiple open data + supplied with pvlib. + + The data for this map comes from multiple open data sources with varying resolutions aggregated by Mapzen [1]_ using Joerd [2]_ and distributed as Terrain Tiles [3]_. diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index f3dba7aff8..06e98aaf1b 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -1901,7 +1901,9 @@ def calcparams_cec(effective_irradiance, temp_cell, ''' Calculates five parameter values for the single diode equation at effective irradiance and cell temperature using the CEC - model. The CEC model [1]_ differs from the De soto et al. + model. + + The CEC model [1]_ differs from the De soto et al. model [3]_ by the parameter Adjust. The five values returned by calcparams_cec can be used by singlediode to calculate an IV curve. The CEC model is used in the System Advisor Model [2]_. @@ -2370,8 +2372,10 @@ def sapm(effective_irradiance, temp_cell, module, *, temperature_ref=25, irradiance_ref=1000): ''' The Sandia PV Array Performance Model (SAPM) generates 5 points on a - PV module's I-V curve (Voc, Isc, Ix, Ixx, Vmp/Imp) according to - SAND2004-3535 [1]_. Assumes a reference cell temperature of 25°C. + PV module's I-V curve (Voc, Isc, Ix, Ixx, Vmp/Imp). + + The model is described in [1]_ and assumes a reference cell + temperature of 25°C. Parameters ---------- diff --git a/pvlib/scaling.py b/pvlib/scaling.py index e407379753..cf8b5c7058 100644 --- a/pvlib/scaling.py +++ b/pvlib/scaling.py @@ -89,7 +89,9 @@ def wvm(clearsky_index, positions, cloud_speed, dt=None): def _compute_vr(positions, cloud_speed, tmscales): """ Compute the variability reduction factors for each wavelet mode for the - Wavelet Variability Model [1]_ [2]_, following the MATLAB code [3]_. + Wavelet Variability Model. + + The model is described in [1]_ and [2]_, with MATLAB code in [3]_. Parameters ---------- @@ -213,10 +215,11 @@ def latlon_to_xy(coordinates): def _compute_wavelet(clearsky_index, dt=None): """ - Compute the wavelet transform on the input clear_sky time series. Uses a - top hat wavelet [-1,1,1,-1] shape, based on the difference of successive - centered moving averages. Smallest scale (filter size of 2) is a degenerate - case that resembles a Haar wavelet. Returns one level of approximation + Compute the wavelet transform on the input clear_sky time series. + + Uses a top hat wavelet [-1,1,1,-1] shape, based on the difference of + successive centered moving averages. Smallest scale (filter size of 2) is + a degenerate case that resembles a Haar wavelet. Returns one level of approximation coefficient (CAn) and n levels of detail coefficients (CD1, CD2, ..., CDn-1, CDn). The transform follows the Wavelet Variability Model [1]_ and its MATLAB implementation [2]_. diff --git a/pvlib/solarposition.py b/pvlib/solarposition.py index 219ed041dd..1ce96329f2 100644 --- a/pvlib/solarposition.py +++ b/pvlib/solarposition.py @@ -132,7 +132,9 @@ def spa_c(time, latitude, longitude, pressure=101325., altitude=0., raw_spa_output=False): r""" Calculate the solar position using the NLR C implementation of the - NREL SPA [1]_. + NREL SPA. + + The SPA implementation is described in [1]_. The source files for this code are located in './spa_c_files/', along with a README file which describes how the C code is wrapped in Python. @@ -697,8 +699,10 @@ def pyephem(time, latitude, longitude, altitude=0., pressure=101325., def ephemeris(time, latitude, longitude, pressure=101325.0, temperature=12.0): """ - Python-native solar position calculator based on [1]_. - The accuracy of this code is not guaranteed. + Python-native solar position calculator. + + The algorithm is based on [1]_. The accuracy of this code is not + guaranteed. Consider using the built-in spa_c code or the PyEphem library. Parameters @@ -1157,9 +1161,9 @@ def equation_of_time_pvcdrom(dayofyear): def declination_spencer71(dayofyear): """ Solar declination from Duffie & Beckman and attributed to - Spencer (1971) [2]_ and Iqbal (1983). + Spencer (1971) and Iqbal (1983). - See [1]_ and [3]_ for details. + See [1]_, [2]_, and [3]_ for details. .. warning:: Return units are radians, not degrees. @@ -1248,9 +1252,10 @@ def declination_cooper69(dayofyear): def solar_azimuth_analytical(latitude, hourangle, declination, zenith): """ Analytical expression of solar azimuth angle based on spherical - trigonometry [1]_ [2]_. + trigonometry. - See also the online descriptions in [3]_ and [4]_. + The equations are described in [1]_ and [2]_. See also the online + descriptions in [3]_ and [4]_. Parameters ---------- @@ -1320,9 +1325,10 @@ def solar_azimuth_analytical(latitude, hourangle, declination, zenith): def solar_zenith_analytical(latitude, hourangle, declination): """ Analytical expression of solar zenith angle based on spherical - trigonometry [1]_ [2]_ [3]_. + trigonometry. - See also the online descriptions in [4]_ and [5]_. + The equations are described in [1]_, [2]_, and [3]_. See also the online + descriptions in [4]_ and [5]_. .. warning:: The analytic form neglects the effect of atmospheric refraction. @@ -1479,7 +1485,9 @@ def _times_to_hours_after_local_midnight(times): def sun_rise_set_transit_geometric(times, latitude, longitude, declination, equation_of_time): """ - Geometric calculation of solar sunrise, sunset, and transit [1]_ [2]_. + Geometric calculation of solar sunrise, sunset, and transit. + + The geometric method is described in [1]_ and [2]_. .. warning:: The geometric calculation assumes a circular earth orbit with the sun as a point source at its center, and neglects the effect of diff --git a/pvlib/tracking.py b/pvlib/tracking.py index 0d4ba808a2..37a9ff0345 100644 --- a/pvlib/tracking.py +++ b/pvlib/tracking.py @@ -261,7 +261,9 @@ def _unit_normal(axis_azimuth, axis_tilt, theta): def calc_surface_orientation(tracker_theta, axis_tilt=0, axis_azimuth=0): """ - Calculate surface tilt and azimuth for a tracker rotation using [1]_. + Calculate the surface tilt and azimuth angles for a given tracker rotation. + + The rotation geometry is described in [1]_. Parameters ---------- From 863819bbe8e8a0713cef90a196e0ea2190d7017f Mon Sep 17 00:00:00 2001 From: WhatIsAPM1989 Date: Wed, 28 Oct 2026 22:33:40 +0000 Subject: [PATCH 3/3] DOC: wrap the wavelet description to the project line limit Assisted-by: Codex (GPT-6) --- pvlib/scaling.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/pvlib/scaling.py b/pvlib/scaling.py index cf8b5c7058..762a23b85a 100644 --- a/pvlib/scaling.py +++ b/pvlib/scaling.py @@ -218,11 +218,11 @@ def _compute_wavelet(clearsky_index, dt=None): Compute the wavelet transform on the input clear_sky time series. Uses a top hat wavelet [-1,1,1,-1] shape, based on the difference of - successive centered moving averages. Smallest scale (filter size of 2) is - a degenerate case that resembles a Haar wavelet. Returns one level of approximation - coefficient (CAn) and n levels of detail coefficients (CD1, CD2, ..., - CDn-1, CDn). The transform follows the Wavelet Variability Model [1]_ - and its MATLAB implementation [2]_. + successive centered moving averages. Smallest scale (filter size of 2) is a + degenerate case that resembles a Haar wavelet. Returns one level of + approximation coefficient (CAn) and n levels of detail coefficients (CD1, + CD2, ..., CDn-1, CDn). The transform follows the Wavelet Variability Model + [1]_ and its MATLAB implementation [2]_. Parameters ----------