add Mount classes

pvlib/modelchain.py

@@ -644,7 +644,9 @@ def orientation_strategy(self, strategy):
             strategy = None
 
         if strategy is not None:
-            self.system.surface_tilt, self.system.surface_azimuth = \
+            # TODO: this is probably not what we want to do here
+            (self.system.arrays[0].mount.surface_tilt,
+             self.system.arrays[0].mount.surface_azimuth) = \
                 get_orientation(strategy, latitude=self.location.latitude)
 
         self._orientation_strategy = strategy

pvlib/pvsystem.py

@@ -11,8 +11,10 @@
 from urllib.request import urlopen
 import numpy as np
 import pandas as pd
+from abc import ABC, abstractmethod
 
-from pvlib._deprecation import deprecated
+import warnings
+from pvlib._deprecation import deprecated, pvlibDeprecationWarning
 
 from pvlib import (atmosphere, iam, inverter, irradiance,
                    singlediode as _singlediode, temperature)
@@ -191,8 +193,7 @@ def __init__(self,
 
         if arrays is None:
             self.arrays = (Array(
-                surface_tilt,
-                surface_azimuth,
+                FixedMount(surface_tilt, surface_azimuth),
                 albedo,
                 surface_type,
                 module,
@@ -249,7 +250,6 @@ def _validate_per_array(self, values, system_wide=False):
 
     @_unwrap_single_value
     def _infer_cell_type(self):
-
         """
         Examines module_parameters and maps the Technology key for the CEC
         database and the Material key for the Sandia database to a common
@@ -765,7 +765,10 @@ def fuentes_celltemp(self, poa_global, temp_air, wind_speed):
         wind_speed = self._validate_per_array(wind_speed, system_wide=True)
 
         def _build_kwargs_fuentes(array):
-            kwargs = {'surface_tilt': array.surface_tilt}
+            # TODO: I think there should be an interface function so that
+            # directly accessing surface_tilt isn't necessary. Doesn't this
+            # break for SAT?
+            kwargs = {'surface_tilt': array.mount.surface_tilt}
             temp_model_kwargs = _build_kwargs([
                 'noct_installed', 'module_height', 'wind_height', 'emissivity',
                 'absorption', 'surface_tilt', 'module_width', 'module_length'],
@@ -1044,24 +1047,60 @@ def temperature_model_parameters(self, value):
             array.temperature_model_parameters = value
 
     @property
-    @_unwrap_single_value
     def surface_tilt(self):
-        return tuple(array.surface_tilt for array in self.arrays)
+        if len(self.arrays) == 1:
+            msg = (
+                'PVSystem.surface_tilt attribute is deprecated. '
+                'Use PVSystem.arrays[0].mount.surface_tilt.'
+            )
+            warnings.warn(msg, pvlibDeprecationWarning)
+        else:
+            raise AttributeError(
+                'PVSystem.surface_tilt not supported for multi-array systems. '
+                'Use PVSystem.arrays[i].mount.surface_tilt.')
+        return self.arrays[0].mount.surface_tilt
 
     @surface_tilt.setter
     def surface_tilt(self, value):
-        for array in self.arrays:
-            array.surface_tilt = value
+        if len(self.arrays) == 1:
+            msg = (
+                'PVSystem.surface_tilt attribute is deprecated. '
+                'Use PVSystem.arrays[0].mount.surface_tilt.'
+            )
+            warnings.warn(msg, pvlibDeprecationWarning)
+        else:
+            raise AttributeError(
+                'PVSystem.surface_tilt not supported for multi-array systems. '
+                'Use PVSystem.arrays[i].mount.surface_tilt.')
+        self.arrays[0].mount.surface_tilt = value
 
     @property
-    @_unwrap_single_value
     def surface_azimuth(self):
-        return tuple(array.surface_azimuth for array in self.arrays)
+        if len(self.arrays) == 1:
+            msg = (
+                'PVSystem.surface_azimuth attribute is deprecated. '
+                'Use PVSystem.arrays[0].mount.surface_azimuth.'
+            )
+            warnings.warn(msg, pvlibDeprecationWarning)
+        else:
+            raise AttributeError(
+                'PVSystem.surface_azimuth not supported for multi-array '
+                'systems. Use PVSystem.arrays[i].mount.surface_azimuth.')
+        return self.arrays[0].mount.surface_azimuth
 
     @surface_azimuth.setter
     def surface_azimuth(self, value):
-        for array in self.arrays:
-            array.surface_azimuth = value
+        if len(self.arrays) == 1:
+            msg = (
+                'PVSystem.surface_azimuth attribute is deprecated. '
+                'Use PVSystem.arrays[0].mount.surface_azimuth.'
+            )
+            warnings.warn(msg, pvlibDeprecationWarning)
+        else:
+            raise AttributeError(
+                'PVSystem.surface_azimuth not supported for multi-array '
+                'systems. Use PVSystem.arrays[i].mount.surface_azimuth.')
+        self.arrays[0].mount.surface_azimuth = value
 
     @property
     @_unwrap_single_value
@@ -1098,20 +1137,15 @@ class Array:
     """
     An Array is a set of of modules at the same orientation.
 
-    Specifically, an array is defined by tilt, azimuth, the
+    Specifically, an array is defined by its mount, the
     module parameters, the number of parallel strings of modules
     and the number of modules on each string.
 
     Parameters
     ----------
-    surface_tilt: float or array-like, default 0
-        Surface tilt angles in decimal degrees.
-        The tilt angle is defined as degrees from horizontal
-        (e.g. surface facing up = 0, surface facing horizon = 90)
-
-    surface_azimuth: float or array-like, default 180
-        Azimuth angle of the module surface.
-        North=0, East=90, South=180, West=270.
+    mount: FixedMount, SingleAxisTrackerMount, or other
+        Mounting strategy for the array, used to determine module orientation.
+        If not provided, a FixedMount with zero tilt is used.
 
     albedo : None or float, default None
         The ground albedo. If ``None``, will attempt to use
@@ -1151,17 +1185,14 @@ class Array:
 
     """
 
-    def __init__(self,
-                 surface_tilt=0, surface_azimuth=180,
+    def __init__(self, mount,
                  albedo=None, surface_type=None,
                  module=None, module_type=None,
                  module_parameters=None,
                  temperature_model_parameters=None,
                  modules_per_string=1, strings=1,
                  racking_model=None, name=None):
-        self.surface_tilt = surface_tilt
-        self.surface_azimuth = surface_azimuth
-
+        self.mount = mount
         self.surface_type = surface_type
         if albedo is None:
             self.albedo = irradiance.SURFACE_ALBEDOS.get(surface_type, 0.25)
@@ -1189,10 +1220,11 @@ def __init__(self,
         self.name = name
 
     def __repr__(self):
-        attrs = ['name', 'surface_tilt', 'surface_azimuth', 'module',
+        attrs = ['name', 'mount', 'module',
                  'albedo', 'racking_model', 'module_type',
                  'temperature_model_parameters',
                  'strings', 'modules_per_string']
+
         return 'Array:\n  ' + '\n  '.join(
             f'{attr}: {getattr(self, attr)}' for attr in attrs
         )
@@ -1213,7 +1245,6 @@ def _infer_temperature_model_params(self):
             return {}
 
     def _infer_cell_type(self):
-
         """
         Examines module_parameters and maps the Technology key for the CEC
         database and the Material key for the Sandia database to a common
@@ -1271,7 +1302,10 @@ def get_aoi(self, solar_zenith, solar_azimuth):
         aoi : Series
             Then angle of incidence.
         """
-        return irradiance.aoi(self.surface_tilt, self.surface_azimuth,
+        orientation = self.mount.calculate_orientation(solar_zenith,
+                                                       solar_azimuth)
+        return irradiance.aoi(orientation['surface_tilt'],
+                              orientation['surface_azimuth'],
                               solar_zenith, solar_azimuth)
 
     def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi,
@@ -1320,8 +1354,10 @@ def get_irradiance(self, solar_zenith, solar_azimuth, dni, ghi, dhi,
         if airmass is None:
             airmass = atmosphere.get_relative_airmass(solar_zenith)
 
-        return irradiance.get_total_irradiance(self.surface_tilt,
-                                               self.surface_azimuth,
+        orientation = self.mount.calculate_orientation(solar_zenith,
+                                                       solar_azimuth)
+        return irradiance.get_total_irradiance(orientation['surface_tilt'],
+                                               orientation['surface_azimuth'],
                                                solar_zenith, solar_azimuth,
                                                dni, ghi, dhi,
                                                dni_extra=dni_extra,
@@ -1373,6 +1409,130 @@ def get_iam(self, aoi, iam_model='physical'):
             raise ValueError(model + ' is not a valid IAM model')
 
 
+class AbstractMount(ABC):
+    def __repr__(self):
+        classname = self.__class__.__name__
+        return f'{classname}:\n    ' + '\n    '.join(
+            f'{attr}: {getattr(self, attr)}' for attr in self._repr_attrs
+        )
+
+    @abstractmethod
+    def calculate_orientation(self, solar_zenith, solar_azimuth):
+        """
+        Determine module orientation.
+
+        Parameters
+        ----------
+        solar_zenith : numeric
+            Solar apparent zenith angle [degrees]
+        solar_azimuth : numeric
+            Solar azimuth angle [degrees]
+
+        Returns
+        -------
+        orientation : dict-like
+            A dict-like object with keys `'surface_tilt', 'surface_azimuth'`
+        """
+        pass
+
+
+class FixedMount(AbstractMount):
+    """
+    Racking at fixed (static) orientation.
+
+    Parameters
+    ----------
+    surface_tilt : float, default 0
+        Surface tilt angle. The tilt angle is defined as angle from horizontal
+        (e.g. surface facing up = 0, surface facing horizon = 90) [degrees]
+
+    surface_azimuth : float, default 180
+        Azimuth angle of the module surface. North=0, East=90, South=180,
+        West=270. [degrees]
+    """
+
+    def __init__(self, surface_tilt=0, surface_azimuth=180):
+        self.surface_tilt = surface_tilt
+        self.surface_azimuth = surface_azimuth
+        self._repr_attrs = ['surface_tilt', 'surface_azimuth']
+
+    def calculate_orientation(self, solar_zenith, solar_azimuth):
+        # note -- docstring is automatically inherited from AbstractMount
+        return {
+            'surface_tilt': self.surface_tilt,
+            'surface_azimuth': self.surface_azimuth,
+        }
+
+
+class SingleAxisTrackerMount(AbstractMount):
+    """
+    Single-axis tracker racking for dynamic solar tracking.
+
+    Parameters
+    ----------
+    axis_tilt : float, default 0
+        The tilt of the axis of rotation (i.e, the y-axis defined by
+        axis_azimuth) with respect to horizontal. [degrees]
+
+    axis_azimuth : float, default 180
+        A value denoting the compass direction along which the axis of
+        rotation lies, measured east of north. [degrees]
+
+    max_angle : float, default 90
+        A value denoting the maximum rotation angle
+        of the one-axis tracker from its horizontal position (horizontal
+        if axis_tilt = 0). A max_angle of 90 degrees allows the tracker
+        to rotate to a vertical position to point the panel towards a
+        horizon. max_angle of 180 degrees allows for full rotation. [degrees]
+
+    backtrack : bool, default True
+        Controls whether the tracker has the capability to "backtrack"
+        to avoid row-to-row shading. False denotes no backtrack
+        capability. True denotes backtrack capability.
+
+    gcr : float, default 2.0/7.0
+        A value denoting the ground coverage ratio of a tracker system
+        which utilizes backtracking; i.e. the ratio between the PV array
+        surface area to total ground area. A tracker system with modules
+        2 meters wide, centered on the tracking axis, with 6 meters
+        between the tracking axes has a gcr of 2/6=0.333. If gcr is not
+        provided, a gcr of 2/7 is default. gcr must be <=1. [unitless]
+
+    cross_axis_tilt : float, default 0.0
+        The angle, relative to horizontal, of the line formed by the
+        intersection between the slope containing the tracker axes and a plane
+        perpendicular to the tracker axes. Cross-axis tilt should be specified
+        using a right-handed convention. For example, trackers with axis
+        azimuth of 180 degrees (heading south) will have a negative cross-axis
+        tilt if the tracker axes plane slopes down to the east and positive
+        cross-axis tilt if the tracker axes plane slopes up to the east. Use
+        :func:`~pvlib.tracking.calc_cross_axis_tilt` to calculate
+        `cross_axis_tilt`. [degrees]
+    """
+
+    def __init__(self, axis_tilt=0, axis_azimuth=180, max_angle=90,
+                 backtrack=True, gcr=2.0/7.0, cross_axis_tilt=0):
+        self.axis_tilt = axis_tilt
+        self.axis_azimuth = axis_azimuth
+        self.max_angle = max_angle
+        self.backtrack = backtrack
+        self.gcr = gcr
+        self.cross_axis_tilt = cross_axis_tilt
+        self._repr_attrs = ['axis_tilt', 'axis_azimuth', 'max_angle',
+                            'backtrack', 'gcr', 'cross_axis_tilt']
+
+    def calculate_orientation(self, solar_zenith, solar_azimuth):
+        # note -- docstring is automatically inherited from AbstractMount
+        from pvlib import tracking  # avoid circular import issue
+        tracking_data = tracking.singleaxis(
+            solar_zenith, solar_azimuth,
+            self.axis_tilt, self.axis_azimuth,
+            self.max_angle, self.backtrack,
+            self.gcr, self.cross_axis_tilt
+        )
+        return tracking_data
+
+
 def calcparams_desoto(effective_irradiance, temp_cell,
                       alpha_sc, a_ref, I_L_ref, I_o_ref, R_sh_ref, R_s,
                       EgRef=1.121, dEgdT=-0.0002677,