Merge remote-tracking branch 'wholmgren/pvsystem' into origin/pvsystem

Author: dacoex

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
 ============
 
@@ -59,10 +61,11 @@ Contents
 
    self
    package_overview
+   whatsnew
    modules
    classes
    comparison_pvlib_matlab
-   whatsnew
+   variables_style_rules
 
 
 Indices and tables

docs/sphinx/source/package_overview.rst

@@ -20,10 +20,11 @@ is well-tested procedural code that implements PV system models.
 pvlib-python also provides a collection of classes for users
 that prefer object-oriented programming.
 These classes can help users keep track of data in a more organized way,
-and can help to simplify the modeling process.
-The classes do not add any functionality beyond the procedural code.
-Most of the object methods are simple wrappers around the
-corresponding procedural code.
+provide some "smart" functions with more flexible inputs,
+and simplify the modeling process for common situations.
+The classes do not add any algorithms beyond what's available
+in the procedural code, and most of the object methods
+are simple wrappers around the corresponding procedural code.
 
 Let's use each of these pvlib modeling paradigms
 to calculate the yearly energy yield for a given hardware
@@ -33,23 +34,31 @@ configuration at a handful of sites listed below.
 
     import pandas as pd
     import matplotlib.pyplot as plt
+    
+    # seaborn makes the plots look nicer
     import seaborn as sns
     sns.set_color_codes()
     
     times = pd.DatetimeIndex(start='2015', end='2016', freq='1h')
     
     # very approximate
-    coordinates = [(30, -110, 'Tucson'),
-                   (35, -105, 'Albuquerque'),
-                   (40, -120, 'San Francisco'),
-                   (50, 10, 'Berlin')]
+    # latitude, longitude, name, altitude
+    coordinates = [(30, -110, 'Tucson', 700),
+                   (35, -105, 'Albuquerque', 1500),
+                   (40, -120, 'San Francisco', 10),
+                   (50, 10, 'Berlin', 34)]
     
     import pvlib
     
+    # get the module and inverter specifications from SAM
     sandia_modules = pvlib.pvsystem.retrieve_sam('SandiaMod')
     sapm_inverters = pvlib.pvsystem.retrieve_sam('sandiainverter')
     module = sandia_modules['Canadian_Solar_CS5P_220M___2009_']
     inverter = sapm_inverters['ABB__MICRO_0_25_I_OUTD_US_208_208V__CEC_2014_']
+    
+    # specify constant ambient air temp and wind for simplicity
+    temp_air = 20
+    wind_speed = 0
 
 
 Procedural
@@ -67,13 +76,15 @@ to accomplish our system modeling goal:
               'surface_azimuth': 180}
 
     energies = {}
-    for latitude, longitude, name in coordinates:
+    for latitude, longitude, name, altitude in coordinates:
         system['surface_tilt'] = latitude
-        cs = pvlib.clearsky.ineichen(times, latitude, longitude)
+        cs = pvlib.clearsky.ineichen(times, latitude, longitude, altitude=altitude)
         solpos = pvlib.solarposition.get_solarposition(times, latitude, longitude)
         dni_extra = pvlib.irradiance.extraradiation(times)
         dni_extra = pd.Series(dni_extra, index=times)
         airmass = pvlib.atmosphere.relativeairmass(solpos['apparent_zenith'])
+        pressure = pvlib.atmosphere.alt2pres(altitude)
+        am_abs = pvlib.atmosphere.absoluteairmass(airmass, pressure)
         aoi = pvlib.irradiance.aoi(system['surface_tilt'], system['surface_azimuth'],
                                    solpos['apparent_zenith'], solpos['azimuth'])
         total_irrad = pvlib.irradiance.total_irrad(system['surface_tilt'],
@@ -83,10 +94,11 @@ to accomplish our system modeling goal:
                                                    cs['dni'], cs['ghi'], cs['dhi'],
                                                    dni_extra=dni_extra,
                                                    model='haydavies')
-        temps = pvlib.pvsystem.sapm_celltemp(total_irrad['poa_global'], 0, 20)
+        temps = pvlib.pvsystem.sapm_celltemp(total_irrad['poa_global'],
+                                             wind_speed, temp_air)
         dc = pvlib.pvsystem.sapm(module, total_irrad['poa_direct'],
                                  total_irrad['poa_diffuse'], temps['temp_cell'],
-                                 airmass, aoi)
+                                 am_abs, aoi)
         ac = pvlib.pvsystem.snlinverter(inverter, dc['v_mp'], dc['p_mp'])
         annual_energy = ac.sum()
         energies[name] = annual_energy
@@ -105,11 +117,11 @@ Object oriented (Location, PVSystem, ModelChain)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The first object oriented paradigm uses a model where
-a :class:`PVSystem <pvlib.pvsystem.PVSystem>` object represents an
+a :py:class:`~pvlib.pvsystem.PVSystem` object represents an
 assembled collection of modules, inverters, etc.,
