From ae3fcff3766d0a70e4866a16f4a40f0faa012253 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Mon, 31 Mar 2025 09:02:33 -0600 Subject: [PATCH 1/7] add reference --- pvlib/atmosphere.py | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/pvlib/atmosphere.py b/pvlib/atmosphere.py index 8150abe405..759ad4c0ae 100644 --- a/pvlib/atmosphere.py +++ b/pvlib/atmosphere.py @@ -153,7 +153,7 @@ def get_relative_airmass(zenith, model='kastenyoung1989'): requires true sun zenith * 'kastenyoung1989' (default) - See reference [3] - requires apparent sun zenith - * 'gueymard1993' - See reference [4] - + * 'gueymard1993' - See references [4] and [9] - requires apparent sun zenith * 'young1994' - See reference [5] - requires true sun zenith @@ -174,6 +174,8 @@ def get_relative_airmass(zenith, model='kastenyoung1989'): other models use true (not refraction-adjusted) zenith angle. Apparent zenith angles should be calculated at sea level. + Comparison among several models is reported in [10]. + References ---------- .. [1] Fritz Kasten. "A New Table and Approximation Formula for the @@ -206,9 +208,14 @@ def get_relative_airmass(zenith, model='kastenyoung1989'): Mapping. Green Energy and Technology. Springer, Cham. :doi:`10.1007/978-3-319-97484-2_5` - .. [9] Matthew J. Reno, Clifford W. Hansen and Joshua S. Stein, "Global + .. [9] C. Gueymard, "Development and performance assessment of a clear + sky spectral radiation model,” in Proc. of the 22nd ASES Conference, + Solar ’93, 1993, pp. 433–438. + + .. [10] Matthew J. Reno, Clifford W. Hansen and Joshua S. Stein, "Global Horizontal Irradiance Clear Sky Models: Implementation and Analysis" Sandia Report, (2012). + ''' # set zenith values greater than 90 to nans @@ -236,7 +243,7 @@ def get_relative_airmass(zenith, model='kastenyoung1989'): (np.cos(zenith_rad) ** 3 + 0.149864*(np.cos(zenith_rad) ** 2) + 0.0102963*(np.cos(zenith_rad)) + 0.000303978)) - elif 'gueymard1993' == model: + elif 'gueymard1993' == model: # [4], Eq. 22 and [9], Eq. 3b am = (1.0 / (np.cos(zenith_rad) + 0.00176759*(z)*((94.37515 - z) ** - 1.21563))) elif 'gueymard2003' == model: From f733c3ad9b5863e21958ad7f21d701d2763d6dd0 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Mon, 31 Mar 2025 09:06:32 -0600 Subject: [PATCH 2/7] whatsnew --- docs/sphinx/source/whatsnew/v0.12.1.rst | 33 +++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 docs/sphinx/source/whatsnew/v0.12.1.rst diff --git a/docs/sphinx/source/whatsnew/v0.12.1.rst b/docs/sphinx/source/whatsnew/v0.12.1.rst new file mode 100644 index 0000000000..9f35593e18 --- /dev/null +++ b/docs/sphinx/source/whatsnew/v0.12.1.rst @@ -0,0 +1,33 @@ +.. _whatsnew_01201: + + +v0.12.1 (XXXX, 2025) +------------------------ + +Breaking Changes +~~~~~~~~~~~~~~~~ + + +Bug fixes +~~~~~~~~~ + + +Enhancements +~~~~~~~~~~~~ + + +Documentation +~~~~~~~~~~~~~ +* Add a supporting reference to :py:func:`pvlib.atmosphere.get_relative_airmass` (:issue:`2390`, :pull:`2424`) + +Testing +~~~~~~~ + + +Maintenance +~~~~~~~~~~~ + + +Contributors +~~~~~~~~~~~~ +* Cliff Hansen (:ghuser:`cwhanse`) From 58aa1a8c382c355f14c7e1380c8306b40dfb0962 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Mon, 31 Mar 2025 10:57:41 -0600 Subject: [PATCH 3/7] underscores --- pvlib/atmosphere.py | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/pvlib/atmosphere.py b/pvlib/atmosphere.py index 759ad4c0ae..b76c9f2a79 100644 --- a/pvlib/atmosphere.py +++ b/pvlib/atmosphere.py @@ -147,20 +147,13 @@ def get_relative_airmass(zenith, model='kastenyoung1989'): * 'simple' - secant(apparent zenith angle) - Note that this gives -Inf at zenith=90 - * 'kasten1966' - See reference [1] - - requires apparent sun zenith - * 'youngirvine1967' - See reference [2] - - requires true sun zenith - * 'kastenyoung1989' (default) - See reference [3] - - requires apparent sun zenith - * 'gueymard1993' - See references [4] and [9] - - requires apparent sun zenith - * 'young1994' - See reference [5] - - requires true sun zenith - * 'pickering2002' - See reference [6] - - requires apparent sun zenith - * 'gueymard2003' - See references [7] and [8] - - requires apparent sun zenith + * 'kasten1966' - See [1]_ - requires apparent sun zenith + * 'youngirvine1967' - See [2]_ - requires true sun zenith + * 'kastenyoung1989' (default) - See [3]_ - requires apparent sun zenith + * 'gueymard1993' - See [4]_, [9]_ - requires apparent sun zenith + * 'young1994' - See [5]_ - requires true sun zenith + * 'pickering2002' - See [6]_ - requires apparent sun zenith + * 'gueymard2003' - See [7]_, [8]_ - requires apparent sun zenith Returns ------- @@ -174,7 +167,7 @@ def get_relative_airmass(zenith, model='kastenyoung1989'): other models use true (not refraction-adjusted) zenith angle. Apparent zenith angles should be calculated at sea level. - Comparison among several models is reported in [10]. + Comparison among several models is reported in [10]_. References ---------- From f99bf6feb58316c9f14d0ece4a8de3596349e838 Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Mon, 31 Mar 2025 11:22:36 -0600 Subject: [PATCH 4/7] reference order --- pvlib/atmosphere.py | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/pvlib/atmosphere.py b/pvlib/atmosphere.py index b76c9f2a79..373a9035ff 100644 --- a/pvlib/atmosphere.py +++ b/pvlib/atmosphere.py @@ -150,10 +150,10 @@ def get_relative_airmass(zenith, model='kastenyoung1989'): * 'kasten1966' - See [1]_ - requires apparent sun zenith * 'youngirvine1967' - See [2]_ - requires true sun zenith * 'kastenyoung1989' (default) - See [3]_ - requires apparent sun zenith - * 'gueymard1993' - See [4]_, [9]_ - requires apparent sun zenith - * 'young1994' - See [5]_ - requires true sun zenith - * 'pickering2002' - See [6]_ - requires apparent sun zenith - * 'gueymard2003' - See [7]_, [8]_ - requires apparent sun zenith + * 'gueymard1993' - See [4]_, [5]_ - requires apparent sun zenith + * 'young1994' - See [6]_ - requires true sun zenith + * 'pickering2002' - See [7]_ - requires apparent sun zenith + * 'gueymard2003' - See [8]_, [9]_ - requires apparent sun zenith Returns ------- @@ -186,25 +186,25 @@ def get_relative_airmass(zenith, model='kastenyoung1989'): clear sky solar irradiance models using theoretical and measured data," Solar Energy, vol. 51, pp. 121-138, 1993. - .. [5] A. T. Young, "AIR-MASS AND REFRACTION," Applied Optics, vol. 33, + .. [5] C. Gueymard, "Development and performance assessment of a clear + sky spectral radiation model,” in Proc. of the 22nd ASES Conference, + Solar ’93, 1993, pp. 433–438. + + .. [6] A. T. Young, "AIR-MASS AND REFRACTION," Applied Optics, vol. 33, pp. 1108-1110, Feb 1994. - .. [6] Keith A. Pickering. "The Ancient Star Catalog". DIO 12:1, 20, + .. [7] Keith A. Pickering. "The Ancient Star Catalog". DIO 12:1, 20, - .. [7] C. Gueymard, "Direct solar transmittance and irradiance + .. [8] C. Gueymard, "Direct solar transmittance and irradiance predictions with broadband models. Part I: detailed theoretical performance assessment". Solar Energy, vol 74, pp. 355-379, 2003. :doi:`10.1016/S0038-092X(03)00195-6` - .. [8] C. Gueymard (2019). Clear-Sky Radiation Models and Aerosol Effects. + .. [9] C. Gueymard (2019). Clear-Sky Radiation Models and Aerosol Effects. In: Polo, J., Martín-Pomares, L., Sanfilippo, A. (eds) Solar Resources Mapping. Green Energy and Technology. Springer, Cham. :doi:`10.1007/978-3-319-97484-2_5` - .. [9] C. Gueymard, "Development and performance assessment of a clear - sky spectral radiation model,” in Proc. of the 22nd ASES Conference, - Solar ’93, 1993, pp. 433–438. - .. [10] Matthew J. Reno, Clifford W. Hansen and Joshua S. Stein, "Global Horizontal Irradiance Clear Sky Models: Implementation and Analysis" Sandia Report, (2012). @@ -236,7 +236,7 @@ def get_relative_airmass(zenith, model='kastenyoung1989'): (np.cos(zenith_rad) ** 3 + 0.149864*(np.cos(zenith_rad) ** 2) + 0.0102963*(np.cos(zenith_rad)) + 0.000303978)) - elif 'gueymard1993' == model: # [4], Eq. 22 and [9], Eq. 3b + elif 'gueymard1993' == model: # [4], Eq. 22 and [5], Eq. 3b am = (1.0 / (np.cos(zenith_rad) + 0.00176759*(z)*((94.37515 - z) ** - 1.21563))) elif 'gueymard2003' == model: From 141bfe74c436906494ef715c10a9229b91e9706e Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Wed, 2 Apr 2025 08:46:54 -0600 Subject: [PATCH 5/7] improve references --- pvlib/atmosphere.py | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/pvlib/atmosphere.py b/pvlib/atmosphere.py index 373a9035ff..789403e31b 100644 --- a/pvlib/atmosphere.py +++ b/pvlib/atmosphere.py @@ -171,43 +171,51 @@ def get_relative_airmass(zenith, model='kastenyoung1989'): References ---------- - .. [1] Fritz Kasten. "A New Table and Approximation Formula for the - Relative Optical Air Mass". Technical Report 136, Hanover, N.H.: - U.S. Army Material Command, CRREL. + .. [1] Fritz Kasten, "A New Table and Approximation Formula for the + Relative Optical Air Mass," CRREL (U.S. Army), Hanover, NH, USA, + Technical Report 136, 1965. + :doi:`11681/5671` .. [2] A. T. Young and W. M. Irvine, "Multicolor Photoelectric Photometry of the Brighter Planets," The Astronomical Journal, vol. 72, pp. 945-950, 1967. + :doi:`10.2172/110366` - .. [3] Fritz Kasten and Andrew Young. "Revised optical air mass tables - and approximation formula". Applied Optics 28:4735-4738 + .. [3] Fritz Kasten and Andrew Young, "Revised optical air mass tables + and approximation formula," Applied Optics 28:4735-4738, 1989. + :doi:`10.1364/AO.28.004735` .. [4] C. Gueymard, "Critical analysis and performance assessment of clear sky solar irradiance models using theoretical and measured data," Solar Energy, vol. 51, pp. 121-138, 1993. + :doi:`10.1016/0038-092X(93)90074-X` .. [5] C. Gueymard, "Development and performance assessment of a clear sky spectral radiation model,” in Proc. of the 22nd ASES Conference, Solar ’93, 1993, pp. 433–438. - .. [6] A. T. Young, "AIR-MASS AND REFRACTION," Applied Optics, vol. 33, - pp. 1108-1110, Feb 1994. + .. [6] A. T. Young, "Air-Mass and Refraction," Applied Optics, vol. 33, + pp. 1108-1110, Feb. 1994. + :doi:`10.1364/AO.33.001108` - .. [7] Keith A. Pickering. "The Ancient Star Catalog". DIO 12:1, 20, + .. [7] Keith A. Pickering, "The Southern Limits of the Ancient Star Catalog + and the Commentary fo Hipparchos," DIO, vol. 12, pp. 3-27, Sept. 2002. .. [8] C. Gueymard, "Direct solar transmittance and irradiance predictions with broadband models. Part I: detailed theoretical performance assessment". Solar Energy, vol 74, pp. 355-379, 2003. :doi:`10.1016/S0038-092X(03)00195-6` - .. [9] C. Gueymard (2019). Clear-Sky Radiation Models and Aerosol Effects. - In: Polo, J., Martín-Pomares, L., Sanfilippo, A. (eds) Solar Resources - Mapping. Green Energy and Technology. Springer, Cham. + .. [9] C. Gueymard, "Clear-Sky Radiation Models and Aerosol Effects", in + Solar Resources Mapping: Fundamentals and Applications, + Polo, J., Martín-Pomares, L., Sanfilippo, A. (Eds), Cham, CH: Springer, + 2019, pp. 137-182. :doi:`10.1007/978-3-319-97484-2_5` .. [10] Matthew J. Reno, Clifford W. Hansen and Joshua S. Stein, "Global Horizontal Irradiance Clear Sky Models: Implementation and Analysis" - Sandia Report, (2012). + Sandia National Laboratories, Albuquerque, NM, USA, SAND2012-2389, 2012. + :doi:`10.2172/1039404` ''' From 411f89a63d206fb241d12467fb644e1fb321d62a Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Wed, 2 Apr 2025 08:58:38 -0600 Subject: [PATCH 6/7] fix errors --- pvlib/atmosphere.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pvlib/atmosphere.py b/pvlib/atmosphere.py index 789403e31b..45eb61bf2b 100644 --- a/pvlib/atmosphere.py +++ b/pvlib/atmosphere.py @@ -177,9 +177,9 @@ def get_relative_airmass(zenith, model='kastenyoung1989'): :doi:`11681/5671` .. [2] A. T. Young and W. M. Irvine, "Multicolor Photoelectric - Photometry of the Brighter Planets," The Astronomical Journal, vol. - 72, pp. 945-950, 1967. - :doi:`10.2172/110366` + Photometry of the Brighter Planets. I. Program and Procedure," + The Astronomical Journal, vol. 72, pp. 945-950, 1967. + :doi:`10.1086/110366` .. [3] Fritz Kasten and Andrew Young, "Revised optical air mass tables and approximation formula," Applied Optics 28:4735-4738, 1989. @@ -199,7 +199,7 @@ def get_relative_airmass(zenith, model='kastenyoung1989'): :doi:`10.1364/AO.33.001108` .. [7] Keith A. Pickering, "The Southern Limits of the Ancient Star Catalog - and the Commentary fo Hipparchos," DIO, vol. 12, pp. 3-27, Sept. 2002. + and the Commentary of Hipparchos," DIO, vol. 12, pp. 3-27, Sept. 2002. .. [8] C. Gueymard, "Direct solar transmittance and irradiance predictions with broadband models. Part I: detailed theoretical From 654dcfb544267d6cef81f1c829cf793d40852eee Mon Sep 17 00:00:00 2001 From: Cliff Hansen Date: Wed, 2 Apr 2025 09:58:12 -0600 Subject: [PATCH 7/7] add url --- pvlib/atmosphere.py | 1 + 1 file changed, 1 insertion(+) diff --git a/pvlib/atmosphere.py b/pvlib/atmosphere.py index 45eb61bf2b..dcd34da6bc 100644 --- a/pvlib/atmosphere.py +++ b/pvlib/atmosphere.py @@ -200,6 +200,7 @@ def get_relative_airmass(zenith, model='kastenyoung1989'): .. [7] Keith A. Pickering, "The Southern Limits of the Ancient Star Catalog and the Commentary of Hipparchos," DIO, vol. 12, pp. 3-27, Sept. 2002. + Available at `DIO `_ .. [8] C. Gueymard, "Direct solar transmittance and irradiance predictions with broadband models. Part I: detailed theoretical