data_structures_rmolinari 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c7f82ec16e728941823e07e7ca20259b04e764c11db71708a1a614b3181fa2c
-  data.tar.gz: e0084c9fe2a93457a2a04279939cf12ec5fb050c65ce04af4449f3e618bfd22c
+  metadata.gz: ea5f3d2fed60234fefe18577985f1e8ae967ecec92ef0812ccaeff0fb81ca392
+  data.tar.gz: e3e59746e8d7e881209a2c3a0e78ea186aa0562d138d7e2b6ed261943f6cb45f
 SHA512:
-  metadata.gz: 8a8dfa180b3992318bbf23b844bb91d3d35c7883fcb9e4ae332ab23d83ad5cb1cf6ddbcd582ae4f0367b6bee0619fa00489dd0c964bd40c94374ec59761f3ecc
-  data.tar.gz: d3d9d6a1f2554f535919ba9328670d97e98b82702d66ab430454c3c503d81e83d71e82325f253a4828399f61cb3cf88c40c391e85ee6116b3ae3a20aeffb09ca
+  metadata.gz: e480ccee258f97479f1768b8f94b65a1c13f3b1e8f15e843c4240adeac555574383ef7de3928a057fd0b6707823cb4eeddee2128a49175c2f671e1526f887c2e
+  data.tar.gz: 30ac4bf22fe37bdfbf4eeccdcdfc2feba23278703957eebf5f9be6c30bb3e68024ccd49ef63c892d78c1fd58b54336a762c86cb107f9f27937222e9baf252ef4

data/lib/data_structures_rmolinari/generic_segment_tree_internal.rb

@@ -0,0 +1,119 @@
+require_relative 'shared'
+
+# A Segment Tree, which can be used for various interval-related purposes, like efficiently finding the sum (or min or max) on a
+# arbitrary subarray of a given array.
+#
+# There is an excellent description of the data structure at https://cp-algorithms.com/data_structures/segment_tree.html. The
+# Wikipedia article (https://en.wikipedia.org/wiki/Segment_tree) appears to describe a different data structure which is sometimes
+# called an "interval tree."
+#
+# For more details (and some close-to-metal analysis of run time, especially for large datasets) see
+# https://en.algorithmica.org/hpc/data-structures/segment-trees/. In particular, this shows how to do a bottom-up
+# implementation, which is faster, at least for large datasets and cache-relevant compiled code.
+#
+# This is a generic implementation.
+#
+# We do O(n) work to build the internal data structure at initialization. Then we answer queries in O(log n) time.
+#
+# @todo
+#   - provide a data-update operation like update_val_at(idx, val)
+#     - this is O(log n)
+#     - note that this may need some rework. Consider something like IndexOfMaxVal: @merge needs to know about the underlying data
+#       in that case. Hmmm. Maybe the lambda can close over the data in a way that makes it possible to change the data "from the
+#       outside". Yes:
+#         a = [1,2,3]
+#         foo = ->() { a.max }
+#         foo.call # 3
+#         a = [1,2,4]
+#         foo.call # 4
+#   - Offer an optional parameter base_case_value_extractor (<-- need better name) to be used in #determine_val in the case that
+#     left == tree_l && right == tree_r instead of simply returning @tree[tree_idx]
+#     - Use case: https://cp-algorithms.com/data_structures/segment_tree.html#saving-the-entire-subarrays-in-each-vertex, such as
+#       finding the least element in a subarray l..r no smaller than a given value x. In this case we store a sorted version the
+#       entire subarray at each node and use a binary search on it.
+#     - the default value would simply be the identity function.
+#     - NOTE that in this case, we have different "combine" functions in #determine_val and #build. In #build we would combine
+#       sorted lists into a larger sorted list. In #determine_val we combine results via #min.
+#     - Think about the interface before doing this.
+class GenericSegmentTreeInternal
+  include Shared::BinaryTreeArithmetic
+
+  # Construct a concrete instance of a Segment Tree. See details at the links above for the underlying concepts here.
+  # @param combine a lambda that takes two values and munges them into a combined value.
+  #   - For example, if we are calculating sums over subintervals, combine.call(a, b) = a + b, while if we are doing maxima we will
+  #     return max(a, b)
+  # @param single_cell_array_val a lambda that takes an index i and returns the value we need to store in the #build
+  #     operation for the subinterval i..i. This is often simply be the value data[i], but in some cases - like "index of max val" -
+  #     it will be something else.
+  # @param size the size of the underlying data array, used in certain internal arithmetic.
+  # @param identity is the value to return when we are querying on an empty interval
+  #   - for sums, this will be zero; for maxima, this will be -Infinity, etc
+  def initialize(combine:, single_cell_array_val:, size:, identity:)
+    @combine = combine
+    @single_cell_array_val = single_cell_array_val
+    @size = size
+    @identity = identity
+
+    @tree = []
+    build(root, 0, @size - 1)
+  end
+
+  # The desired value (max, sum, etc.) on the subinterval left..right.
+  # @param left the left end of the subinterval.
+  # @param right the right end (inclusive) of the subinterval.
+  #
+  # The type of the return value depends on the concrete instance of the segment tree.
+  def query_on(left, right)
+    raise "Bad query interval #{left}..#{right}" if left.negative? || right >= @size
+
+    return @identity if left > right # empty interval
+
+    determine_val(root, left, right, 0, @size - 1)
+  end
+
+  private def determine_val(tree_idx, left, right, tree_l, tree_r)
+    # Does the current tree node exactly serve up the interval we're interested in?
+    return @tree[tree_idx] if left == tree_l && right == tree_r
+
+    # We need to go further down the tree
+    mid = midpoint(tree_l, tree_r)
+    if mid >= right
+      # Our interval is contained by the left child's interval
+      determine_val(left(tree_idx),  left, right, tree_l,  mid)
+    elsif mid + 1 <= left
+      # Our interval is contained by the right child's interval
+      determine_val(right(tree_idx), left, right, mid + 1, tree_r)
+    else
+      # Our interval is split between the two, so we need to combine the results from the children.
+      @combine.call(
+        determine_val(left(tree_idx),  left,    mid,   tree_l,  mid),
+        determine_val(right(tree_idx), mid + 1, right, mid + 1, tree_r)
+      )
+    end
+  end
+
+  # Build the internal data structure.
+  #
+  # - tree_idx is the index into @tree
+  # - tree_l..tree_r is the subinterval of the underlying data that node tree_idx corresponds to
+  private def build(tree_idx, tree_l, tree_r)
+    if tree_l == tree_r
+      @tree[tree_idx] = @single_cell_array_val.call(tree_l) # single-cell interval
+    else
+      # divide and conquer
+      mid = midpoint(tree_l, tree_r)
+      left = left(tree_idx)
+      right = right(tree_idx)
+
+      build(left, tree_l, mid)
+      build(right, mid + 1, tree_r)
+
+      @tree[tree_idx] = @combine.call(@tree[left], @tree[right])
+    end
+  end
+
+  # Do it in one place so we don't accidently round up here and down there, which would lead to chaos
+  private def midpoint(left, right)
+    (left + right) / 2
+  end
+end

data/lib/data_structures_rmolinari/heap_internal.rb

