BUG: ENH: update spa_files to patch timezone bug

pvlib/spa_c_files/README.md

@@ -1,34 +1,81 @@
 README
 ------
 
-NREL provides a C implementation of the solar position algorithm 
-described in 
-[Reda, I.; Andreas, A. (2003). Solar Position Algorithm for Solar Radiation Applications. 55 pp.; NREL Report No. TP-560-34302](
-http://www.nrel.gov/docs/fy08osti/34302.pdf).
+NREL provides a C implementation of the solar position algorithm described in
+[Reda, I.; Andreas, A. (2003). Solar Position Algorithm for Solar Radiation Applications. 55 pp.; NREL Report No. TP-560-34302](http://www.nrel.gov/docs/fy08osti/34302.pdf).
 
 This folder contains the files required to make NREL's C code accessible
 to the ``pvlib-python`` package. We use the Cython package to wrap NREL's SPA 
 implementation. 
 
-** Due to licensing issues, you must download the NREL C files from their 
-[website](http://www.nrel.gov/midc/spa) **
-
-Download the ``spa.c`` and ``spa.h`` files from NREL, 
-and copy them into the ``pvlib/spa_c_files`` directory. 
+** Due to licensing issues, the [SPA C files](https://midcdmz.nrel.gov/spa/) can
+_not_ be included in the pvlib-python distribution. The SPA C files will be
+downloaded when you build the Python extension. By using this module you agree
+to the NREL license in SPA_NOTICE. **
 
 There are a total of 5 files needed to compile the C code, described below:
 
 * ``spa.c``: original C code from NREL 
 * ``spa.h``: header file for spa.c
-* ``cspa_py.pxd``: a cython header file which essentially tells cython which parts of the main header file to pay attention to
-* ``spa_py.pyx``: the cython code used to define both functions in the python namespace. NOTE: It is possible to provide user access to other paramters of the SPA algorithm through modifying this file 
+* ``cspa_py.pxd``: a cython header file which essentially tells cython which
+  parts of the main header file to pay attention to
+* ``spa_py.pyx``: the cython code used to define both functions in the python
+  namespace. NOTE: It is possible to provide user access to other paramters of
+  the SPA algorithm through modifying this file 
 * ``setup.py``: a distutils file which performs the compiling of the cython code
 
 The cython compilation process produces two files:
 * ``spa_py.c``: an intermediate cython c file
-* ``spa_py.so``: the python module which can be imported into a namespace
+* ``spa_py.so`` or ``spa_py.<cpyver-platform>.pyd``: the python module which
+  can be imported into a namespace
+
+To create the SPA Python extension, use the following shell command inside this
+folder:
+
+    $ python setup.py build_ext --inplace
+
+Executing the build command will also download the ``spa.c`` and ``spa.h``
+files from NREL and copy them into the ``pvlib/spa_c_files`` directory.
+
+This build process may not be not compatible with Python-2.7.
+
+There are four optional keyword arguments `delta_ut1=0`, `slope=30.0`,
+`azm_rotation=-10`, `atmos_refract` that effect four optional return values
+`incidence`, `suntransit`, `sunrise`, and `sunset`. If not given, the defaults
+shown are used.
+
+There is an example in `spa_py_example.py` that contains a test function called
+`spa_calc_example` that users can use to check that the result is consistent
+with expected values:
 
-To process the original 5 files, 
-use the following shell command inside this folder
-
- $ python setup.py build_ext --inplace
+    >>> from spa_py_example import spa_calc_example
+    >>> r = spa_calc_example()
+    {
+        'year': 2004,
+        'month': 10,
+        'day': 17,
+        'hour': 12,
+        'minute': 30,
+        'second': 30.0,
+        'delta_ut1': 0.0,
+        'delta_t': 67.0,
+        'time_zone': -7.0,
+        'longitude': -105.1786,
+        'latitude': 39.742476,
+        'elevation': 1830.14,
+        'pressure': 820.0,
+        'temperature': 11.0,
+        'slope': 30.0,
+        'azm_rotation': -10.0,
+        'atmos_refract': 0.5667,
+        'function': 3,
+        'e0': 39.59209464796398,
+        'e': 39.60858878898177,
+        'zenith': 50.39141121101823,
+        'azimuth_astro': 14.311961805946808,
+        'azimuth': 194.3119618059468,
+        'incidence': 25.42168493680471,
+        'suntransit': 11.765833793714224,
+        'sunrise': 6.22578372122376,
+        'sunset': 17.320379610556166
+    }

pvlib/spa_c_files/SPA_NOTICE.md

@@ -1,5 +1,39 @@
-NOTICE
-Copyright © 2008-2011 Alliance for Sustainable Energy, LLC, All Rights Reserved
-The Solar Position Algorithm ("Software") is code in development prepared by employees of the Alliance for Sustainable Energy, LLC, (hereinafter the "Contractor"), under Contract No. DE-AC36-08GO28308 ("Contract") with the U.S. Department of Energy (the "DOE"). The United States Government has been granted for itself and others acting on its behalf a paid-up, non-exclusive, irrevocable, worldwide license in the Software to reproduce, prepare derivative works, and perform publicly and display publicly. Beginning five (5) years after the date permission to assert copyright is obtained from the DOE, and subject to any subsequent five (5) year renewals, the United States Government is granted for itself and others acting on its behalf a paid-up, non-exclusive, irrevocable, worldwide license in the Software to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so. If the Contractor ceases to make this computer software available, it may be obtained from DOE's Office of Scientific and Technical Information's Energy Science and Technology Software Center (ESTSC) at P.O. Box 1020, Oak Ridge, TN 37831-1020. THIS SOFTWARE IS PROVIDED BY THE CONTRACTOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE CONTRACTOR OR THE U.S. GOVERNMENT BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER, INCLUDING BUT NOT LIMITED TO CLAIMS ASSOCIATED WITH THE LOSS OF DATA OR PROFITS, WHICH MAY RESULT FROM AN ACTION IN CONTRACT, NEGLIGENCE OR OTHER TORTIOUS CLAIM THAT ARISES OUT OF OR IN CONNECTION WITH THE ACCESS, USE OR PERFORMANCE OF THIS SOFTWARE.
-The Software is being provided for internal, noncommercial purposes only and shall not be re-distributed. Please contact Jennifer Ramsey in the NREL Commercialization and Technology Transfer Office for information concerning a commercial license to use the Software.
-As a condition of using the Software in an application, the developer of the application agrees to reference the use of the Software and make this Notice readily accessible to any end-user in a Help|About screen or equivalent manner.
+# NOTICE
+
+Copyright (c) 2008-2011 Alliance for Sustainable Energy, LLC, All Rights Reserved
+
+The Solar Position Algorithm ("Software") is code in development prepared by 
+employees of the Alliance for Sustainable Energy, LLC, (hereinafter the 
+"Contractor"), under Contract No. DE-AC36-08GO28308 ("Contract") with the 
+U.S. Department of Energy (the "DOE"). The United States Government has been 
+granted for itself and others acting on its behalf a paid-up, non-exclusive, 
+irrevocable, worldwide license in the Software to reproduce, prepare 
+derivative works, and perform publicly and display publicly. Beginning five 
+(5) years after the date permission to assert copyright is obtained from the 
+DOE, and subject to any subsequent five (5) year renewals, the United States 
+Government is granted for itself and others acting on its behalf a paid-up, 
+non-exclusive, irrevocable, worldwide license in the Software to reproduce, 
+prepare derivative works, distribute copies to the public, perform publicly 
+and display publicly, and to permit others to do so. If the Contractor ceases 
+to make this computer software available, it may be obtained from DOE's 
+Office of Scientific and Technical Information's Energy Science and 
+Technology Software Center (ESTSC) at P.O. Box 1020, Oak Ridge, TN 
+37831-1020. THIS SOFTWARE IS PROVIDED BY THE CONTRACTOR "AS IS" AND ANY 
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING BUT NOT LIMITED TO, THE IMPLIED 
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
+DISCLAIMED. IN NO EVENT SHALL THE CONTRACTOR OR THE U.S. GOVERNMENT BE LIABLE 
+FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER, 
+INCLUDING BUT NOT LIMITED TO CLAIMS ASSOCIATED WITH THE LOSS OF DATA OR 
+PROFITS, WHICH MAY RESULT FROM AN ACTION IN CONTRACT, NEGLIGENCE OR OTHER 
+TORTIOUS CLAIM THAT ARISES OUT OF OR IN CONNECTION WITH THE ACCESS, USE OR 
+PERFORMANCE OF THIS SOFTWARE.
+
+The Software is being provided for internal, noncommercial purposes only and 
+shall not be re-distributed. Please contact [Jean 
+Schulte](mailto:[email protected]) in the NREL Commercialization and 
+Technology Transfer Office for information concerning a commercial license to 
+use the Software.
+
+As a condition of using the Software in an application, the developer of the 
+application agrees to reference the use of the Software and make this Notice 
+readily accessible to any end-user in a Help|About screen or equivalent manner.

pvlib/spa_c_files/cspa_py.pxd

@@ -1,40 +1,43 @@
 cdef extern from "spa.h":
-	ctypedef struct spa_data:
-		int year           
-		int month          
-		int day            
-		int hour           
-		int minute         
-		double second  
-		double delta_ut1   
-		double delta_t     
-		double timezone    
-		double longitude   
-		double latitude        
+    ctypedef enum:
+        SPA_ZA, SPA_ZA_INC, SPA_ZA_RTS, SPA_ALL
 
-		double elevation       
+    ctypedef struct spa_data:
+        int year
+        int month
+        int day
+        int hour
+        int minute
+        double second
+        double delta_ut1
+        double delta_t
+        double time_zone
+        double longitude
+        double latitude
 
-		double pressure        
+        double elevation
 
-		double temperature     
+        double pressure
 
-		double slope           
+        double temperature
 
-		double azm_rotation        
+        double slope
 
-		double atmos_refract    
+        double azm_rotation
 
-		int function       
+        double atmos_refract
 
-		double e0
-		double e
-		double zenith     
-		double azimuth_astro
-		double azimuth    
-		double incidence  
+        int function
 
-		double suntransit 
-		double sunrise    
-		double sunset   
+        double e0
+        double e
+        double zenith
+        double azimuth_astro
+        double azimuth
+        double incidence
 
-	int spa_calculate(spa_data *spa)
+        double suntransit
+        double sunrise
+        double sunset
+
+    int spa_calculate(spa_data *spa)

pvlib/spa_c_files/setup.py

@@ -1,9 +1,41 @@
-#setup.py
+# setup.py
 
+import os
+from urllib import request, parse
 from distutils.core import setup
 from distutils.extension import Extension
 from Cython.Build import cythonize
 
+DIRNAME = os.path.dirname(__file__)
+SPA_C_URL = r'https://midcdmz.nrel.gov/apps/download.pl'
+SPA_H_URL = r'https://midcdmz.nrel.gov/spa/spa.h'
+VALUES = {'software': 'SPA'}
+LICENSE = 'SPA_NOTICE.md'
+
+with open(os.path.join(DIRNAME, LICENSE)) as f:
+    print(f.read())
+
+print('\nEnter the following information to accept the NREL LICENSE ...\n')
+VALUES['name'] = input('Name: ')
+VALUES['company'] = input('Company (or enter "Individual"): ')
+VALUES['country'] = input('Country: ')
+VALUES['email'] = input('Email (optional): ')
+DATA = parse.urlencode(VALUES).encode('ascii')
+
+# get spa.c
+REQ = request.Request(SPA_C_URL, DATA)
+with request.urlopen(REQ) as response:
+    SPA_C = response.read()
+SPA_C = SPA_C.replace(b'timezone', b'time_zone')
+with open(os.path.join(DIRNAME, 'spa.c'), 'wb') as f:
+    f.write(SPA_C)
+# get spa.h
+with request.urlopen(SPA_H_URL) as response:
+    SPA_H = response.read()
+SPA_H = SPA_H.replace(b'timezone', b'time_zone')
+with open(os.path.join(DIRNAME, 'spa.h'), 'wb') as f:
+    f.write(SPA_H)
+
 setup(
-    ext_modules = cythonize([Extension("spa_py", ["spa_py.pyx",'spa.c'])])
+    ext_modules=cythonize([Extension('spa_py', ['spa_py.pyx', 'spa.c'])])
 )