carray-jit 0.1.0

data/examples/applications/relaxation.rb

@@ -0,0 +1,115 @@
+# Steady heat on a plate: Laplace's equation by Jacobi relaxation.
+#
+# The plate's edges are held at fixed temperatures and the interior settles
+# into the average of its neighbours.  One sweep is a five-point stencil, and
+# the boundary is the whole difficulty: those cells are data, not something to
+# compute, so the sweep has to leave them exactly as it found them.  That is
+# `border: :skip`, said at the call -- the loop itself knows nothing about it.
+#
+# Beside it, the same sweep written over whole arrays, which is what this would
+# be without a compiler: four shifted views added, four passes over the plate,
+# and a fresh array for each.
+#
+#   ruby examples/applications/relaxation.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+ROWS, COLUMNS = 120, 160
+SWEEPS = 1200
+
+def fresh_plate
+  plate = CArray.double(ROWS, COLUMNS)
+  plate[nil, 0] = 25.0             # the sides, somewhere in between
+  plate[nil, -1] = 25.0
+  plate[0, nil] = 100.0            # the top edge is hot, corners included
+  plate[-1, nil] = 0.0             # the bottom is held at zero
+  plate
+end
+
+# One sweep.  `into:` writes the array we already have, and gives it back;
+# `border: :skip` leaves the four edges holding the temperatures they were set
+# to, so nothing in the kernel has to know that they are the boundary.
+def sweep (plate, scratch)
+  CArray.jit_stencil(plate, border: :skip, into: scratch) { |a|
+    0.25 * (a[-1, 0] + a[1, 0] + a[0, -1] + a[0, 1])
+  }
+end
+
+plate = fresh_plate
+scratch = plate.copy
+
+SWEEPS.times do
+  sweep(plate, scratch)
+  plate, scratch = scratch, plate
+end
+
+puts "the plate after #{SWEEPS} sweeps"
+(0...12).map { |t| t * (ROWS - 1) / 11 }.each do |i|
+  row = (0...40).map { |t| t * (COLUMNS - 1) / 39 }.map { |j|
+    " .:-=+*#%@"[(plate[i, j] / 100.0 * 9).round]
+  }.join
+  puts "  " + row
+end
+
+# The edges are still what they were set to, and the interior is the average
+# of its neighbours to within the residual below.
+edges_held = plate[0, nil].to_a.all?(100.0) && plate[-1, nil].to_a.all?(0.0)
+residual = 0.0
+(1...(ROWS-1)).each do |i|
+  (1...(COLUMNS-1)).each do |j|
+    average = 0.25 * (plate[i-1, j] + plate[i+1, j] + plate[i, j-1] + plate[i, j+1])
+    difference = (plate[i, j] - average).abs
+    residual = difference if difference > residual
+  end
+end
+puts format("  the edges were left alone   %s", edges_held)
+puts format("  largest residual            %.2e", residual)
+
+# The same sweep over whole arrays, for the answer to check against and the
+# time to measure against.  The interior is written from four shifted views;
+# the boundary is not addressed, which is what :skip does at the call.
+def fused_sweep (plate, scratch)
+  scratch[1..-2, 1..-2] = 0.25 * (plate[0..-3, 1..-2] + plate[2..-1, 1..-2] +
+                                  plate[1..-2, 0..-3] + plate[1..-2, 2..-1])
+  scratch
+end
+
+fused = fresh_plate
+spare = fused.copy
+SWEEPS.times do
+  fused_sweep(fused, spare)
+  fused, spare = spare, fused
+end
+puts format("  agrees with whole arrays    %s (largest difference %.1e)",
+            fused.to_a == plate.to_a, (fused - plate).abs.max)
+
+# What a sweep costs each way.
+warm = fresh_plate
+warm_scratch = warm.copy
+sweep(warm, warm_scratch)
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+100.times { sweep(warm, warm_scratch) }
+stencilled = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / 100
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+100.times { fused_sweep(warm, warm_scratch) }
+whole = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / 100
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+3.times do
+  (1...(ROWS-1)).each do |i|
+    (1...(COLUMNS-1)).each do |j|
+      warm_scratch[i, j] = 0.25 * (warm[i-1, j] + warm[i+1, j] +
+                                   warm[i, j-1] + warm[i, j+1])
+    end
+  end
+end
+interpreted = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / 3
+
+puts
+puts format("a sweep over %d cells", ROWS * COLUMNS)
+puts format("  jit_stencil                 %.3f ms", stencilled * 1e3)
+puts format("  four shifted views          %.3f ms (%.1fx)", whole * 1e3, whole / stencilled)
+puts format("  the same loop in Ruby       %.3f ms (%.0fx)", interpreted * 1e3, interpreted / stencilled)

