Max Elevation Scan Angle Config (#11)

Add max elevation scan angle to LOS parameters. Restrict to [0,90].

In LOS Validator simple checks, add back same x,y coordinate check separate from elevation scan angle check. Allow elevation scan angle to be 90 degrees. Because of x,y coordinate check, 90 degrees technically is not allowed, but this enables the user to allow all elevation scan angles < 90 degrees (even if that is not advisable).

Author: dbeylkin

docs/algorithm/line_of_sight/Easy_Negative_Cases.md

@@ -1,12 +1,15 @@
 # Easy Negative Cases
 
-Regardless of the model, there are four situations which immediately return
+Regardless of the model, there are five situations which immediately return
 invalid LOS that has nothing to do with obstructions.
 
-1. The elevation angle between the two sites is too large (i.e., it should be
-   much less than 90 degrees).
-2. Both sites are on the same building (generally, such sites can be connected
+1. Sites have the same latitude and longitude.
+2. The elevation angle between the two sites is larger than a user-specified
+   maximum elevation scan angle. While this would seemingly make #1 redundant,
+   a user can effectively disable this check by setting it to 90 degrees (even
+   if that is not advisable).
+3. Both sites are on the same building (generally, such sites can be connected
    by wire).
-3. The distance between the sites exceeds the maximum distance (i.e., the
+4. The distance between the sites exceeds the maximum distance (i.e., the
    signal is not sufficiently strong to merit valid LOS).
-4. The LOS intersects with exclusion zones.
+5. The LOS intersects with exclusion zones.

terragraph_planner/common/configuration/configs.py

@@ -424,6 +424,7 @@ def __init__(
         link_availability_percentage: float = 99.9,
         maximum_los_distance: Optional[int] = 200,
         minimum_los_distance: int = 50,
+        maximum_elevation_scan_angle: float = 25,
         carrier_frequency: float = DEFAULT_CARRIER_FREQUENCY,
         thermal_noise_power: float = -81.0,
         noise_figure: float = 7.0,
@@ -464,6 +465,11 @@ def __init__(
             "and maximum LOS distance must be larger than minimum LOS distance",
             ConfigException,
         )
+        planner_assert(
+            0 <= maximum_elevation_scan_angle <= 90,
+            "Maximum elevation scan angle must be in [0, 90]",
+            ConfigException,
+        )
         planner_assert(
             mounting_height_above_rooftop >= 0,
             "Mounting height above rooftop cannot be negative",
@@ -494,6 +500,7 @@ def __init__(
         self.rain_rate = rain_rate
         self.maximum_los_distance = maximum_los_distance
         self.minimum_los_distance = minimum_los_distance
+        self.maximum_elevation_scan_angle = maximum_elevation_scan_angle
         self.carrier_frequency = carrier_frequency
         self.thermal_noise_power = thermal_noise_power
         self.noise_figure = noise_figure

terragraph_planner/common/configuration/test/test_data/exhausted_configs_with_non_default.yaml

@@ -23,6 +23,7 @@ LINE_OF_SIGHT:
   DEFAULT_CN_HEIGHT_ON_POLE: 8
   MAXIMUM_LOS_DISTANCE: 500
   MINIMUM_LOS_DISTANCE: 5
+  MAXIMUM_ELEVATION_SCAN_ANGLE: 30
   MINIMUM_MCS_OF_BACKHAUL_LINKS: 2
   MINIMUM_MCS_OF_ACCESS_LINKS: 3
   USE_ELLIPSOIDAL_LOS_MODEL: True

terragraph_planner/common/configuration/test/test_utils.py

@@ -284,6 +284,7 @@ def test_struct_object_from_non_default_file(self) -> None:
             link_availability_percentage=78.9,
             maximum_los_distance=500,
             minimum_los_distance=5,
+            maximum_elevation_scan_angle=30,
             carrier_frequency=50000.0,
             thermal_noise_power=-78.0,
             noise_figure=6.6,

terragraph_planner/common/constants.py

@@ -11,8 +11,6 @@
     3  # precision used in placement of equidistance sectors
 )
 EARTH_RADIUS: float = 6371000.0  # the radius of the earth, in meters
-# The upper bound for elevation deviation for valid los
-ELE_SCAN_ANGLE_LIMIT = 25
 FSPL_MARGIN = 92.45  # free-space path loss constant
 FULL_ROTATION_ANGLE = 360.0
 # WGS 84, aka EPSG 4326, latitude/longitude coordinate system based on the Earth's

terragraph_planner/data/template.yaml

@@ -103,6 +103,10 @@ LINE_OF_SIGHT:
   # viable communication between two sites
   MINIMUM_LOS_DISTANCE: 50
 
+  # [Float] Maximum elevation scan angle with respect to the xy-plane for
+  # viable communication between two sites.
+  MAXIMUM_ELEVATION_SCAN_ANGLE: 25
+
   # [Optional][Int] Minimum MCS used to determine the maximum line-of-sight
   # distance for backhaul/access links in the LOS candidate graph. This
   # distance is computed to be the point at which the link capacity goes to 0

terragraph_planner/los/base_los_validator.py

@@ -38,7 +38,7 @@ def __init__(
             LOSException,
         )
         planner_assert(
-            0 < max_el_dev < 90,
+            0 <= max_el_dev <= 90,
             "Invalid max elevation deviation",
             LOSException,
         )
@@ -74,11 +74,15 @@ def _comp_los_distance(site1: LOSSite, site2: LOSSite) -> float:
     def _passes_simple_checks(self, site1: LOSSite, site2: LOSSite) -> bool:
         """
         Performs these simple checks
-        Check 1: on the same building
-        Check 2: out of distance range
-        Check 3: exceeds max elevation deviation
-        Check 4: intersects with the exclusion zones
+        Check 1: same xy location
+        Check 2: on the same building
+        Check 3: out of distance range
+        Check 4: exceeds max elevation deviation
+        Check 5: intersects with the exclusion zones
         """
+        if self._same_xy(site1, site2):
+            return False
+
         if self._on_the_same_building(site1, site2):
             return False
 
@@ -96,6 +100,9 @@ def _passes_simple_checks(self, site1: LOSSite, site2: LOSSite) -> bool:
 
         return True
 
+    def _same_xy(self, site1: LOSSite, site2: LOSSite) -> bool:
+        return site1.utm_x == site2.utm_x and site1.utm_y == site2.utm_y
+
     def _on_the_same_building(self, site1: LOSSite, site2: LOSSite) -> bool:
         return (
             site1.location_type

terragraph_planner/los/core.py

@@ -150,6 +150,7 @@ def generate_candidate_topology(
         exclusion_zones,
         max_los_distance,
         los_params.minimum_los_distance,
+        los_params.maximum_elevation_scan_angle,
         los_params.los_confidence_threshold,
         los_params.use_ellipsoidal_los_model,
         los_params.fresnel_radius,
@@ -255,6 +256,7 @@ def compute_los(
     exclusion_zones: List[Polygon],
     max_los_distance: int,
     min_los_distance: int,
+    max_el_scan_angle: float,
     los_confidence_threshold: float,
     use_ellipsoidal_los_model: bool,
     fresnel_radius: float,
@@ -276,7 +278,8 @@ def compute_los(
     @params exlcusion_zones
     A list of Polygons where a LOS is prohibited.
 
-    @params max_los_distance, min_los_distance, los_confidence_threshold, fresnel_radius, carrier_frequency
+    @params max_los_distance, min_los_distance, max_el_scan_angle, los_confidence_threshold,
+    fresnel_radius, carrier_frequency
     A set of params to construct the LOS validator to validate the LOS
 
     @params use_ellipsoidal_los_model
@@ -338,6 +341,7 @@ def compute_los(
                 else None,
                 max_los_distance=max_los_distance,
                 min_los_distance=min_los_distance,
+                max_el_scan_angle=max_el_scan_angle,
                 los_confidence_threshold=los_confidence_threshold,
                 use_ellipsoidal_los_model=use_ellipsoidal_los_model,
                 fresnel_radius=fresnel_radius,
@@ -415,6 +419,7 @@ def build_candidate_topology(
         los_params.device_list,
         device_pair_to_max_los_dist,
         los_params.minimum_los_distance,
+        los_params.maximum_elevation_scan_angle,
     )
     logger.info("Completed constructing the topology.")
     return topology

terragraph_planner/los/helper.py

@@ -30,7 +30,6 @@
     StatusType,
 )
 from terragraph_planner.common.constants import (
-    ELE_SCAN_ANGLE_LIMIT,
     LOWER_BOUND_FOR_LOS_DISTANCE,
     UPPER_BOUND_FOR_LOS_DISTANCE,
 )
@@ -515,6 +514,7 @@ def compute_los_batch(
     left_top_y: Optional[float],
     max_los_distance: int,
     min_los_distance: int,
+    max_el_scan_angle: float,
     los_confidence_threshold: float,
     use_ellipsoidal_los_model: bool,
     fresnel_radius: float,
@@ -549,7 +549,7 @@ def compute_los_batch(
             surface_elevation,
             max_los_distance * (1 + DISTANCE_TOLERANCE_PERCENT),
             min_los_distance * (1 - DISTANCE_TOLERANCE_PERCENT),
-            ELE_SCAN_ANGLE_LIMIT + ELE_SCAN_ANGLE_TOLERANCE,
+            min(max_el_scan_angle + ELE_SCAN_ANGLE_TOLERANCE, 90),
             carrier_frequency,
             exclusion_zones,
             los_confidence_threshold,
@@ -559,7 +559,7 @@ def compute_los_batch(
             surface_elevation,
             max_los_distance * (1 + DISTANCE_TOLERANCE_PERCENT),
             min_los_distance * (1 - DISTANCE_TOLERANCE_PERCENT),
-            ELE_SCAN_ANGLE_LIMIT + ELE_SCAN_ANGLE_TOLERANCE,
+            min(max_el_scan_angle + ELE_SCAN_ANGLE_TOLERANCE, 90),
             fresnel_radius,
             exclusion_zones,
             los_confidence_threshold,
@@ -831,6 +831,7 @@ def construct_topology_from_los_result(
     device_list: List[DeviceData],
     device_pair_to_max_los_dist: Dict[Tuple[str, str], int],
     min_los_dist: int,
+    max_el_scan_angle: float,
 ) -> Topology:
     """
     Construct a Topology instance for candidate graph from LOS result.
@@ -849,6 +850,8 @@ def construct_topology_from_los_result(
     A dict mapping a pair of device SKUs to the max los distance.
     @param min_los_dist
     An int for the min los distance.
+    @param max_el_scan_angle
+    An float for the max elevation scan angle.
     @return
     A Topology representing the candidate graph.
     """
@@ -868,6 +871,7 @@ def construct_topology_from_los_result(
         confidence_dict,
         device_pair_to_max_los_dist,
         min_los_dist,
+        max_el_scan_angle,
     )
 
 
@@ -928,6 +932,7 @@ def add_links_to_topology(
     confidence_dict: Dict[Tuple[int, int], float],
     device_pair_to_max_los_dist: Dict[Tuple[str, str], int],
     min_los_dist: int,
+    max_el_scan_angle: float,
 ) -> Topology:
     """
     Called by construct_topology_from_los_result, this function is to add links to
@@ -961,7 +966,7 @@ def add_links_to_topology(
                                 rx_site.device.device_sku,
                             )
                         ]
-                        and link.el_dev <= ELE_SCAN_ANGLE_LIMIT
+                        and link.el_dev <= max_el_scan_angle
                     ):
                         topology.add_link(link)
     return topology

terragraph_planner/los/test/test_base_los_validator.py

@@ -43,10 +43,10 @@ def setUp(self) -> None:
 
     def test_same_x_y_coordinate(self) -> None:
         base_los_validator = MockBaseLOSValidator(
-            self.elevation, 5, 1, 89, [], 1
+            self.elevation, 5, 1, 90, [], 1
         )
         self.assertEqual(
-            base_los_validator._passes_simple_checks(
+            base_los_validator._same_xy(
                 build_los_site_for_los_test(
                     2.5,
                     2.5,
@@ -62,7 +62,7 @@ def test_same_x_y_coordinate(self) -> None:
                     building_id=1,
                 ),
             ),
-            False,
+            True,
         )
 
     def test_on_the_same_building(self) -> None: