compsci 0.0.2.1 → 0.0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4ee20715906280e4a366f493195ae4decf079cf1
-  data.tar.gz: '0088708c15ca4dae9cdc58ef35d1f85dd60203cc'
+  metadata.gz: cc2eff6c2450cd9807ab097dd86eebb37420a7b7
+  data.tar.gz: 470311b19fc70c7ab1a5d405c3aba939f57464e7
 SHA512:
-  metadata.gz: 38071308dbc5a6e1988abf8671166c10b793f4baa9bb7371c1fe65c3d2570f1a38caaf61042fa247d58a0451b8711b1ec0eb0ea98e67bfe9fab8bbd8c0652318
-  data.tar.gz: 11a04a2484e15b29a049c1d6c48c373e2360c98b24f02d4bc874353aa29917acbf53acc1932b1d3629796afd5956c91048a14ff8c46b54904f457d1588e7aa45
+  metadata.gz: 37214ed2f4c2fd3f8837f1908fc78b07be79e624ba7f387f40c68aec49f93b1b866589fab0b863e02e6add2d6dcbfe4508c9ae1bdf1864269427dce25fdb15b4
+  data.tar.gz: 52dc0115e1f44a769da4dc3f1e721624e3963cef0111d098af6ad6beb72728b120905aaaeb45161950c79455810bbf8caab5426fb22aee716f5e7e92f84244a4

data/README.md

@@ -34,11 +34,55 @@ second, constant up past 1M pushes.
 
 ## [`Timer`](/lib/compsci/timer.rb) functions
 
-* `Timer.now`          - uses `Process::CLOCK_MONOTONIC` if available
-* `Timer.since`        - provides the elapsed time since a prior time
-* `Timer.elapsed`      - provides the elapsed time to run a block
-* `Timer.loop_average` - runs a block repeatedly and provides the mean elapsed
-                         time
+* `Timer.now`      - uses `Process::CLOCK_MONOTONIC` if available
+* `Timer.since`    - provides the elapsed time since a prior time
+* `Timer.elapsed`  - provides the elapsed time to run a block
+* `Timer.loop_avg` - loops a block; returns final value and mean elapsed time
+
+```ruby
+require 'compsci/timer'
+
+include CompSci
+
+overall_start = Timer.now
+
+start = Timer.now
+print "running sleep 0.01 (50x): "
+_answer, each_et = Timer.loop_avg(count: 50) {
+  print '.'
+  sleep 0.01
+}
+puts
+puts "each: %0.3f" % each_et
+puts "elapsed: %0.3f" % Timer.since(start)
+puts "cumulative: %0.3f" % Timer.since(overall_start)
+puts
+
+
+start = Timer.now
+print "running sleep 0.02 (0.3 s): "
+_answer, each_et = Timer.loop_avg(seconds: 0.3) {
+  print '.'
+  sleep 0.02
+}
+puts
+puts "each: %0.3f" % each_et
+puts "elapsed: %0.3f" % Timer.since(start)
+puts "cumulative: %0.3f" % Timer.since(overall_start)
+puts
+```
+
+```
+running sleep 0.01 (50x): ..................................................
+each: 0.010
+elapsed: 0.524
+cumulative: 0.524
+
+running sleep 0.02 (0.3 s): ...............
+each: 0.020
+elapsed: 0.304
+cumulative: 0.828
+```
 
 ## [`Fit`](lib/compsci/fit.rb) functions
 

data/Rakefile

@@ -31,7 +31,7 @@ metrics_tasks = []
 begin
   require 'flog_task'
   FlogTask.new do |t|
-    t.threshold = 450
+    t.threshold = 600
     t.dirs = ['lib']
     t.verbose = true
   end

data/VERSION

@@ -1 +1 @@
-0.0.2.1
+0.0.3.1

data/compsci.gemspec

@@ -23,7 +23,6 @@ Gem::Specification.new do |s|
     lib/compsci/tree.rb
     examples/binary_tree.rb
     examples/heap.rb
-    examples/timer.rb
     test/fibonacci.rb
     test/fit.rb
     test/heap.rb

data/examples/heap.rb

@@ -13,7 +13,7 @@ EOF
 count = 0
 start = Timer.now
 start_100k = Timer.now
