fix for https://github.com/pvlib/pvlib-python/issues/102

docs/sphinx/source/index.rst

@@ -42,6 +42,8 @@ and
 
 The GitHub wiki also has a page on `Projects and publications that use pvlib python <https://github.com/pvlib/pvlib-python/wiki/Projects-and-publications-that-use-pvlib-python>`_ for inspiration and listing of your application.
 
+There is a :ref:`variable naming convention <variables_style_rules>` to ensure consistency throughout the library.
+
 Installation
 ============
 
@@ -60,6 +62,7 @@ Contents
    self
    whatsnew
    comparison_pvlib_matlab
+   variables_style_rules
    pvlib
 
 

docs/sphinx/source/variables_style_rules.rst

@@ -0,0 +1,29 @@
+.. _variables_style_rules:
+
+Variables and Symbols
+=====================
+
+There is a convention on consistent variable names throughout the library:
+
+.. csv-table:: List of used Variables and Parameters
+   :file: ../../../pvlib/data/variables_style_rules.csv
+   :delim: ;
+   :header-rows: 1
+   :widths: 5, 5
+   :stub-columns: 1
+
+For a definition and further explanation on the variables, common symbols and units refer to the following sources:
+
+
+* `Reference Variable List by PVPMC <https://pvpmc.sandia.gov/resources/variable-list/>`_
+* `IEC 61724:1998 -- Photovoltaic system performance monitoring - Guidelines for measurement, data exchange and analysis <https://webstore.iec.ch/publication/5733>`_ ; the Indian Standard referencing the global IEC standard is available online: `IS/IEC 61724 (1998) <https://law.resource.org/pub/in/bis/S05/is.iec.61724.1998.pdf>`_
+* Explanation of Solar irradiation and solar geometry by `SoDa Service <http://www.soda-pro.com/home>`_
+
+   * `Acronyms, Terminology and Units <http://www.soda-pro.com/help/general/acronyms-terminology-and-units>`_
+   * `Plane orientations and radiation components <http://www.soda-pro.com/help/general/plane-orientations-and-radiation-components>`_
+   * `Time references <http://www.soda-pro.com/help/general/time-references>`_
+   * `Units and conversion tool <http://www.soda-is.com/eng/education/units.html>`_
+   * `Terminology: definitions of the main quantities. <http://www.soda-is.com/eng/education/terminology.html>`_
+   * `Acronyms in solar radiation <http://www.soda-is.com/eng/education/acronymes.html>`_ (more extensive list)
+
+.. note:: These further references might not use the same terminology as *pvlib*. But the physical process referred to is the same.

pvlib/data/variables_style_rules.csv

@@ -0,0 +1,38 @@
+variable;description
+tz;timezone
+latitude;latitude
+longitude;longitude
+dni;direct normal irradiance
+dni_extra;direct normal irradiance at top of atmosphere (extraterrestrial)
+dhi;diffuse horizontal irradiance
+ghi;global horizontal irradiance
+aoi;angle of incidence
+aoi_projection;cos(aoi)
+airmass;airmass
+airmass_relative;relative airmass
+airmass_absolute;absolute airmass
+poa_ground_diffuse;in plane ground reflected irradiation
+poa_direct;direct/beam irradiation in plane
+poa_diffuse;total diffuse irradiation in plane. sum of ground and sky diffuse.
+poa_global;global irradiation in plane. sum of diffuse and beam projection.
+poa_sky_diffuse;diffuse irradiation in plane from scattered light in the atmosphere (without ground reflected irradiation)
+surface_tilt;tilt angle of the surface
+surface_azimuth;azimuth angle of the surface
+solar_zenith;zenith angle of the sun in degrees
+apparent_zenith;refraction-corrected solar zenith angle in degrees
+solar_azimuth;azimuth angle of the sun in degrees East of North
+temp_cell;temperature of the cell
+temp_module;temperature of the module
+temp_air;temperature of the air
+temp_dew;dewpoint temperature
+relative_humidity;relative humidity
+v_mp, i_mp, p_mp;module voltage, current, power at the maximum power point
+v_oc;open circuit module voltage
+i_sc;short circuit module current
+i_x, i_xx;Sandia Array Performance Model IV curve parameters
+effective_irradiance;effective irradiance
+photocurrent;photocurrent
+saturation_current;diode saturation current
+resistance_series;series resistance
+resistance_shunt;shunt resistance
+transposition_factor; the gain ratio of the radiation on inclined plane to global horizontal irradiation: :math:`\frac{poa\_global}{ghi}`