data/examples/applications/sensor_gaps.rb

@@ -0,0 +1,118 @@
+# Quality control on a sensor record with gaps
+#
+# Real measurements have holes in them, and CArray already has a mask to say
+# where.  What is awkward in a loop is that the rules refer to the holes: fill
+# a gap of one sample from its neighbours, drop a spike, and take the daily
+# mean only from the days that have enough readings left.
+#
+# `reading[i] == UNDEF` is how you ask in Ruby, and it means the same inside a
+# kernel -- it reads the mask, not the value, so what the branch writes is not
+# itself masked.  That is what makes filling a hole possible at all.
+#
+#   ruby examples/applications/sensor_gaps.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+days, hours = 30, 24
+random = Random.new(20260902)
+
+# Hourly temperature: a daily cycle, a seasonal drift, and noise.
+reading = CArray.double(days, hours) { |d, h|
+  15.0 + 8.0 * Math.sin((h - 9) * Math::PI / 12) + d * 0.1 +
+    random.rand(-1.0..1.0)
+}
+
+# The logger dropped some samples, and once reported a spike.
+dropped = 0
+days.times do |d|
+  hours.times do |h|
+    if random.rand < 0.06
+      reading[d, h] = UNDEF
+      dropped += 1
+    end
+  end
+end
+reading[7, 13] = 71.4
+reading[19, 3] = -40.0
+
+# And on day 12 it was offline from midnight until noon.
+(0..12).each { |h| reading[12, h] = UNDEF }
+dropped = reading.count_masked
+
+puts "#{days} days x #{hours} hours, #{dropped} samples missing"
+
+# 1. Reject physically impossible readings.  Writing UNDEF marks the cell
+#    missing and leaves its value alone.
+rejected = CArray.int32(1)
+CArray.jit_for(days, hours) { |d, h|
+  if reading[d, h] > 50.0
+    reading[d, h] = UNDEF
+  elsif reading[d, h] < -30.0
+    reading[d, h] = UNDEF
+  end
+}
+puts "  #{reading.count_masked - dropped} readings rejected as out of range"
+
+# 2. Fill a hole from its neighbours, but only where both neighbours are there.
+#    Where they are not, the average reads a masked cell and the result comes
+#    out masked by itself -- the rule does not have to be written twice.
+filled = CArray.double(days, hours)
+CArray.jit_for(days, 1...(hours-1)) { |d, h|
+  if reading[d, h] == UNDEF
+    filled[d, h] = 0.5 * (reading[d, h-1] + reading[d, h+1])
+  else
+    filled[d, h] = reading[d, h]
+  end
+}
+filled[nil, 0] = reading[nil, 0]
+filled[nil, hours-1] = reading[nil, hours-1]
+
+recovered = reading.count_masked - filled.count_masked
+puts "  #{recovered} holes interpolated, #{filled.count_masked} still missing"
+
+# 3. The daily mean, from the readings that survived -- and a day with fewer
+#    than twenty valid hours does not get a mean at all.
+mean = CArray.double(days)
+valid = CArray.int32(days)
+CArray.jit_for(days) { |d|
+  total = 0.0
+  count = 0
+  (0...hours).each { |h|
+    if filled[d, h] == UNDEF
+      count = count
+    else
+      total = total + filled[d, h]
+      count = count + 1
+    end
+  }
+  valid[d] = count
+  if count >= 20
+    mean[d] = total / count
+  else
+    mean[d] = UNDEF
+  end
+}
+
+puts "  #{mean.count_masked} of #{days} days rejected for too few readings"
+puts
+puts "  day  valid  mean"
+(0...days).each do |d|
+  next unless d < 6 || d > days - 4 || valid[d] < 20
+  text = mean[d] == UNDEF ? "  --  " : format("%6.2f", mean[d])
+  bar = mean[d] == UNDEF ? "" : "#" * ((mean[d] - 10) * 2).round
+  puts format("  %3d  %5d  %s  %s", d, valid[d], text, bar)
+end
+
+# The same rules written as a Ruby loop, for comparison -- and to check that
+# they agree, which is possible precisely because the kernel asks about the
+# mask rather than relying on it propagating.
+reference = Array.new(days) do |d|
+  values = (0...hours).map { |h| filled[d, h] == UNDEF ? nil : filled[d, h] }.compact
+  values.size >= 20 ? values.sum / values.size : nil
+end
+agrees = (0...days).all? { |d|
+  reference[d].nil? ? mean[d] == UNDEF : (mean[d] - reference[d]).abs < 1e-12
+}
+puts
+puts "  agrees with the same rules written in Ruby: #{agrees}"

