Merge remote-tracking branch 'pvlib/master' into forecast

Author: wholmgren

LICENSE

@@ -1,6 +1,9 @@
 Copyright (c) 2013, Sandia National Labs
 All rights reserved.
 
+Copyright (c) 2014-2016, PVLIB Python Developers
+All rights reserved.
+
 Redistribution and use in source and binary forms, with or without modification,
 are permitted provided that the following conditions are met:
 

README.md

@@ -8,87 +8,47 @@ pvlib-python
 [![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.50141.svg)](http://dx.doi.org/10.5281/zenodo.50141)
 
 
-pvlib-python is a community supported tool that provides a set of documented functions for simulating the performance of photovoltaic energy systems. The toolbox was originally developed in MATLAB at Sandia National Laboratories and it implements many of the models and methods developed at the Labs. More information on Sandia Labs PV performance modeling programs can be found at https://pvpmc.sandia.gov/. We collaborate with the PVLIB-MATLAB project, but operate independently of it.
+PVLIB Python is a community supported tool that provides a set of
+functions and classes for simulating the performance of photovoltaic
+energy systems. PVLIB Python was originally ported from the PVLIB MATLAB
+toolbox developed at Sandia National Laboratories and it implements many
+of the models and methods developed at the Labs. More information on
+Sandia Labs PV performance modeling programs can be found at
+https://pvpmc.sandia.gov/. We collaborate with the PVLIB MATLAB project,
+but operate independently of it.
 
 
 Documentation
 =============
 
-Full documentation can be found at [readthedocs](http://pvlib-python.readthedocs.org/en/latest/).
-
-
-Contributing
-============
-
-We need your help to make pvlib-python a great tool! Please see the [Contributing page](http://pvlib-python.readthedocs.org/en/latest/contributing.html) for more on how you can contribute. The long-term success of pvlib-python requires substantial community support.
+Full documentation can be found at [readthedocs](http://pvlib-python.readthedocs.io/en/latest/).
 
 
 Installation
 ============
 
-To obtain the most recent stable release, just use ``pip`` or ``conda``:
-
-```
-pip install pvlib
-```
-
-```
-conda install -c pvlib pvlib
-```
-
-Please see the [Installation page](http://pvlib-python.readthedocs.org/en/latest/installation.html) of the documentation for complete instructions.
-
-
-NREL SPA algorithm
-------------------
-pvlib-python is distributed with several validated, high-precision, and high-performance solar position calculators.
-It also includes wrappers for the official NREL SPA algorithm.
-To use the NREL SPA algorithm, a pip install from the web cannot be used. Instead:
-
-1. Download the pvlib repository from https://github.com/pvlib/pvlib-python.git
-2. Download the SPA files from [NREL](http://www.nrel.gov/midc/spa/)
-3. Copy the SPA files into ``pvlib-python/pvlib/spa_c_files``
-4. From the ``pvlib-python`` directory, run ``pip uninstall pvlib`` followed by ``pip install . ``
+pvlib-python releases may be installed using the ``pip`` and ``conda`` tools.
+Please see the [Installation page](http://pvlib-python.readthedocs.io/en/latest/installation.html) of the documentation for complete instructions.
 
+pvlib-python is compatible with Python versions 2.7, 3.4, 3.5
 
-Usage
-=====
-You're now ready to start some version of the Python interpreter and use pvlib. The easiest way to start is with one of our [Jupyter](http://jupyter.org) notebook tutorials:
 
-1. Use the nbviewer website to choose a tutorial to experiment with. Go to our [nbviewer tutorial page](http://nbviewer.jupyter.org/github/pvlib/pvlib-python/tree/master/docs/tutorials/), click on e.g. [``tmy_to_power.ipynb``](http://nbviewer.jupyter.org/github/pvlib/pvlib-python/blob/master/docs/tutorials/tmy_to_power.ipynb), and then click on the download symbol.
-1. Start the Jupyter Notebook server: ``jupyter notebook``. This should open a web browser with the Jupyter Notebook's file/folder listing. If not, navigate to the url shown in the command line history, likely ``http://localhost:8888``
-2. In Jupyter Notebook, navigate to the file that you downloaded in step one and open it.
-2. Use ``shift-enter`` to execute the notebook cell-by-cell. There is also a Play button that will execute all of the cells in the notebook.
-
-You can also use a Jupyter notebook or any other Python interpreter to experiment with the simple code in the [Package overview](http://pvlib-python.readthedocs.org/en/latest/package_overview.html) section of the documentation.
+Contributing
+============
 
-Many good online resources exist for getting started with scientific Python.
+We need your help to make pvlib-python a great tool!
+Please see the [Contributing page](http://pvlib-python.readthedocs.io/en/latest/contributing.html) for more on how you can contribute.
+The long-term success of pvlib-python requires substantial community support.
 
 
 License
 =======
-3 clause BSD.
-
-
-Compatibility
-=============
-
-pvlib-python is compatible with Python versions 2.7, 3.3, 3.4, 3.5 and Pandas versions 0.13.1 through 0.18. Note that our Numba-accelerated solar position algorithms have more specific version requirements that will be resolved by the Numba installer.
-
-For Linux + Python 3 users: Continuum's Python 3.x SciPy conda package is not compiled properly and has a few bugs related to complex arithmetic. The most common place for these bugs to show up when using pvlib-python is in calculating IV curve parameters using the ``singlediode`` function. We reported [the issue](https://github.com/ContinuumIO/anaconda-issues/issues/425) to Continuum and are waiting for it to be fixed. In the meantime, you can compile your own SciPy distribution, or you can use this trick on Python 3.3 and 3.4 (not 3.5): Downgrade your NumPy to 1.8 and SciPy to 0.14, then install whatever version of pandas you want but without dependencies. The conda commands for this are:
 
-```
-conda install numpy=1.8 scipy=0.14
-conda install pandas --no-deps
-```
+BSD 3-clause
 
-For Windows + Python 2.7 users: Continuum's Python 2.7 SciPy 0.16.1 and 0.17.0 packages are not compiled properly and will crash your Python interpreter if you use our Linke turbidity lookup function. See [Anaconda issue 650](https://github.com/ContinuumIO/anaconda-issues/issues/650) for more.
 
-
-Testing
+Contact
 =======
-Testing can easily be accomplished by running ``nosetests`` on the pvlib directory:
-```
-nosetests -v pvlib
-```
-Unit test code should be placed in the corresponding test module in the pvlib/test directory. Use ``pip`` or ``conda`` to install ``nose``. Developers must include comprehensive tests for any additions or modifications to pvlib.
+
+Please use our [issues page](https://github.com/pvlib/pvlib-python/issues)
+to contact the developers and pvlib community.

docs/sphinx/source/contributing.rst

@@ -80,10 +80,32 @@ commits to the main repo. Exceptions may be made for extremely minor
 changes, such as fixing documentation typos.
 
 
+Testing
+-------
+
+pvlib's unit tests can easily be run by executing ``nosetests`` on the
+pvlib directory:
+
+``nosetests -v pvlib``
+
+or, for a single module:
+
+``nosetests -v pvlib/tests/test_clearsky.py``
+
+While copy/paste coding should generally be avoided, it's a great way
+to learn how to write unit tests!
+
+Unit test code should be placed in the corresponding test module in the
+pvlib/test directory.
+
+Developers **must** include comprehensive tests for any additions or
+modifications to pvlib.
+
+
 This documentation
 ------------------
+
 If this documentation is unclear, help us improve it! Consider looking
-at `IPython <https://github.com/ipython/ipython/wiki/Dev:-Index>`_,
-`pandas <https://github.com/pydata/pandas/wiki>`_, and
-`Sandia-Labs/PVLIB_Python#33 <https://github.com/Sandia-Labs/
-PVLIB_Python/issues/33>`_ for inspiration.
+at the `pandas
+documentation <http://pandas.pydata.org/pandas-docs/version/0.18.1/
+contributing.html>`_ for inspiration.

docs/sphinx/source/index.rst

@@ -1,12 +1,14 @@
 pvlib-python
 ========================================
 
-pvlib-python provides a set of documented functions for simulating the
-performance of photovoltaic energy systems. The toolbox was originally
-developed in MATLAB at Sandia National Laboratories and it implements
-many of the models and methods developed at the Labs. More information
-on Sandia Labs PV performance modeling programs can be found at
-https://pvpmc.sandia.gov/.
+PVLIB Python is a community supported tool that provides a set of
+functions and classes for simulating the performance of photovoltaic
+energy systems. PVLIB Python was originally ported from the PVLIB MATLAB
+toolbox developed at Sandia National Laboratories and it implements many
+of the models and methods developed at the Labs. More information on
+Sandia Labs PV performance modeling programs can be found at
+https://pvpmc.sandia.gov/. We collaborate with the PVLIB MATLAB project,
+but operate independently of it.
 
 The source code for pvlib-python is hosted on `github
 <https://github.com/pvlib/pvlib-python>`_.

docs/sphinx/source/installation.rst

@@ -194,6 +194,50 @@ interpreter will also work.
 Remember to ``source activate pvlibdev`` (or whatever you named your
 environment) when you start a new shell or terminal.
 
+.. _nrelspa:
+
+NREL SPA algorithm
+------------------
+
+pvlib-python is distributed with several validated, high-precision, and
+high-performance solar position calculators. We strongly recommend using
+the built-in solar position calculators.
+
+pvlib-python also includes unsupported wrappers for the official NREL
+SPA algorithm. NREL's license does not allow redistribution of the
+source code, so you must jump through some hoops to use it with pvlib.
+You will need a C compiler to use this code.
+
+To install the NREL SPA algorithm for use with pvlib:
+
+#. Download the pvlib repository (as described in :ref:`obtainsource`)
+#. Download the `SPA files from NREL <http://www.nrel.gov/midc/spa/>`_
+#. Copy the SPA files into ``pvlib-python/pvlib/spa_c_files``
+#. From the ``pvlib-python`` directory, run ``pip uninstall pvlib``
+   followed by ``pip install .``
+
+.. _compatibility:
+
+Compatibility
+-------------
+
+pvlib-python is compatible with Python versions 2.7, 3.4, 3.5 and Pandas
+versions 0.13.1 or newer.
+
+There have been several problems with Continuum's Anaconda packages that
+have impacted pvlib users. The current problems that we're aware of are
+listed below:
+
+#. For Windows + Python 2.7 users: Continuum's Python 2.7 SciPy 0.16.1,
+   0.17.0, 0.17.1 packages are not compiled properly and will crash your
+   Python interpreter if you use our Linke turbidity lookup function. See
+   `Anaconda issue 650
+   <https://github.com/ContinuumIO/anaconda-issues/issues/650>`_ for more.
+
+Note that our Numba-accelerated solar position algorithms have more
+specific version requirements that will be resolved by the Numba
+installer.
+
 .. _references:
 
 References

docs/sphinx/source/package_overview.rst

@@ -43,14 +43,14 @@ configuration at a handful of sites listed below.
     import seaborn as sns
     sns.set_color_codes()
 
-    times = pd.DatetimeIndex(start='2015', end='2016', freq='1h')
+    naive_times = pd.DatetimeIndex(start='2015', end='2016', freq='1h')
 
     # very approximate
-    # latitude, longitude, name, altitude
-    coordinates = [(30, -110, 'Tucson', 700),
-                   (35, -105, 'Albuquerque', 1500),
-                   (40, -120, 'San Francisco', 10),
-                   (50, 10, 'Berlin', 34)]
+    # latitude, longitude, name, altitude, timezone
+    coordinates = [(30, -110, 'Tucson', 700, 'Etc/GMT+7'),
+                   (35, -105, 'Albuquerque', 1500, 'Etc/GMT+7'),
+                   (40, -120, 'San Francisco', 10, 'Etc/GMT+8'),
+                   (50, 10, 'Berlin', 34, 'Etc/GMT-1')]
 
     import pvlib
 
@@ -80,7 +80,9 @@ to accomplish our system modeling goal:
               'surface_azimuth': 180}
 
     energies = {}
-    for latitude, longitude, name, altitude in coordinates:
+    # localize datetime indices (pvlib>=0.3.0)
+    for latitude, longitude, name, altitude, timezone in coordinates:
+        times = naive_times.tz_localize(timezone)
         system['surface_tilt'] = latitude
         cs = pvlib.clearsky.ineichen(times, latitude, longitude, altitude=altitude)
         solpos = pvlib.solarposition.get_solarposition(times, latitude, longitude)
@@ -125,8 +127,9 @@ a full understanding of what it is doing internally!
     from pvlib.modelchain import basic_chain
 
     energies = {}
-    for latitude, longitude, name, altitude in coordinates:
-        dc, ac = basic_chain(times, latitude, longitude,
+    for latitude, longitude, name, altitude, timezone in coordinates:
+        dc, ac = basic_chain(naive_times.tz_localize(timezone),
+                             latitude, longitude,
                              module, inverter,
                              altitude=altitude,
                              orientation_strategy='south_at_latitude_tilt')
@@ -173,14 +176,15 @@ objects to accomplish our system modeling goal:
                       inverter_parameters=inverter)
 
     energies = {}
-    for latitude, longitude, name, altitude in coordinates:
-        location = Location(latitude, longitude, name=name, altitude=altitude)
+    for latitude, longitude, name, altitude, timezone in coordinates:
+        location = Location(latitude, longitude, name=name, altitude=altitude,
+                            tz=timezone)
         # very experimental
         mc = ModelChain(system, location,
                         orientation_strategy='south_at_latitude_tilt')
         # model results (ac, dc) and intermediates (aoi, temps, etc.)
         # assigned as mc object attributes
-        mc.run_model(times)
+        mc.run_model(naive_times.tz_localize(timezone))
         annual_energy = mc.ac.sum()
         energies[name] = annual_energy
 
@@ -211,15 +215,17 @@ object to accomplish our modeling goal:
     from pvlib.pvsystem import LocalizedPVSystem
 
     energies = {}
-    for latitude, longitude, name, altitude in coordinates:
+    for latitude, longitude, name, altitude, timezone 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)
+                                             altitude=altitude,
+                                             tz=timezone)
+        times = naive_times.tz_localize(timezone)
         clearsky = localized_system.get_clearsky(times)
         solar_position = localized_system.get_solarposition(times)
         total_irrad = localized_system.get_irradiance(solar_position['apparent_zenith'],
@@ -283,4 +289,3 @@ The pvlib-python maintainers thank all of pvlib's contributors of issues
 and especially pull requests.
 The pvlib-python community thanks all of the
 maintainers and contributors to the PyData stack.
-

docs/sphinx/source/whatsnew.rst

@@ -6,6 +6,7 @@ What's New
 
 These are new features and improvements of note in each release.
 
+.. include:: whatsnew/v0.4.0.txt
 .. include:: whatsnew/v0.3.3.txt
 .. include:: whatsnew/v0.3.2.txt
 .. include:: whatsnew/v0.3.1.txt

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

@@ -1,6 +1,6 @@
 .. _whatsnew_0320:
 
-v0.3.1 (May 3, 2016)
+v0.3.2 (May 3, 2016)
 -----------------------
 
 This is a minor release from 0.3.1.