data_structures_rmolinari 0.4.1 → 0.4.2

data/lib/data_structures_rmolinari/algorithms.rb

@@ -0,0 +1,103 @@
+# A collection of algorithms that use the module's data structures but don't belong as a method on one of the data structures
+module DataStructuresRMolinari::Algorithms
+  include Shared
+
+  # We are given a set P of points in the x-y plane. An _empty rectangle for P_ is a rectangle (left, right, bottom, top)
+  # satisifying the following
+  #   - it has positive area;
+  #   - its sides are parallel to the axes;
+  #   - it lies within the smallest bounding box (x_min, x_max, y_min, y_max) containing P; and
+  #   - no point of P lies in its interior.
+  #
+  # A _maximal empty rectangle_ (MER) for P is an empty rectangle for P not properly contained in any other.
+  #
+  # We enumerate all maximal empty rectangles for P, yielding each as (left, right, bottom, top) to a block. The algorithm is due to
+  # De, M., Maheshwari, A., Nandy, S. C., Smid, M., _An In-Place Min-max Priority Search Tree_, Computational Geometry, v46 (2013),
+  # pp 310-327.
+  #
+  # It runs in O(m log n) time, where m is the number of MERs enumerated and n is the number of points in P.  (Contructing the
+  # MaxPST below takes O(n log^2 n) time, but m = O(n^2) so we are still O(m log n) overall.)
+  #
+  # @param points [Array] an array of points in the x-y plane. Each must respond to +x+ and +y+.
+  def self.maximal_empty_rectangles(points)
+    # We break the emtpy rectangles into three types
+    #   1. bounded at bottom and top by y_min and y_max
+    #   2. bounded at the top by y_max and at the bottom by one of the points of P
+    #   3. bounded at the top by a point in P
+
+    return if points.size <= 1
+
+    sorted_points = points.sort_by(&:x)
+    x_min = sorted_points.first.x
+    x_max = sorted_points.last.x
+    y_min, y_max = sorted_points.map(&:y).minmax
+
+    # Half of the smallest non-zero gap between x values. This is needed below
+    epsilon = INFINITY
+
+    # Enumerate type 1
+    sorted_points.each_cons(2) do |pt1, pt2|
+      next if pt1.x == pt2.x
+
+      d = (pt2.x.to_f - pt1.x) / 2
+      epsilon = d if d < epsilon
+
+      yield [pt1.x, pt2.x, y_min, y_max]
+    end
+
+    # This builds its internal structure inside sorted_points itself.
+    max_pst = DataStructuresRMolinari::MaxPrioritySearchTree.new(sorted_points, dynamic: true)
+
+    # Enumerate type 2. We consider each point of P and work out the largest rectangle bounded below by P and above by y_max. The
+    # points constraining us on the left and right are given by queries on the MaxPST.
+    points.each do |pt|
+      next if pt.y == y_max # 0 area
+      next if pt.y == y_min # type 1
+
+      # Epsilon means we don't just get pt back again. The De et al. paper is rather vague.
+      left_bound  = max_pst.largest_x_in_nw( pt.x - epsilon, pt.y)
+      right_bound = max_pst.smallest_x_in_ne(pt.x + epsilon, pt.y)
+
+      left = left_bound.x.infinite? ? x_min : left_bound.x
+      right = right_bound.x.infinite? ? x_max : right_bound.x
+      next if left == right
+
+      yield [left, right, pt.y, y_max]
+    end
+
+    # Enumerate type 3. This is the cleverest part of the algorithm. Start with a point (x0, y0) in P. We imagine a horizontal line
+    # drawing down over the bounding rectangle, starting at y = y0 with l = x_min and r = x_max. Every time we meet another point
+    # (x1, y1) of P we emit a maximal rectangle and shorten the horizonal line. At any time, the next point that we encounter is the
+    # highest (max y) point in the region l < x < r and y >= y_min.
+    #
+    # If we have a MaxPST containing with the points (x0, y0) and above deleted, (x1, y1) is almost given by
+    #
+    #      largest_y_in_3_sided(l, r, y_min)
+    #
+    # That call considers the points in the closed region l <= x <= r and y >= y_min, so we use l + epsilon and r - epsilon.
+    until max_pst.empty?
+      top_pt = max_pst.delete_top!
+      top = top_pt.y
+      next if top == y_max # this one is type 1 or 2
+      next if top == y_min # zero area: no good
+
+      l = x_min
+      r = x_max
+
+      loop do
+        next_pt = max_pst.largest_y_in_3_sided(l + epsilon, r - epsilon, y_min)
+
+        bottom = next_pt.y.infinite? ? y_min : next_pt.y
+        yield [l, r, bottom, top]
+
+        break if next_pt.y.infinite? # we have reached the bottom
+
+        if next_pt.x < top_pt.x
+          l = next_pt.x
+        else
+          r = next_pt.x
+        end
+      end
+    end
+  end
+end