-a :class:`Location <pvlib.location.Location>` object represents a
+a :py:class:`~pvlib.location.Location` object represents a
 particular place on the planet,
-and a :class:`ModelChain <pvlib.modelchain.ModelChain>` object describes
+and a :py:class:`~pvlib.modelchain.ModelChain` object describes
 the modeling chain used to calculate PV output at that Location.
 This can be a useful paradigm if you prefer to think about
 the PV system and its location as separate concepts or if
@@ -118,9 +130,9 @@ It can also be helpful if you make extensive use of Location-specific
 methods for other calculations.
 
 The following code demonstrates how to use
-:class:`Location <pvlib.location.Location>`,
-:class:`PVSystem <pvlib.pvsystem.PVSystem>`, and
-:class:`ModelChain <pvlib.modelchain.ModelChain>`
+:py:class:`~pvlib.location.Location`,
+:py:class:`~pvlib.pvsystem.PVSystem`, and
+:py:class:`~pvlib.modelchain.ModelChain`
 objects to accomplish our system modeling goal:
 
 .. ipython:: python
@@ -129,57 +141,86 @@ objects to accomplish our system modeling goal:
     from pvlib.location import Location
     from pvlib.modelchain import ModelChain
     
-    system = PVSystem(module, inverter, **other_params)
+    system = PVSystem(module_parameters=module,
+                      inverter_parameters=inverter)
     
     energies = {}
-    for latitude, longitude, name in coordinates:
-        location = Location(latitude, longitude)
-        # not yet clear what, exactly, goes into ModelChain(s)
-        mc = ModelChain(system, location, times,
-                        'south_at_latitude', **other_modelchain_params)
-        output = mc.run_model()
-        annual_energy = output['power'].sum()
+    for latitude, longitude, name, altitude in coordinates:
+        location = Location(latitude, longitude, name=name, altitude=altitude)
+        # very experimental
+        mc = ModelChain(system, location,
+                        orientation_strategy='south_at_latitude_tilt')
+        # optional parameters for irradiance and weather data
+        dc, ac = mc.run_model(times)
+        annual_energy = ac.sum()
         energies[name] = annual_energy
     
-    #energies = pd.DataFrame(energies)
-    #energies.plot()
+    energies = pd.Series(energies)
+    
+    # based on the parameters specified above, these are in W*hrs
+    print(energies.round(0))
+    
+    energies.plot(kind='bar', rot=0)
+    @savefig modelchain-energies.png width=6in
+    plt.ylabel('Yearly energy yield (W hr)')
 
 
 Object oriented (LocalizedPVSystem)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The second object oriented paradigm uses a model where a 
-:class:`LocalizedPVSystem <pvlib.pvsystem.LocalizedPVSystem>` represents a
+:py:class:`~pvlib.pvsystem.LocalizedPVSystem` represents a
 PV system at a particular place on the planet.
 This can be a useful paradigm if you're thinking about
 a power plant that already exists.
 
 The following code demonstrates how to use a
-:class:`LocalizedPVSystem <pvlib.pvsystem.LocalizedPVSystem>`
+:py:class:`~pvlib.pvsystem.LocalizedPVSystem`
 object to accomplish our modeling goal:
 
 .. ipython:: python
     
-    from pvlib.pvsystem import PVSystem, LocalizedPVSystem
-
-    module = 
-    inverter = 
-    other_system_params = {} # sometime helpful to break apart
-    base_system = PVSystem(module, inverter, **other_system_params)
+    from pvlib.pvsystem import LocalizedPVSystem
 
     energies = {}
-    for latitude, longitude, name in coordinates:
-        localized_system = base_system.localize(latitude, longitude, name=name)
-        localized_system.surface_tilt = latitude
-        cs = localized_system.get_clearsky(times)
-        solpos = localized_system.get_solarposition(times)
-        total_irrad = localized_system.get_irradiance(times, **solpos, **cs)
-        power = localized_system.get_power(stuff)
-        annual_energy = power.sum()
+    for latitude, longitude, name, altitude in coordinates:
+        localized_system = LocalizedPVSystem(module_parameters=module,
+                                             inverter_parameters=inverter,
+                                             surface_tilt=latitude,
+                                             surface_azimuth=180,
+                                             latitude=latitude,
+                                             longitude=longitude,
+                                             name=name,
+                                             altitude=altitude)
+        clearsky = localized_system.get_clearsky(times)
+        solar_position = localized_system.get_solarposition(times)
+        total_irrad = localized_system.get_irradiance(solar_position['apparent_zenith'],
+                                                      solar_position['azimuth'],
+                                                      clearsky['dni'],
+                                                      clearsky['ghi'],
+                                                      clearsky['dhi'])
+        temps = localized_system.sapm_celltemp(total_irrad['poa_global'],
+                                               wind_speed, temp_air)
+        aoi = localized_system.get_aoi(solar_position['apparent_zenith'],
+                                       solar_position['azimuth'])
+        airmass = localized_system.get_airmass(solar_position=solar_position)
+        dc = localized_system.sapm(total_irrad['poa_direct'],
+                                   total_irrad['poa_diffuse'],
+                                   temps['temp_cell'],
+                                   airmass['airmass_absolute'],
+                                   aoi)
+        ac = localized_system.snlinverter(dc['v_mp'], dc['p_mp'])
+        annual_energy = ac.sum()
         energies[name] = annual_energy
     
