carray-jit 0.1.2 → 0.1.3

data/examples/applications/collatz.rb

@@ -0,0 +1,105 @@
+# Collatz: how long each number takes to fall to 1.
+#
+# Halve it when it is even, take 3n+1 when it is odd, and count the steps
+# until it reaches 1.  How many steps that is depends on the number, and
+# nothing about the number says in advance -- 3 takes 7 steps and 27 takes
+# 111 -- so the length of the loop is the cell's own business and is what
+# `while` is for.
+#
+# Written over whole arrays this is a pass per step over everything still
+# running, and every cell pays for the longest one; there is no expression
+# that lets one cell stop.  Here each cell stops when it reaches 1, and the
+# two answers -- the step count and the highest value on the way -- are
+# written in the same pass.
+#
+#   ruby examples/applications/collatz.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+N = 1_000_000
+
+def collatz (n)
+  steps = CArray.int32(n)
+  peak  = CArray.int64(n)
+  kernel = CArray.jit_for(1...n) { |i|
+    x = i
+    hi = x
+    count = 0
+    while x != 1
+      x = x % 2 == 0 ? x / 2 : 3 * x + 1
+      hi = x if x > hi
+      count = count + 1
+    end
+    steps[i] = count
+    peak[i] = hi
+  }
+  [steps, peak, kernel]
+end
+
+steps, peak, kernel = collatz(N)
+
+# The numbers that took longer than anything before them.
+puts "record holders below #{N}"
+record = 0
+(1...N).each do |i|
+  next unless steps[i] > record
+  record = steps[i]
+  next unless record > 400
+  puts format("  %7d  %3d steps, reaching %d", i, record, peak[i])
+end
+puts format("  the highest value reached by any of them is %d, from %d",
+            peak.max, peak.max_addr)
+
+# `x` is an int64 in the generated C, and nothing here asked for that.  A
+# local's type is settled from the whole body: `hi` is what `peak` is given,
+# `peak` is an int64 array, and `hi = x` carries that back to `x`.  Which is
+# why 704511 reaches 56 billion without overflowing an int32 on the way.
+puts
+puts "what the local was compiled as"
+puts format("  %s", kernel.c_source.lines.grep(/^\s*int\d+_t x;/).first.strip)
+
+# The same walk in Ruby, for the answer and the time.  Over the first tenth,
+# because the point of the comparison is the ratio.
+CHECK = N / 10
+
+def collatz_in_ruby (n)
+  steps = Array.new(n, 0)
+  (1...n).each do |i|
+    x = i
+    count = 0
+    while x != 1
+      x = x.even? ? x / 2 : 3 * x + 1
+      count += 1
+    end
+    steps[i] = count
+  end
+  steps
+end
+
+in_ruby = collatz_in_ruby(CHECK)
+puts
+puts format("agrees with Ruby over 1...%d  %s",
+            CHECK, steps[0...CHECK].to_a == in_ruby)
+
+collatz(CHECK)                          # compiled and cached on the first call
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+5.times { collatz(CHECK) }
+compiled = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / 5
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+collatz_in_ruby(CHECK)
+interpreted = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+puts format("%d starting values: %.0f ms compiled, %.0f ms in Ruby (%.0fx)",
+            CHECK, compiled * 1e3, interpreted * 1e3, interpreted / compiled)
+
+# And the loop the kernel runs is the one the block states: `x.even?` is not
+# in the subset, so the parity test is written as the arithmetic it is.
+begin
+  CArray.jit_for(1) { |i| steps[i] = i.even? ? 0 : 1 }
+rescue CArray::JIT::Unsupported => error
+  puts
+  puts "refused: #{error.message.sub(/ \(at line.*/m, "")}"
+end

data/examples/applications/cubic_spline.rb