data/lib/data_structures_rmolinari/max_priority_search_tree.rb

@@ -30,9 +30,14 @@ require_relative 'shared'
 #
 # The final operation (enumerate) takes O(m + log n) time, where m is the number of points that are enumerated.
 #
-# In the current implementation no two points can share an x-value. This (rather severe) restriction can be relaxed with some more
-# complicated code, but it hasn't been written yet. See issue #9.
+# If the MaxPST is constructed to be "dynamic" we also have an operation that deletes the top element.
 #
+# - +delete_top!+: remove the top (max-y) element of the tree and return it.
+#
+# It runs in O(log n) time, where n is the size of the PST when it was initially created.
+#
+# In the current implementation no two points can share an x-value. This restriction can be relaxed with some more complicated code,
+# but it hasn't been written yet. See issue #9.
 #
 # There is a related data structure called the Min-max priority search tree so we have called this a "Max priority search tree", or
 # MaxPST.
@@ -53,18 +58,26 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
   #   - The +x+ values must be distinct. We raise a +Shared::DataError+ if this isn't the case.
   #     - This is a restriction that simplifies some of the algorithm code. It can be removed as the cost of some extra work. Issue
   #       #9.
-  #
+  # @param dynamic [Boolean] when truthy the PST is _dynamic_. This means the root can be deleted, which is useful in certain
+  #        algorithms than use a PST.
+  #        - a dynamic PST needs more bookwork for some internal work and so slows things down a little.
   # @param verify [Boolean] when truthy, check that the properties of a PST are satisified after construction, raising an exception
   #        if not.
-  def initialize(data, verify: false)
+  def initialize(data, dynamic: false, verify: false)
     @data = data
     @size = @data.size
+    @member_count = @size # these can diverge for dynamic PSTs
+    @dynamic = dynamic
 
     construct_pst
 
     verify_properties if verify
   end
 
+  def empty?
+    @member_count.zero?
+  end
+
   ########################################
   # Highest NE and Highest NW
 
@@ -154,9 +167,9 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
       elsif p_val.y < y0
         # p is too low for Q, so the entire subtree is too low as well
         return best
-      elsif one_child?(p)
+      elsif (child = one_child?(p))
         # With just one child we need to check it
-        p = left(p)
+        p = child
       elsif exclusionary_x.call(@data[preferred_child.call(p)].x)
         # right(p) might be in Q, but nothing in the left subtree can be, by the PST property on x.
         p = preferred_child.call(p)
@@ -234,6 +247,8 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
       best = Point.new(-INFINITY, INFINITY)
     end
 
+    return best if empty?
+
     p = q = root
 
     in_q = lambda do |pair|
@@ -307,13 +322,15 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
       [new_p, new_q]
     end
 
-    until leaf?(p)
+    # Now that we have the possibility of dynamic PSTs we need to worry about more cases. For example, p might be a leaf even though
+    # q is not
+    until leaf?(p) && leaf?(q)
       update_best.call(p)
       update_best.call(q)
 
       if p == q
-        if one_child?(p)
-          p = q = left(p)
+        if (child = one_child?(p))
+          p = q = child
         else
           q = right(p)
           p = left(p)
@@ -321,13 +338,23 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
       else
         # p != q
         if leaf?(q)
-          q = p # p itself is just one layer above the leaves, or is itself a leaf
-        elsif one_child?(q)
+          q = p
+        elsif leaf?(p)
+          p = q
+        else
+          p_only_child = one_child?(p)
+          q_only_child = one_child?(q)
           # This generic approach is not as fast as the bespoke checks described in the paper. But it is easier to maintain the code
           # this way and allows easy implementation of largest_x_in_nw
-          p, q = determine_next_nodes.call(left(p), right(p), left(q))
-        else
-          p, q = determine_next_nodes.call(left(p), right(p), left(q), right(q))
+          if p_only_child && q_only_child
+            p, q = determine_next_nodes.call(p_only_child, q_only_child)
+          elsif p_only_child
+            p, q = determine_next_nodes.call(p_only_child, left(q), right(q))
+          elsif q_only_child
+            p, q = determine_next_nodes.call(left(p), right(p), q_only_child)
+          else
+            p, q = determine_next_nodes.call(left(p), right(p), left(q), right(q))
+          end
         end
         break unless p # we've run out of useful nodes
       end
@@ -374,6 +401,8 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     # Sometimes we don't have a relevant node to the left or right of Q. The booleans L and R (which we call left and right) track
     # whether p and q are defined at the moment.
     best = Point.new(INFINITY, -INFINITY)
+    return best if empty?
+
     p = q = left = right = nil
 
     x_range = (x0..x1)