@@ -0,0 +1,179 @@
+require_relative 'shared'
+
+# A heap is a balanced binary tree in which each entry has an associated priority. For each node p of the tree that isn't the root,
+# the priority of the element at p is not less than the priority of the element at the parent of p.
+#
+# Thus the priority at each node p - root or not - is no greater than the priorities of the elements in the subtree rooted at p. It
+# is a "min-heap".
+#
+# We can make it a max-heap, in which each node's priority is no greater than the priority of its parent, via a parameter to the
+# initializer.
+#
+# We provide the following operations
+# - +empty?+
+#   - is the heap empty?
+#   - O(1)
+# - +insert+
+#   - add a new element to the heap with an associated priority
+#   - O(log N)
+# - +top+
+#   - return the lowest-priority element, which is the element at the root of the tree. In a max-heap this is the highest-priority
+#     element.
+#   - O(1)
+# - +pop+
+#   - removes and returns the item that would be returned by +top+
+#   - O(log N)
+# - +update+
+#   - tell the heap that the priority of a particular item has changed
+#   - O(log N)
+#
+# Here N is the number of elements in the heap.
+#
+# References:
+#
+# - https://en.wikipedia.org/wiki/Binary_heap
+# - Edelkamp, S., Elmasry, A., Katajainen, J., _Optimizing Binary Heaps_, Theory Comput Syst (2017), vol 61, pp 606-636,
+#   DOI 10.1007/s00224-017-9760-2
+#
+# @todo
+#   - relax the requirement that priorities must be comparable vai +<+ and respond to negation. Instead, allow comparison via +<=>+
+#     and handle max-heaps differently.
+#     - this will allow priorities to be arrays for tie-breakers and similar.
+class HeapInternal
+  include Shared::BinaryTreeArithmetic
+
+  attr_reader :size
+
+  Pair = Struct.new(:priority, :item)
+
+  # @param max_heap when truthy, make a max-heap rather than a min-heap
+  # @param debug when truthy, verify the heap property after each update than might violate it. This makes operations much slower.
+  def initialize(max_heap: false, debug: false)
+    @data = []
+    @size = 0
+    @max_heap = max_heap
+    @index_of = {}
+    @debug = debug
+  end
+
+  # Is the heap empty?
+  def empty?
+    @size.zero?
+  end
+
+  # Insert a new element into the heap with the given property.
+  # @param value the item to be inserted. It is an error to insert an item that is already present in the heap, though we don't
+  #   check for this.
+  # @param priority the priority to use for new item. The values used as priorities ust be totally ordered via +<+ and, if +self+ is
+  #   a max-heap, must respond to negation +@-+ in the natural order-respecting way.
+  # @todo
+  #   - check for duplicate
+  def insert(value, priority)
+    priority *= -1 if @max_heap
+
+    @size += 1
+
+    d = Pair.new(priority, value)
+    assign(d, @size)
+
+    sift_up(@size)
+  end
+
+  # Return the top of the heap without removing it
+  # @return the value with minimal (maximal for max-heaps) priority. Strictly speaking, it returns the item at the root of the
+  #   binary tree; this element has minimal priority, but there may be other elements with the same priority.
+  def top
+    raise 'Heap is empty!' unless @size.positive?
+
+    @data[root].item
+  end
+
+  # Return the top of the heap and remove it, updating the structure to maintain the necessary properties.
+  # @return (see #top)
+  def pop
+    result = top
+    @index_of.delete(result)
+
+    assign(@data[@size], root)
+
+    @data[@size] = nil
+    @size -= 1
+
+    sift_down(root) if @size.positive?
+
+    result
+  end
+
+  # Update the priority of the given element and maintain the necessary heap properties.
+  # @param element the item whose priority we are updating. It is an error to update the priority of an element not already in the
+  #   heap
+  # @param priority the new priority
+  #
+  # @todo
+  #   - check that the element is in the heap
+  def update(element, priority)
+    priority *= -1 if @max_heap
+
+    idx = @index_of[element]
+    old = @data[idx].priority
+    @data[idx].priority = priority
+    if priority > old
+      sift_down(idx)
+    elsif priority < old
+      sift_up(idx)
+    end
+
+    check_heap_property if @debug
+  end
+
+  # Filter the value at index up to its correct location. Algorithm from Edelkamp et. al.
+  private def sift_up(idx)
+    return if idx == root
+
+    x = @data[idx]
+    while idx != root
+      i = parent(idx)
+      break unless x.priority < @data[i].priority
+
+      assign(@data[i], idx)
+      idx = i
+    end
+    assign(x, idx)
+
+    check_heap_property if @debug
+  end
+
+  # Filter the value at index down to its correct location. Algorithm from Edelkamp et. al.
+  private def sift_down(idx)
+    x = @data[idx]
+
+    while (j = left(idx)) <= @size
+      j += 1 if j + 1 <= @size && @data[j + 1].priority < @data[j].priority
+
+      break unless @data[j].priority < x.priority
+
+      assign(@data[j], idx)
+      idx = j
+    end
+    assign(x, idx)
+
+    check_heap_property if @debug
+  end
+
+  # Put the pair in the given heap location
+  private def assign(pair, idx)
+    @data[idx] = pair
+    @index_of[pair.item] = idx
+  end
+
+  # For debugging
+  private def check_heap_property
+    (root..@size).each do |idx|
+      left = left(idx)
+      right = right(idx)
+
+      raise "Heap property violated by left child of index #{idx}" if left <= @size && @data[idx].priority >= @data[left].priority
+      raise "Heap property violated by right child of index #{idx}" if right <= @size && @data[idx].priority >= @data[right].priority
+    end
+  end
+end

data/lib/data_structures_rmolinari/max_priority_search_tree_internal.rb