-    #energies = pd.DataFrame(energies)
-    #energies.plot()
+    energies = pd.Series(energies)
+    
+    # based on the parameters specified above, these are in W*hrs
+    print(energies.round(0))
+    
+    energies.plot(kind='bar', rot=0)
+    @savefig localized-pvsystem-energies.png width=6in
+    plt.ylabel('Yearly energy yield (W hr)')
 
 
 User extensions

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.

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

@@ -7,19 +7,49 @@ This is a major release from 0.2.2.
 We recommend that all users upgrade to this version after testing
 their code for compatibility and updating as necessary.
 
+
 Enhancements
 ~~~~~~~~~~~~
 
-* Adds ``PVSystem`` and ``SingleAxisTracker`` classes. (:issue:`17`)
+* Adds ``PVSystem``, ``LocalizedPVSystem``, ``ModelChain``,
+  and ``SingleAxisTracker`` classes. (:issue:`17`)
 * Replaces ``location`` arguments with ``latitude``, ``longitude``,
   ``altitude``, and ``tz`` as appropriate.
   This separates the object-oriented API from the procedural API.
   (:issue:`17`)
-
+* ``Location`` classes can be created from TMY2/TMY3 metadata
+  using the ``from_tmy`` constructor.
+* ``Location`` classes gain the ``get_solarposition``, ``get_clearsky``,
+  and ``get_airmass`` functions.
+* Add Package Overview and Classes pages to documentation.
+* Adds support for Appveyor, a Windows continuous integration service.
+  (:issue:`111`)
+* The readthedocs documentation build now uses conda packages
+  instead of mock packages. This enables code to be run
+  and figures to be generated during the documentation builds.
+  (:issue:`104`)
+* Reconfigures TravisCI builds and adds e.g. ``has_numba`` decorators
+  to the test suite. The result is that the TravisCI test suite runs
+  almost 10x faster and users do not have to install all optional
+  dependencies to run the test suite. (:issue:`109`)
+* Adds more unit tests that test that the return values are
+  actually correct.
+* Add ``atmosphere.APPARENT_ZENITH_MODELS`` and
+  ``atmosphere.TRUE_ZENITH_MODELS`` to enable code that can
+  automatically determine which type of zenith data to use
+  e.g. ``Location.get_airmass``.
+* Change default ``Location`` timezone to ``'UTC'``.
 
 Bug fixes
 ~~~~~~~~~
 
+* ``pvsystem.sapm_celltemp`` argument names now follow the
+  variable conventions.
+* ``irradiance.total_irrad`` now follows the variable conventions.
+  (:issue:`105`)
+* Fixed the metadata key specification in documentation of the
+  readtmy2 function.
+
 
 Contributors
 ~~~~~~~~~~~~

pvlib/atmosphere.py

@@ -11,10 +11,11 @@
 
 import numpy as np
 
-AIRMASS_MODELS = ['kastenyoung1989', 'kasten1966', 'simple', 
-                  'pickering2002', 'youngirvine1967', 'young1994',
-                  'gueymard1993']
-                  
+APPARENT_ZENITH_MODELS = ('simple', 'kasten1966', 'kastenyoung1989',
+                          'gueymard1993', 'pickering2002')
+TRUE_ZENITH_MODELS = ('youngirvine1967', 'young1994')
+AIRMASS_MODELS = APPARENT_ZENITH_MODELS + TRUE_ZENITH_MODELS
+
 
 def pres2alt(pressure):
     '''
@@ -143,12 +144,12 @@ def absoluteairmass(airmass_relative, pressure=101325.):
 
 def relativeairmass(zenith, model='kastenyoung1989'):
     '''
-    Gives the relative (not pressure-corrected) airmass
+    Gives the relative (not pressure-corrected) airmass.
 
-    Gives the airmass at sea-level when given a sun zenith angle, z (in 
-    degrees). 
-    The "model" variable allows selection of different airmass models
-    (described below). "model" must be a valid string. If "model" is not 
+    Gives the airmass at sea-level when given a sun zenith angle
+    (in degrees). 
+    The ``model`` variable allows selection of different airmass models
+    (described below). If ``model`` is not 
     included or is not valid, the default model is 'kastenyoung1989'.
 
     Parameters