@@ -402,15 +431,15 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     #   become a child of (the original) p.
     check_left = lambda do
       if leaf?(p)
-        left = false # Question: did p ever get checked as a potential winner?
-      elsif one_child?(p)
-        if x_range.cover? @data[left(p)].x
-          update_highest.call(left(p))
+        left = false
+      elsif (only_child = one_child?(p))
+        if x_range.cover? @data[only_child].x
+          update_highest.call(only_child)
           left = false # can't do y-better in the subtree
-        elsif @data[left(p)].x < x0
-          p = left(p)
+        elsif @data[only_child].x < x0
+          p = only_child
         else
-          q = left(p)
+          q = only_child
           right = true
           left = false
         end
@@ -457,16 +486,16 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     check_right = lambda do
       if leaf?(q)
         right = false
-      elsif one_child?(q)
-        if x_range.cover? @data[left(q)].x
-          update_highest.call(left(q))
+      elsif (only_child = one_child?(q))
+        if x_range.cover? @data[only_child].x
+          update_highest.call(only_child)
           right = false # can't do y-better in the subtree
-        elsif @data[left(q)].x < x0
-          p = left(q)
+        elsif @data[only_child].x < x0
+          p = only_child
           left = true
           right = false
         else
-          q = left(q)
+          q = only_child
         end
       else
         # q has two children
@@ -499,6 +528,8 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
       end
     end
 
+    return best if empty?
+
     root_val = @data[root]
 
     # If the root value is in the region Q, the max-heap property on y means we can't do better
@@ -595,6 +626,11 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     p = p_in = q_in = q = nil
 
     result = Set.new
+    if empty?
+      return if block_given?
+
+      return result
+    end
 
     report = lambda do |node|
       if block_given?
@@ -620,14 +656,14 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
           if @data[current].y >= y0
             report.call(current)
           end
-          if !leaf?(current) && @data[left(current)].y >= y0
+          if !leaf?(current) && in_tree?(left(current)) && @data[left(current)].y >= y0
             current = left(current)
           else
             state = 1
           end
         when 1
           # State 1: we've already handled this node and its left subtree. Should we descend to the right subtree?
-          if two_children?(current) && @data[right(current)].y >= y0
+          if in_tree?(right(current)) && @data[right(current)].y >= y0
             current = right(current)
             state = 0
           else
@@ -698,14 +734,15 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
         return
       end
 
-      if one_child?(p)
-        if x_range.cover? @data[left(p)].x
-          add_leftmost_inner_node.call(left(p))
+      if (only_child = one_child?(p))
+        child_val = @data[only_child]
+        if x_range.cover? child_val.x
+          add_leftmost_inner_node.call(only_child)
           left = false
-        elsif @data[left(p)].x < x0
-          p = left(p)
+        elsif child_val.x < x0
+          p = only_child
         else
-          q = left(p)
+          q = only_child
           right = true
           left = false
         end
@@ -754,25 +791,26 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
         return
       end
 
-      left_val = @data[left(p_in)]
-      if one_child?(p_in)
-        if x_range.cover? left_val.x
-          p_in = left(p_in)
-        elsif left_val.x < x0
+      if (only_child = one_child?(p_in))
+        child_val = @data[only_child]
+        if x_range.cover? child_val.x
+          p_in = only_child
+        elsif child_val.x < x0
           # We aren't in the [x0, x1] zone any more and have moved out to the left
-          p = left(p_in)
+          p = only_child
           deactivate_p_in.call
           left = true
         else
           # similar, but we've moved out to the right. Note that left(p_in) is the leftmost node to the right of Q.
           raise 'q_in should not be active (by the val of left(p_in))' if right_in
 
-          q = left(p_in)
+          q = only_child
           deactivate_p_in.call
           right = true
         end
       else
         # p' has two children
+        left_val = @data[left(p_in)]
         right_val = @data[right(p_in)]
         if left_val.x < x0
           if right_val.x < x0
@@ -828,16 +866,17 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
         return
       end
 
-      if one_child?(q)
-        if x_range.cover? @data[left(q)].x
-          add_rightmost_inner_node.call(left(q))
+      if (only_child = one_child?(q))
+        child_val = @data[only_child]
+        if x_range.cover? child_val.x
+          add_rightmost_inner_node.call(only_child)
           right = false
-        elsif @data[left(q)].x < x0
-          p = left(q)
+        elsif child_val.x < x0
+          p = only_child
           left = true
           right = false
         else
-          q = left(q)
+          q = only_child
         end
         return
       end
@@ -887,18 +926,18 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
         return
       end
 
-      left_val = @data[left(q_in)]
-      if one_child?(q_in)
-        if x_range.cover? left_val.x
-          q_in = left(q_in)
-        elsif left_val.x < x0
+      if (only_child = one_child?(q_in))
+        child_val = @data[only_child]
+        if x_range.cover? child_val.x
+          q_in = only_child
+        elsif child_val.x < x0
           # We have moved out to the left