@@ -1,8 +1,6 @@
 require 'set'
-
 require_relative 'shared'
 
-class LogicError < StandardError; end
 
 # A priority search tree (PST) stores a set, P, of two-dimensional points (x,y) in a way that allows efficient answes to certain
 # questions about P.
@@ -44,6 +42,7 @@ class LogicError < StandardError; end
 #   Geometry, 2011
 class MaxPrioritySearchTreeInternal
   include Shared
+  include BinaryTreeArithmetic
 
   # Construct a MaxPST from the collection of points in +data+.
   #
@@ -1047,52 +1046,52 @@ class MaxPrioritySearchTreeInternal
   ########################################
   # Tree arithmetic
 
-  # First element and root of the tree structure
-  private def root
-    1
-  end
-
-  # Indexing is from 1
-  private def parent(i)
-    i >> 1
-  end
-
-  private def left(i)
-    i << 1
-  end
-
-  private def right(i)
-    1 + (i << 1)
-  end
-
-  private def level(i)
-    l = 0
-    while i > root
-      i >>= 1
-      l += 1
-    end
-    l
-  end
-
-  # i has no children
-  private def leaf?(i)
-    i > @last_non_leaf
-  end
-
-  # i has exactly one child (the left)
-  private def one_child?(i)
-    i == @parent_of_one_child
-  end
-
-  # i has two children
-  private def two_children?(i)
-    i <= @last_parent_of_two_children
-  end
-
-  # i is the left child of its parent.
-  private def left_child?(i)
-    (i & 1).zero?
-  end
+  # # First element and root of the tree structure
+  # private def root
+  #   1
+  # end
+
+  # # Indexing is from 1
+  # private def parent(i)
+  #   i >> 1
+  # end
+
+  # private def left(i)
+  #   i << 1
+  # end
+
+  # private def right(i)
+  #   1 + (i << 1)
+  # end
+
+  # private def level(i)
+  #   l = 0
+  #   while i > root
+  #     i >>= 1
+  #     l += 1
+  #   end
+  #   l
+  # end
+
+  # # i has no children
+  # private def leaf?(i)
+  #   i > @last_non_leaf
+  # end
+
+  # # i has exactly one child (the left)
+  # private def one_child?(i)
+  #   i == @parent_of_one_child
+  # end
+
+  # # i has two children
+  # private def two_children?(i)
+  #   i <= @last_parent_of_two_children
+  # end
+
+  # # i is the left child of its parent.
+  # private def left_child?(i)
+  #   (i & 1).zero?
+  # end
 
   private def swap(index1, index2)
     return if index1 == index2

data/lib/data_structures_rmolinari/minmax_priority_search_tree_internal.rb

@@ -1,3 +1,7 @@
+require 'must_be'
+
+require_relative 'shared'
+
 # A priority search tree (PST) stores points in two dimensions (x,y) and can efficiently answer certain questions about the set of
 # point.
 #
@@ -26,28 +30,18 @@
 # I started implementing the in-place PST. Then, finding the follow-up paper [3], decided to do that one instead, as the paper says
 # it is more flexible. The point is to learn a new data structure and its associated algorithms.
 #
-# Hmmm. The algorithms are rather bewildering. Highest3SidedUp is complicated, and only two of the functions CheckLeft, CheckLeftIn,
+# The algorithms are rather bewildering. Highest3SidedUp is complicated, and only two of the functions CheckLeft, CheckLeftIn,
 # CheckRight, CheckRightIn are given; the other two are "symmetric". But it's not really clear what the first are actually doing, so
 # it's hard to know what the others actually do.
 #
-# I either need to go back to MaxPST until I understand things better, or spend quite a lot of time going through the algorithms
-# here on paper.
-
+# The implementation is incomplete. The pseduo-code in the paper is buggy (see the code below), which makes progress difficult.
+#
 # [1] E. McCreight, _Priority Search Trees_, SIAM J. Computing, v14, no 3, May 1985, pp 257-276.
 # [2] De, Maheshwari, Nandy, Smid, _An in-place priority search tree_, 23rd Annual Canadian Conference on Computational Geometry.
 # [3] De, Maheshwari, Nandy, Smid, _An in-place min-max priority search tree_, Computational Geometry, v46 (2013), pp 310-327.
 # [4] Atkinson, Sack, Santoro, Strothotte, _Min-max heaps and generalized priority queues_, Commun. ACM 29 (10) (1986), pp 996-1000.
