Add TwoAxisTrackerField class (#14)

* Create twoaxistrackerfield.py

* Add TwoAxisTrackerField to __init__.py and documentation.rst

* Add _calculate_l_min to layout

* Fix linter error

* Update twoaxistrackerfield.py

* Reorder layout ValueError warnings

* Fix typo

* Remove layout_type from generate_field_layout function

* Add layout_type code to TwoAxisTrackerField

* L_min -> min_tracker_spacing

* Add whatsnew entry

* Fix linting errors

* Update twoaxistrackerfield.py

* Correct horizon shading

* Update twoaxistracking/twoaxistrackerfield.py

Co-authored-by: Kevin Anderson <[email protected]>

* Update twoaxistracking/twoaxistrackerfield.py

Co-authored-by: Kevin Anderson <[email protected]>

* Update twoaxistracking/twoaxistrackerfield.py

Co-authored-by: Kevin Anderson <[email protected]>

* Return scalar when scalar is passed

* Correct use of np.isscalar

* Update documentation

* Update whatsnew

* Rework intro_tutorial.ipynb

* Add test_twoaxistrackerfield.py

* Update whatsnew.md

* Update README.md

Co-authored-by: Kevin Anderson <[email protected]>

Author: AdamRJensen

docs/source/documentation.rst

@@ -8,4 +8,7 @@ Code documentation
    :toctree: generated/
 
    shaded_fraction
-   generate_field_layout
+   generate_field_layout
+   TwoAxisTrackerField
+   TwoAxisTrackerField.get_shaded_fraction
+   TwoAxisTrackerField.plot_field_layout

docs/source/notebooks/intro_tutorial.ipynb

@@ -13,14 +13,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Tilted fields can now be simulated by specifyig the keywords ``slope_azimuth`` and
    ``slope_tilt`` (see PR#7).
 - The code now is able to differentiate between the active area and total area (see PR#11).
-
+- The class TwoAxisTrackerField has been added, which is now the recommended way for using
+  the package and is sufficient for most use cases.
 
 ### Changed
 - Divide code into modules: shading, plotting, and layout
 - Changed the overall file structure to become a Python package
 - Changed names of notebooks
 - Change repository name from "two_axis_tracker_shading" to
   "twoaxistracking"
+- Changed naming of ``L_min`` to ``min_tracker_spacing``
+- Changed naming of ``collector_area`` to ``total_collector_area``
+- The field layout parameters are now required when using the
+  {py:func}`twoaxistracking.layout.generate_field_layout` function. The standard field layouts
+  are only available through the TwoAxisTrackerField class.
 
 ### Testing
 - Linting using flake8 was added in PR#11

docs/source/whatsnew.md

@@ -1,6 +1,6 @@
 from .layout import generate_field_layout  # noqa: F401
 from .shading import shaded_fraction  # noqa: F401
-
+from .twoaxistrackerfield import TwoAxisTrackerField  # noqa: F401
 
 try:
     from shapely.geos import lgeos  # noqa: F401

twoaxistracking/__init__.py

@@ -1,5 +1,5 @@
 import numpy as np
-from twoaxistracking import plotting
+from shapely import geometry
 
 
 def _rotate_origin(x, y, rotation_deg):
@@ -11,22 +11,19 @@ def _rotate_origin(x, y, rotation_deg):
     return xx, yy
 
 
-def generate_field_layout(gcr, total_collector_area, L_min, neighbor_order,
-                          aspect_ratio=None, offset=None, rotation=None,
-                          layout_type=None, slope_azimuth=0,
-                          slope_tilt=0, plot=False):
+def _calculate_min_tracker_spacing(collector_geometry):
+    min_tracker_spacing = 2 * collector_geometry.hausdorff_distance(geometry.Point(0, 0))
+    return min_tracker_spacing
+
+
+def generate_field_layout(gcr, total_collector_area, min_tracker_spacing,
+                          neighbor_order, aspect_ratio, offset, rotation,
+                          slope_azimuth=0, slope_tilt=0):
     """
     Generate a regularly-spaced collector field layout.
 
     Field layout parameters and limits are described in [1]_.
 
-    Notes
-    -----
-    The field layout can be specified either by selecting a standard layout
-    using the layout_type argument or by specifying the individual layout
-    parameters aspect_ratio, offset, and rotation. For both cases the ground
-    cover ratio (gcr) needs to be specified.
-
     Any length unit can be used as long as the usage is consistent with the
     collector geometry.
 
@@ -36,26 +33,22 @@ def generate_field_layout(gcr, total_collector_area, L_min, neighbor_order,
         Ground cover ratio. Ratio of collector area to ground area.
     total_collector_area: float
         Surface area of one collector.
-    L_min: float
+    min_tracker_spacing: float
         Minimum distance between collectors.
     neighbor_order: int
         Order of neighbors to include in layout. neighbor_order=1 includes only
         the 8 directly adjacent collectors.
-    aspect_ratio: float, optional
+    aspect_ratio: float
         Ratio of the spacing in the primary direction to the secondary.
-    offset: float, optional
+    offset: float
         Relative row offset in the secondary direction as fraction of the
         spacing in the primary direction. -0.5 <= offset < 0.5.
-    rotation: float, optional
+    rotation: float
         Counterclockwise rotation of the field in degrees. 0 <= rotation < 180
-    layout_type: {square, square_rotated, hexagon_e_w, hexagon_n_s}, optional
-        Specification of the special layout type (only depend on gcr).
     slope_azimuth : float, optional
         Direction of normal to slope on horizontal [degrees]
     slope_tilt : float, optional
         Tilt of slope relative to horizontal [degrees]
-    plot: bool, default: False
-        Whether to plot the field layout.
 
     Returns
     -------
@@ -81,48 +74,22 @@ def generate_field_layout(gcr, total_collector_area, L_min, neighbor_order,
     .. [1] `Shading and land use in regularly-spaced sun-tracking collectors, Cumpston & Pye.
        <https://doi.org/10.1016/j.solener.2014.06.012>`_
     """
-    # Consider special layouts which can be defined only by GCR
-    if layout_type == 'square':
-        aspect_ratio = 1
-        offset = 0
-        rotation = 0
-    # Diagonal layout is the square layout rotated 45 degrees
-    elif layout_type == 'diagonal':
-        aspect_ratio = 1
-        offset = 0
-        rotation = 45
-    # Hexagonal layouts are defined by aspect_ratio=0.866 and offset=-0.5
-    elif layout_type == 'hexagonal_n_s':
-        aspect_ratio = np.sqrt(3)/2
-        offset = -0.5
-        rotation = 0
-    # The hexagonal E-W layout is the hexagonal N-S layout rotated 90 degrees
-    elif layout_type == 'hexagonal_e_w':
-        aspect_ratio = np.sqrt(3)/2
-        offset = -0.5
-        rotation = 90
-    elif layout_type is not None:
-        raise ValueError('The layout type specified was not recognized.')
-    elif ((aspect_ratio is None) or (offset is None) or (rotation is None)):
-        raise ValueError('Aspect ratio, offset, and rotation needs to be '
-                         'specified when no layout type has not been selected')
-
     # Check parameters are within their ranges
-    if aspect_ratio < np.sqrt(1-offset**2):
-        raise ValueError('Aspect ratio is too low and not feasible')
-    if aspect_ratio > total_collector_area/(gcr*L_min**2):
-        raise ValueError('Apsect ratio is too high and not feasible')
     if (offset < -0.5) | (offset >= 0.5):
         raise ValueError('The specified offset is outside the valid range.')
     if (rotation < 0) | (rotation >= 180):
         raise ValueError('The specified rotation is outside the valid range.')
-    # Check if mimimum and maximum ground cover ratios are exceded
-    gcr_max = total_collector_area / (L_min**2 * np.sqrt(1-offset**2))
-    if (gcr < 0) or (gcr > gcr_max):
-        raise ValueError('Maximum ground cover ratio exceded.')
     # Check if Lmin is physically possible given the collector area.
-    if (L_min < np.sqrt(4*total_collector_area/np.pi)):
+    if (min_tracker_spacing < np.sqrt(4*total_collector_area/np.pi)):
         raise ValueError('Lmin is not physically possible.')
+    # Check if mimimum and maximum ground cover ratios are exceded
+    gcr_max = total_collector_area / (min_tracker_spacing**2 * np.sqrt(1-offset**2))
+    if (gcr < 0) or (gcr > gcr_max):
+        raise ValueError('Maximum ground cover ratio exceded or less than 0.')
+    if aspect_ratio < np.sqrt(1-offset**2):
+        raise ValueError('Aspect ratio is too low and not feasible')
+    if aspect_ratio > total_collector_area/(gcr*min_tracker_spacing**2):
+        raise ValueError('Aspect ratio is too high and not feasible')
 
     N = 1 + 2 * neighbor_order  # Number of collectors along each side
 
@@ -156,8 +123,4 @@ def generate_field_layout(gcr, total_collector_area, L_min, neighbor_order,
     # positive means collector is higher than reference collector
     relative_slope = -np.cos(np.deg2rad(slope_azimuth - relative_azimuth)) * slope_tilt  # noqa: E501
 
-    # Visualize layout
-    if plot:
-        plotting._plot_field_layout(X, Y, Z, L_min)
-
     return X, Y, Z, tracker_distance, relative_azimuth, relative_slope

twoaxistracking/layout.py

@@ -6,33 +6,33 @@
 from matplotlib import cm
 
 
-def _plot_field_layout(X, Y, Z, L_min):
-    """Plot field layout."""
+def _plot_field_layout(X, Y, Z, min_tracker_spacing):
+    """Create a plot of the field layout."""
     # Collector heights is illustrated with colors from a colormap
     norm = mcolors.Normalize(vmin=min(Z)-0.000001, vmax=max(Z)+0.000001)
-    # 0.000001 is added/subtracted for the limits in order for the colormap
+    # 0.000001 is added/subtracted to/from the limits in order for the colormap
     # to correctly display the middle color when all tracker Z coords are zero
     cmap = cm.viridis_r
     colors = cmap(norm(Z))
     fig, ax = plt.subplots(figsize=(6, 6), subplot_kw={'aspect': 'equal'})
-    # Plot a circle for each neighboring collector (diameter equals L_min)
+    # Plot a circle for each neighboring collector (diameter equals min_tracker_spacing)
     ax.add_collection(collections.EllipseCollection(
-        widths=L_min, heights=L_min, angles=0, units='xy', facecolors=colors,
-        edgecolors=("black",), linewidths=(1,), offsets=list(zip(X, Y)),
-        transOffset=ax.transData))
+        widths=min_tracker_spacing, heights=min_tracker_spacing, angles=0,
+        units='xy', facecolors=colors, edgecolors=("black",), linewidths=(1,),
+        offsets=list(zip(X, Y)), transOffset=ax.transData))
     # Similarly, add a circle for the origin
     ax.add_collection(collections.EllipseCollection(
-        widths=L_min, heights=L_min, angles=0, units='xy', facecolors='red',
-        edgecolors=("black",), linewidths=(1,), offsets=[0, 0],
-        transOffset=ax.transData))
-    plt.axis('equal')
+        widths=min_tracker_spacing, heights=min_tracker_spacing, angles=0,
+        units='xy', facecolors='red', edgecolors=("black",), linewidths=(1,),
+        offsets=[0, 0], transOffset=ax.transData))
     fig.colorbar(cm.ScalarMappable(norm=norm, cmap=cmap), ax=ax, shrink=0.8,
                  label='Relative tracker height (vertical)')
     # Set limits