data/examples/applications/sieve.rb

@@ -0,0 +1,95 @@
+# The sieve of Eratosthenes.
+#
+# Each prime crosses out its own multiples, and how many that is depends on
+# the prime: the inner loop's length is different for every cell and is not
+# knowable before the loop runs, which is what `while` is for.  The cells it
+# writes are at computed subscripts, and they are cells this same loop will
+# later read -- crossing out 2's multiples is what makes 4 composite before
+# the loop reaches it.
+#
+# Written over whole arrays this is a pass per prime, each one building an
+# index array to scatter through.  Written here it is the sieve as it is
+# stated.
+#
+#   ruby examples/applications/sieve.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+N = 1_000_000
+
+def sieve (n)
+  flags = CArray.int8(n).fill(1)
+  flags[0] = 0
+  flags[1] = 0
+  CArray.jit_for(2...n) { |i|
+    if flags[i] == 1
+      j = i * i                   # everything smaller was crossed out already
+      while j < n
+        flags[j] = 0
+        j = j + i
+      end
+    end
+  }
+  flags
+end
+
+flags = sieve(N)
+primes = flags.eq(1).count(1)
+
+puts "primes below #{N}"
+puts "  how many                  #{primes}"
+puts "  the first few             #{(0...30).select { |i| flags[i] == 1 }.inspect}"
+puts "  the largest               #{(0...N).reverse_each.find { |i| flags[i] == 1 }}"
+
+# The inner loop cannot be written as an extent here.  `(i*i...n).step(i)` is
+# refused, and so is any inner range whose bounds a cell works out: an inner
+# loop runs over an integer expression in literals and captured scalars, so
+# that the kernel knows its shape before it runs.  `while` is the spelling
+# that carries the bound the data decides.
+begin
+  counts = CArray.int32(N)
+  CArray.jit_for(2...N) { |i|
+    seen = 0
+    (i...N).each { |j| seen = seen + 1 }
+    counts[i] = seen
+  }
+rescue CArray::JIT::Unsupported => error
+  puts "  a per-cell inner range    refused: #{error.message.sub(/ \(at line.*/m, "")}"
+end
+
+# The same sieve in Ruby, for the answer and the time.
+def sieve_in_ruby (n)
+  flags = Array.new(n, 1)
+  flags[0] = 0
+  flags[1] = 0
+  i = 2
+  while i < n
+    if flags[i] == 1
+      j = i * i
+      while j < n
+        flags[j] = 0
+        j = j + i
+      end
+    end
+    i = i + 1
+  end
+  flags
+end
+
+in_ruby = sieve_in_ruby(N)
+puts "  agrees with Ruby          #{flags.to_a == in_ruby}"
+
+sieve(N)                                # compiled and cached on the first call
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+5.times { sieve(N) }
+compiled = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / 5
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+sieve_in_ruby(N)
+interpreted = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+puts
+puts format("one sieve to %d: %.1f ms compiled, %.1f ms in Ruby (%.0fx)",
+            N, compiled * 1e3, interpreted * 1e3, interpreted / compiled)

data/examples/applications/sobel_edges.rb

