carray-jit 0.1.0

data/examples/features/12_sweep.rb

@@ -0,0 +1,139 @@
+# Letting CArray drive the loop.
+#
+# An element-wise pass is the one shape that is a *sweep*: nothing reaches a
+# neighbour, nothing chooses an order.  So where this CArray has
+# `ca_call_cslab` (3.0.1 and later), jit_each hands it the compiled body
+# and lets it acquire the operands -- broadcasting them, ORing and propagating
+# the masks, and calling back a chunk at a time.
+#
+# Nothing about the expression changes, and nothing here is written
+# differently.  What changes is who opens the arrays, and what that costs.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+require "benchmark"
+
+Sweep = CArray::JIT::Sweep
+Access = CArray::JIT::Access
+
+puts "this CArray has ca_call_cslab: #{Sweep.available?}"
+puts
+
+# The rank leaves the loop
+# ------------------------
+# A chunk is one flat run of cells -- and CArray's acquire reads an operand's
+# element count and element size and never looks at its shape, so a chunk is
+# already flat.  Nothing is reshaped.  What is compiled flat is the *kernel*.
+
+def doubled (source, out)
+  CArray.jit_each { out = source * 2.0 }
+end
+
+flat_in = CArray.double(6).seq!
+flat_out = CArray.double(6)
+cube_in = CArray.double(2, 3, 4).seq!
+cube_out = CArray.double(2, 3, 4)
+
+flat = doubled(flat_in, flat_out)
+cube = doubled(cube_in, cube_out)
+
+puts "one block, a run of cells and a cube of them"
+puts "  loop axes            #{flat.rank} and #{cube.rank}"
+puts "  arrays keep shape    #{flat_out.dim.inspect} and #{cube_out.dim.inspect}"
+puts "  one compiled kernel  #{flat.equal?(cube)}"
+puts "  answers              #{flat_out.to_a == (flat_in * 2.0).to_a} and " \
+     "#{cube_out.to_a == (cube_in * 2.0).to_a}"
+puts
+
+# The wrapper is a call, not a second code generator: the kernel's first three
+# arguments are already base, stride and bounds, which is what a chunk arrives
+# as.
+puts "the sweep entry point"
+puts flat.slab_source.lines
+       .grep(/^carray_jit_slab|bounds\[1\] = n|carray_jit_kernel\(base/)
+       .map { |line| "  " + line.strip }
+puts
+
+# What it is worth
+# ----------------
+# An operand CArray cannot walk in place -- a gather, a lazy array -- is
+# re-gathered 32KB at a time by the sweep.  The tiers here move the whole box
+# the kernel touches instead, and for an element-wise pass that box is the
+# whole array.
+
+n = 2_000_000
+src = CArray.double(n).seq!
+b = CArray.double(n).seq!(0.5, 0.5)
+out = CArray.double(n)
+gather = src[CArray.int32(n).seq.reverse]
+
+def timed
+  2.times { yield }
+  Benchmark.realtime { 3.times { yield } } / 3
+end
+
+puts "n = #{n}, out[] = x + b * 2.0"
+[["entity", src], ["gather view", gather]].each do |label, x|
+  elapsed = timed { CArray.jit_each { out = x + b * 2.0 } }
+  scratch = Access.classify(x)[:tier] == 3 ? "%.0f MB" % (n * 8.0 / 1024 / 1024) : "none"
+  puts "  %-12s tier %d   %6.2f ms   the driver here would hold %s" %
+       [label, Access.classify(x)[:tier], elapsed * 1e3, scratch]
+end
+puts "  -- the sweep holds 32 KB per gathered operand, whatever n is."
+
+# A strided view is the case where the re-gather buys nothing: the tiers
+# address a column, a transpose or every other cell in place, so there is no
+# whole-array copy to be saved from.  That is why the driver is chosen on the
+# operands and not only on the shape.
+half = (0...n).step(2)
+strided_x, strided_b, strided_out = src[half], b[half], out[half]
+elapsed = timed { CArray.jit_each { strided_out = strided_x + strided_b * 2.0 } }
+puts "  %-12s tier %d   %6.2f ms   %.2f ns/cell, and no scratch either way" %
+     ["strided view", Access.classify(strided_x)[:tier], elapsed * 1e3,
+      elapsed * 1e9 / strided_x.elements]
+puts "  -- swept, the same pass was 4.7 ns/cell: re-gathered for nothing."
+puts
+
+# What keeps the driver here
+# --------------------------
+# Four things, and only the last is about this CArray being old.
+
+columns = CArray.double(64, 64).seq!
+into = CArray.double(64, 64)
+every_other = columns[nil, (0...64).step(2)]
+every_other_out = into[nil, (0...64).step(2)]
+kernel = CArray.jit_each { every_other_out = every_other * 2.0 }
+puts "a strided view operand   loop axes #{kernel.rank}"
+puts "  -- walked in place here, re-gathered there for nothing."
+
+matrix = CArray.double(3, 4).seq!
+row = CArray.double(1, 4).seq!(10.0)
+stretched = CArray.double(3, 4)
+kernel = CArray.jit_each { stretched = matrix * row }
+puts "a stretched operand      loop axes #{kernel.rank}"
+puts "  -- broadcasting arrives as a stride of zero on an axis, and a flat"
+puts "     run has no axes, so cell k would stop lining up."
+
+masked = CArray.double(5).seq!(1.0)
+masked[2] = UNDEF
+masked_out = CArray.double(5)
+kernel = CArray.jit_each { masked_out = masked * 2.0 }
+puts "a mask anywhere in the pass     sweepable? #{kernel.sweepable?}"
+puts "  -- an operand that carries one, or a body that asks about one."
+puts "     CArray ORs and propagates the masks, but `a[i] == UNDEF` is a"
+puts "     question about a single cell, and a chunk carries no per-cell"
+puts "     mask to ask it of.  The answer is the same either way:"
+puts "     #{masked_out.is_masked.to_a.inspect}"
+puts
+puts "a CArray without the family     asked for by symbol, not assumed;"
+puts "  -- an older one falls back without the caller hearing about it."
+puts
+
+# jit_for never goes this way, and that is not a limitation: a kernel that
+# names an index reaches neighbours, chooses an order and runs inner loops,
+# none of which a chunked walk can offer.  Splitting the two methods by what
+# the block names drew the same line as what a sweep can drive.
+recurrence = CArray.double(8).seq!(1.0)
+CArray.jit_for(1...8) { |i| recurrence[i] = recurrence[i-1] * 1.5 }
+puts "jit_for stays here by its nature"
+puts "  #{recurrence.to_a.map { |v| v.round(4) }.inspect}"

data/examples/features/13_cscalar.rb

@@ -0,0 +1,80 @@
+# CScalar: a value with a home.
+#
+# A CScalar is the one-cell CArray it subclasses, minus the index.  `s[]` is
+# the value and `s[] = ...` puts one back, and that missing index is the whole
+# of the difference -- which is why it needed saying to a compiler whose
+# kernel language is written in subscripts.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+gain = CScalar.double() { 2.0 }
+offset = CScalar.double() { 10.0 }
+signal = CArray.double(6).seq!(1.0)
+out = CArray.double(6)
+
+# In an expression it is read at every cell, which is what CArray's own
+# operators do with it.  Nothing here says it is a scalar; it says so itself.
+CArray.jit_each { out = signal * gain + offset }
+puts "signal * gain + offset"
+puts "  #{out.to_a.inspect}"
+puts "  same as CArray's own operators  #{out.to_a == (signal * gain + offset).to_a}"
+puts
+
+# And written like any other cell.
+CArray.jit_each { gain = gain + 0.5 }
+puts "gain after gain[] = gain + 0.5   #{gain[0]}"
+puts
+
+# An indexed kernel reaches it too, and there the missing index is the point:
+# there is no axis to walk, so there is no index to write.  A bare name says
+# the same thing.
+indexed = CArray.double(6)
+CArray.jit_for(6) { |i| indexed[i] = signal[i] * gain[] }
+puts "the same, with the loop written out"
+puts "  #{indexed.to_a.inspect}"
+
+bare = CArray.double(6)
+CArray.jit_for(6) { |i| bare[i] = signal[i] * gain }
+puts "  a bare `gain` agrees  #{bare.to_a == indexed.to_a}"
+
+# It is still the one-cell array it is, so the index spelling keeps working
+# and means the same cell.
+spelled = CArray.double(6)
+CArray.jit_for(6) { |i| spelled[i] = signal[i] * gain[0] }
+puts "  and so does gain[0]   #{spelled.to_a == indexed.to_a}"
+puts
+
+# Every iteration writes the one cell it has, and what is left is what the
+# same Ruby loop leaves -- which makes it an accumulator without asking for
+# one.  The inner loop of a reduction rests on exactly this.
+total = CScalar.int() { 0 }
+counts = CArray.int(4).seq!(1)
+CArray.jit_for(4) { |i| total[] = total[] + counts[i] }
+puts "total after one pass over #{counts.to_a.inspect}  #{total[0]}"
+
+in_ruby = 0
+(0...4).each { |i| in_ruby = in_ruby + counts[i] }
+puts "  what the same Ruby loop leaves  #{in_ruby}"
+puts
+
+# A contraction takes one as it takes any other operand it does not index.
+left = CArray.double(3).seq!(1.0)
+right = CArray.double(3).seq!(1.0)
+weight = CScalar.double() { 2.0 }
+puts "weighted dot product  #{CArray.jit_contract { |k| left[k] * right[k] * weight[] }[0]}"
+puts
+
+# What it will not do is take an expression wider than itself, because there
+# is one cell and no answer to which of the values lands.  CArray refuses the
+# same assignment, in the same terms.
+begin
+  CArray.jit_each { weight = signal + 1.0 }
+rescue CArray::JIT::Unsupported => error
+  puts "refused: #{error.message}"
+end
+begin
+  weight[] = signal + 1.0
+rescue => error
+  puts "CArray:  #{error.message.lines.first.strip[0, 78]}"
+end

data/examples/features/14_stencil_window.rb

@@ -0,0 +1,106 @@
+# The window spelling of a stencil, and the border as an argument.
+#
+# 02_stencil.rb writes the same five-point average with the indices named.
+# What that spelling has nowhere to put is the edge: `src[i-1, j]` at i = 0
+# has no meaning, so the extents avoid it and the border keeps whatever the
+# output array held.  A window has no index to write and so has somewhere to
+# put the question -- `border:` at the call.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+rows, columns = 5, 6
+src = CArray.double(rows, columns).seq!(1.0)
+
+# The block's parameters are windows onto the arrays given, in that order:
+# a[0, 0] is the cell the loop is on, a[-1, 0] its neighbour.  The block's
+# value is what the cell gets, as jit_map's is, and an array of the same shape
+# comes back.
+smoothed = CArray.jit_stencil(src) { |a|
+  0.25 * (a[-1, 0] + a[1, 0] + a[0, -1] + a[0, 1])
+}
+
+# The same stencil with the indices named, over the interior alone.
+written = CArray.double(rows, columns)
+CArray.jit_for(1...(rows-1), 1...(columns-1)) { |i, j|
+  written[i, j] = 0.25 * (src[i-1, j] + src[i+1, j] + src[i, j-1] + src[i, j+1])
+}
+
+puts "the window"
+puts "  interior matches jit_for   #{smoothed[1..-2, 1..-2].to_a == written[1..-2, 1..-2].to_a}"
+# The default is :mask, because CArray can say "not computed", and a border of
+# zeros that means the same cannot be told from zeros that were computed.
+puts "  border missing by default  #{smoothed.count_masked} cells"
+
+# ---------------------------------------------------------------- the border
+
+# Five answers, on one row of a small array so they can be read side by side.
+line = CArray.double(1, 5).seq!(1.0)              # 1 2 3 4 5
+
+def row (result)
+  result.to_a[0].map { |e| e == UNDEF ? "  --" : format("%4.1f", e) }.join(" ")
+end
+
+puts
+puts "border:, on [1 2 3 4 5] averaging each cell with its two neighbours"
+[:mask, :skip, :zero, :clamp, :wrap].each do |border|
+  # :skip leaves the border as it was found, so what it was found as is worth
+  # seeing: this one is filled with -1 first.
+  into = CArray.double(1, 5).seq!(-1.0, 0.0)
+  result = CArray.jit_stencil(line, border: border, into: into) { |a|
+    (a[0, -1] + a[0, 0] + a[0, 1]) / 3.0
+  }
+  puts format("  %-6s  %s", border, row(result))
+end
+
+# :mask and :skip are answers about the cell -- it is not computed.  The other
+# three answer for the read instead, so those cells are computed after all:
+# :zero reads 0 outside, :clamp the nearest cell, :wrap the far side.  A Game
+# of Life board is a torus because of :wrap; an image filter usually wants
+# :clamp.
+
+# --------------------------------------------------- several arrays and rest
+
+# Each array given gets a window, in the order the block names them; the names
+# shadow whatever they hold outside, as CArray.fuse's do.  A diffusion step
+# with a conductivity that varies from cell to cell:
+u = CArray.double(6, 6) { |i, j| (i - 2.5).abs + (j - 2.5).abs }
+k = CArray.double(6, 6).fill(0.2)
+
+stepped = CArray.jit_stencil(u, k, border: :clamp) { |u, k|
+  u[0,0] + k[0,0] * (u[-1,0] + u[1,0] + u[0,-1] + u[0,1] - 4.0 * u[0,0])
+}
+puts
+puts "several arrays"
+puts "  every cell computed        #{stepped.count_masked.zero?}"
+
+# The offsets have to be known before the loop runs -- the radius is what lets
+# the interior be walked without asking, at each cell, whether it is inside.
+# Arithmetic over literals is not a computed offset: it is folded where the
+# block is read, so a stencil drawn from a formula may be written as one.
+wide = CArray.jit_stencil(src, border: :clamp) { |a| a[0, -1-1] + a[0, 1+1] }
+puts "  a folded offset            #{wide[2, 2] == src[2, 0] + src[2, 4]}"
+
+# What may not appear is anything that has to be read to be known -- a
+# captured integer included, since one compiled kernel serves every value of
+# it and the loop would not know the radius.
+begin
+  offset = 1
+  CArray.jit_stencil(src) { |a| a[0, offset] }
+rescue CArray::JIT::Unsupported => error
+  puts "  a computed offset          refused: #{error.message.sub(/ \(at line.*/m, "")}"
+end
+
+# ------------------------------------------------------ the array comes back
+
+# Typed from the block's value unless you say otherwise, as jit_map's is.
+counts = CArray.jit_stencil(src, border: :zero, type: :int32) { |a|
+  a[-1, 0] + a[1, 0] > a[0, 0] ? 1 : 0
+}
+puts
+puts "the result"
+puts "  type:                      #{counts.data_type_name}"
+# into: writes an array of yours and returns it; the type is then that array's.
+mine = CArray.float32(rows, columns)
+same = CArray.jit_stencil(src, border: :clamp, into: mine) { |a| a[0, 0] * 2.0 }
+puts "  into:                      #{same.equal?(mine)}, and typed #{mine.data_type_name} by it"

data/examples/features/15_loops.rb

@@ -0,0 +1,148 @@
+# Loops inside a kernel: an inner `each` with a `break`, and `while` where the
+# bound is not knowable.
+#
+# The kernel's own loop is written by the extents.  Inside the body a cell may
+# still need a loop of its own -- a search, an iteration to a tolerance -- and
+# there are two spellings, which differ in whether the number of passes can be
+# bounded before the loop runs.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+rows, columns = 5, 8
+source = CArray.double(rows, columns) { |i, j| (j - i) * 1.0 }
+threshold = 1.5
+
+# A search: the first column past the threshold, or -1.  `break` in an inner
+# loop means what it means in Ruby, and so does `next`.
+first = CArray.int32(rows)
+CArray.jit_for(rows) { |i|
+  found = -1
+  (0...columns).each { |j|
+    if source[i, j] > threshold
+      found = j
+      break
+    end
+  }
+  first[i] = found
+}
+
+reference = (0...rows).map { |i|
+  (0...columns).find { |j| source[i, j] > threshold } || -1
+}
+
+puts "an inner loop with a break"
+puts "  first past #{threshold}         #{first.to_a.inspect}"
+puts "  matches Ruby           #{first.to_a == reference}"
+
+# ------------------------------------------------------- a bounded iteration
+
+# Newton's method for a square root, with the bound in the extent.  This is
+# the better spelling wherever a bound exists: the kernel cannot fail to stop,
+# and a cell that ran out of passes can be told from one that converged.
+n = 2000
+a = CArray.double(n).seq!(1.0)
+tolerance = 1e-12
+cap = 40
+
+root = CArray.double(n)
+passes = CArray.int32(n)
+CArray.jit_for(n) { |i|
+  x = a[i]
+  taken = 0
+  (0...cap).each { |k|
+    break if (x * x - a[i]).abs <= tolerance * a[i]
+    x = 0.5 * (x + a[i] / x)
+    taken = taken + 1
+  }
+  root[i] = x
+  passes[i] = taken
+}
+
+puts
+puts "Newton, bounded by the extent"
+puts format("  worst relative error   %.1e", ((root ** 2 - a).abs / a).max)
+puts "  passes taken           #{passes.min}..#{passes.max}"
+puts "  none ran out           #{passes.max < cap}"
+
+# ----------------------------------------------------------------- and while
+
+# Where the bound is not knowable, `while` says so.  The condition is read at
+# the top of every pass, as Ruby's is; a local the condition reads has to be a
+# local before the loop, since the condition is read before the body is.
+by_while = CArray.double(n)
+CArray.jit_for(n) { |i|
+  guess = a[i]
+  while (guess * guess - a[i]).abs > tolerance * a[i]
+    guess = 0.5 * (guess + a[i] / guess)
+  end
+  by_while[i] = guess
+}
+
+puts
+puts "while"
+puts "  same answers           #{by_while.to_a == root.to_a}"
+
+# What it gives up is the guarantee that the loop ends -- nothing here can
+# decide that in general, and a kernel that does not return cannot be
+# interrupted, because the generated loop has no place to notice a signal.
+# The one runaway that can be read off the page is refused rather than
+# compiled:
+begin
+  CArray.jit_for(4) { |i| while true do root[i] = root[i] + 1.0 end }
+rescue CArray::JIT::Unsupported => error
+  puts "  while true, no break   refused: #{error.message.sub(/ \(at line.*/m, "")}"
+end
+# `while true` with a `break` in it is an ordinary thing to write, and is left
+# alone.  `until` is not in the subset: `while` with the condition negated is
+# the same loop, and one spelling is enough to keep.
+
+# ------------------------------------------------------------------- and next
+
+# `next` in the kernel block skips the cell, the way it would end a block Ruby
+# was running: the cell keeps its value and its mask, and the loop moves on.
+kept = CArray.double(n).fill(-1.0)
+CArray.jit_for(n) { |i|
+  next if a[i] % 2.0 == 0.0
+  kept[i] = a[i]
+}
+puts
+puts "next in the kernel block"
+puts "  even cells untouched   #{(0...8).map { |i| kept[i] }.inspect}"
+
+# What it costs: an inner loop carrying a break is not a fold, so it is not
+# split into partial sums -- it stays the serial chain it was.  The kernel is
+# compiled on its first call and cached, so it is run once before the clock
+# starts.
+newton = lambda do
+  CArray.jit_for(n) { |i|
+    x = a[i]
+    (0...cap).each { |k|
+      break if (x * x - a[i]).abs <= tolerance * a[i]
+      x = 0.5 * (x + a[i] / x)
+    }
+    root[i] = x
+  }
+end
+newton.call
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+20.times { newton.call }
+compiled = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / 20
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+20.times do
+  (0...n).each do |i|
+    x = a[i]
+    cap.times do
+      break if (x * x - a[i]).abs <= tolerance * a[i]
+      x = 0.5 * (x + a[i] / x)
+    end
+    root[i] = x
+  end
+end
+interpreted = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / 20
+
+puts
+puts format("Newton over %d cells: %.3f ms compiled, %.3f ms in Ruby (%.0fx)",
+            n, compiled * 1e3, interpreted * 1e3, interpreted / compiled)

data/examples/features/16_raising.rb

@@ -0,0 +1,69 @@
+# Raising from a kernel.
+#
+# A kernel can stop and say why.  What comes back is a RuntimeError with the
+# message written in the block -- what `raise "..."` gives in Ruby -- and the
+# loop stops where it raised: the cell that raised is not written, and neither
+# are the ones after it.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+n = 8
+depth = CArray.double(n).seq!(3.0, -1.0)          # 3 2 1 0 -1 -2 ...
+out = CArray.double(n).fill(-99.0)
+
+begin
+  CArray.jit_for(n) { |i|
+    raise "depth went negative" if depth[i] < 0.0
+    out[i] = Math.sqrt(depth[i])
+  }
+rescue RuntimeError => error
+  puts "raising"
+  puts "  class                 #{error.class}"
+  puts "  message               #{error.message}"
+end
+
+# The cells before the raise keep what the kernel wrote, as they do when a
+# division with no divisor stops one.
+puts "  written before it     #{out.to_a[0, 4].map { |e| e.round(3) }.inspect}"
+puts "  untouched after it    #{out.to_a[4..].all?(-99.0)}"
+
+# The message is written out and the class is not named, and both follow from
+# where the message goes: C has nothing to carry a string out of a cell in, so
+# the message is registered as the kernel is compiled and the cell writes a
+# code for it into the error slot the kernel already watches.  The raise
+# itself happens once the loop has stopped and there is a Ruby stack to raise
+# on.
+
+# A cell whose value is missing does not raise: the comparison was decided by
+# bytes that mean nothing, and this is the rule the division helper already
+# keeps and that `if` keeps for what it writes.
+holed = CArray.double(4).seq!(1.0)
+holed[2] = 999.0          # a value that would raise below
+holed[2] = UNDEF          # marked missing; the bytes are left alone
+squares = CArray.double(4)
+CArray.jit_for(4) { |i|
+  raise "out of range" if holed[i] > 100.0
+  squares[i] = holed[i] * holed[i]
+}
+puts "  a masked cell         did not raise on its 999.0; #{squares.count_masked} cell came back missing"
+
+# A jit_function body raises the same way, and the message travels with the
+# function: f.call(-1.0) and the same body reached from a kernel raise the
+# same thing.
+safe_sqrt = CArray.jit_function("double (*)(double)") { |x|
+  raise "negative argument" if x < 0.0
+  Math.sqrt(x)
+}
+
+begin
+  safe_sqrt.call(-1.0)
+rescue RuntimeError => error
+  puts "  from jit_function     #{error.message} (called from Ruby)"
+end
+
+begin
+  CArray.jit_for(n) { |i| out[i] = safe_sqrt.call(depth[i]) }
+rescue RuntimeError => error
+  puts "  from a kernel         #{error.message} (the same message, pasted in)"
+end