-    lower_lim = min(min(X), min(Y)) - L_min
-    upper_lim = max(max(X), max(Y)) + L_min
-    ax.set_ylim(lower_lim, upper_lim)
+    lower_lim = min(min(X), min(Y)) - min_tracker_spacing
+    upper_lim = max(max(X), max(Y)) + min_tracker_spacing
     ax.set_xlim(lower_lim, upper_lim)
+    ax.set_ylim(lower_lim, upper_lim)
+    return fig
 
 
 def _polygons_to_patch_collection(geometries, **kwargs):
@@ -49,7 +49,7 @@ def _polygons_to_patch_collection(geometries, **kwargs):
 
 
 def _plot_shading(active_collector_geometry, unshaded_geometry,
-                  shading_geometries, L_min):
+                  shading_geometries, min_tracker_spacing):
     """Plot the shaded and unshaded area for a specific solar position."""
     active_patches = _polygons_to_patch_collection(
         active_collector_geometry, facecolor='red', linewidth=0.5, alpha=0.5)
@@ -59,12 +59,12 @@ def _plot_shading(active_collector_geometry, unshaded_geometry,
         shading_geometries, facecolor='blue', linewidth=0.5, alpha=0.5)
 
     fig, axes = plt.subplots(1, 2, subplot_kw=dict(aspect='equal'))