@@ -0,0 +1,80 @@
+# Edge detection on an image
+#
+# A Sobel filter is two 3x3 convolutions and a hypotenuse.  With array
+# operators that is eighteen shifted arrays, eighteen passes over the image and
+# a dozen temporaries the size of it; here it is the filter as written, one
+# pass, nothing allocated in between.
+#
+#   ruby examples/applications/sobel_edges.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+def sobel (image, edges)
+  rows, columns = image.dim
+  CArray.jit_for(1...(rows-1), 1...(columns-1)) { |i, j|
+    gx = (image[i-1, j+1] + 2.0 * image[i, j+1] + image[i+1, j+1]) -
+         (image[i-1, j-1] + 2.0 * image[i, j-1] + image[i+1, j-1])
+    gy = (image[i+1, j-1] + 2.0 * image[i+1, j] + image[i+1, j+1]) -
+         (image[i-1, j-1] + 2.0 * image[i-1, j] + image[i-1, j+1])
+    edges[i, j] = Math.sqrt(gx * gx + gy * gy)
+  }
+end
+
+# A synthetic picture: a disc, a bar, and a soft background gradient.
+rows, columns = 40, 96
+image = CArray.double(rows, columns)
+rows.times do |i|
+  columns.times do |j|
+    y = (i - 20.0) / 16.0
+    x = (j - 30.0) / 16.0
+    value = 0.25 * (j.to_f / columns)
+    value += 0.7 if x * x + y * y < 1.0                          # the disc
+    value += 0.6 if i.between?(8, 30) && j.between?(58, 84)      # the bar
+    image[i, j] = value
+  end
+end
+
+edges = CArray.double(rows, columns)
+sobel(image, edges)
+
+def draw (field, title)
+  puts title
+  scale = field.max
+  field.to_a.each_slice(2) do |row, _|
+    puts "  " + row.each_slice(1).map { |v|
+      " .:-=+*#@"[[(v.first / scale * 8).round, 8].min]
+    }.join
+  end
+end
+
+draw(image, "image")
+draw(edges, "edges")
+
+# On an image of a size you would actually filter -- the same filter, and the
+# same loop written in Ruby, both over the whole thing.
+size = 512
+large = CArray.double(size, size) { |i, j| Math.sin(i * 0.03) * Math.cos(j * 0.02) }
+result = CArray.double(size, size)
+
+sobel(large, result)   # compile it before timing it
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+5.times { sobel(large, result) }
+compiled = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / 5
+
+reference = CArray.double(size, size)
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+(1...(size-1)).each do |i|
+  (1...(size-1)).each do |j|
+    gx = (large[i-1, j+1] + 2.0 * large[i, j+1] + large[i+1, j+1]) -
+         (large[i-1, j-1] + 2.0 * large[i, j-1] + large[i+1, j-1])
+    gy = (large[i+1, j-1] + 2.0 * large[i+1, j] + large[i+1, j+1]) -
+         (large[i-1, j-1] + 2.0 * large[i-1, j] + large[i-1, j+1])
+    reference[i, j] = Math.sqrt(gx * gx + gy * gy)
+  end
+end
+interpreted = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+puts format("%dx%d image: %.1f ms compiled, %.0f ms as a Ruby loop (%.0fx)",
+            size, size, compiled * 1e3, interpreted * 1e3, interpreted / compiled)
+puts "  identical results: #{result.to_a == reference.to_a}"

data/examples/features/01_element_wise.rb

@@ -0,0 +1,69 @@
+# An expression over whole arrays, in one pass.
+#
+# jit_each is jit_for's sibling, for work that reaches no neighbour: no
+# index to name, so no extent to give, and the arrays are written the way
+# CArray already spells the whole of one.  What changes is not the expression
+# but how it runs -- at the cell, reading the data once, instead of one pass
+# per operation with intermediate arrays in between.
+#
+# Every name in the block is a cell, the loop being this compiler's and not
+# written here, so the assignment is Ruby's own: `out = ...` writes the array
+# `out` names outside.  jit_map is the same block with its value asked for.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+n = 100_000
+a = CArray.double(n).seq!(1.0)
+b = CArray.double(n).seq!(0.5, 0.5)
+c = CArray.double(n).seq!(2.0, -0.25)
+out = CArray.double(n)
+
+CArray.jit_each { out = (a + b) * (c - a) + b * c - a }
+
+# The same expression evaluated by CArray, which allocates an array per
+# operation along the way.
+expected = (a + b) * (c - a) + b * c - a
+
+puts "element-wise"
+puts "  first three cells   #{out[0..2].to_a.inspect}"
+puts "  matches CArray      #{out.to_a == expected.to_a}"
+
+# The rank comes from the arrays rather than from the block, so the same
+# expression serves whatever shape it is given, and broadcasting costs nothing
+# -- a stretched axis arrives as a stride of zero.
+matrix = CArray.double(3, 4).seq!(1.0)
+row = CArray.double(1, 4).seq!(10.0, 10.0)
+scaled = CArray.double(3, 4)
+
+CArray.jit_each { scaled = matrix * row }
+
+puts "  broadcast row       #{scaled.to_a.inspect}"
+puts "  matches CArray      #{scaled.to_a == (matrix * row).to_a}"
+
+# jit_map: the same block, with its value asked for.
+#
+# The last statement is the value every cell of the result gets, and the
+# result is allocated here -- typed from that value rather than from the
+# arrays -- so there is no output array to name.  The name is what says a
+# value comes back; the block is read exactly the same way.
+
+sums = CArray.jit_map { a + b }
+puts
+puts "asking for the value back"
+puts "  first three cells   #{sums[0..2].to_a.inspect}"
+puts "  matches CArray      #{sums.to_a == (a + b).to_a}"
+
+# It is the same shape of block CArray.jit_function takes and not the same thing:
+# there the loop belongs to whoever calls the function, so the body may close
+# over nothing.  Here the loop is ours and the body is inlined into it.
+weight = 0.25
+blended = CArray.jit_map { a * weight + b * (1.0 - weight) }
+puts "  closing over a value #{blended[0..2].to_a.inspect}"
+
+# An assignment is a statement with a value -- Ruby's rule, not a special
+# case here -- so a block may write an array of yours and hand the same value
+# back.  Which is jit_each's block, asked a different question.
+kept = CArray.double(n)
+also = CArray.jit_map { kept = a - b }
+puts "  written and returned #{kept[0..2].to_a == also[0..2].to_a}"

