add Mount classes (#1176)

* add Mount classes, incorporate into Array and PVSystem

* update pvsystem tests

* delete mounts module

* fix modelchain tests

* some modifications to SingleAxisTracker

* changes from review

* stickler

* use dataclasses for mounts

* update tests

* update docs

* whatsnew

* test mount classes

* stickler

* more tests

* another test

* fix typo

* clean up AbstractMount

* remove unnecessary use of dataclasses.field

* calculate -> get

* Update pvlib/pvsystem.py

Co-authored-by: Cliff Hansen <[email protected]>

* stickler

* test fixes

* add optional surface_tilt parameter to PVSystem.fuentes_celltemp

* move racking_model and module_height to the Mounts

* fix some tests

* remove unnecessary fixture

* Revert "remove unnecessary fixture"

This reverts commit 74a6be4.

* update merged test

* fix fuentes issue, sort of

* pep8

* pep8

* remove PVSystem.fuentes_celltemp surface_tilt parameter

* placeholder fuentes surface_tilt logic

* test updates

* remove unused imports

* remove fuentes override complexity

* stickler

* update RST pages

* revert unnecessary docs change

* add link to pvsystem and modelchain pages in api listing

* other changes from review

* get module_height from mount instead of temperature_model_parameters

* coverage for fuentes module_height parameter

* deprecate SingleAxisTracker

* suppress SAT deprecation warnings in tests

* Apply suggestions from code review

Co-authored-by: Will Holmgren <[email protected]>

* Tracking -> Tracker

Co-authored-by: Cliff Hansen <[email protected]>
Co-authored-by: Will Holmgren <[email protected]>

Author: 3 people

docs/sphinx/source/api.rst

@@ -13,14 +13,17 @@ object-oriented programming. These classes can help users keep track of
 data in a more organized way, and can help to simplify the modeling
 process. The classes do not add any functionality beyond the procedural
 code. Most of the object methods are simple wrappers around the
-corresponding procedural code.
+corresponding procedural code. For examples of using these classes, see
+the :ref:`pvsystemdoc` and :ref:`modelchaindoc` pages.
 
 .. autosummary::
    :toctree: generated/
 
    location.Location
    pvsystem.PVSystem
    pvsystem.Array
+   pvsystem.FixedMount
+   pvsystem.SingleAxisTrackerMount
    tracking.SingleAxisTracker
    modelchain.ModelChain
    modelchain.ModelChainResult

docs/sphinx/source/modelchain.rst

@@ -1,3 +1,4 @@
+.. _modelchaindoc:
 
 ModelChain
 ==========
@@ -40,7 +41,7 @@ objects, module data, and inverter data.
     # pvlib imports
     import pvlib
 
-    from pvlib.pvsystem import PVSystem
+    from pvlib.pvsystem import PVSystem, FixedMount
     from pvlib.location import Location
     from pvlib.modelchain import ModelChain
     from pvlib.temperature import TEMPERATURE_MODEL_PARAMETERS
@@ -53,8 +54,8 @@ objects, module data, and inverter data.
     sandia_module = sandia_modules['Canadian_Solar_CS5P_220M___2009_']
     cec_inverter = cec_inverters['ABB__MICRO_0_25_I_OUTD_US_208__208V_']
 
-Now we create a Location object, a PVSystem object, and a ModelChain
-object.
+Now we create a Location object, a Mount object, a PVSystem object, and a
+ModelChain object.
 
 .. ipython:: python
 
@@ -448,11 +449,11 @@ are in the same order as in ``PVSystem.arrays``.
     location = Location(latitude=32.2, longitude=-110.9)
     inverter_parameters = {'pdc0': 10000, 'eta_inv_nom': 0.96}
     module_parameters = {'pdc0': 250, 'gamma_pdc': -0.004}
-    array_one = Array(surface_tilt=20, surface_azimuth=200,
+    array_one = Array(mount=FixedMount(surface_tilt=20, surface_azimuth=200),
                       module_parameters=module_parameters,
                       temperature_model_parameters=temperature_model_parameters,
                       modules_per_string=10, strings=2)
-    array_two = Array(surface_tilt=20, surface_azimuth=160,
+    array_two = Array(mount=FixedMount(surface_tilt=20, surface_azimuth=160),
                       module_parameters=module_parameters,
                       temperature_model_parameters=temperature_model_parameters,
                       modules_per_string=10, strings=2)

docs/sphinx/source/pvsystem.rst

@@ -138,8 +138,9 @@ provided for each array, and the arrays are provided to
 .. ipython:: python
 
     module_parameters = {'pdc0': 5000, 'gamma_pdc': -0.004}
-    array_one = pvsystem.Array(module_parameters=module_parameters)
-    array_two = pvsystem.Array(module_parameters=module_parameters)
+    mount = pvsystem.FixedMount(surface_tilt=20, surface_azimuth=180)
+    array_one = pvsystem.Array(mount=mount, module_parameters=module_parameters)
+    array_two = pvsystem.Array(mount=mount, module_parameters=module_parameters)
     system_two_arrays = pvsystem.PVSystem(arrays=[array_one, array_two],
                                           inverter_parameters=inverter_parameters)
     print([array.module_parameters for array in system_two_arrays.arrays])
@@ -148,7 +149,7 @@ provided for each array, and the arrays are provided to
 
 The :py:class:`~pvlib.pvsystem.Array` class includes those 
 :py:class:`~pvlib.pvsystem.PVSystem` attributes that may vary from array
-to array. These attributes include `surface_tilt`, `surface_azimuth`,
+to array. These attributes include
 `module_parameters`, `temperature_model_parameters`, `modules_per_string`,
 `strings_per_inverter`, `albedo`, `surface_type`, `module_type`, and
 `racking_model`.
@@ -179,27 +180,30 @@ Tilt and azimuth
 The first parameters which describe the DC part of a PV system are the tilt
 and azimuth of the modules. In the case of a PV system with a single array,
 these parameters can be specified using the `PVSystem.surface_tilt` and
-`PVSystem.surface_azimuth` attributes.
+`PVSystem.surface_azimuth` attributes.  This will automatically create
+an :py:class:`~pvlib.pvsystem.Array` with a :py:class:`~pvlib.pvsystem.FixedMount`
+at the specified tilt and azimuth:
 
 .. ipython:: python
 
     # single south-facing array at 20 deg tilt
     system_one_array = pvsystem.PVSystem(surface_tilt=20, surface_azimuth=180)
-    print(system_one_array.arrays[0].surface_tilt,
-          system_one_array.arrays[0].surface_azimuth)
+    print(system_one_array.arrays[0].mount)
 
 
 In the case of a PV system with several arrays, the parameters are specified
-for each array using the attributes `Array.surface_tilt` and `Array.surface_azimuth`.
+for each array by passing a different :py:class:`~pvlib.pvsystem.FixedMount`
+(or another `Mount` class):
 
 .. ipython:: python
 
-    array_one = pvsystem.Array(surface_tilt=30, surface_azimuth=90)
-    print(array_one.surface_tilt, array_one.surface_azimuth)
-    array_two = pvsystem.Array(surface_tilt=30, surface_azimuth=220)
+    array_one = pvsystem.Array(pvsystem.FixedMount(surface_tilt=30, surface_azimuth=90))
+    print(array_one.mount.surface_tilt, array_one.mount.surface_azimuth)
+    array_two = pvsystem.Array(pvsystem.FixedMount(surface_tilt=30, surface_azimuth=220))
     system = pvsystem.PVSystem(arrays=[array_one, array_two])
     system.num_arrays
-    [(array.surface_tilt, array.surface_azimuth) for array in system.arrays]
+    for array in system.arrays:
+        print(array.mount)
 
 
 The `surface_tilt` and `surface_azimuth` attributes are used in PVSystem
@@ -215,8 +219,7 @@ and `solar_azimuth` as arguments.
 
     # single south-facing array at 20 deg tilt
     system_one_array = pvsystem.PVSystem(surface_tilt=20, surface_azimuth=180)
-    print(system_one_array.arrays[0].surface_tilt,
-          system_one_array.arrays[0].surface_azimuth)
+    print(system_one_array.arrays[0].mount)
 
     # call get_aoi with solar_zenith, solar_azimuth
     aoi = system_one_array.get_aoi(solar_zenith=30, solar_azimuth=180)
@@ -229,7 +232,7 @@ operates in a similar manner.
 .. ipython:: python
 
     # two arrays each at 30 deg tilt with different facing
-    array_one = pvsystem.Array(surface_tilt=30, surface_azimuth=90)
+    array_one = pvsystem.Array(pvsystem.FixedMount(surface_tilt=30, surface_azimuth=90))
     array_one_aoi = array_one.get_aoi(solar_zenith=30, solar_azimuth=180)
     print(array_one_aoi)
 
@@ -240,7 +243,7 @@ operates on all `Array` instances in the `PVSystem`, whereas the the
 
 .. ipython:: python
 
-    array_two = pvsystem.Array(surface_tilt=30, surface_azimuth=220)
+    array_two = pvsystem.Array(pvsystem.FixedMount(surface_tilt=30, surface_azimuth=220))
     system_multiarray = pvsystem.PVSystem(arrays=[array_one, array_two])
     print(system_multiarray.num_arrays)
     # call get_aoi with solar_zenith, solar_azimuth
@@ -315,8 +318,8 @@ Losses
 
 The `losses_parameters` attribute contains data that may be used with
 methods that calculate system losses. At present, these methods include
-only :py:meth:`PVSystem.pvwatts_losses` and
-:py:func:`pvsystem.pvwatts_losses`, but we hope to add more related functions
+only :py:meth:`pvlib.pvsystem.PVSystem.pvwatts_losses` and
+:py:func:`pvlib.pvsystem.pvwatts_losses`, but we hope to add more related functions
 and methods in the future.
 
 

docs/sphinx/source/whatsnew/v0.9.0.rst

@@ -100,6 +100,10 @@ Deprecations
   * ``PVSystem.surface_azimuth``
   * ``PVSystem.temperature_model_parameters``
 
+* The :py:class:`pvlib.tracking.SingleAxisTracker` class is deprecated and
+  replaced by using :py:class:`pvlib.pvsystem.PVSystem` with the new
+  :py:class:`pvlib.pvsystem.SingleAxisTrackerMount` (:pull:`1176`)
+
 
 Enhancements
 ~~~~~~~~~~~~
@@ -120,6 +124,9 @@ Enhancements
 * Added :py:class:`~pvlib.pvsystem.Array` class to represent an array of
   modules separately from a :py:class:`~pvlib.pvsystem.PVSystem`.
   (:pull:`1076`, :issue:`1067`)
+* Added :py:class:`~pvlib.pvsystem.FixedMount` and
+  :py:class:`~pvlib.pvsystem.SingleAxisTrackerMount` classes to use with
+  the new :py:class:`~pvlib.pvsystem.Array` class (:pull:`1176`)
 * Added capability for modeling a PV system with multiple arrays in
   :py:class:`~pvlib.pvsystem.PVSystem`. Updates the ``PVSystem`` API
   to operate on and return tuples where each element of the tuple corresponds