-h = Heap.new
+h = BinaryHeap.new
 
 loop {
   count += 1

data/lib/compsci/heap.rb

@@ -1,27 +1,136 @@
 require 'compsci/tree'
 
-# A Heap is a partially sorted, complete binary tree with the property:
-# * Every node has a value larger (or smaller) than that of its children.
-#
-# This class implements a heap using a simple array for storage.
-# Array index math is used to find:
-# * The root node (idx 0)
-# * The "bottom-most" leaf node (last idx)
-# * Parent idx (idx-1 / 2)
-# * Child idx (2*idx + 1, 2*idx + 2)
+include CompSci
+
+# A Heap is a partially sorted, complete N-ary tree with the property:
+# * Every node has a value larger (or smaller) than that of its children
+#   (the heap property is satisfied when a parent value equals a child value)
 #
-# Any Comparable may be used for node values.
-# Initialize a heap with a cmp_val, either 1 for a MaxHeap or -1 for a MinHeap.
-# The heap property is satisfied when a parent value equals a child value.
-# Insertion (push) and removal (pop) are O(log n) where n is the heap size.
-# Nodes are inserted at the end of the array, and sift_up is called to
+# Implementation details:
+# * Any Comparable may be used for node values.
+# * Initialize a heap with a cmp_val, either 1 for a MaxHeap or -1 for a
+#   MinHeap.
+# * Insertion (push) and removal (pop) are O(logb n) where n is the heap size
+#   and b is child_slots (the N in N-ary)
+# * Nodes are inserted at the end of the array, and sift_up is called to
 #   reestablish the heap property.
-# Nodes are removed from the start of the array, and sift_down is called to
+# * Nodes are removed from the start of the array, and sift_down is called to
 #   reestablish the heap property.
-# Sift_up and sift_down are O(log n) because they only have to check and swap
-#   nodes at each layer of the tree, and there are log n layers to the tree.
+# * Sift_up and sift_down are O(logb n) because they only have to check and
+#   swap nodes at each layer of the tree, and there are log(n, base b) layers
+#   to the tree.
+#
+class Heap < CompleteNaryTree
+  # * defaults to a MaxHeap, with the largest node at the root
+  # * specify a minheap with minheap: true or cmp_val: -1
+  #
+  def initialize(cmp_val: 1, minheap: false, child_slots: 2)
+    super(child_slots: child_slots)
+    cmp_val = -1 if minheap
+    case cmp_val
+    when -1, 1
+      @cmp_val = cmp_val
+    else
+      raise(ArgumentError, "unknown comparison value: #{cmp_val}")
+    end
+  end
+
+  # * append to the array
+  # * sift_up -- O(log n) on heap size
+  #
+  def push(node)
+    @store << node
+    self.sift_up(@store.size - 1)
+  end
+
+  # * remove from the front of the array
+  # * move last node to root
+  # * sift_down -- O(log n) on heap size
+  #
+  def pop
+    node = @store.shift
+    replacement = @store.pop
+    @store.unshift replacement if replacement
+    self.sift_down(0)
+    node
+  end
+
+  # * return what pop would return (avoid sifting)
+  #
+  def peek
+    @store.first
+  end
+
+  # * called recursively
+  # * idx represents the node suspected to violate the heap
+  # * intended to be O(log n) on heap size (log base child_slots)
+  #
+  def sift_up(idx)
+    return self if idx <= 0
+    pidx = self.class.parent_idx(idx, @child_slots)
+    if !self.heapish?(pidx, idx)
+      @store[idx], @store[pidx] = @store[pidx], @store[idx]   # swap
+      self.sift_up(pidx)
+    end
+    self
+  end
+
+  # * called recursively
+  # * idx represents the node suspected to violate the heap
+  # * intended to be O(log n) on heap size (log base child_slots)
+  # * slower than sift_up because one parent vs multiple children
+  #
+  def sift_down(idx)
+    return self if idx >= @store.size
+    cidxs = self.class.children_idx(idx, @child_slots)
+    # promote the heapiest child
+    cidx = self.heapiest(cidxs)
+    if !self.heapish?(idx, cidx)
+      @store[idx], @store[cidx] = @store[cidx], @store[idx]   # swap
+      self.sift_down(cidx)
+    end
+    self
+  end
+
+  # are values of parent and child (by index) in accordance with heap property?
+  #
+  def heapish?(pidx, cidx)
+    (@store[pidx] <=> @store[cidx]) != (@cmp_val * -1)
+  end
+
+  # return the heapiest idx in cidxs
+  #
+  def heapiest(cidxs)
+    idx = cidxs.first
+    cidxs.each { |cidx|
+      idx = cidx if cidx < @store.size and self.heapish?(cidx, idx)
+    }
+    idx
+  end
+
+  # * not used internally
+  # * checks that every node satisfies the heap property
+  # * calls heapish? on idx's children and then heap? on them recursively
+  #
+  def heap?(idx: 0)
+    check_children = []
+    self.class.children_idx(idx, @child_slots).each { |cidx|
+      # cidx is arithmetically produced; the corresponding child may not exist
+      if cidx < @store.size
+        return false unless self.heapish?(idx, cidx)
+        check_children << cidx
+      end
+    }
+    check_children.each { |cidx| return false unless self.heap?(idx: cidx) }
+    true
+  end
+end
+
 #
-class CompSci::Heap < CompSci::CompleteBinaryTree
+# LEGACY BELOW untouched for now
+#
+
+class BinaryHeap < CompleteBinaryTree
   # defaults to a MaxHeap, with the largest node at the root
   # specify a minheap with minheap: true or cmp_val: -1
   #

data/lib/compsci/timer.rb

@@ -21,7 +21,7 @@ module CompSci::Timer
     return yield, self.since(t)
   end
 
-  def self.loop_average(count: 999, seconds: 1, &work)
+  def self.loop_avg(count: 999, seconds: 1, &work)
     i = 0
     start = self.now
     val = nil

data/lib/compsci/tree.rb

@@ -149,21 +149,30 @@ module CompSci
   # A CompleteBinaryTree can very efficiently use an array for storage using
   # simple arithmetic to determine parent child relationships.
   #
-  class CompleteBinaryTree
-    # integer math says idx 2 and idx 1 both have parent at idx 0
-    def self.parent_idx(idx)
-      (idx-1) / 2
+  # Likewise, we should be able to use an array for N children
+  #
+  class CompleteNaryTree
+    def self.parent_idx(idx, n)
+      (idx-1) / n
     end
 
-    def self.children_idx(idx)
-      [2*idx + 1, 2*idx + 2]
+    def self.children_idx(idx, n)
+      Array.new(n) { |i| n*idx + i + 1 }
     end
 
     attr_reader :store
 
-    def initialize(store: [])
+    def initialize(store: [], child_slots: 2)
       @store = store
-      # yield self if block_given?
+      @child_slots = child_slots
+    end
+
+    def push node
+      @store.push node
+    end
+
+    def pop
+      @store.pop
     end
 
     def size
@@ -174,4 +183,35 @@ module CompSci
       @store.size - 1 unless @store.empty?
     end
   end
+
+  # Heap still expects CompleteBinaryTree
+  #
+  class CompleteBinaryTree < CompleteNaryTree
+    # integer math says idx 2 and idx 1 both have parent at idx 0
+    def self.parent_idx(idx)
+      (idx-1) / 2
+    end
+
+    def self.children_idx(idx)
+      [2*idx + 1, 2*idx + 2]
+    end
+
+    attr_reader :store
+
+    def initialize(store: [])
+      super(store: store, child_slots: 2)
+    end
+
+    # TODO: generalize for N != 2
+    def to_s(node: nil, width: 80)
+      str = ''
+      @store.each_with_index { |n, i|
+        level = Math.log(i+1, 2).floor
+        block_width = width / (2**level)
+        str += "\n" if 2**level == i+1 and i > 0
+        str += n.to_s.ljust(block_width / 2, ' ').rjust(block_width, ' ')
+      }
+      str
+    end
+  end
 end

data/test/timer.rb

@@ -20,10 +20,10 @@ describe Timer do
     end
   end
 
-  describe "loop_average" do
+  describe "loop_avg" do
     it "return the block value and a positive number" do
       start = Timer.now
-      answer, avg_et = Timer.loop_average(seconds: 0.1) {
+      answer, avg_et = Timer.loop_avg(seconds: 0.1) {
         sleep 0.01
         :foo
       }
@@ -34,12 +34,21 @@ describe Timer do
 
     it "must repeat short loops and stop on time" do
       # see above, Timer.since(start)
-      true.must_equal true
+      true
+    end
+
+    it "must cease looping after 5 loops" do
+      start = Timer.now
+      _answer, avg_et = Timer.loop_avg(count: 5) {
+        sleep 0.01
+      }
+      avg_et.must_be_close_to 0.015, 0.005
+      Timer.since(start).must_be_close_to 0.1, 0.05
     end
 
     it "must not interrupt long loops" do
       start = Timer.now
-      _answer, avg_et = Timer.loop_average(seconds: 0.01) {
+      _answer, avg_et = Timer.loop_avg(seconds: 0.01) {
         sleep 0.1
       }
       Timer.since(start).must_be_close_to avg_et, 0.05

data/test/tree.rb

@@ -293,3 +293,72 @@ describe CompleteBinaryTree do
     end
   end
 end
+
+describe CompleteNaryTree do
+  it "must calculate a parent index for N=3" do
+    valid = {
+      1 => 0,
+      2 => 0,
+      3 => 0,
+      4 => 1,
+      5 => 1,
+      6 => 1,
+      7 => 2,
+      8 => 2,
+      9 => 2,
+      10 => 3,
+    }
+
+    invalid = {
+      0 => -1,
+      -1 => -1,
+      -2 => -1,
+    }
+    valid.each { |idx, pidx|
+      CompleteNaryTree.parent_idx(idx, 3).must_equal pidx
+    }
+    invalid.each { |idx, pidx|
+      CompleteNaryTree.parent_idx(idx, 3).must_equal pidx
+    }
+  end
+
+  it "must calculate children indices for N=3" do
+    valid = {
+      0 => [1, 2, 3],
+      1 => [4, 5, 6],
+      2 => [7, 8, 9],
+      3 => [10, 11, 12],
+    }
+
+    invalid = {
+      -3 => [-8, -7, -6],
+      -2 => [-5, -4, -3],
+      -1 => [-2, -1,  0],
+    }
+
+    valid.each { |idx, cidx|
+      CompleteNaryTree.children_idx(idx, 3).must_equal cidx
+    }
+    invalid.each { |idx, cidx|
+      CompleteNaryTree.children_idx(idx, 3).must_equal cidx
+    }
+  end
+
+  describe "instance" do
+    before do
+      @array = (0..99).sort_by { rand }
+      @empty = CompleteNaryTree.new(child_slots: 5)
+      @nonempty = CompleteNaryTree.new(store: @array, child_slots: 3)
+    end
+
+    it "must have a size" do
+      @empty.size.must_equal 0
+      @nonempty.size.must_equal @array.size
+    end
+
+    it "must have a last_idx, nil when empty" do
+      @empty.last_idx.nil?.must_equal true
+      @nonempty.last_idx.must_equal 99
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: compsci
 version: !ruby/object:Gem::Version
-  version: 0.0.2.1
+  version: 0.0.3.1
 platform: ruby
 authors:
 - Rick Hull
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-26 00:00:00.000000000 Z
+date: 2017-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -36,7 +36,6 @@ files:
 - compsci.gemspec
 - examples/binary_tree.rb
 - examples/heap.rb
-- examples/timer.rb
 - lib/compsci.rb
 - lib/compsci/fibonacci.rb
 - lib/compsci/fit.rb

data/examples/timer.rb

@@ -1,30 +0,0 @@
-require 'compsci/timer'
-
-include CompSci
-
-overall_start = Timer.now
-
-start = Timer.now
-print "running sleep 0.01 (50x): "
-_answer, each_et = Timer.loop_average(count: 50) {
-  print '.'
-  sleep 0.01
-}
-puts
-puts "each: %0.3f" % each_et
-puts "elapsed: %0.3f" % Timer.since(start)
-puts "cumulative: %0.3f" % Timer.since(overall_start)
-puts
-
-
-start = Timer.now
-print "running sleep 0.02 (0.3 s): "
-_answer, each_et = Timer.loop_average(seconds: 0.3) {
-  print '.'
-  sleep 0.02
-}
-puts
-puts "each: %0.3f" % each_et
-puts "elapsed: %0.3f" % Timer.since(start)
-puts "cumulative: %0.3f" % Timer.since(overall_start)
-puts