data/examples/features/02_stencil.rb

@@ -0,0 +1,40 @@
+# A stencil: each cell from its neighbours.
+#
+# Naming the indices is what lets a kernel reach a neighbouring cell, and the
+# extents say which cells are written -- here the interior, leaving the border
+# alone.  The offsets mean what they mean in Ruby: src[i-1, j] is the cell at
+# index i-1.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+rows, columns = 6, 8
+src = CArray.double(rows, columns).seq!(1.0)
+out = CArray.double(rows, columns)
+
+CArray.jit_for(1...(rows-1), 1...(columns-1)) { |i, j|
+  out[i, j] = 0.25 * (src[i-1, j] + src[i+1, j] + src[i, j-1] + src[i, j+1])
+}
+
+reference = CArray.double(rows, columns)
+(1...(rows-1)).each do |i|
+  (1...(columns-1)).each do |j|
+    reference[i, j] = 0.25 * (src[i-1, j] + src[i+1, j] + src[i, j-1] + src[i, j+1])
+  end
+end
+
+puts "five-point stencil"
+puts "  interior matches the Ruby loop   #{out.to_a == reference.to_a}"
+puts "  border untouched                 #{out[0, nil].to_a.all?(0.0)}"
+
+# An extent may step by more than one, which changes which cells are written
+# and therefore which offsets are dependencies: with a step of two, a[i-1] is
+# a cell this loop never writes.
+values = CArray.double(10).seq!(1.0)
+CArray.jit_for((2...10).step(2)) { |i| values[i] = values[i-1] * 100.0 }
+puts "  every other cell                 #{values.to_a.inspect}"
+
+# Written this way the border is what the extents avoid, and the cells there
+# keep whatever the output array held -- zeros, which cannot be told from
+# zeros that were computed.  The same stencil with the loop implied and the
+# edge said at the call is jit_stencil's; see 14_stencil_window.rb.

data/examples/features/03_recurrence.rb

@@ -0,0 +1,50 @@
+# A recurrence: each cell from the ones before it.
+#
+# This is the case a vectorised library cannot help with, because cell i is
+# not available until cell i-1 has been written.  Reading behind the cell
+# being written propagates only upward, and the extent is where that is
+# written down -- by the caller, since nothing else can know it was meant.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+# Legendre polynomials at x, by their three-term recurrence.
+n = 24
+x = 0.5
+legendre = CArray.double(n)
+legendre[0] = 1.0
+legendre[1] = x
+
+CArray.jit_for(2...n) { |i|
+  w = x * legendre[i-1]
+  wy = w - legendre[i-2]
+  legendre[i] = wy + w - wy / i
+}
+
+reference = Array.new(n, 0.0)
+reference[0] = 1.0
+reference[1] = x
+(2...n).each do |i|
+  w = x * reference[i-1]
+  wy = w - reference[i-2]
+  reference[i] = wy + w - wy / i
+end
+
+puts "Legendre recurrence, x = #{x}"
+puts "  P_2 .. P_5            #{legendre[2..5].to_a.inspect}"
+puts "  bit-exact vs Ruby     #{legendre.to_a == reference}"
+
+# `wy / i` divides a Float by an Integer, so it is a Float division here as it
+# is in Ruby.  Where both sides are integers, the division is floored -- also
+# as in Ruby, and not as C would truncate it.
+counts = CArray.int32(6)
+CArray.jit_for(6) { |i| counts[i] = (i - 4) / 3 }
+puts "  floored integer /     #{counts.to_a.inspect} == #{(0...6).map { |i| (i - 4) / 3 }.inspect}"
+
+# A range that would read outside the array is refused before anything runs,
+# rather than quietly starting one cell later.
+begin
+  CArray.jit_for(0...n) { |i| legendre[i] = legendre[i-1] * 2.0 }
+rescue CArray::JIT::Unsupported => error
+  puts "  refused:              #{error.message.lines.first.strip}"
+end

