diff --git a/docs/sphinx/source/comparison_pvlib_matlab.rst b/docs/sphinx/source/comparison_pvlib_matlab.rst new file mode 100644 index 0000000000..b3b392da56 --- /dev/null +++ b/docs/sphinx/source/comparison_pvlib_matlab.rst @@ -0,0 +1,64 @@ +.. _comparison_pvlib_matlab: + +**************************** +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. + + +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/conf.py b/docs/sphinx/source/conf.py index 60cf1e8a30..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' ] @@ -64,8 +65,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 +192,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 @@ -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 --------------------------------------- diff --git a/docs/sphinx/source/index.rst b/docs/sphinx/source/index.rst index 2efadbb696..bd13f48d2c 100644 --- a/docs/sphinx/source/index.rst +++ b/docs/sphinx/source/index.rst @@ -1,25 +1,60 @@ -.. 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/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 +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 `_. + +The github page also contains a valuable +`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 `_. + +.. note:: + + This documentation assumes general familiarity with + 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. -You may also want to browser the tutorials using nbviewer at -http://nbviewer.ipython.org/github/pvlib/pvlib-python/tree/master/docs/tutorials/ +Installation +============ +1. Follow Pandas' + `instructions `_ + for installing the scientific python stack, including ``pip``. +#. ``pip install pvlib-python`` -Contents: +Contents +======== .. toctree:: :maxdepth: 2 self + whatsnew + comparison_pvlib_matlab 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..d52699c226 --- /dev/null +++ b/docs/sphinx/source/whatsnew/v0.1.0.txt @@ -0,0 +1,90 @@ +.. _whatsnew_0100: + +v0.1.0 (March 17, 2015) +----------------------- + +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 +~~~~~~~~~ + +* 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. + + +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 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 a9d6670f9f..abe6b4f604 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) @@ -332,9 +321,8 @@ def disc(GHI, zenith, times, pressure=101325): January 12, 2012 See Also - -------- - ephemeris - alt2pres + -------- + atmosphere.alt2pres dirint ''' 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 cae3488ec8..87993013f7 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,21 +1047,21 @@ 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: - - ============= ============================================================================================================================================================================================== - Field DataFrame - ============= ============================================================================================================================================================================================== - 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) - ============= ============================================================================================================================================================================================== + Required DataFrame columns are: + + ====== ============================================================================================================================================================================================ + 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.