-          p = left(q_in)
+          p = only_child
           right_in = false
           left = true
         else
           # We have moved out to the right
-          q = left(q_in)
+          q = only_child
           right_in = false
           right = true
         end
@@ -906,6 +945,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
       end
 
       # q' has two children
+      left_val = @data[left(q_in)]
       right_val = @data[right(q_in)]
       if left_val.x < x0
         raise InternalLogicError, 'p_in cannot be active, by the value in the left child of q_in' if left_in
@@ -967,7 +1007,6 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     end
 
     while left || left_in || right_in || right
-      # byebug if $do_it
       raise InternalLogicError, 'It should not be that q_in is active but p_in is not' if right_in && !left_in
 
       set_i = []
@@ -992,6 +1031,110 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     return result unless block_given?
   end
 
+  ########################################
+  # Delete Top
+  #
+
+  # Delete the top (max-y) element of the PST. This is possible only for dynamic PSTs
+  #
+  # It runs in guaranteed O(log n) time, where n is the size of the PST when it was intially constructed. As elements are deleted
+  # the internal tree structure is no longer guaranteed to be balanced and so we cannot guarantee operation in O(log n') time, where
+  # n' is the current size. In practice, "random" deletion is likely to leave the tree almost balanced.
+  #
+  # @return [Point] the top element that was deleted
+  def delete_top!
+    raise LogicError, 'delete_top! not supported for PSTs that are not dynamic' unless dynamic?
+    raise DataError, 'delete_top! not possible for empty PSTs' unless @member_count.positive?
+
+    i = root
+    while !leaf?(i)
+      if (child = one_child?(i))
+        next_node = child
+      else
+        next_node = left(i)
+
+        if better_y?(right(i), next_node)
+          next_node = right(i)
+        end
+      end
+      swap(i, next_node)
+      i = next_node
+    end
+    @member_count -= 1
+    @data[i]
+  end
+
+  ########################################
+  # Helpers for the internal guts of things
+
+  private def dynamic?
+    @dynamic
+  end
+
+  # i has no children
+  private def leaf?(i)
+    return i > @last_non_leaf unless dynamic?
+
+    !(in_tree?(left(i)) || in_tree?(right(i)))
+  end
+
+  # i has exactly one child. We return the unique child if there is one, and nil otherwise
+
+  # Unless the PST is dynamic this will be the left child. Otherwise it could be either
+  private def one_child?(i)
+    if dynamic?
+      l_child = left(i)
+      r_child = right(i)
+      left_is_in_tree = in_tree?(l_child)
+      return nil unless left_is_in_tree ^ in_tree?(r_child)
+      return l_child if left_is_in_tree
+
+      r_child
+    else
+      return left(i) if i == @parent_of_one_child
+
+      nil
+    end
+  end
+
+  # i has two children
+  private def two_children?(i)
+    i <= @last_parent_of_two_children unless dynamic?
+
+    in_tree?(left(i)) && in_tree?(right(i))
+  end
+
+  # Does the value at index i have a "better" y value than the value at index j.
+  #
+  # A value is better if it is larger, or if it is equal and the x value is smaller (which is how we break the tie)
+  private def better_y?(i, j)
+    val_i = @data[i]
+    val_j = @data[j]
+    return true if val_i.y > val_j.y
+    return false if val_i.y < val_j.y
+
+    val_i.x < val_j.x
+  end
+
+  # Is node i in the tree?
+  private def in_tree?(i)
+    return i <= @size unless dynamic?
+
+    return false if empty?
+    return false if i > @size
+    return true if i == root
+
+    better_y?(parent(i), i)
+
+    # p = parent(i)
+    # return true if @data[i].y < @data[p].y
+    # return false if @data[i].y > @data[p].y
+
+    # # the y values are equal so the tie is broken by x. We are "normal", and in the tree, if our value of x is worse than our
+    # # parent's value
+    # @data[i].x > @data[p].x
+  end
+
   ########################################
   # Build the initial stucture
 
@@ -1058,7 +1201,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
   end
 
   # The index in @data[l..r] having the largest value for y, breaking ties with the smaller x value. Since we are already sorted by
-  # x we don't actually need to check this.
+  # x we don't actually need to check the x value.
   private def index_with_largest_y_in(l, r)
     return nil if r < l
 
@@ -1084,7 +1227,6 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
   private def verify_properties
     # It's a max-heap in y
     (2..@size).each do |node|
-      byebug unless @data[node].y <= @data[parent(node)].y
       raise InternalLogicError, "Heap property violated at child #{node}" unless @data[node].y <= @data[parent(node)].y
     end