-
-require 'must_be'
-
-Pair = Struct.new(:x, :y) do
-  def fmt
-    "(#{x},#{y})"
-  end
-end
-
 class MinmaxPrioritySearchTreeInternal
-  INFINITY = Float::INFINITY
+  include Shared
 
   # The array of pairs is turned into a minmax PST in-place without cloning. So clone before passing it in, if you care.
   #

data/lib/data_structures_rmolinari/shared.rb

@@ -3,4 +3,62 @@ module Shared
   INFINITY = Float::INFINITY
 
   Pair = Struct.new(:x, :y)
+
+  # @private
+  class LogicError < StandardError; end
+
+  # @private
+  #
+  # Provide simple arithmetic for an implied binary tree stored in an array, with the root at 1
+  module BinaryTreeArithmetic
+    # First element and root of the tree structure
+    private def root
+      1
+    end
+
+    # The parent of node i
+    private def parent(i)
+      i >> 1
+    end
+
+    # The left child of node i
+    private def left(i)
+      i << 1
+    end
+
+    # The right child of node i
+    private def right(i)
+      1 + (i << 1)
+    end
+
+    # The level in the tree of node i. The root is at level 0.
+    private def level(i)
+      l = 0
+      while i > root
+        i >>= 1
+        l += 1
+      end
+      l
+    end
+
+    # i has no children
+    private def leaf?(i)
+      i > @last_non_leaf
+    end
+
+    # i has exactly one child (the left)
+    private def one_child?(i)
+      i == @parent_of_one_child
+    end
+
+    # i has two children
+    private def two_children?(i)
+      i <= @last_parent_of_two_children
+    end
+
+    # i is the left child of its parent.
+    private def left_child?(i)
+      (i & 1).zero?
+    end
+  end
 end

data/lib/data_structures_rmolinari.rb

@@ -1,7 +1,46 @@
+require_relative 'data_structures_rmolinari/shared'
+require_relative 'data_structures_rmolinari/generic_segment_tree_internal'
+require_relative 'data_structures_rmolinari/heap_internal'
 require_relative 'data_structures_rmolinari/max_priority_search_tree_internal'
 require_relative 'data_structures_rmolinari/minmax_priority_search_tree_internal'
 
 module DataStructuresRMolinari
+  Pair = Shared::Pair
+
+  ########################################
+  # Priority Search Trees
+  #
+  # Note that MinmaxPrioritySearchTree is only a fragment of what we need
   MaxPrioritySearchTree = MaxPrioritySearchTreeInternal
   MinmaxPrioritySearchTree = MinmaxPrioritySearchTreeInternal
+
+  ########################################
+  # Segment Trees
+
+  GenericSegmentTree = GenericSegmentTreeInternal
+
+  # Takes an array A[0...n] and tells us what the maximum value is on a subinterval i..j in O(log n) time.
+  #
+  # TODO:
+  # - allow min val too
+  #   - add a flag to the initializer
+  #   - call it ExtremalValSegment tree or something similar
+  class MaxValSegmentTree
+    extend Forwardable
+
+    def_delegator :@structure, :query_on, :max_on
+
+    def initialize(data)
+      @structure = GenericSegmentTree.new(
+        combine:               ->(a, b) { [a, b].max },
+        single_cell_array_val: ->(i) { data[i] },
+        size:                  data.size,
+        identity:              -Float::INFINITY
+      )
+    end
+  end
+
+  ########################################
+  # Heap
+  Heap = HeapInternal
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_structures_rmolinari
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Rory Molinari
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-04 00:00:00.000000000 Z
+date: 2023-01-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: must_be
@@ -78,6 +78,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/data_structures_rmolinari.rb
+- lib/data_structures_rmolinari/generic_segment_tree_internal.rb
+- lib/data_structures_rmolinari/heap_internal.rb
 - lib/data_structures_rmolinari/max_priority_search_tree_internal.rb
 - lib/data_structures_rmolinari/minmax_priority_search_tree_internal.rb
 - lib/data_structures_rmolinari/shared.rb
@@ -91,7 +93,7 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '='
+  - - "~>"
     - !ruby/object:Gem::Version
       version: 3.1.3
 required_rubygems_version: !ruby/object:Gem::Requirement