From 96b1a86f7e62936cf69414a64931ed44f9ec60ac Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Mon, 9 Mar 2015 21:15:28 -0700 Subject: [PATCH 01/14] updates documentation in most modules --- pvlib/atmosphere.py | 15 ++--- pvlib/clearsky.py | 78 +++++++++------------ pvlib/irradiance.py | 160 ++++++++++++++++---------------------------- pvlib/location.py | 39 ++++++----- pvlib/pvsystem.py | 69 +++++++++++-------- 5 files changed, 155 insertions(+), 206 deletions(-) diff --git a/pvlib/atmosphere.py b/pvlib/atmosphere.py index 5438017963..c5b40ebffb 100644 --- a/pvlib/atmosphere.py +++ b/pvlib/atmosphere.py @@ -1,5 +1,5 @@ """ -The atmosphere module contains methods to calculate +The ``atmosphere`` module contains methods to calculate relative and absolute airmass and to determine pressure from altitude or vice versa. """ @@ -18,7 +18,7 @@ def pres2alt(pressure): ''' - Determine altitude from site pressure + Determine altitude from site pressure. Parameters ---------- @@ -42,7 +42,7 @@ def pres2alt(pressure): Gravitational acceleration 9.80665 m/s^2 Lapse rate -6.5E-3 K/m Gas constant for air 287.053 J/(kgK) - Relative Humidity 0% + Relative Humidity 0% ============================ ================ References @@ -60,7 +60,7 @@ def pres2alt(pressure): def alt2pres(altitude): ''' - Determine site pressure from altitude + Determine site pressure from altitude. Parameters ---------- @@ -84,7 +84,7 @@ def alt2pres(altitude): Gravitational acceleration 9.80665 m/s^2 Lapse rate -6.5E-3 K/m Gas constant for air 287.053 J/(kgK) - Relative Humidity 0% + Relative Humidity 0% ============================ ================ References @@ -130,15 +130,10 @@ def absoluteairmass(AMrelative, pressure=101325.): References ---------- - [1] C. Gueymard, "Critical analysis and performance assessment of clear sky solar irradiance models using theoretical and measured data," Solar Energy, vol. 51, pp. 121-138, 1993. - See also - --------- - relativeairmass - ''' AMa = AMrelative * pressure / 101325. diff --git a/pvlib/clearsky.py b/pvlib/clearsky.py index 29a14956a5..d6be323222 100644 --- a/pvlib/clearsky.py +++ b/pvlib/clearsky.py @@ -1,5 +1,6 @@ """ -Contains several methods to calculate clear sky GHI, DNI, and DHI. +The ``clearsky`` module contains several methods +to calculate clear sky GHI, DNI, and DHI. """ from __future__ import division @@ -32,8 +33,9 @@ def ineichen(time, location, linke_turbidity=None, the clear-sky diffuse horizontal (DHI) component as the difference between GHI and DNI*cos(zenith) as presented in [1, 2]. A report on clear sky models found the Ineichen/Perez model to have excellent performance - with a minimal input data set [3]. Default values for Linke turbidity - provided by SoDa [4, 5]. + with a minimal input data set [3]. + + Default values for montly Linke turbidity provided by SoDa [4, 5]. Parameters ----------- @@ -42,9 +44,11 @@ def ineichen(time, location, linke_turbidity=None, location : pvlib.Location linke_turbidity : None or float + If None, uses ``LinkeTurbidities.mat`` lookup table. solarposition_method : string - See pvlib.solarposition.get_solarposition() + Sets the solar position algorithm. + See solarposition.get_solarposition() zenith_data : None or pandas.Series If None, ephemeris data will be calculated using ``solarposition_method``. @@ -55,21 +59,14 @@ def ineichen(time, location, linke_turbidity=None, airmass_data : None or pandas.Series If None, absolute air mass data will be calculated using ``airmass_model`` and location.alitude. + + interp_turbidity : bool + If ``True``, interpolates the monthly Linke turbidity values + found in ``LinkeTurbidities.mat`` to daily values. Returns -------- - - ClearSkyGHI : Dataframe. - the modeled global horizonal irradiance in W/m^2 provided - by the Ineichen clear-sky model. - - ClearSkyDNI : Dataframe. - the modeled direct normal irradiance in W/m^2 provided - by the Ineichen clear-sky model. - - ClearSkyDHI : Dataframe. - the calculated diffuse horizonal irradiance in W/m^2 - provided by the Ineichen clear-sky model. + DataFrame with the following columns: ``GHI, DNI, DHI``. Notes ----- @@ -78,7 +75,6 @@ def ineichen(time, location, linke_turbidity=None, the loop and feed it in as a variable, rather than having the function open the file each time it is called. - References ---------- @@ -235,7 +231,8 @@ def haurwitz(ApparentZenith): Returns ------- - pd.Series. The modeled global horizonal irradiance in W/m^2 provided + pd.Series + The modeled global horizonal irradiance in W/m^2 provided by the Haurwitz clear-sky model. Initial implementation of this algorithm by Matthew Reno. @@ -252,14 +249,6 @@ def haurwitz(ApparentZenith): [3] M. Reno, C. Hansen, and J. Stein, "Global Horizontal Irradiance Clear Sky Models: Implementation and Analysis", Sandia National Laboratories, SAND2012-2389, 2012. - - See Also - --------- - maketimestruct - makelocationstruct - ephemeris - spa - ineichen ''' cos_zenith = tools.cosd(ApparentZenith) @@ -296,34 +285,31 @@ def disc(GHI, SunZen, Time, pressure=101325): ---------- GHI : float or DataFrame - global horizontal irradiance in W/m^2. GHI must be >=0. + Global horizontal irradiance in W/m^2. - Z : float or DataFrame + SunZen : float or DataFrame True (not refraction - corrected) zenith angles in decimal degrees. - Z must be >=0 and <=180. - - doy : float or DataFrame - the day of the year. doy must be >= 1 and < 367. - - Other Parameters - ---------------- - pressure : float or DataFrame (optional, Default=101325) + Time : float or DataFrame + The day of the year. - site pressure in Pascal. Pressure may be measured + pressure : float or DataFrame + Site pressure in Pascal. Pressure may be measured or an average pressure may be calculated from site altitude. If pressure is omitted, standard pressure (101325 Pa) will be used, this is acceptable if the site is near sea level. If the site is not near - sea:level, inclusion of a measured or average pressure is highly + sea level, inclusion of a measured or average pressure is highly recommended. Returns ------- - DNI : float or DataFrame - The modeled direct normal irradiance in W/m^2 provided by the - Direct Insolation Simulation Code (DISC) model. - Kt : float or DataFrame - Ratio of global to extraterrestrial irradiance on a horizontal plane. + DataFrame with the following keys: + * ``DNI_gen_DISC``: The modeled direct normal irradiance in W/m^2 provided by the + Direct Insolation Simulation Code (DISC) model. + * ``Kt_gen_DISC``: Ratio of global to extraterrestrial + irradiance on a horizontal plane. + * ``AM``: Airmass + * ``Ztemp``: Zenith References ---------- @@ -339,11 +325,9 @@ def disc(GHI, SunZen, Time, pressure=101325): January 12, 2012 See Also - -------- - ephemeris - alt2pres + -------- + atmosphere.alt2pres dirint - ''' #create a temporary dataframe to house masked values, initially filled with NaN diff --git a/pvlib/irradiance.py b/pvlib/irradiance.py index 4dfcf0d685..7c50fdaf72 100644 --- a/pvlib/irradiance.py +++ b/pvlib/irradiance.py @@ -1,3 +1,10 @@ +""" +The ``irradiance`` module contains functions for modeling +global horizontal irradiance, direct normal irradiance, +diffuse horizontal irradiance, and total irradiance +under various conditions. +""" + from __future__ import division import logging @@ -44,7 +51,7 @@ def extraradiation(datetime_or_doy, solar_constant=1366.1, method='spencer'): method : string The method by which the ET radiation should be calculated. - Options include 'pyephem', 'spencer', 'asce'. + Options include ``'pyephem', 'spencer', 'asce'``. Returns ------- @@ -283,6 +290,23 @@ def poa_horizontal_ratio(surf_tilt, surf_az, sun_zen, sun_az): def beam_component(surf_tilt, surf_az, sun_zen, sun_az, DNI): """ Calculates the beam component of the plane of array irradiance. + + Parameters + ---------- + surf_tilt : float or Series. + Panel tilt from horizontal. + surf_az : float or Series. + Panel azimuth from north. + sun_zen : float or Series. + Solar zenith angle. + sun_az : float or Series. + Solar azimuth angle. + DNI : float or Series + Direct Normal Irradiance + + Returns + ------- + Series """ beam = DNI * aoi_projection(surf_tilt, surf_az, sun_zen, sun_az) beam[beam < 0] = 0 @@ -308,26 +332,42 @@ def total_irrad(surf_tilt, surf_az, Parameters ---------- - - + surf_tilt : float or Series. + Panel tilt from horizontal. + surf_az : float or Series. + Panel azimuth from north. + sun_zen : float or Series. + Solar zenith angle. + sun_az : float or Series. + Solar azimuth angle. + DNI : float or Series + Direct Normal Irradiance + GHI : float or Series + Global horizontal irradiance + DHI : float or Series + Diffuse horizontal irradiance + DNI_ET : float or Series + Extraterrestrial direct normal irradiance + AM : float or Series + Airmass + albedo : float + Surface albedo + surface_type : String + Surface type. See grounddiffuse. + model : String + Irradiance model. + model_perez : String + See perez. Returns ------- - - DataFrame with columns 'total', 'beam', 'sky', 'ground'. - + DataFrame with columns ``'total', 'beam', 'sky', 'ground'``. References ---------- - [1] Loutzenhiser P.G. et. al. "Empirical validation of models to compute solar irradiance on inclined surfaces for building energy simulation" 2007, Solar Energy vol. 81. pp. 254-267 - - - See also - -------- - ''' pvl_logger.debug('planeofarray.total_irrad()') @@ -404,26 +444,10 @@ def globalinplane(SurfTilt,SurfAz,AOI,DNI,In_Plane_SkyDiffuse, GR): Returns ------- - - E : float or DataFrame - Total in-plane irradiance (W/m^2) - Eb : float or DataFrame - Total in-plane beam irradiance (W/m^2) - Ediff : float or DataFrame - Total in-plane diffuse irradiance (W/m^2) - - See also - -------- - - pvl_grounddiffuse - pvl_getaoi - pvl_perez - pvl_reindl1990 - pvl_klucher1979 - pvl_haydavies1980 - pvl_isotropicsky - pvl_kingdiffuse - + DataFrame with the following keys: + * ``E`` : Total in-plane irradiance (W/m^2) + * ``Eb`` : Total in-plane beam irradiance (W/m^2) + * ``Ediff`` : Total in-plane diffuse irradiance (W/m^2) ''' Vars=locals() Expect={'SurfTilt':('num','x>=0'), @@ -471,9 +495,9 @@ def grounddiffuse(surf_tilt, ghi, albedo=.25, surface_type=None): Will be overridden if surface_type is supplied. surface_type: None or string in - 'urban', 'grass', 'fresh grass', 'snow', 'fresh snow', + ``'urban', 'grass', 'fresh grass', 'snow', 'fresh snow', 'asphalt', 'concrete', 'aluminum', 'copper', - 'fresh steel', 'dirty steel'. + 'fresh steel', 'dirty steel'``. Overrides albedo. Returns @@ -568,15 +592,6 @@ def isotropic(surf_tilt, DHI): [2] Hottel, H.C., Woertz, B.B., 1942. Evaluation of flat-plate solar heat collector. Trans. ASME 64, 91. - - See also - -------- - - pvl_reindl1990 - pvl_haydavies1980 - pvl_perez - pvl_klucher1979 - pvl_kingdiffuse ''' pvl_logger.debug('diffuse_sky.isotropic()') @@ -661,17 +676,6 @@ def klucher(surf_tilt, surf_az, DHI, GHI, sun_zen, sun_az): [2] Klucher, T.M., 1979. Evaluation of models to predict insolation on tilted surfaces. Solar Energy 23 (2), 111-114. - - See also - -------- - pvl_ephemeris - pvl_extraradiation - pvl_isotropicsky - pvl_haydavies1980 - pvl_perez - pvl_reindl1990 - pvl_kingdiffuse - ''' pvl_logger.debug('diffuse_sky.klucher()') @@ -763,18 +767,6 @@ def haydavies(surf_tilt, surf_az, DHI, DNI, DNI_ET, sun_zen, sun_az): on an inclined surface. In: Hay, J.E., Won, T.K. (Eds.), Proc. of First Canadian Solar Radiation Data Workshop, 59. Ministry of Supply and Services, Canada. - - See Also - -------- - pvl_ephemeris - pvl_extraradiation - pvl_isotropicsky - pvl_reindl1990 - pvl_perez - pvl_klucher1979 - pvl_kingdiffuse - pvl_spa - ''' pvl_logger.debug('diffuse_sky.haydavies()') @@ -886,17 +878,6 @@ def reindl(surf_tilt, surf_az, DHI, DNI, GHI, DNI_ET, sun_zen, sun_az): [3] Reindl, D.T., Beckmann, W.A., Duffie, J.A., 1990b. Evaluation of hourly tilted surface radiation models. Solar Energy 45(1), 9-17. - - See Also - --------- - pvl_ephemeris - pvl_extraradiation - pvl_isotropicsky - pvl_haydavies1980 - pvl_perez - pvl_klucher1979 - pvl_kingdiffuse - ''' pvl_logger.debug('diffuse_sky.reindl()') @@ -965,19 +946,6 @@ def king(surf_tilt, DHI, GHI, sun_zen): the diffuse component of the solar radiation on an arbitrarily tilted surface as given by a model developed by David L. King at Sandia National Laboratories. - - - See Also - -------- - - pvl_ephemeris - pvl_extraradiation - pvl_isotropicsky - pvl_haydavies1980 - pvl_perez - pvl_klucher1979 - pvl_reindl1990 - ''' pvl_logger.debug('diffuse_sky.king()') @@ -1098,18 +1066,6 @@ def perez(surf_tilt, surf_az, DHI, DNI, DNI_ET, sun_zen, sun_az, AM, [4] Perez, R. et. al 1988. "The Development and Verification of the Perez Diffuse Radiation Model". SAND88-7030 - - See also - -------- - pvl_ephemeris - pvl_extraradiation - pvl_isotropicsky - pvl_haydavies1980 - pvl_reindl1990 - pvl_klucher1979 - pvl_kingdiffuse - pvl_relativeairmass - ''' pvl_logger.debug('diffuse_sky.perez()') diff --git a/pvlib/location.py b/pvlib/location.py index 954ce645ce..9157766d20 100644 --- a/pvlib/location.py +++ b/pvlib/location.py @@ -23,30 +23,29 @@ class Location(object): * ``location.pytz`` is a pytz timezone object. Location objects support the print method. + + Parameters + ---------- + latitude : float. + Positive is north of the equator. + Use decimal degrees notation. + longitude : float. + Positive is east of the prime meridian. + Use decimal degrees notation. + tz : string or pytz.timezone. + See + http://en.wikipedia.org/wiki/List_of_tz_database_time_zones + for a list of valid time zones. + pytz.timezone objects will be converted to strings. + alitude : float. + Altitude from sea level in meters. + name : None or string. + Sets the name attribute of the Location object. """ def __init__(self, latitude, longitude, tz='US/Mountain', altitude=100, name=None): - """ - Parameters - ========== - latitude : float. - Positive is north of the equator. - Use decimal degrees notation. - longitude : float. - Positive is east of the prime meridian. - Use decimal degrees notation. - tz : string or pytz.timezone. - See - http ://en.wikipedia.org/wiki/List_of_tz_database_time_zones - for a list of valid time zones. - pytz.timezone objects will be converted to strings. - alitude : float. - Altitude from sea level in meters. - name : None or string. - Optional. Sets the name attribute of the Location object. - """ - + pvl_logger.debug('creating Location object') self.latitude = latitude diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index bcf460221a..6017d114da 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -1,3 +1,8 @@ +""" +The ``pvsystem`` module contains functions for modeling the output and +performance of PV modules and inverters. +""" + from __future__ import division import logging @@ -152,9 +157,7 @@ def ashraeiam(b, theta): See Also -------- - getaoi - ephemeris - spa + irradiance.aoi physicaliam ''' @@ -281,24 +284,24 @@ def calcparams_desoto(S, Tcell, alpha_isc, module_parameters, EgRef, dEgdT, alpha_isc : float The short-circuit current temperature coefficient of the module in units of 1/C. - module_parameters : dict or Series + module_parameters : dict Parameters describing PV module performance at reference conditions according to DeSoto's paper. Parameters may be generated or found by lookup. For ease of use, retrieve_sam can automatically generate a dict based on the most recent SAM CEC module database. The module_parameters dict must contain the following 5 fields: - * a_ref - modified diode ideality factor parameter at + * A_ref - modified diode ideality factor parameter at reference conditions (units of eV), a_ref can be calculated from the usual diode ideality factor (n), number of cells in series (Ns), and cell temperature (Tcell) per equation (2) in [1]. - * IL_ref - Light-generated current (or photocurrent) + * I_l_ref - Light-generated current (or photocurrent) in amperes at reference conditions. This value is referred to as Iph in some literature. - * I0_ref - diode reverse saturation current in amperes, + * I_o_ref - diode reverse saturation current in amperes, under reference conditions. - * Rsh_ref - shunt resistance under reference conditions (ohms). - * Rs_ref - series resistance under reference conditions (ohms). + * R_sh_ref - shunt resistance under reference conditions (ohms). + * R_s - series resistance under reference conditions (ohms). EgRef : float The energy bandgap at reference temperature (in eV). @@ -461,7 +464,7 @@ def calcparams_desoto(S, Tcell, alpha_isc, module_parameters, EgRef, dEgdT, def retrieve_sam(name=None, samfile=None): ''' - Retrieve lastest module and inverter info from SAM website + Retrieve lastest module and inverter info from SAM website. This function will retrieve either: @@ -498,7 +501,7 @@ def retrieve_sam(name=None, samfile=None): Examples -------- - >>> invdb = pvsystem.retreiveSAM(name='SandiaInverter') + >>> invdb = pvsystem.retrieveSAM(name='SandiaInverter') >>> inverter = invdb.AE_Solar_Energy__AE6_0__277V__277V__CEC_2012_ >>> inverter Vac 277.000000 @@ -753,10 +756,15 @@ def singlediode(Module, IL, I0, Rs, Rsh, nNsVth, **kwargs): ''' Solve the single-diode model to obtain a photovoltaic IV curve. - singlediode solves the single diode equation [1]: - I = IL - I0*[exp((V+I*Rs)/(nNsVth))-1] - (V + I*Rs)/Rsh - for I and V when given IL, I0, Rs, Rsh, and nNsVth (nNsVth = n*Ns*Vth) which - are described later. pvl_singlediode returns a struct which contains + Singlediode solves the single diode equation [1] + + .. math:: + + I = IL - I0*[exp((V+I*Rs)/(nNsVth))-1] - (V + I*Rs)/Rsh + + for ``I`` and ``V`` when given + ``IL, I0, Rs, Rsh,`` and ``nNsVth (nNsVth = n*Ns*Vth)`` which + are described later. Returns a DataFrame which contains the 5 points on the I-V curve specified in SAND2004-3535 [3]. If all IL, I0, Rs, Rsh, and nNsVth are scalar, a single curve will be returned, if any are DataFrames (of the same length), multiple IV @@ -897,15 +905,16 @@ def singlediode(Module, IL, I0, Rs, Rsh, nNsVth, **kwargs): -''' -Created April,2014 -Author: Rob Andrews, Calama Consulting -''' +# Created April,2014 +# Author: Rob Andrews, Calama Consulting +# These may become private methods in 0.2 def golden_sect_DataFrame(df,VL,VH,func): ''' Vectorized golden section search for finding MPPT - from a dataframe timeseries + from a dataframe timeseries. + + Do not expect this function to remain in the public API. Parameters ---------- @@ -972,7 +981,9 @@ def golden_sect_DataFrame(df,VL,VH,func): def pwr_optfcn(df,loc): ''' - Function to find power from I_from_V + Function to find power from I_from_V. + + Do not expect this function to remain in the public API. ''' I=I_from_V(Rsh=df['Rsh'],Rs=df['Rs'], nNsVth=df['nNsVth'], V=df[loc], I0=df['I0'], IL=df['IL']) @@ -982,7 +993,9 @@ def pwr_optfcn(df,loc): def Voc_optfcn(df,loc): ''' - Function to find V_oc from I_from_V + Function to find V_oc from I_from_V. + + Do not expect this function to remain in the public API. ''' I = -abs(I_from_V(Rsh=df['Rsh'], Rs=df['Rs'], nNsVth=df['nNsVth'], V=df[loc], I0=df['I0'], IL=df['IL'])) return I @@ -991,10 +1004,12 @@ def Voc_optfcn(df,loc): def I_from_V(Rsh, Rs, nNsVth, V, I0, IL): ''' - calculates I from V per Eq 2 Jain and Kapoor 2004 + Calculates I from V per Eq 2 Jain and Kapoor 2004 uses Lambert W implemented in wapr_vec.m Rsh, nVth, V, I0, IL can all be DataFrames - Rs can be a DataFrame, but should be a scalar + Rs can be a DataFrame, but should be a scalar. + + Do not expect this function to remain in the public API. ''' try: from scipy.special import lambertw @@ -1014,7 +1029,7 @@ def I_from_V(Rsh, Rs, nNsVth, V, I0, IL): def snlinverter(inverter, Vmp, Pmp): ''' Converts DC power and voltage to AC power using - Sandia's Grid-Connected PV Inverter model + Sandia's Grid-Connected PV Inverter model. Determine the AC power output of an inverter given the DC voltage, DC power, and appropriate Sandia Grid-Connected Photovoltaic Inverter @@ -1032,10 +1047,10 @@ def snlinverter(inverter, Vmp, Pmp): inverter performance parameters are provided with pvlib, or may be generated from a System Advisor Model (SAM) [2] library using retreivesam. - Required DataFrame components are: + Required DataFrame columns are: ============= ============================================================================================================================================================================================== - Field DataFrame + Field Column name ============= ============================================================================================================================================================================================== Inverter.Pac0 AC-power output from inverter based on input power and voltage, (W) Inverter.Pdc0 DC-power input to inverter, typically assumed to be equal to the PV array maximum power, (W) From bb45530fb3cf42ff80c3ae5f0b5cebc40bfa2007 Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Mon, 9 Mar 2015 21:43:21 -0700 Subject: [PATCH 02/14] update sphinx sources --- docs/sphinx/source/conf.py | 6 +++--- docs/sphinx/source/index.rst | 30 ++++++++++++++++++++++++------ 2 files changed, 27 insertions(+), 9 deletions(-) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index 60cf1e8a30..d721dc8eb0 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -64,8 +64,8 @@ def __getattr__(cls, name): master_doc = 'index' # General information about the project. -project = u'PVLIB_Python' -copyright = u'2014, Sandia National Labs, Rob Andrews, University of Arizona, github contributors' +project = u'pvlib-python' +copyright = u'2015, Sandia National Labs, Rob Andrews, University of Arizona, github contributors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -191,7 +191,7 @@ def __getattr__(cls, name): #html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True +html_show_copyright = False # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 2efadbb696..52c0db06d2 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -3,14 +3,32 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to pvlib/pvlib-python's documentation! +Welcome to pvlib-python's documentation! ======================================== -This is the documentation for the pvlib-python project hosted at -https://github.com/pvlib/pvlib-python - -You may also want to browser the tutorials using nbviewer at -http://nbviewer.ipython.org/github/pvlib/pvlib-python/tree/master/docs/tutorials/ +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/. + +The source code for pvlib-python is hosted on +[github](https://github.com/pvlib/pvlib-python). + +The github page also contains a valuable +[wiki](https://github.com/pvlib/pvlib-python/wiki) +with information on how you can contribute to pvlib-python development! + +Please see the links above for details on the status of the pvlib-python +project. We are at an early stage in the development of this project, +so expect to see significant API changes in the next few releases. + +This documenation focuses on providing a reference for all of +the modules and functions available in pvlib-python. +For examples of how to use pvlib-python, please see the +[tutorials](http://nbviewer.ipython.org/github/pvlib/pvlib-python/tree/master/docs/tutorials/). From 3b528a4c4e26257f259fe93c7d4766b0f5e53dc2 Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Mon, 9 Mar 2015 21:50:31 -0700 Subject: [PATCH 03/14] fix rst hyperlinks --- docs/sphinx/source/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 52c0db06d2..20c25bd232 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -15,10 +15,10 @@ More information on Sandia Labs PV performance modeling programs can be found at https://pvpmc.sandia.gov/. The source code for pvlib-python is hosted on -[github](https://github.com/pvlib/pvlib-python). +`github `_. The github page also contains a valuable -[wiki](https://github.com/pvlib/pvlib-python/wiki) +`wiki `_ with information on how you can contribute to pvlib-python development! Please see the links above for details on the status of the pvlib-python @@ -28,7 +28,7 @@ so expect to see significant API changes in the next few releases. This documenation focuses on providing a reference for all of the modules and functions available in pvlib-python. For examples of how to use pvlib-python, please see the -[tutorials](http://nbviewer.ipython.org/github/pvlib/pvlib-python/tree/master/docs/tutorials/). +`tutorials `_. From 73d60dda9e33bec62799a1aef20aafe223406c82 Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Tue, 10 Mar 2015 10:42:58 -0700 Subject: [PATCH 04/14] add whatsnew template --- docs/sphinx/source/index.rst | 1 + docs/sphinx/source/whatsnew.rst | 9 +++++++++ docs/sphinx/source/whatsnew/v0.1.0.txt | 17 +++++++++++++++++ 3 files changed, 27 insertions(+) create mode 100644 docs/sphinx/source/whatsnew.rst create mode 100644 docs/sphinx/source/whatsnew/v0.1.0.txt diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 20c25bd232..766c45c031 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -38,6 +38,7 @@ Contents: :maxdepth: 2 self + whatsnew pvlib diff --git a/docs/sphinx/source/whatsnew.rst b/docs/sphinx/source/whatsnew.rst new file mode 100644 index 0000000000..48ed18ab78 --- /dev/null +++ b/docs/sphinx/source/whatsnew.rst @@ -0,0 +1,9 @@ +.. _whatsnew: + +********** +What's New +********** + +These are new features and improvements of note in each release. + +.. include:: whatsnew/v0.1.0.txt diff --git a/docs/sphinx/source/whatsnew/v0.1.0.txt b/docs/sphinx/source/whatsnew/v0.1.0.txt new file mode 100644 index 0000000000..1f19f58ee0 --- /dev/null +++ b/docs/sphinx/source/whatsnew/v0.1.0.txt @@ -0,0 +1,17 @@ +.. _whatsnew_0100: + +v0.1.0 (March 17, 2015) +----------------------- + +This is the first true release of the pvlib-python project. +As such, this document is a little hard to write. +There will be significant overlap with the to-be-written document +that describes the differences between pvlib-python and PVLIB\_Matlab. + +New features +~~~~~~~~~~~~ + + + +Bug fixes +~~~~~~~~~ From d59cbfcc01896cbdd64bf7da56f7723ae88596c0 Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Tue, 10 Mar 2015 11:46:20 -0700 Subject: [PATCH 05/14] add comparison stub, install notes --- docs/sphinx/source/comparison_pvlib_matlab.rst | 11 +++++++++++ docs/sphinx/source/index.rst | 14 ++++++++++++++ 2 files changed, 25 insertions(+) create mode 100644 docs/sphinx/source/comparison_pvlib_matlab.rst diff --git a/docs/sphinx/source/comparison_pvlib_matlab.rst b/docs/sphinx/source/comparison_pvlib_matlab.rst new file mode 100644 index 0000000000..56fe840a8e --- /dev/null +++ b/docs/sphinx/source/comparison_pvlib_matlab.rst @@ -0,0 +1,11 @@ +.. _comparison_pvlib_matlab: + +**************************** +Comparison with PVLIB_MATLAB +**************************** + +This document is under construction. + +Please see our +`PVSC 2015 abstract `_ +for more information diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 766c45c031..25f1c7b9ec 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -30,6 +30,19 @@ the modules and functions available in pvlib-python. For examples of how to use pvlib-python, please see the `tutorials `_. +.. note:: + + This documentation assumes general familiarity with + Python, NumPy, and Pandas. Google searches will yield many + excellent tutorials for these packages. + + +Installation +============ +1. Follow Pandas +`instructions `_ +for installing the scientific python stack, including ``pip``. +2. ``pip install pvlib-python`` Contents: @@ -39,6 +52,7 @@ Contents: self whatsnew + comparison_pvlib_matlab pvlib From f01bc8773cb9ba28457039f5a60eb1f2e20138b7 Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Tue, 10 Mar 2015 11:47:28 -0700 Subject: [PATCH 06/14] remove auto gen comment --- docs/sphinx/source/index.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 25f1c7b9ec..65cd26bd80 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -1,8 +1,3 @@ -.. PVLIB_Python documentation master file, created by - sphinx-quickstart on Fri Nov 7 15:56:33 2014. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Welcome to pvlib-python's documentation! ======================================== From c7dcc859c8d52918769c8b2b52647eaacbffdbb2 Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Tue, 10 Mar 2015 11:52:03 -0700 Subject: [PATCH 07/14] fix list --- docs/sphinx/source/index.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 65cd26bd80..b44b9826d2 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -34,10 +34,11 @@ For examples of how to use pvlib-python, please see the Installation ============ -1. Follow Pandas -`instructions `_ -for installing the scientific python stack, including ``pip``. -2. ``pip install pvlib-python`` + +1. Follow Pandas' + `instructions `_ + for installing the scientific python stack, including ``pip``. +#. ``pip install pvlib-python`` Contents: From 78c74750f124f636b99a6b542dfd5c1930fcb05c Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Tue, 10 Mar 2015 12:03:05 -0700 Subject: [PATCH 08/14] make contents label larger --- docs/sphinx/source/index.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index b44b9826d2..765d3a50a9 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -41,7 +41,8 @@ Installation #. ``pip install pvlib-python`` -Contents: +Contents +======== .. toctree:: :maxdepth: 2 From d1934048ef8082583c8d1344f2728bca1b4e8123 Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Tue, 10 Mar 2015 12:03:38 -0700 Subject: [PATCH 09/14] small improvement to snlinverter table --- pvlib/pvsystem.py | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/pvlib/pvsystem.py b/pvlib/pvsystem.py index 6017d114da..a0554038bc 100644 --- a/pvlib/pvsystem.py +++ b/pvlib/pvsystem.py @@ -1049,19 +1049,19 @@ def snlinverter(inverter, Vmp, Pmp): Required DataFrame columns are: - ============= ============================================================================================================================================================================================== - Field Column name - ============= ============================================================================================================================================================================================== - Inverter.Pac0 AC-power output from inverter based on input power and voltage, (W) - Inverter.Pdc0 DC-power input to inverter, typically assumed to be equal to the PV array maximum power, (W) - Inverter.Vdc0 DC-voltage level at which the AC-power rating is achieved at the reference operating condition, (V) - Inverter.Ps0 DC-power required to start the inversion process, or self-consumption by inverter, strongly influences inverter efficiency at low power levels, (W) - Inverter.C0 Parameter defining the curvature (parabolic) of the relationship between ac-power and dc-power at the reference operating condition, default value of zero gives a linear relationship, (1/W) - Inverter.C1 Empirical coefficient allowing Pdco to vary linearly with dc-voltage input, default value is zero, (1/V) - Inverter.C2 empirical coefficient allowing Pso to vary linearly with dc-voltage input, default value is zero, (1/V) - Inverter.C3 empirical coefficient allowing Co to vary linearly with dc-voltage input, default value is zero, (1/V) - Inverter.Pnt ac-power consumed by inverter at night (night tare) to maintain circuitry required to sense PV array voltage, (W) - ============= ============================================================================================================================================================================================== + ====== ============================================================================================================================================================================================ + Column Description + ====== ============================================================================================================================================================================================ + Pac0 AC-power output from inverter based on input power and voltage (W) + Pdc0 DC-power input to inverter, typically assumed to be equal to the PV array maximum power (W) + Vdc0 DC-voltage level at which the AC-power rating is achieved at the reference operating condition (V) + Ps0 DC-power required to start the inversion process, or self-consumption by inverter, strongly influences inverter efficiency at low power levels (W) + C0 Parameter defining the curvature (parabolic) of the relationship between ac-power and dc-power at the reference operating condition, default value of zero gives a linear relationship (1/W) + C1 Empirical coefficient allowing Pdco to vary linearly with dc-voltage input, default value is zero (1/V) + C2 Empirical coefficient allowing Pso to vary linearly with dc-voltage input, default value is zero (1/V) + C3 Empirical coefficient allowing Co to vary linearly with dc-voltage input, default value is zero (1/V) + Pnt AC-power consumed by inverter at night (night tare) to maintain circuitry required to sense PV array voltage (W) + ====== ============================================================================================================================================================================================ Vdc : float or DataFrame DC voltages, in volts, which are provided as input to the inverter. From fe7935944d7b59beafcb23a0b7df547bd8d0c72f Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Tue, 10 Mar 2015 12:07:17 -0700 Subject: [PATCH 10/14] add link to robs pvsc paper --- docs/sphinx/source/comparison_pvlib_matlab.rst | 4 +++- docs/sphinx/source/index.rst | 5 +++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/source/comparison_pvlib_matlab.rst b/docs/sphinx/source/comparison_pvlib_matlab.rst index 56fe840a8e..9244cdabdb 100644 --- a/docs/sphinx/source/comparison_pvlib_matlab.rst +++ b/docs/sphinx/source/comparison_pvlib_matlab.rst @@ -7,5 +7,7 @@ Comparison with PVLIB_MATLAB This document is under construction. Please see our +`PVSC 2014 paper `_ +and `PVSC 2015 abstract `_ -for more information +for more information. diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 765d3a50a9..bd13f48d2c 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -31,6 +31,11 @@ For examples of how to use pvlib-python, please see the Python, NumPy, and Pandas. Google searches will yield many excellent tutorials for these packages. +Please see our +`PVSC 2014 paper `_ +and +`PVSC 2015 abstract `_ +for more information. Installation ============ From 8eccb5ef125e0743ff267a00195f739bb50537a4 Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Tue, 10 Mar 2015 12:50:02 -0700 Subject: [PATCH 11/14] improve whats new and comparison --- .../sphinx/source/comparison_pvlib_matlab.rst | 41 ++++++++++ docs/sphinx/source/whatsnew/v0.1.0.txt | 75 ++++++++++++++++++- 2 files changed, 114 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/source/comparison_pvlib_matlab.rst b/docs/sphinx/source/comparison_pvlib_matlab.rst index 9244cdabdb..f90a517be2 100644 --- a/docs/sphinx/source/comparison_pvlib_matlab.rst +++ b/docs/sphinx/source/comparison_pvlib_matlab.rst @@ -11,3 +11,44 @@ Please see our and `PVSC 2015 abstract `_ for more information. + +Here are some of the major differences between the latest pvlib-python build +and the original Sandia PVLIB\_Python project, but many of these +comments apply to the difference between pvlib-python and PVLIB\_MATLAB. + + +Library wide changes +~~~~~~~~~~~~~~~~~~~~ + +* Remove ``pvl_`` from module names. +* Consolidation of similar modules. For example, functions from ``pvl_clearsky_ineichen.py`` and ``pvl_clearsky_haurwitz.py`` have been consolidated into ``clearsky.py``. +* Removed ``Vars=Locals(); Expect...; var=pvl\_tools.Parse(Vars,Expect);`` pattern. Very few tests of input validitity remain. Garbage in, garbage or ``nan`` out. +* Removing unnecssary and sometimes undesired behavior such as setting maximum zenith=90 or airmass=0. Instead, we make extensive use of ``nan`` values. +* Changing function and module names so that they do not conflict. +* Added ``/pvlib/data`` for lookup tables, test, and tutorial data. + + +More specific changes +~~~~~~~~~~~~~~~~~~~~~ + +* Add PyEphem option to solar position calculations. +* ``irradiance.py`` has more AOI, projection, and irradiance sum and calculation functions +* Locations are now ``pvlib.location.Location`` objects, not structs. +* Specify time zones using a string from the standard IANA Time Zone Database naming conventions or using a pytz.timezone instead of an integer GMT offset. We may add dateutils support in the future. +* ``clearsky.ineichen`` supports interpolating monthly Linke Turbidities to daily resolution. + +Documentation +~~~~~~~~~~~~~ + +* Using readthedocs for documentation hosting. +* Many typos and formatting errors corrected. +* Documentation source code and tutorials live in ``/`` rather than ``/pvlib/docs``. +* Additional tutorials in ``/docs/tutorials``. + +Testing +~~~~~~~ + +* Tests are cleaner and more thorough. They are still no where near complete. +* Using Coveralls to measure test coverage. +* Using TravisCI for automated testing. +* Using ``nosetests`` for more concise test code. diff --git a/docs/sphinx/source/whatsnew/v0.1.0.txt b/docs/sphinx/source/whatsnew/v0.1.0.txt index 1f19f58ee0..f9599a5246 100644 --- a/docs/sphinx/source/whatsnew/v0.1.0.txt +++ b/docs/sphinx/source/whatsnew/v0.1.0.txt @@ -3,15 +3,86 @@ v0.1.0 (March 17, 2015) ----------------------- -This is the first true release of the pvlib-python project. -As such, this document is a little hard to write. +This is the first official release of the pvlib-python project. +As such, a "What's new" document is a little hard to write. There will be significant overlap with the to-be-written document that describes the differences between pvlib-python and PVLIB\_Matlab. + +API changes +~~~~~~~~~~~ + +* Remove ``pvl_`` from module names. +* Consolidation of similar modules. For example, functions from ``pvl_clearsky_ineichen.py`` and ``pvl_clearsky_haurwitz.py`` have been consolidated into ``clearsky.py``. +* Return one DataFrame instead of a tuple of DataFrames. +* Change function and module names so that they do not conflict. + + New features ~~~~~~~~~~~~ +* Library is Python 3.3 and 3.4 compatible +* Add What's New section to docs (:issue:`10`) +* Add PyEphem option to solar position calculations. +* ``irradiance.py`` has more AOI, projection, and irradiance sum and calculation functions +* TMY data import has a ``coerce_year`` option +* TMY data can be loaded from a url (:issue:`5`) +* Locations are now ``pvlib.location.Location`` objects, not "structs". +* Specify time zones using a string from the standard IANA Time Zone Database naming conventions or using a pytz.timezone instead of an integer GMT offset. We may add dateutils support in the future. +* ``clearsky.ineichen`` supports interpolating monthly Linke Turbidities to daily resolution. + + +Other changes +~~~~~~~~~~~~~ + +* Removed ``Vars=Locals(); Expect...; var=pvl\_tools.Parse(Vars,Expect);`` pattern. Very few tests of input validitity remain. Garbage in, garbage or ``nan`` out. +* Removing unnecssary and sometimes undesired behavior such as setting maximum zenith=90 or airmass=0. Instead, we make extensive use of ``nan`` values. +* Adding logging calls, removing print calls. +* Improved PEP8 compliance. +* Added ``/pvlib/data`` for lookup tables, test, and tutorial data. + + +Documentation +~~~~~~~~~~~~~ + +* Using readthedocs for documentation hosting. +* Many typos and formatting errors corrected (:issue:`16`) +* Documentation source code and tutorials live in ``/`` rather than ``/pvlib/docs``. +* Additional tutorials in ``/docs/tutorials``. +* Clarify ``pvsystem.systemdef`` input (:issue:`17`) + + +Testing +~~~~~~~ + +* Tests are cleaner and more thorough. They are still no where near complete. +* Using Coveralls to measure test coverage. +* Using TravisCI for automated testing. +* Using ``nosetests`` for more concise test code. Bug fixes ~~~~~~~~~ + +* TODO: Fix DISC algorithm conditional evaluation (:issue:`6`) +* TODO: Prevent DISC algorithm from modifying input zenith Series (:issue:`24`) +* Many more bug fixes were made, but you'll have to look at the detailed commit history. + + +Contributors +~~~~~~~~~~~~ + +This list includes all (I hope) contributors to +`pvlib/pvlib-python `_, +`Sandia-Labs/PVLIB_Python `_, +and +`UARENForecasting/PVLIB_Python `_. + +* Rob Andrews +* Will Holmgren +* bmu +* Tony Lorenzo +* jforbess +* Jorissup +* dacoex +* alexisph From d532ed99e5f8e0e43204b852049cfd8a18a838f9 Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Tue, 10 Mar 2015 16:16:33 -0700 Subject: [PATCH 12/14] add a few words on python vs matlab --- docs/sphinx/source/comparison_pvlib_matlab.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/source/comparison_pvlib_matlab.rst b/docs/sphinx/source/comparison_pvlib_matlab.rst index f90a517be2..b3b392da56 100644 --- a/docs/sphinx/source/comparison_pvlib_matlab.rst +++ b/docs/sphinx/source/comparison_pvlib_matlab.rst @@ -5,13 +5,23 @@ Comparison with PVLIB_MATLAB **************************** This document is under construction. - Please see our `PVSC 2014 paper `_ and `PVSC 2015 abstract `_ for more information. +The pvlib-python license is BSD 3-clause, +the PVLIB\_MATLAB license is ??. + +We want to keep developing the core functionality and algorithms +of the Python and MATLAB projects roughly in parallel, +but we're not making any promises at this point. +The PVLIB\_MATLAB and pvlib-python projects are currently developed +by different teams that do not regularly work together. +We hope to grow this collaboration in the future. +Do not expect feature parity between the libaries, only similarity. + Here are some of the major differences between the latest pvlib-python build and the original Sandia PVLIB\_Python project, but many of these comments apply to the difference between pvlib-python and PVLIB\_MATLAB. From df25f1ca4c30744f66eca2ee548667ddd215f46f Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Thu, 12 Mar 2015 11:11:37 -0700 Subject: [PATCH 13/14] add sphinx extlinks --- docs/sphinx/source/conf.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index d721dc8eb0..b7befe749b 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -47,6 +47,7 @@ def __getattr__(cls, name): 'sphinx.ext.autodoc', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', + 'sphinx.ext.extlinks', 'numpydoc', 'sphinx.ext.autosummary' ] @@ -246,6 +247,11 @@ def __getattr__(cls, name): # If false, no module index is generated. #latex_domain_indices = True +# extlinks alias +extlinks = {'issue': ('https://github.com/pvlib/pvlib-python/issues/%s', + 'GH'), + 'wiki': ('https://github.com/pvlib/pvlib-python/wiki/%s', + 'wiki ')} # -- Options for manual page output --------------------------------------- From e61a726539b78dd0acaad0191dd5815e98252da9 Mon Sep 17 00:00:00 2001 From: Will Holmgren Date: Thu, 12 Mar 2015 16:32:00 -0700 Subject: [PATCH 14/14] clarify disc fixes in whatsnew --- docs/sphinx/source/whatsnew/v0.1.0.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/source/whatsnew/v0.1.0.txt b/docs/sphinx/source/whatsnew/v0.1.0.txt index f9599a5246..d52699c226 100644 --- a/docs/sphinx/source/whatsnew/v0.1.0.txt +++ b/docs/sphinx/source/whatsnew/v0.1.0.txt @@ -64,8 +64,10 @@ Testing Bug fixes ~~~~~~~~~ -* TODO: Fix DISC algorithm conditional evaluation (:issue:`6`) -* TODO: Prevent DISC algorithm from modifying input zenith Series (:issue:`24`) +* Fixed DISC algorithm bugs concerning + modifying input zenith Series (:issue:`24`), + the ``Kt`` conditional evaluation (:issue:`6`), + and ignoring the input pressure (:issue:`25`). * Many more bug fixes were made, but you'll have to look at the detailed commit history.