add basic_chain to package_overview

Author: wholmgren

docs/sphinx/source/package_overview.rst

@@ -10,7 +10,7 @@ The core mission of pvlib-python is to provide open, reliable,
 interoperable, and benchmark implementations of PV system models.
 
 There are at least as many opinions about how to model PV systems as
-there are modelers of PV systems, so 
+there are modelers of PV systems, so
 pvlib-python provides several modeling paradigms.
 
 
@@ -36,28 +36,28 @@ configuration at a handful of sites listed below.
 
     import pandas as pd
     import matplotlib.pyplot as plt
-    
+
     # seaborn makes the plots look nicer
     import seaborn as sns
     sns.set_color_codes()
-    
+
     times = pd.DatetimeIndex(start='2015', end='2016', freq='1h')
-    
+
     # very approximate
     # latitude, longitude, name, altitude
     coordinates = [(30, -110, 'Tucson', 700),
                    (35, -105, 'Albuquerque', 1500),
                    (40, -120, 'San Francisco', 10),
                    (50, 10, 'Berlin', 34)]
-    
+
     import pvlib
-    
+
     # get the module and inverter specifications from SAM
     sandia_modules = pvlib.pvsystem.retrieve_sam('SandiaMod')
     sapm_inverters = pvlib.pvsystem.retrieve_sam('sandiainverter')
     module = sandia_modules['Canadian_Solar_CS5P_220M___2009_']
     inverter = sapm_inverters['ABB__MICRO_0_25_I_OUTD_US_208_208V__CEC_2014_']
-    
+
     # specify constant ambient air temp and wind for simplicity
     temp_air = 20
     wind_speed = 0
@@ -73,7 +73,7 @@ The following code demonstrates how to use the procedural code
 to accomplish our system modeling goal:
 
 .. ipython:: python
-    
+
     system = {'module': module, 'inverter': inverter,
               'surface_azimuth': 180}
 
@@ -104,32 +104,56 @@ to accomplish our system modeling goal:
         ac = pvlib.pvsystem.snlinverter(inverter, dc['v_mp'], dc['p_mp'])
         annual_energy = ac.sum()
         energies[name] = annual_energy
-    
+
     energies = pd.Series(energies)
 
     # based on the parameters specified above, these are in W*hrs
     print(energies.round(0))
-    
+
     energies.plot(kind='bar', rot=0)
     @savefig proc-energies.png width=6in
     plt.ylabel('Yearly energy yield (W hr)')
 
+pvlib-python provides a :py:func:`~pvlib.modelchain.basic_chain`
+function that implements much of the code above. Use this function with
+a full understanding of what it is doing internally!
+
+.. ipython:: python
+
+    from pvlib.modelchain import basic_chain
+
+    energies = {}
+    for latitude, longitude, name, altitude in coordinates:
+        dc, ac = basic_chain(times, latitude, longitude,
+                             module, inverter,
+                             altitude=altitude,
+                             orientation_strategy='south_at_latitude_tilt')
+        annual_energy = ac.sum()
+        energies[name] = annual_energy
+
+    energies = pd.Series(energies)
+
+    # based on the parameters specified above, these are in W*hrs
+    print(energies.round(0))
+
+    energies.plot(kind='bar', rot=0)
+    @savefig basic-chain-energies.png width=6in
+    plt.ylabel('Yearly energy yield (W hr)')
+
 
 Object oriented (Location, PVSystem, ModelChain)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The first object oriented paradigm uses a model where
-a :py:class:`~pvlib.pvsystem.PVSystem` object represents an
-assembled collection of modules, inverters, etc.,
-a :py:class:`~pvlib.location.Location` object represents a
-particular place on the planet,
-and a :py:class:`~pvlib.modelchain.ModelChain` object describes
-the modeling chain used to calculate PV output at that Location.
-This can be a useful paradigm if you prefer to think about
-the PV system and its location as separate concepts or if
-you develop your own ModelChain subclasses.
-It can also be helpful if you make extensive use of Location-specific
-methods for other calculations.
+The first object oriented paradigm uses a model where a
+:py:class:`~pvlib.pvsystem.PVSystem` object represents an assembled
+collection of modules, inverters, etc., a
+:py:class:`~pvlib.location.Location` object represents a particular
+place on the planet, and a :py:class:`~pvlib.modelchain.ModelChain`
+object describes the modeling chain used to calculate PV output at that
+Location. This can be a useful paradigm if you prefer to think about the
+PV system and its location as separate concepts or if you develop your
+own ModelChain subclasses. It can also be helpful if you make extensive
+use of Location-specific methods for other calculations.
 
 The following code demonstrates how to use
 :py:class:`~pvlib.location.Location`,
@@ -138,14 +162,14 @@ The following code demonstrates how to use
 objects to accomplish our system modeling goal:
 
 .. ipython:: python
-    
+
     from pvlib.pvsystem import PVSystem
     from pvlib.location import Location
     from pvlib.modelchain import ModelChain
-    
+
     system = PVSystem(module_parameters=module,
                       inverter_parameters=inverter)
-    
+
     energies = {}
     for latitude, longitude, name, altitude in coordinates:
         location = Location(latitude, longitude, name=name, altitude=altitude)
@@ -156,12 +180,12 @@ objects to accomplish our system modeling goal:
         dc, ac = mc.run_model(times)
         annual_energy = ac.sum()
         energies[name] = annual_energy
-    
+
     energies = pd.Series(energies)
-    
+
     # based on the parameters specified above, these are in W*hrs
     print(energies.round(0))
-    
+
     energies.plot(kind='bar', rot=0)
     @savefig modelchain-energies.png width=6in
     plt.ylabel('Yearly energy yield (W hr)')
@@ -170,18 +194,17 @@ objects to accomplish our system modeling goal:
 Object oriented (LocalizedPVSystem)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The second object oriented paradigm uses a model where a 
+The second object oriented paradigm uses a model where a
 :py:class:`~pvlib.pvsystem.LocalizedPVSystem` represents a
-PV system at a particular place on the planet.
-This can be a useful paradigm if you're thinking about
-a power plant that already exists.
+PV system at a particular place on the planet. This can be a useful
+paradigm if you're thinking about a power plant that already exists.
 
 The following code demonstrates how to use a
 :py:class:`~pvlib.pvsystem.LocalizedPVSystem`
 object to accomplish our modeling goal:
 
 .. ipython:: python
-    
+
     from pvlib.pvsystem import LocalizedPVSystem
 
     energies = {}
@@ -214,22 +237,22 @@ object to accomplish our modeling goal:
         ac = localized_system.snlinverter(dc['v_mp'], dc['p_mp'])
         annual_energy = ac.sum()
         energies[name] = annual_energy
-    
+
     energies = pd.Series(energies)
-    
+
     # based on the parameters specified above, these are in W*hrs
     print(energies.round(0))
-    
+
     energies.plot(kind='bar', rot=0)
     @savefig localized-pvsystem-energies.png width=6in
     plt.ylabel('Yearly energy yield (W hr)')
 
 
 User extensions
 ---------------
-There are many other ways to organize PV modeling code. 
-We encourage you to build on these paradigms and to share your experiences
-with the pvlib community via issues and pull requests.
+There are many other ways to organize PV modeling code. We encourage you
+to build on these paradigms and to share your experiences with the pvlib
+community via issues and pull requests.
 
 
 Getting support