-    axes[0].set_title('Unshaded and shading areas')
+    axes[0].set_title('Total area and shading areas')
     axes[0].add_collection(active_patches, autolim=True)
     axes[0].add_collection(shading_patches, autolim=True)
     axes[1].set_title('Unshaded area')
     axes[1].add_collection(unshaded_patches, autolim=True)
     for ax in axes:
-        ax.set_xlim(-L_min, L_min)
-        ax.set_ylim(-L_min, L_min)
-    plt.show()
+        ax.set_xlim(-min_tracker_spacing, min_tracker_spacing)
+        ax.set_ylim(-min_tracker_spacing, min_tracker_spacing)
+    return fig

twoaxistracking/plotting.py

@@ -3,19 +3,10 @@
 from twoaxistracking import plotting
 
 
-def _rotate_origin(x, y, rotation_deg):
-    """Rotate a set of 2D points counterclockwise around the origin (0, 0)."""
-    rotation_rad = np.deg2rad(rotation_deg)
-    # Rotation is set negative to make counterclockwise rotation
-    xx = x * np.cos(-rotation_rad) + y * np.sin(-rotation_rad)
-    yy = -x * np.sin(-rotation_rad) + y * np.cos(-rotation_rad)
-    return xx, yy
-
-
 def shaded_fraction(solar_elevation, solar_azimuth,
                     total_collector_geometry, active_collector_geometry,
-                    L_min, tracker_distance, relative_azimuth, relative_slope,
-                    slope_azimuth=0, slope_tilt=0, plot=False):
+                    min_tracker_spacing, tracker_distance, relative_azimuth,
+                    relative_slope, slope_azimuth=0, slope_tilt=0, plot=False):
     """Calculate the shaded fraction for any layout of two-axis tracking collectors.
 
     Parameters
@@ -28,7 +19,7 @@ def shaded_fraction(solar_elevation, solar_azimuth,
         Polygon corresponding to the total collector area.
     active_collector_geometry: Shapely Polygon or MultiPolygon
         One or more polygons defining the active collector area.
-    L_min: float
+    min_tracker_spacing: float
         Minimum distance between collectors. Used for selecting possible
         shading collectors.
     tracker_distance: array of floats
@@ -57,7 +48,9 @@ def shaded_fraction(solar_elevation, solar_azimuth,
         return np.nan
     # Set shaded fraction to 1 (fully shaded) if the solar elevation is below
     # the horizon line caused by the tilted ground
-    elif solar_elevation < - np.cos(np.deg2rad(slope_azimuth-solar_azimuth)) * slope_tilt:
+    elif np.tan(np.deg2rad(solar_elevation)) <= (
+            - np.cos(np.deg2rad(slope_azimuth-solar_azimuth))
+            * np.tan(np.deg2rad(slope_tilt))):
         return 1
 
     azimuth_difference = solar_azimuth - relative_azimuth
@@ -75,7 +68,7 @@ def shaded_fraction(solar_elevation, solar_azimuth,
     unshaded_geometry = active_collector_geometry
     shading_geometries = []
     for i, (x, y) in enumerate(zip(xoff, yoff)):
-        if np.sqrt(x**2+y**2) < L_min:
+        if np.sqrt(x**2+y**2) < min_tracker_spacing:
             # Project the geometry of the shading collector (total area) onto
             # the plane of the reference collector
             shading_geometry = shapely.affinity.translate(total_collector_geometry, x, y)  # noqa: E501
@@ -86,7 +79,7 @@ def shaded_fraction(solar_elevation, solar_azimuth,
 
     if plot:
         plotting._plot_shading(active_collector_geometry, unshaded_geometry,
-                               shading_geometries, L_min)
+                               shading_geometries, min_tracker_spacing)
 
     shaded_fraction = 1 - unshaded_geometry.area / active_collector_geometry.area
     return shaded_fraction