@@ -0,0 +1,331 @@
+# A cubic spline through measured points, natural and clamped
+#
+# Fitting a C2 curve through n points is a tridiagonal solve: the second
+# derivatives at the knots are the unknowns, and each interior knot gives one
+# row with three entries in it.  The rows are diagonally dominant, so the
+# Thomas algorithm applies -- two sequential sweeps, which is the part an
+# array library cannot do for you.
+#
+# The boundary conditions differ only in the first and last row.  Natural
+# asks for zero curvature at the ends, and needs nothing but the samples;
+# clamped asks for a given slope there, and needs to be told what it is.  What
+# that buys is visible below: where the true curve is still bending at the end,
+# the natural spline flattens it, and the error there is several times what it
+# is anywhere inside -- the clamped fit removes it.  Not-a-knot asks for the
+# first two pieces to be one cubic, and the last two as well, which costs no
+# information at all and recovers a good part of the difference.
+#
+# Evaluating the result is a second kernel, and a different shape of one --
+# every query point searches for its interval on its own, so the body is a
+# bisection with the bound in the extent.  That search is where the time goes,
+# and it is not always needed: query points that arrive sorted -- resampling
+# onto a grid gives that -- let the interval be carried forward instead of
+# looked up, which is a sweep of the kind the solver already is.  Both are
+# here, and they agree bit for bit.
+#
+#   ruby examples/applications/cubic_spline.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+# The curve being sampled, and its slope -- known here so that the clamped
+# ends have something to be given, and so the error can be measured.
+def curve (x)      Math.exp(-0.35 * x) * Math.sin(2.0 * x) end
+def slope (x)      Math.exp(-0.35 * x) * (2.0 * Math.cos(2.0 * x) - 0.35 * Math.sin(2.0 * x)) end
+
+# ------------------------------------------------------------ the two kernels
+
+# The moments M[i] = S''(x[i]).  Interior rows come from the continuity of the
+# first derivative; the two end rows are the boundary condition and are the
+# only thing the three of them disagree about.
+#
+# Not-a-knot is the one that does not fit in a row of its own: asking S''' to
+# be continuous at x[1] puts M[0], M[1] and M[2] in one equation, which is a
+# band too wide.  Stated the other way round it says M is linear across x[1],
+# so M[0] is an extrapolation of the two inside it -- drop the first and last
+# unknown, solve the n-2 rows between them, and put the two back afterwards.
+# That is what `first_row` and `last_row` are: the same two sweeps, over the
+# rows that are actually unknown.
+def moments (x, y, n, work, ends)
+  a, b, c, d, cc, dd, moment = work
+
+  CArray.jit_for(1...(n-1)) { |i|
+    left  = x[i] - x[i-1]
+    right = x[i+1] - x[i]
+    a[i] = left
+    b[i] = 2.0 * (left + right)
+    c[i] = right
+    d[i] = 6.0 * ((y[i+1] - y[i]) / right - (y[i] - y[i-1]) / left)
+  }
+
+  case ends
+  when nil                                      # natural: S'' = 0 at both ends
+    first_row, last_row = 0, n-1
+    b[0] = 1.0 ; c[0] = 0.0 ; d[0] = 0.0
+    a[n-1] = 0.0 ; b[n-1] = 1.0 ; d[n-1] = 0.0
+  when :not_a_knot                              # not-a-knot: S''' continuous at x[1], x[n-2]
+    raise ArgumentError, "not-a-knot needs at least 4 points, got #{n}" if n < 4
+    first_row, last_row = 1, n-2
+    h0 = x[1] - x[0] ; h1 = x[2] - x[1]         # d[1] and d[n-2] are the interior
+    b[1] = 3.0 * h0 + 2.0 * h1 + h0 * h0 / h1   # right-hand sides already
+    c[1] = (h1 * h1 - h0 * h0) / h1
+    hm = x[n-2] - x[n-3] ; hn = x[n-1] - x[n-2]
+    a[n-2] = (hm * hm - hn * hn) / hm
+    b[n-2] = 2.0 * hm + 3.0 * hn + hn * hn / hm
+  else                                          # clamped: S' given at both ends
+    first_row, last_row = 0, n-1
+    first, last = ends
+    h0 = x[1] - x[0]
+    b[0] = 2.0 * h0 ; c[0] = h0
+    d[0] = 6.0 * ((y[1] - y[0]) / h0 - first)
+    hn = x[n-1] - x[n-2]
+    a[n-1] = hn ; b[n-1] = 2.0 * hn
+    d[n-1] = 6.0 * (last - (y[n-1] - y[n-2]) / hn)
+  end
+
+  cc[first_row] = c[first_row] / b[first_row]   # Thomas, forward
+  dd[first_row] = d[first_row] / b[first_row]
+  CArray.jit_for((first_row+1)..last_row) { |i|
+    denominator = b[i] - a[i] * cc[i-1]
+    cc[i] = c[i] / denominator
+    dd[i] = (d[i] - a[i] * dd[i-1]) / denominator
+  }
+
+  moment[last_row] = dd[last_row]               # Thomas, back substitution
+  CArray.jit_for((last_row-1).step(first_row, -1)) { |i|
+    moment[i] = dd[i] - cc[i] * moment[i+1]
+  }
+
+  if ends == :not_a_knot                        # the rows that were left out
+    moment[0]   = moment[1] - (x[1] - x[0]) * (moment[2] - moment[1]) / (x[2] - x[1])
+    moment[n-1] = moment[n-2] + (x[n-1] - x[n-2]) * (moment[n-2] - moment[n-3]) / (x[n-2] - x[n-3])
+  end
+  moment
+end
+
+# Evaluate at arbitrary points.  The knots are not equally spaced, so each
+# query point has to find its interval; `passes` bounds the bisection, and a
+# kernel that cannot fail to stop is the better kind.
+def evaluate (x, y, moment, n, query, value, derivative)
+  points = query.dim[0]
+  passes = Math.log2(n).ceil + 1
+
+  CArray.jit_for(points) { |k|
+    lo = 0
+    hi = n - 2
+    (0...passes).each { |pass|
+      break if lo >= hi
+      middle = (lo + hi + 1) / 2
+      if x[middle] <= query[k]
+        lo = middle
+      else
+        hi = middle - 1
+      end
+    }
+    h = x[lo+1] - x[lo]
+    t = query[k] - x[lo]
+    linear = (y[lo+1] - y[lo]) / h - h * (2.0 * moment[lo] + moment[lo+1]) / 6.0
+    cubic = (moment[lo+1] - moment[lo]) / (6.0 * h)
+    value[k] = y[lo] + t * (linear + t * (0.5 * moment[lo] + t * cubic))
+    derivative[k] = linear + t * (moment[lo] + t * 3.0 * cubic)
+  }
+end
+
+# The same evaluation where the query points are sorted.  Then nothing has to
+# search: the interval only moves forward, so one sweep carries it from cell to
+# cell and passes each knot once -- O(m + n) against O(m log n).  How far it
+# advances at one cell is the data's business, which is what `while` is for;
+# there is no bound to put in an extent.
+#
+# The first cell has no k-1 to read, so it is seeded here and the sweep starts
+# at 1 -- `jit_for(points)` over a body reading interval[k-1] is refused, and
+# says so, exactly as the Thomas sweeps above are stated from 1.
+#
+# The intervals are found first and evaluated second, which is what keeps the
+# seed from needing a copy of the polynomial: it is one entry in `interval`,
+# and the second kernel does every point the same way.  Fusing the two into a
+# single kernel is worth about 30% more, at that price.
+def resample (x, y, moment, n, query, value, derivative, interval)
+  points = query.dim[0]
+
+  seed = 0
+  seed += 1 while seed < n - 2 && x[seed+1] <= query[0]
+  interval[0] = seed
+
+  CArray.jit_for(1...points) { |k|
+    lo = interval[k-1]
+    while lo < n - 2 && x[lo+1] <= query[k]
+      lo = lo + 1
+    end
+    interval[k] = lo
+  }
+
+  CArray.jit_for(points) { |k|
+    lo = interval[k]
+    h = x[lo+1] - x[lo]
+    t = query[k] - x[lo]
+    linear = (y[lo+1] - y[lo]) / h - h * (2.0 * moment[lo] + moment[lo+1]) / 6.0
+    cubic = (moment[lo+1] - moment[lo]) / (6.0 * h)
+    value[k] = y[lo] + t * (linear + t * (0.5 * moment[lo] + t * cubic))
+    derivative[k] = linear + t * (moment[lo] + t * 3.0 * cubic)
+  }
+end
+
+# ------------------------------------------------------------------ the fit
+
+n = 15
+random = Random.new(20260909)
+# Knots that are not equally spaced -- measurements rarely are, and nothing
+# above assumed they would be.
+x = CArray.double(n) { |i| 6.0 * i / (n - 1) }
+(1...(n-1)).each { |i| x[i] += random.rand(-0.12..0.12) }
+y = CArray.double(n) { |i| curve(x[i]) }
+
+work = Array.new(7) { CArray.double(n) }
+natural = moments(x, y, n, work, nil).copy
+clamped = moments(x, y, n, work, [slope(x[0]), slope(x[n-1])]).copy
+not_a_knot = moments(x, y, n, work, :not_a_knot).copy
+
+points = 601
+query = CArray.double(points) { |k| x[0] + (x[n-1] - x[0]) * k / (points - 1) }
+truth = CArray.double(points) { |k| curve(query[k]) }
+
+value = CArray.double(points)
+derivative = CArray.double(points)
+
+puts "cubic spline through #{n} unevenly spaced points, sampled at #{points}"
+
+results = {}
+{ "natural" => natural, "clamped" => clamped, "not-a-knot" => not_a_knot }.each do |name, moment|
+  evaluate(x, y, moment, n, query, value, derivative)
+  results[name] = [value.copy, derivative.copy]
+
+  error = (value - truth).abs
+  edge = x[1] - x[0]                     # the first and last interval
+  ends = (0...points).select { |k| query[k] < x[0] + edge || query[k] > x[n-1] - edge }
+  inside = (0...points).to_a - ends
+
+  puts format("  %-10s  max error %.2e overall, %.2e in the end intervals, %.2e inside",
+              name, error.max, ends.map { |k| error[k] }.max, inside.map { |k| error[k] }.max)
+end
+
+# What each boundary condition asked for, checked at the ends.
+puts format("  natural   S''(a) = %.1e, S''(b) = %.1e -- zero, by construction",
+            natural[0], natural[n-1])
+puts format("  clamped   S'(a)  = %+.6f vs %+.6f asked for", results["clamped"][1][0], slope(x[0]))
+puts format("            S'(b)  = %+.6f vs %+.6f", results["clamped"][1][points-1], slope(x[n-1]))
+jump = lambda { |m, i, j, k|                   # S''' across the knot that is not one
+  (m[j] - m[i]) / (x[j] - x[i]) - (m[k] - m[j]) / (x[k] - x[j])
+}
+puts format("  not-knot  S''' jumps by %.1e at x[1] and %.1e at x[n-2] -- neither is a knot",
+            jump.call(not_a_knot, 0, 1, 2), jump.call(not_a_knot, n-3, n-2, n-1))
+
+# The interpolation itself: all of them pass through every knot, so all three
+# are asked, not just the one whose name comes first.
+knots = CArray.double(n) { |i| x[i] }
+at_knots = CArray.double(n)
+at_knots_slope = CArray.double(n)
+{ "natural" => natural, "clamped" => clamped, "not-a-knot" => not_a_knot }.each do |name, moment|
+  evaluate(x, y, moment, n, knots, at_knots, at_knots_slope)
+  puts format("  %-10s max |S(x_i) - y_i| = %.2e", name, (at_knots - y).abs.max)
+end
+
+# The query grid above is sorted, so the sweep applies to it -- and gives back
+# the same doubles, not merely close ones: the interval a point lands in is the
+# same interval, and the polynomial evaluated in it is the same expression.
+swept = CArray.double(points)
+swept_slope = CArray.double(points)
+resample(x, y, clamped, n, query, swept, swept_slope, CArray.int32(points))
+puts "  the sorted sweep agrees bit for bit  #{swept.to_a == results["clamped"][0].to_a}"
+
+# The curve, and the samples it was built from.
+rows, columns = 15, 74
+low, high = -0.55, 0.85
+canvas = Array.new(rows) { " " * columns }
+plot = lambda { |xs, ys, mark|
+  xs.each_with_index do |xv, k|
+    column = ((xv - x[0]) / (x[n-1] - x[0]) * (columns - 1)).round
+    row = ((high - ys[k]) / (high - low) * (rows - 1)).round
+    canvas[row][column] = mark if row.between?(0, rows - 1) && column.between?(0, columns - 1)
+  end
+}
+plot.call(query.to_a, results["clamped"][0].to_a, ".")
+plot.call(x.to_a, y.to_a, "o")
+puts
+canvas.each { |row| puts "  |#{row}|" }
+puts "  o samples, . the clamped spline through them"
+
+# ------------------------------------------------------------------- the cost
+
+def time (repeats)
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  repeats.times { yield }
+  (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / repeats
+end
+
+# The same two kernels written as Ruby loops.  The fit is O(n) and the
+# evaluation O(m log n), so both grow slowly -- what the compiled version
+# removes is the per-element cost, which is where all of the difference is.
+def ruby_moments (x, y, n, work)
+  a, b, c, d, cc, dd, moment = work
+  (1...(n-1)).each do |i|
+    left  = x[i] - x[i-1]
+    right = x[i+1] - x[i]
+    a[i] = left
+    b[i] = 2.0 * (left + right)
+    c[i] = right
+    d[i] = 6.0 * ((y[i+1] - y[i]) / right - (y[i] - y[i-1]) / left)
+  end
+  b[0] = 1.0 ; c[0] = 0.0 ; d[0] = 0.0
+  a[n-1] = 0.0 ; b[n-1] = 1.0 ; d[n-1] = 0.0
+  cc[0] = c[0] / b[0]
+  dd[0] = d[0] / b[0]
+  (1...n).each do |i|
+    denominator = b[i] - a[i] * cc[i-1]
+    cc[i] = c[i] / denominator
+    dd[i] = (d[i] - a[i] * dd[i-1]) / denominator
+  end
+  moment[n-1] = dd[n-1]
+  (n-2).step(0, -1) do |i|
+    moment[i] = dd[i] - cc[i] * moment[i+1]
+  end
+  moment
+end
+
+def ruby_evaluate (x, y, moment, n, query, value, derivative)
+  query.dim[0].times do |k|
+    lo, hi = 0, n - 2
+    while lo < hi
+      middle = (lo + hi + 1) / 2
+      if x[middle] <= query[k] then lo = middle else hi = middle - 1 end
+    end
+    h = x[lo+1] - x[lo]
+    t = query[k] - x[lo]
+    linear = (y[lo+1] - y[lo]) / h - h * (2.0 * moment[lo] + moment[lo+1]) / 6.0
+    cubic = (moment[lo+1] - moment[lo]) / (6.0 * h)
+    value[k] = y[lo] + t * (linear + t * (0.5 * moment[lo] + t * cubic))
+    derivative[k] = linear + t * (moment[lo] + t * 3.0 * cubic)
+  end
+end
+
+puts
+[[200, 20_000], [2_000, 200_000]].each do |size, sampled|
+  knots = CArray.double(size) { |i| 6.0 * i / (size - 1) }
+  values = CArray.double(size) { |i| curve(knots[i]) }
+  scratch = Array.new(7) { CArray.double(size) }
+  at = CArray.double(sampled) { |k| 6.0 * k / (sampled - 1) }
+  out, slopes = CArray.double(sampled), CArray.double(sampled)
+
+  fit = time(20) { moments(knots, values, size, scratch, nil) }
+  fit_ruby = time(3) { ruby_moments(knots, values, size, scratch) }
+  moment = moments(knots, values, size, scratch, nil)
+  sample = time(5) { evaluate(knots, values, moment, size, at, out, slopes) }
+  sample_ruby = time(2) { ruby_evaluate(knots, values, moment, size, at, out, slopes) }
+  cells = CArray.int32(sampled)
+  swept = time(5) { resample(knots, values, moment, size, at, out, slopes, cells) }
+
+  puts format("  n = %5d   fit %7.1f us vs %8.1f us Ruby (%3.0fx)", size, fit * 1e6, fit_ruby * 1e6, fit_ruby / fit)
+  puts format("  m = %6d  eval %7.1f us vs %8.1f us Ruby (%3.0fx)", sampled, sample * 1e6, sample_ruby * 1e6, sample_ruby / sample)
+  puts format("             sorted %7.1f us -- the same points, with the search taken out (%.1fx)",
+              swept * 1e6, sample / swept)
+end

data/examples/applications/dithering.rb

@@ -0,0 +1,144 @@
+# Floyd-Steinberg dithering: one bit per pixel, and the error passed on.
+#
+# Each pixel is rounded to black or white, and what the rounding threw away is
+# handed to the neighbours that have not been visited yet -- seven sixteenths
+# to the right, and the rest to the row below.  So a cell writes the cells the
+# loop is about to read, and the order it visits them in is not an
+# optimisation but the definition: run the same rule right to left and a
+# different picture comes out.
+#
+# That is what separates this from `sobel_edges.rb`, where every cell only
+# reads its neighbours and the pass is a stencil.  Here there is no window, no
+# expression over whole arrays, and no order to be derived -- there is a walk,
+# and the walk is the algorithm.  The kernel is one cell whose body is that
+# walk, which is the shape to reach for when the order is the point.
+#
+#   ruby examples/applications/dithering.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+# A grey ramp, top to bottom, with a brighter disc sitting in it.
+def picture (rows, columns)
+  image = CArray.double(rows, columns)
+  CArray.jit_for(rows, columns) { |y, x|
+    dy = (y - rows / 2.0) / (rows / 2.0)
+    dx = (x - columns / 2.0) / (columns / 2.0) * 0.42
+    ramp = 0.08 + 0.84 * y / rows
+    image[y, x] = dx * dx + dy * dy < 0.16 ? ramp * 0.35 + 0.62 : ramp
+  }
+  image
+end
+
+# The work array carries a row below and a column on each side, so that the
+# four neighbours a pixel writes are always cells that exist.  A kernel's
+# bounds are checked against the subscripts it is written with rather than
+# against the branches that guard them, so the room is made in the array, not
+# in an `if`.
+def dither (image)
+  rows, columns = image.dim
+  out = CArray.int8(rows, columns)
+  work = CArray.double(rows + 1, columns + 2)
+  work[0..-2, 1..-2] = image
+  CArray.jit_for(1) { |z|
+    (0...rows).each { |y|
+      (0...columns).each { |x|
+        old = work[y, x + 1]
+        new = old > 0.5 ? 1.0 : 0.0
+        out[y, x] = new
+        error = old - new
+        work[y, x + 2] += error * 7.0 / 16.0
+        work[y + 1, x] += error * 3.0 / 16.0
+        work[y + 1, x + 1] += error * 5.0 / 16.0
+        work[y + 1, x + 2] += error * 1.0 / 16.0
+      }
+    }
+  }
+  out
+end
+
+ROWS, COLUMNS = 22, 72
+
+def show (bits, title)
+  puts title
+  bits.dim[0].times do |y|
+    puts "  " + (0...bits.dim[1]).map { |x| bits[y, x] == 1 ? "@" : " " }.join
+  end
+  puts
+end
+
+image = picture(ROWS, COLUMNS)
+
+# Rounding each pixel on its own is an expression over the whole array, and it
+# is what the error has to be passed on to avoid: a ramp becomes two flat
+# bands with a step where it crosses a half.
+show(image.gt(0.5).int8, "rounded, each pixel on its own")
+show(dither(image), "dithered, the error passed on")
+
+# The same walk in Ruby, at a size worth timing.
+def dither_in_ruby (image)
+  rows, columns = image.dim
+  out = Array.new(rows) { Array.new(columns, 0) }
+  work = Array.new(rows + 1) { Array.new(columns + 2, 0.0) }
+  rows.times { |y| columns.times { |x| work[y][x + 1] = image[y, x] } }
+  rows.times do |y|
+    columns.times do |x|
+      old = work[y][x + 1]
+      new = old > 0.5 ? 1.0 : 0.0
+      out[y][x] = new.to_i
+      error = old - new
+      work[y][x + 2] += error * 7.0 / 16.0
+      work[y + 1][x] += error * 3.0 / 16.0
+      work[y + 1][x + 1] += error * 5.0 / 16.0
+      work[y + 1][x + 2] += error * 1.0 / 16.0
+    end
+  end
+  out
+end
+
+large = picture(600, 600)
+here = dither(large)
+there = dither_in_ruby(large)
+puts format("600x600, agrees with Ruby  %s", here.to_a == there)
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+5.times { dither(large) }
+compiled = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / 5
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+dither_in_ruby(large)
+interpreted = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+puts format("  %.1f ms compiled, %.0f ms in Ruby (%.0fx)",
+            compiled * 1e3, interpreted * 1e3, interpreted / compiled)
+
+# Right to left, with the offsets mirrored: the same rule, the same picture
+# going in, and a different picture coming out.  Nothing here is wrong with
+# either -- the walk is part of what the algorithm says, which is why this is
+# not a pass an expression over arrays could have been rearranged into.
+def dither_backwards (image)
+  rows, columns = image.dim
+  out = CArray.int8(rows, columns)
+  work = CArray.double(rows + 1, columns + 2)
+  work[0..-2, 1..-2] = image
+  CArray.jit_for(1) { |z|
+    (0...rows).each { |y|
+      (columns - 1).step(0, -1) { |x|
+        old = work[y, x + 1]
+        new = old > 0.5 ? 1.0 : 0.0
+        out[y, x] = new
+        error = old - new
+        work[y, x] += error * 7.0 / 16.0
+        work[y + 1, x + 2] += error * 3.0 / 16.0
+        work[y + 1, x + 1] += error * 5.0 / 16.0
+        work[y + 1, x] += error * 1.0 / 16.0
+      }
+    }
+  }
+  out
+end
+
+differ = dither(large).ne(dither_backwards(large)).count(1)
+puts
+puts format("walked the other way, %d of %d pixels land differently (%.1f%%)",
+            differ, large.elements, 100.0 * differ / large.elements)

data/examples/applications/group_stats.rb

@@ -0,0 +1,115 @@
+# Aggregating by a label, when the aggregate is not a sum.
+#
+# Two million readings, each tagged with the station it came from, and the
+# question is what each station did.  Counting them and adding them up are
+# what `CArray#bincount` is for and it is very good at it -- a pass over the
+# labels and a pass over the weights, in C, and nothing here beats that.
+#
+# The rest is the problem.  A maximum per station, the reading where that
+# maximum happened, how many readings passed a threshold: none of those is a
+# sum, and an array expression has no way to say "add this cell to the slot
+# its label names, and only if it is larger than what is there".  So the
+# whole-array answer is a pass per label -- select the label's cells, reduce
+# them, repeat -- and the cost is the number of labels times the size of the
+# data, no matter how few cells each label owns.
+#
+# A kernel says it the way it is meant: one walk, and each cell updates the
+# slot its label names.
+#
+#   ruby examples/applications/group_stats.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+READINGS = 2_000_000
+STATIONS = 64
+
+random = CArray::Rng.new(seed: 20260913)
+
+# Stations of very different sizes: the square of a uniform draw lands most
+# of the readings on the low-numbered ones.
+station = CArray.double(READINGS)
+station.random!(rng: random)
+station = ((station ** 2) * STATIONS).int32
+
+value = CArray.double(READINGS)
+value.random!(rng: random)
+value = value * 40.0
+
+LIMIT = 35.0
+
+count = CArray.int64(STATIONS)
+total = CArray.double(STATIONS)
+peak = CArray.double(STATIONS).fill(-Float::INFINITY)
+peak_at = CArray.int64(STATIONS).fill(-1)
+exceed = CArray.int64(STATIONS)
+
+def summarise (station, value, count, total, peak, peak_at, exceed)
+  count.fill(0)
+  total.fill(0.0)
+  peak.fill(-Float::INFINITY)
+  peak_at.fill(-1)
+  exceed.fill(0)
+  CArray.jit_for(station.elements) { |i|
+    k = station[i]
+    v = value[i]
+    count[k] += 1
+    total[k] += v
+    exceed[k] += 1 if v > LIMIT
+    if v > peak[k]
+      peak[k] = v
+      peak_at[k] = i
+    end
+  }
+end
+
+summarise(station, value, count, total, peak, peak_at, exceed)
+
+puts format("%d readings over %d stations", READINGS, STATIONS)
+puts "  station   count      mean     peak   at reading   over #{LIMIT.to_i}"
+[0, 1, 2, STATIONS / 2, STATIONS - 1].each do |k|
+  puts format("  %7d %7d %9.3f %8.3f %12d %8d",
+              k, count[k], total[k] / count[k], peak[k], peak_at[k], exceed[k])
+end
+
+# Every one of those is checkable by selecting the station's cells, which is
+# also the whole-array way of computing it in the first place.
+k = 1
+cells = value[station.eq(k)]
+puts
+puts format("  station %d checks out  %s", k,
+            [count[k], peak[k], exceed[k]] ==
+            [cells.elements, cells.max, cells.gt(LIMIT).count(1)])
+
+# What the sum and the count cost when CArray does them, which is the part of
+# this a kernel has no business replacing.
+def timed (repeats = 5)
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  repeats.times { yield }
+  (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / repeats
+end
+
+binned = timed { station.bincount(length: STATIONS)
+                 station.bincount(weights: value, length: STATIONS) }
+
+# The maximum per station, over whole arrays: one selection and one reduction
+# per station.  The readings are walked STATIONS times over.
+by_masks = timed(1) {
+  STATIONS.times.map { |label| value[station.eq(label)].max }
+}
+
+everything = timed {
+  summarise(station, value, count, total, peak, peak_at, exceed)
+}
+
+puts
+puts format("  count and sum, CArray#bincount     %6.1f ms", binned * 1e3)
+puts format("  the maximum alone, by selection    %6.1f ms", by_masks * 1e3)
+puts format("  all five in one walk, this kernel  %6.1f ms   %.0fx",
+            everything * 1e3, by_masks / everything)
+
+# Which is the shape of it: bincount walks the data twice whatever the labels
+# are, the selections walk it once per label, and the kernel walks it once.
+puts
+puts format("  readings walked -- bincount %d, selections %d, kernel %d",
+            READINGS * 2, READINGS * STATIONS, READINGS)