data/examples/features/04_thomas.rb

@@ -0,0 +1,81 @@
+# The Thomas algorithm: two sweeps in opposite directions.
+#
+# The back substitution reads x[i+1] -- ahead of the cell it writes -- so it
+# has to run downward to propagate.  `(n-2).step(0, -1)` is that, and is the
+# spelling Ruby itself iterates backwards with; `(n-2)..0` is refused, because
+# Ruby gives that Range no elements and the same loop written by hand would do
+# nothing.
+#
+# The forward sweep also shows why a kernel writes as many arrays as it likes:
+# cc and dd share a denominator, and splitting them in two would compute it
+# twice.
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+n = 2_000
+random = Random.new(20260902)
+
+# A diagonally dominant tridiagonal system: a is the subdiagonal, b the
+# diagonal, c the superdiagonal, d the right-hand side.
+a = CArray.double(n) { random.rand(-1.0..1.0) }
+c = CArray.double(n) { random.rand(-1.0..1.0) }
+b = CArray.double(n) { |i| 4.0 + random.rand }
+d = CArray.double(n) { random.rand(-1.0..1.0) }
+a[0] = 0.0
+c[n-1] = 0.0
+
+cc = CArray.double(n)
+dd = CArray.double(n)
+x  = CArray.double(n)
+
+cc[0] = c[0] / b[0]
+dd[0] = d[0] / b[0]
+
+CArray.jit_for(1...n) { |i|                        # upward: reads cc[i-1]
+  denominator = b[i] - a[i] * cc[i-1]
+  cc[i] = c[i] / denominator
+  dd[i] = (d[i] - a[i] * dd[i-1]) / denominator
+}
+
+x[n-1] = dd[n-1]
+CArray.jit_for((n-2).step(0, -1)) { |i|            # downward: reads x[i+1]
+  x[i] = dd[i] - cc[i] * x[i+1]
+}
+
+# Multiply the solution back through the original system and look at what is
+# left over.
+residual = 0.0
+n.times do |i|
+  row = b[i] * x[i]
+  row += a[i] * x[i-1] if i > 0
+  row += c[i] * x[i+1] if i < n - 1
+  residual = [residual, (row - d[i]).abs].max
+end
+
+puts "Thomas algorithm, n = #{n}"
+puts "  x[0..2]                #{x[0..2].to_a.inspect}"
+puts "  max |A x - d|          #{format('%.3e', residual)}"
+
+# The extent is where the algorithm is stated, and nothing second-guesses it.
+# Run the same body upward and it computes something else -- not an error, but
+# not back substitution either: each cell reads an x[i+1] the sweep has not
+# reached yet.  It is the answer the same Ruby loop gives, which is the only
+# thing this promises.
+wrong_way = CArray.double(n)
+wrong_way[n-1] = dd[n-1]
+CArray.jit_for(0...(n-1)) { |i| wrong_way[i] = dd[i] - cc[i] * wrong_way[i+1] }
+
+in_ruby = Array.new(n) { |i| i == n-1 ? dd[n-1] : 0.0 }
+(0...(n-1)).each { |i| in_ruby[i] = dd[i] - cc[i] * in_ruby[i+1] }
+
+wrong_residual = 0.0
+n.times do |i|
+  row = b[i] * wrong_way[i]
+  row += a[i] * wrong_way[i-1] if i > 0
+  row += c[i] * wrong_way[i+1] if i < n - 1
+  wrong_residual = [wrong_residual, (row - d[i]).abs].max
+end
+
+puts "  same body, upward      max |A x - d| = #{format('%.3e', wrong_residual)}"
+puts "  ...which is what Ruby's own loop gives: #{wrong_way.to_a == in_ruby}"