Skip to content

Commit 45109de

Browse files
wholmgrenwholmgren
authored
add PVSystem documentation page (#549)
* add stub pvsystem.ipynb doc * use rst instead of ipynb * updates, add whatsnew * add scale section. other edits * incorporate review feedback
1 parent abe8bf1 commit 45109de

File tree

3 files changed

+178
-0
lines changed

3 files changed

+178
-0
lines changed

‎docs/sphinx/source/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ Contents
7575
whatsnew
7676
installation
7777
contributing
78+
pvsystem
7879
modelchain
7980
timetimezones
8081
clearsky

‎docs/sphinx/source/pvsystem.rst

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
.. _pvsystemdoc:
2+
3+
PVSystem
4+
========
5+
6+
.. ipython:: python
7+
:suppress:
8+
9+
import pandas as pd
10+
from pvlib import pvsystem
11+
12+
The :py:class:`~pvlib.pvsystem.PVSystem` class wraps many of the
13+
functions in the :py:mod:`~pvlib.pvsystem` module. This simplifies the
14+
API by eliminating the need for a user to specify arguments such as
15+
module and inverter properties when calling PVSystem methods.
16+
:py:class:`~pvlib.pvsystem.PVSystem` is not better or worse than the
17+
functions it wraps -- it is simply an alternative way of organizing
18+
your data and calculations.
19+
20+
This guide aims to build understanding of the PVSystem class. It assumes
21+
basic familiarity with object-oriented code in Python, but most
22+
information should be understandable without a solid understanding of
23+
classes. Keep in mind that `functions` are independent of objects,
24+
while `methods` are attached to objects.
25+
26+
See :py:class:`~pvlib.modelchain.ModelChain` for an application of
27+
PVSystem to time series modeling.
28+
29+
30+
.. _designphilosophy:
31+
32+
Design philosophy
33+
-----------------
34+
35+
The PVSystem class allows modelers to easily separate the data that
36+
represents a PV system (e.g. tilt angle or module parameters) from the
37+
data that influences the PV system (e.g. the weather).
38+
39+
The data that represents the PV system is *intrinsic*. The
40+
data that influences the PV system is *extrinsic*.
41+
42+
Intrinsic data is stored in object attributes. For example, the data
43+
that describes a PV system's module parameters is stored in
44+
`PVSystem.module_parameters`.
45+
46+
.. ipython:: python
47+
48+
module_parameters = {'pdc0': 10, 'gamma_pdc': -0.004}
49+
system = pvsystem.PVSystem(module_parameters=module_parameters)
50+
print(system.module_parameters)
51+
52+
Extrinsic data is passed to a PVSystem as method arguments. For example,
53+
the :py:meth:`~pvlib.pvsystem.PVSystem.pvwatts_dc` method accepts extrinsic
54+
data irradiance and temperature.
55+
56+
.. ipython:: python
57+
58+
pdc = system.pvwatts_dc(1000, 30)
59+
print(pdc)
60+
61+
Methods attached to a PVSystem object wrap corresponding functions in
62+
:py:mod:`~pvlib.pvsystem`. The methods simplify the argument list by
63+
using data stored in the PVSystem attributes. Compare the
64+
:py:meth:`~pvlib.pvsystem.PVSystem.pvwatts_dc` method signature to the
65+
:py:func:`~pvlib.pvsystem.pvwatts_dc` function signature:
66+
67+
* :py:meth:`PVSystem.pvwatts_dc(g_poa_effective, temp_cell) <pvlib.pvsystem.PVSystem.pvwatts_dc>`
68+
* :py:func:`pvwatts_dc(g_poa_effective, temp_cell, pdc0, gamma_pdc, temp_ref=25.) <pvlib.pvsystem.pvwatts_dc>`
69+
70+
How does this work? The :py:meth:`~pvlib.pvsystem.PVSystem.pvwatts_dc`
71+
method looks in `PVSystem.module_parameters` for the `pdc0`, and
72+
`gamma_pdc` arguments. Then the :py:meth:`PVSystem.pvwatts_dc
73+
<pvlib.pvsystem.PVSystem.pvwatts_dc>` method calls the
74+
:py:func:`pvsystem.pvwatts_dc <pvlib.pvsystem.pvwatts_dc>` function with
75+
all of the arguments and returns the result to the user. Note that the
76+
function includes a default value for the parameter `temp_ref`. This
77+
default value may be overridden by specifying the `temp_ref` key in the
78+
`PVSystem.module_parameters` dictionary.
79+
80+
.. ipython:: python
81+
82+
system.module_parameters['temp_ref'] = 0
83+
# lower temp_ref should lead to lower DC power than calculated above
84+
pdc = system.pvwatts_dc(1000, 30)
85+
print(pdc)
86+
87+
Multiple methods may pull data from the same attribute. For example, the
88+
`PVSystem.module_parameters` attribute is used by the DC model methods
89+
as well as the incidence angle modifier methods.
90+
91+
92+
.. _pvsystemattributes:
93+
94+
PVSystem attributes
95+
-------------------
96+
97+
Here we review the most commonly used PVSystem attributes. Please see
98+
the :py:class:`~pvlib.pvsystem.PVSystem` class documentation for a
99+
comprehensive list.
100+
101+
The first PVSystem parameters are `surface_tilt` and `surface_azimuth`.
102+
These parameters are used in PVSystem methods such as
103+
:py:meth:`~pvlib.pvsystem.PVSystem.get_aoi` and
104+
:py:meth:`~pvlib.pvsystem.PVSystem.get_irradiance`. Angle of incidence
105+
(AOI) calculations require `surface_tilt`, `surface_azimuth` and also
106+
the sun position. The :py:meth:`~pvlib.pvsystem.PVSystem.get_aoi` method
107+
uses the `surface_tilt` and `surface_azimuth` attributes in its PVSystem
108+
object, and so requires only `solar_zenith` and `solar_azimuth` as
109+
arguments.
110+
111+
.. ipython:: python
112+
113+
# 20 deg tilt, south-facing
114+
system = pvsystem.PVSystem(surface_tilt=20, surface_azimuth=180)
115+
print(system.surface_tilt, system.surface_azimuth)
116+
117+
# call get_aoi with solar_zenith, solar_azimuth
118+
aoi = system.get_aoi(30, 180)
119+
print(aoi)
120+
121+
`module_parameters` and `inverter_parameters` contain the data
122+
necessary for computing DC and AC power using one of the available
123+
PVSystem methods. These are typically specified using data from
124+
the :py:func:`~pvlib.pvsystem.retrieve_sam` function:
125+
126+
.. ipython:: python
127+
128+
# retrieve_sam returns a dict. the dict keys are module names,
129+
# and the values are model parameters for that module
130+
modules = pvsystem.retrieve_sam('cecmod')
131+
module_parameters = modules['Example_Module']
132+
inverters = pvsystem.retrieve_sam('cecinverter')
133+
inverter_parameters = inverters['ABB__MICRO_0_25_I_OUTD_US_208_208V__CEC_2014_']
134+
system = pvsystem.PVSystem(module_parameters=module_parameters, inverter_parameters=inverter_parameters)
135+
136+
The module and/or inverter parameters can also be specified manually.
137+
This is useful for specifying modules and inverters that are not
138+
included in the supplied databases. It is also useful for specifying
139+
systems for use with the PVWatts models, as demonstrated in
140+
:ref:`designphilosophy`.
141+
142+
The `losses_parameters` attribute contains data that may be used with
143+
methods that calculate system losses. At present, these methods include
144+
only :py:meth:`PVSystem.pvwatts_losses
145+
<pvlib.pvsystem.PVSystem.pvwatts_losses>` and
146+
:py:func:`pvsystem.pvwatts_losses <pvlib.pvsystem.pvwatts_losses>`, but
147+
we hope to add more related functions and methods in the future.
148+
149+
The attributes `modules_per_string` and `strings_per_inverter` are used
150+
in the :py:meth:`~pvlib.pvsystem.PVSystem.scale_voltage_current_power`
151+
method. Some DC power models in :py:class:`~pvlib.modelchain.ModelChain`
152+
automatically call this method and make use of these attributes. As an
153+
example, consider a system with 35 modules arranged into 5 strings of 7
154+
modules each.
155+
156+
.. ipython:: python
157+
158+
system = pvsystem.PVSystem(modules_per_string=7, strings_per_inverter=5)
159+
# crude numbers from a single module
160+
data = pd.DataFrame({'v_mp': 8, 'v_oc': 10, 'i_mp': 5, 'i_x': 6,
161+
'i_xx': 4, 'i_sc': 7, 'p_mp': 40}, index=[0])
162+
data_scaled = system.scale_voltage_current_power(data)
163+
print(data_scaled)
164+
165+
166+
.. _sat:
167+
168+
SingleAxisTracker
169+
-----------------
170+
171+
The :py:class:`~pvlib.tracking.SingleAxisTracker` is a subclass of
172+
:py:class:`~pvlib.pvsystem.PVSystem`. The SingleAxisTracker class
173+
includes a few more keyword arguments and attributes that are specific
174+
to trackers, plus the
175+
:py:meth:`~pvlib.tracking.SingleAxisTracker.singleaxis` method. It also
176+
overrides the `get_aoi` and `get_irradiance` methods.

‎docs/sphinx/source/whatsnew/v0.6.0.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,7 @@ Documentation
146146
* Move the "Getting Started"/"Modeling Paradigms" section to a new
147147
top-level "Intro Examples" page.
148148
* Copy pvlib documentation's "Getting support" section to README.md.
149+
* Add PVSystem documentation page. (:issue:`514`, :issue:`319`)
149150

150151

151152
Testing

0 commit comments

Comments
 (0)