diff --git a/docs/sphinx/source/contributing/style_guide.rst b/docs/sphinx/source/contributing/style_guide.rst index 58faa59a98..02d93a8494 100644 --- a/docs/sphinx/source/contributing/style_guide.rst +++ b/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:`glossary`. 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. diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index ce62c56e28..1ace32acf0 100644 --- a/docs/sphinx/source/index.rst +++ b/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 ` to +There is a :ref:`variable naming convention ` to ensure consistency throughout the library. diff --git a/docs/sphinx/source/user_guide/glossary.rst b/docs/sphinx/source/user_guide/glossary.rst new file mode 100644 index 0000000000..6c5d9b8f61 --- /dev/null +++ b/docs/sphinx/source/user_guide/glossary.rst @@ -0,0 +1,192 @@ +.. glossary: + +Glossary +======== + +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 `_: + + * `Acronyms, Terminology and Units `_ + * `Plane orientations and radiation components `_ + * `Time references `_ + +.. note:: These further references might not use the same terminology as + *pvlib*. But the physical process referred to is the same. diff --git a/docs/sphinx/source/user_guide/index.rst b/docs/sphinx/source/user_guide/index.rst index 416cc0b260..36c67bcb69 100644 --- a/docs/sphinx/source/user_guide/index.rst +++ b/docs/sphinx/source/user_guide/index.rst @@ -15,6 +15,6 @@ User Guide clearsky bifacial weather_data - variables_style_rules singlediode + glossary faq diff --git a/docs/sphinx/source/user_guide/variables_style_rules.rst b/docs/sphinx/source/user_guide/variables_style_rules.rst deleted file mode 100644 index 4d3574ab4b..0000000000 --- a/docs/sphinx/source/user_guide/variables_style_rules.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _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: - - -* `IEC 61724-1:2017 -- Photovoltaic system performance - Part 1: Monitoring `_ section: 3 -- Terms and definitions; the Indian Standard referencing the withdrawn earlier global IEC standard IEC 61724:1998 is available online: `IS/IEC 61724 (1998) `_ and can provide relevant contents. -* Explanation of Solar irradiation and solar geometry by `SoDa Service `_ - - * `Acronyms, Terminology and Units `_ - * `Plane orientations and radiation components `_ - * `Time references `_ - -.. note:: These further references might not use the same terminology as *pvlib*. But the physical process referred to is the same. diff --git a/docs/sphinx/source/user_guide/weather_data.rst b/docs/sphinx/source/user_guide/weather_data.rst index 06e54d2296..9e5c144033 100644 --- a/docs/sphinx/source/user_guide/weather_data.rst +++ b/docs/sphinx/source/user_guide/weather_data.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:`glossary`). Typical usage looks something like this: diff --git a/docs/sphinx/source/whatsnew/v0.11.2.rst b/docs/sphinx/source/whatsnew/v0.11.2.rst index e192ebe18a..48a4ba4c3f 100644 --- a/docs/sphinx/source/whatsnew/v0.11.2.rst +++ b/docs/sphinx/source/whatsnew/v0.11.2.rst @@ -18,6 +18,8 @@ Documentation :py:func:`~pvlib.pvsystem.dc_ohmic_losses` for clarity. (:issue:`1601`, :pull:`2229`) * Updated :py:func:`~pvlib.irradiance.reindl` to include definitions of terms and a new "notes" section (:issue:`2183`, :pull:`2193`) +* Added a new :ref:`Glossary` page in place of the Variables and Symbols + page. (:issue:`1421`, :pull:`2234`) Testing ~~~~~~~ diff --git a/docs/sphinx/source/whatsnew/v0.3.0.txt b/docs/sphinx/source/whatsnew/v0.3.0.txt index 62cc9839f7..36db1b3b90 100644 --- a/docs/sphinx/source/whatsnew/v0.3.0.txt +++ b/docs/sphinx/source/whatsnew/v0.3.0.txt @@ -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. diff --git a/pvlib/data/variables_style_rules.csv b/pvlib/data/variables_style_rules.csv deleted file mode 100644 index f7930bd445..0000000000 --- a/pvlib/data/variables_style_rules.csv +++ /dev/null @@ -1,56 +0,0 @@ -variable;description -tz;timezone -latitude;latitude -longitude;longitude -dni;direct normal irradiance -dni_extra;direct normal irradiance at top of atmosphere (extraterrestrial) -dni_clear;clear sky direct normal irradiance -dhi;diffuse horizontal irradiance -bhi;beam/direct horizontal irradiance -ghi;global horizontal irradiance -ghi_extra;horizontal irradiance at top of atmosphere (extraterrestrial) -gri;ground-reflected irradiance -ape;average photon energy -aoi;angle of incidence. Angle between the surface normal vector and the vector pointing towards the sun's center -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) -g_poa_effective;broadband plane of array effective irradiance. -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 -wind_speed;wind speed -wind_direction;wind direction -pressure;atmospheric pressure -albedo;ratio of reflected solar irradiance to global horizontal irradiance, unitless -precipitable_water;total precipitable water contained in a column of unit cross section from earth to top of atmosphere -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}` -pdc0; nameplate DC rating -pdc, dc; dc power -gamma_pdc; module temperature coefficient. Typically in units of 1/C. -pac, ac; ac power -eta_inv; inverter efficiency -eta_inv_ref; reference inverter efficiency -eta_inv_nom; nominal inverter efficiency diff --git a/pvlib/iotools/midc.py b/pvlib/iotools/midc.py index 99b6f20680..b0aa45499f 100644 --- a/pvlib/iotools/midc.py +++ b/pvlib/iotools/midc.py @@ -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:`glossary`. Be sure to check the units for the variables you will use on the `MIDC site `_. diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index d1854cfb6c..1a3ac5e71e 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -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⁻²]