Change Variables and Symbols page into a Glossary of terms (#2234)

* initial test

* Update irradiance.py

* update list of terms

* update dni description in irradiance.py

* minor edits, aoi definition

* Update glossary.rst

* Update glossary.rst

* remove in-text dni term glossary link

* delete one surface_tilt definition

* review: dni definition

Co-Authored-By: Adam R. Jensen <[email protected]>

* remove old files, add general text to glossary

* remove first bullet, add colon, on SoDa line

* Update glossary.rst

* conciseness (suggestion)

* updated aoi definition #2247

* update references old variables style rules page

* remove old page link from v0.3.0 whatsnew

* Update index.rst

Co-Authored-By: Echedey Luis <[email protected]>

* Update v0.11.2.rst

* Update docs/sphinx/source/user_guide/glossary.rst

Co-authored-by: Kevin Anderson <[email protected]>

* Update docs/sphinx/source/contributing/style_guide.rst

Co-authored-by: Cliff Hansen <[email protected]>

* add underscore

* changed reference label

* update labels

* name: nomenclature, update labels

* update whatsnew wording

* update file name

---------

Co-authored-by: Adam R. Jensen <[email protected]>
Co-authored-by: Echedey Luis <[email protected]>
Co-authored-by: Kevin Anderson <[email protected]>
Co-authored-by: Cliff Hansen <[email protected]>

Author: 5 people

docs/sphinx/source/contributing/style_guide.rst

@@ -13,7 +13,7 @@ pvlib python generally follows the `PEP 8 -- Style Guide for Python Code
 is 79 characters.
 
 pvlib python uses a mix of full and abbreviated variable names. See
-:ref:`variables_style_rules`. We could be better about consistency.
+:ref:`nomenclature`. 
 Prefer full names for new contributions. This is especially important
 for the API. Abbreviations can be used within a function to improve the
 readability of formulae.

docs/sphinx/source/index.rst

@@ -26,7 +26,7 @@ pvlib python
 that-use-pvlib-python>`_ page for inspiration and listing of your
 application.
 
-There is a :ref:`variable naming convention <variables_style_rules>` to
+There is a :ref:`variable naming convention <nomenclature>` to
 ensure consistency throughout the library.
 
 

docs/sphinx/source/user_guide/index.rst

@@ -15,6 +15,6 @@ User Guide
    clearsky
    bifacial
    weather_data
-   variables_style_rules
    singlediode
+   nomenclature
    faq

docs/sphinx/source/user_guide/nomenclature.rst

@@ -0,0 +1,192 @@
+.. _nomenclature:
+
+Nomenclature
+============
+
+There is a convention on consistent variable names throughout the library:
+
+.. glossary::
+
+    airmass
+        Airmass
+    
+    airmass_absolute
+        Absolute airmass
+    
+    airmass_relative
+        Relative airmass
+    
+    albedo
+        Ratio of reflected solar irradiance to global horizontal irradiance
+        [unitless]
+    
+    aoi
+        Angle of incidence. Angle between the surface normal vector and the
+        vector pointing towards the sun’s center
+    
+    aoi_projection
+        cos(aoi)
+
+    ape
+        Average photon energy
+
+    apparent_zenith
+        Refraction-corrected solar zenith angle in degrees
+
+    bhi
+        Beam/direct horizontal irradiance
+
+    dhi
+        Diffuse horizontal irradiance
+
+    dni
+        Direct normal irradiance [Wm⁻²]. Irradiance received per unit area by a
+        surface perpendicular (normal) to the sun's rays that propagate in a
+        straight line from the sun.
+
+    dni_clear
+        Clear sky direct normal irradiance
+
+    dni_extra
+        Direct normal irradiance at top of atmosphere (extraterrestrial)
+
+    effective_irradiance
+        Effective irradiance
+
+    eta_inv
+        Inverter efficiency
+
+    eta_inv_nom
+        Nominal inverter efficiency
+
+    eta_inv_ref
+        Reference inverter efficiency
+
+    g_poa_effective
+        Broadband plane of array effective irradiance
+
+    gamma_pdc
+        Module temperature coefficient. Typically in units of 1/C.
+
+    ghi
+        Global horizontal irradiance
+
+    ghi_extra
+        Horizontal irradiance at top of atmosphere (extraterrestrial)
+
+    gri
+        Ground-reflected irradiance
+
+    i_sc
+        Short circuit module current
+
+    i_x, i_xx
+        Sandia Array Performance Model IV curve parameters
+
+    latitude
+        Latitude
+
+    longitude
+        Longitude
+
+    pac, ac
+        AC power
+
+    pdc, dc
+        DC power
+
+    pdc0
+        Nameplate DC rating
+
+    photocurrent
+        Photocurrent
+
+    poa_diffuse
+        Total diffuse irradiation in plane. Sum of ground and sky diffuse.
+
+    poa_direct
+        Direct/beam irradiation in plane
+
+    poa_global
+        Global irradiation in plane. sum of diffuse and beam projection.
+
+    poa_ground_diffuse
+        In plane ground reflected irradiation
+
+    poa_sky_diffuse
+        Diffuse irradiation in plane from scattered light in the atmosphere
+        (without ground reflected irradiation)
+
+    precipitable_water
+        Total precipitable water contained in a column of unit cross section
+        from earth to top of atmosphere
+
+    pressure
+        Atmospheric pressure
+
+    relative_humidity
+        Relative humidity
+
+    resistance_series
+        Series resistance
+
+    resistance_shunt
+        Shunt resistance
+
+    saturation_current
+        Diode saturation current
+
+    solar_azimuth
+        Azimuth angle of the sun in degrees East of North
+
+    solar_zenith
+        Zenith angle of the sun in degrees
+
+    surface_azimuth
+        Azimuth angle of the surface
+
+    surface_tilt
+        Panel tilt from horizontal [°]. For example, a surface facing up = 0°,
+        surface facing horizon = 90°.
+
+    temp_air
+        Temperature of the air
+
+    temp_cell
+        Temperature of the cell
+
+    temp_dew
+        Dewpoint temperature
+
+    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
+
+    v_mp, i_mp, p_mp
+        Module voltage, current, power at the maximum power point
+
+    v_oc
+        Open circuit module voltage
+
+    wind_direction
+        Wind direction
+
+    wind_speed
+        Wind speed
+
+
+For further explanation of the variables, common symbols, and
+units, refer to the following sources from `SoDa Service <http://www.soda-pro.com/home>`_:
+
+   * `Acronyms, Terminology and Units <https://www.soda-pro.com/help/general/acronyms-terminology-and-units>`_
+   * `Plane orientations and radiation components <https://www.soda-pro.com/help/general/plane-orientations-and-radiation-components>`_
+   * `Time references <https://www.soda-pro.com/help/general/time-references>`_
+
+.. note:: These further references might not use the same terminology as
+          *pvlib*. But the physical process referred to is the same.

docs/sphinx/source/user_guide/variables_style_rules.rst

@@ -83,7 +83,7 @@ a :py:class:`pandas.DataFrame` of the actual dataset, plus a metadata
 dictionary.  Most :py:mod:`pvlib.iotools` functions also have
 a ``map_variables`` parameter to automatically translate
 the column names used in the data file (which vary widely from dataset to dataset)
-into standard pvlib names (see :ref:`variables_style_rules`).  
+into standard pvlib names (see :ref:`nomenclature`).  
 
 Typical usage looks something like this:
 

docs/sphinx/source/user_guide/weather_data.rst

@@ -25,6 +25,8 @@ Documentation
   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`)
 

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

@@ -47,7 +47,7 @@ Enhancements
     * :ref:`installation` (:issue:`135`)
     * :ref:`contributing` (:issue:`46`)
     * :ref:`timetimezones` (:issue:`47`)
-    * :ref:`variables_style_rules` (:issue:`102`)
+    * Variables and Symbols (:issue:`102`)
     * Classes (:issue:`93`) (Moved to :ref:`api` in :issue:`258`)
 
 * Adds support for Appveyor, a Windows continuous integration service.

docs/sphinx/source/whatsnew/v0.3.0.txt

@@ -193,7 +193,7 @@ def read_midc(filename, variable_map={}, raw_data=False, **kwargs):
 
     See the MIDC_VARIABLE_MAP for collection of mappings by site.
     For a full list of pvlib variable names see the
-    :ref:`variables_style_rules`.
+    :ref:`nomenclature`.
 
     Be sure to check the units for the variables you will use on the
     `MIDC site <https://midcdmz.nrel.gov/>`_.

pvlib/data/variables_style_rules.csv

@@ -734,16 +734,14 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
     The Hay and Davies model determines the diffuse irradiance from
     the sky (ground reflected irradiance is not included in this
     algorithm) on a tilted surface using the surface tilt angle, surface
-    azimuth angle, diffuse horizontal irradiance, direct normal
-    irradiance, extraterrestrial irradiance, sun zenith angle, and sun
-    azimuth angle.
+    azimuth angle, diffuse horizontal irradiance, direct normal irradiance,
+    extraterrestrial irradiance, sun zenith angle, and sun azimuth angle.
 
     Parameters
     ----------
     surface_tilt : numeric
-        Surface tilt angles in decimal degrees. The tilt angle is
-        defined as degrees from horizontal (e.g. surface facing up = 0,
-        surface facing horizon = 90)
+        Panel tilt from the horizontal, in decimal degrees, see
+        :term:`surface_tilt`.
 
     surface_azimuth : numeric
         Surface azimuth angles in decimal degrees. The azimuth
@@ -754,7 +752,7 @@ def haydavies(surface_tilt, surface_azimuth, dhi, dni, dni_extra,
         Diffuse horizontal irradiance. [Wm⁻²]
 
     dni : numeric
-        Direct normal irradiance. [Wm⁻²]
+        Direct normal irradiance, see :term:`dni`. [Wm⁻²]
 
     dni_extra : numeric
         Extraterrestrial normal irradiance. [Wm⁻²]