carray-jit 0.1.2 → 0.1.3

data/examples/applications/random_walk.rb

@@ -0,0 +1,98 @@
+# Gambler's ruin: how long a random walk lasts, and which end it stops at.
+#
+# A walk steps up or down by one until it reaches -A or +B.  How many steps
+# that takes is different every time and is not bounded by anything, so this
+# is `while` again -- but the new part is where the steps come from.  A kernel
+# runs with the GVL released, so Ruby's `rand` is not reachable from inside
+# one; what is reachable is `CArray::Rng`, whose C the compiler pastes into
+# the kernel.  One draw per step, in the loop, at no call.
+#
+# The answers are known exactly, which is what makes this worth running: a
+# walk started at 0 between -A and +B lasts A*B steps on average and stops at
+# +B with probability A/(A+B).  A hundred thousand walks should land near
+# both.
+#
+#   ruby examples/applications/random_walk.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+WALKS = 200_000
+DOWN, UP = -8, 12                       # the two barriers
+
+def walk (n, seed)
+  random = CArray::Rng.new(seed: seed)
+  steps = CArray.int32(n)
+  ended = CArray.int8(n)                # 1 when it stopped at the top
+  CArray.jit_for(n) { |i|
+    position = 0
+    taken = 0
+    while position > DOWN && position < UP
+      position = random.random < 0.5 ? position - 1 : position + 1
+      taken = taken + 1
+    end
+    steps[i] = taken
+    ended[i] = position == UP ? 1 : 0
+  }
+  [steps, ended]
+end
+
+steps, ended = walk(WALKS, 20260913)
+
+puts format("%d walks between %d and %d", WALKS, DOWN, UP)
+puts format("  mean length        %8.2f   (exactly %d)",
+            steps.mean, -DOWN * UP)
+puts format("  stopped at the top %8.4f   (exactly %.4f)",
+            ended.sum.to_f / WALKS, -DOWN.to_f / (UP - DOWN))
+puts format("  longest walk       %8d steps", steps.max)
+
+# The shape of it, which no formula on the line above shows.
+puts
+puts "how long they lasted"
+edges = [0, 25, 50, 100, 200, 400, 800, 1 << 30]
+edges.each_cons(2) do |low, high|
+  count = steps.ge(low).and(steps.lt(high)).count(1)
+  width = 60 * count / WALKS
+  bar = "#" * (count.positive? ? [width, 1].max : 0)
+  label = high > WALKS ? format("%4d+", low) : format("%4d-%-4d", low, high - 1)
+  puts format("  %-10s %6d  %s", label, count, bar)
+end
+
+# A draw is not fixed to a cell.  Which draw a cell gets is the order the loop
+# ran in, so the same seed through the same kernel repeats exactly -- and if a
+# cell has to get *its own* draw whatever the loop does, the way to say that
+# is to fill an array with `CArray#random!` first and read a cell of it.
+again, = walk(WALKS, 20260913)
+puts
+puts format("the same seed gives the same walks  %s", steps.to_a == again.to_a)
+
+# The same thing in Ruby, which is where a Monte Carlo usually starts life.
+def walk_in_ruby (n, seed)
+  random = Random.new(seed)
+  steps = Array.new(n, 0)
+  n.times do |i|
+    position = 0
+    taken = 0
+    while position > DOWN && position < UP
+      position = random.rand < 0.5 ? position - 1 : position + 1
+      taken += 1
+    end
+    steps[i] = taken
+  end
+  steps
+end
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+3.times { walk(WALKS, 20260913) }
+compiled = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / 3
+
+started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+in_ruby = walk_in_ruby(WALKS, 20260913)
+interpreted = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+puts
+puts format("%d walks, about %d draws in all", WALKS, steps.sum)
+puts format("  %6.1f ms compiled, %6.0f ms in Ruby (%.0fx)",
+            compiled * 1e3, interpreted * 1e3, interpreted / compiled)
+puts format("  Ruby's own walks average %.2f steps, which is the same law",
+            in_ruby.sum.to_f / WALKS)

data/examples/applications/van_der_pol.rb

@@ -0,0 +1,186 @@
+# An adaptive integrator, where the step size is the trajectory's own.
+#
+# The van der Pol oscillator is stiff in proportion to its parameter: at
+# mu = 0.1 it is a gentle circle, at mu = 40 it spends most of the cycle
+# crawling and the rest of it snapping across.  An integrator worth using
+# answers that by changing its step -- taking it as long as the error allows,
+# shortening it and *doing the step again* when the estimate comes back too
+# large.
+#
+# Neither half of that survives an expression over whole arrays.  A fixed step
+# can be written as an array pass, but then every trajectory pays the stiffest
+# one's step count; and a rejected step -- this trajectory redoing what it
+# just did while the others move on -- has no array spelling at all.  Here the
+# step, the retry and the count belong to the cell.
+#
+# The method is Bogacki-Shampine 3(2): four stages, the third-order answer
+# carried forward and the second-order one used to size the error.
+#
+#   ruby examples/applications/van_der_pol.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+TRAJECTORIES = 2_000
+FINISH = 20.0
+TOLERANCE = 1.0e-8
+CAP = 200_000                           # a `while` in a kernel carries a bound
+
+stiffness = CArray.double(TRAJECTORIES).seq!(0.1, 40.0 / TRAJECTORIES)
+position = CArray.double(TRAJECTORIES)
+velocity = CArray.double(TRAJECTORIES)
+accepted = CArray.int32(TRAJECTORIES)
+rejected = CArray.int32(TRAJECTORIES)
+
+def integrate (stiffness, position, velocity, accepted, rejected)
+  CArray.jit_for(stiffness.elements) { |i|
+    mu = stiffness[i]
+    x = 2.0                             # the trajectory starts out here
+    v = 0.0
+    t = 0.0
+    step = 0.01
+    taken = 0
+    thrown = 0
+    while t < FINISH && taken < CAP
+      step = FINISH - t if t + step > FINISH
+
+      k1x = v
+      k1v = mu * (1.0 - x * x) * v - x
+      x2 = x + 0.5 * step * k1x
+      v2 = v + 0.5 * step * k1v
+      k2x = v2
+      k2v = mu * (1.0 - x2 * x2) * v2 - x2
+      x3 = x + 0.75 * step * k2x
+      v3 = v + 0.75 * step * k2v
+      k3x = v3
+      k3v = mu * (1.0 - x3 * x3) * v3 - x3
+      nx = x + step * (2.0 * k1x + 3.0 * k2x + 4.0 * k3x) / 9.0
+      nv = v + step * (2.0 * k1v + 3.0 * k2v + 4.0 * k3v) / 9.0
+      k4x = nv
+      k4v = mu * (1.0 - nx * nx) * nv - nx
+
+      ex = step * (-5.0 * k1x / 72.0 + k2x / 12.0 + k3x / 9.0 - k4x / 8.0)
+      ev = step * (-5.0 * k1v / 72.0 + k2v / 12.0 + k3v / 9.0 - k4v / 8.0)
+      error = ex.abs > ev.abs ? ex.abs : ev.abs
+      allowed = TOLERANCE * (1.0 + (nx.abs > nv.abs ? nx.abs : nv.abs))
+
+      if error <= allowed
+        t = t + step
+        x = nx
+        v = nv
+        taken = taken + 1
+      else
+        # The step is not taken: this trajectory does it again, shorter,
+        # while every other one carries on from wherever it is.
+        thrown = thrown + 1
+      end
+
+      growth = 0.9 * Math.exp(Math.log(allowed / (error + 1.0e-300)) / 3.0)
+      growth = 5.0 if growth > 5.0
+      growth = 0.2 if growth < 0.2
+      step = step * growth
+    end
+    position[i] = x
+    velocity[i] = v
+    accepted[i] = taken
+    rejected[i] = thrown
+  }
+end
+
+integrate(stiffness, position, velocity, accepted, rejected)
+
+puts format("%d trajectories, mu from %.1f to %.1f, integrated to t = %.0f",
+            TRAJECTORIES, stiffness[0], stiffness[TRAJECTORIES - 1], FINISH)
+puts format("  steps taken      %d at the least, %d at the most, %.0f on average",
+            accepted.min, accepted.max, accepted.mean)
+puts format("  steps thrown away  up to %d on one trajectory", rejected.max)
+puts format("  a fixed step would have to be the stiffest one's, so %d for everybody",
+            accepted.max)
+puts format("  which is %.1f times the work this did", accepted.max.to_f / accepted.mean)
+
+# Against a reference: the same trajectory by fixed-step RK4, fine enough that
+# it is the answer rather than another approximation.
+def reference (mu, finish, steps)
+  x = 2.0
+  v = 0.0
+  step = finish / steps
+  steps.times do
+    k1x = v;                  k1v = mu * (1.0 - x * x) * v - x
+    ax = x + 0.5 * step * k1x; av = v + 0.5 * step * k1v
+    k2x = av;                 k2v = mu * (1.0 - ax * ax) * av - ax
+    bx = x + 0.5 * step * k2x; bv = v + 0.5 * step * k2v
+    k3x = bv;                 k3v = mu * (1.0 - bx * bx) * bv - bx
+    cx = x + step * k3x;      cv = v + step * k3v
+    k4x = cv;                 k4v = mu * (1.0 - cx * cx) * cv - cx
+    x += step * (k1x + 2 * k2x + 2 * k3x + k4x) / 6.0
+    v += step * (k1v + 2 * k2v + 2 * k3v + k4v) / 6.0
+  end
+  x
+end
+
+puts
+puts "     mu     here   reference        diff   steps"
+[0, TRAJECTORIES / 2, TRAJECTORIES - 1].each do |i|
+  exact = reference(stiffness[i], FINISH, 200_000)
+  puts format("  %5.1f  %8.5f  %10.5f  %10.2e  %6d",
+              stiffness[i], position[i], exact, (position[i] - exact).abs, accepted[i])
+end
+
+# Ruby does the same adaptive integration, over as many trajectories as is
+# polite to wait for.
+SAMPLE = 100
+
+def integrate_in_ruby (stiffness, count)
+  count.times.map do |i|
+    mu = stiffness[i]
+    x = 2.0
+    v = 0.0
+    t = 0.0
+    step = 0.01
+    taken = 0
+    while t < FINISH && taken < CAP
+      step = FINISH - t if t + step > FINISH
+      k1x = v;                   k1v = mu * (1.0 - x * x) * v - x
+      x2 = x + 0.5 * step * k1x; v2 = v + 0.5 * step * k1v
+      k2x = v2;                  k2v = mu * (1.0 - x2 * x2) * v2 - x2
+      x3 = x + 0.75 * step * k2x; v3 = v + 0.75 * step * k2v
+      k3x = v3;                  k3v = mu * (1.0 - x3 * x3) * v3 - x3
+      nx = x + step * (2.0 * k1x + 3.0 * k2x + 4.0 * k3x) / 9.0
+      nv = v + step * (2.0 * k1v + 3.0 * k2v + 4.0 * k3v) / 9.0
+      k4x = nv;                  k4v = mu * (1.0 - nx * nx) * nv - nx
+      ex = step * (-5.0 * k1x / 72.0 + k2x / 12.0 + k3x / 9.0 - k4x / 8.0)
+      ev = step * (-5.0 * k1v / 72.0 + k2v / 12.0 + k3v / 9.0 - k4v / 8.0)
+      error = [ex.abs, ev.abs].max
+      allowed = TOLERANCE * (1.0 + [nx.abs, nv.abs].max)
+      if error <= allowed
+        t += step
+        x = nx
+        v = nv
+        taken += 1
+      end
+      growth = 0.9 * (allowed / (error + 1.0e-300)) ** (1.0 / 3.0)
+      growth = 5.0 if growth > 5.0
+      growth = 0.2 if growth < 0.2
+      step *= growth
+    end
+    x
+  end
+end
+
+in_ruby = integrate_in_ruby(stiffness, SAMPLE)
+agree = (0...SAMPLE).all? { |i| (position[i] - in_ruby[i]).abs < 1.0e-12 }
+
+def timed (repeats = 3)
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  repeats.times { yield }
+  (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / repeats
+end
+
+compiled = timed { integrate(stiffness, position, velocity, accepted, rejected) }
+interpreted = timed(1) { integrate_in_ruby(stiffness, SAMPLE) }
+
+puts
+puts format("  agrees with the same integrator in Ruby  %s", agree)
+puts format("  %6.0f ms here for %d trajectories, %6.0f ms in Ruby for %d (%.0fx a trajectory)",
+            compiled * 1e3, TRAJECTORIES, interpreted * 1e3, SAMPLE,
+            (interpreted / SAMPLE) / (compiled / TRAJECTORIES))

data/examples/applications/wet_bulb.rb

@@ -0,0 +1,140 @@
+# A derived field on a weather grid, where one of the fields needs solving.
+#
+# Temperature and relative humidity come off a grid -- a GRIB message, a
+# netCDF variable, a model's output -- and what is wanted is something else.
+# The dew point is an expression: saturation vapour pressure, the actual
+# vapour pressure from the humidity, and Magnus inverted.  Written over whole
+# arrays that is four passes and three temporaries the size of the grid;
+# written as a kernel it is one pass and none, which is the ordinary reason
+# to use one.
+#
+# The wet-bulb temperature is the other kind.  It is defined by the
+# psychrometric equation, which has no closed form, so every cell solves its
+# own -- and how many Newton steps that takes depends on how far the cell's
+# dew point is from its answer, which is the cell's own business.  The
+# whole-array route can still be written, because a fixed number of rounds
+# covers the worst cell; what it cannot do is let a cell that has converged
+# stop, so every cell pays the worst one's count, and each round is a pass
+# over the grid holding another grid.
+#
+#   ruby examples/applications/wet_bulb.rb
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "carray/jit"
+
+ROWS, COLUMNS = 721, 1440               # a quarter-degree global grid
+PRESSURE = 1013.25                      # hPa, one level
+TOLERANCE = 1.0e-6                      # degrees, how close is close enough
+CAP = 50                                # a `while` in a kernel takes a cap
+
+# Stand-ins for the fields that would have been read: a pole-to-pole
+# temperature gradient with a wave in it, and humidity that varies across it.
+temperature = CArray.double(ROWS, COLUMNS)
+humidity = CArray.double(ROWS, COLUMNS)
+CArray.jit_for(ROWS, COLUMNS) { |j, i|
+  latitude = 90.0 - 180.0 * j / (ROWS - 1)
+  temperature[j, i] = 30.0 - 55.0 * (latitude / 90.0).abs +
+                      4.0 * Math.sin(i / 40.0) * Math.cos(latitude / 25.0)
+  humidity[j, i] = 35.0 + 60.0 * (0.5 + 0.5 * Math.cos(i / 30.0 + j / 60.0))
+}
+
+dew_point = CArray.double(ROWS, COLUMNS)
+wet_bulb = CArray.double(ROWS, COLUMNS)
+rounds_taken = CArray.int8(ROWS, COLUMNS)
+
+# Everything in one walk.  `vapour` and `gamma` are the cell's own values and
+# never become arrays; `low` and `high` are the cell's bracket, which is why
+# the loop can end when this cell is done rather than when the last one is.
+def derive (temperature, humidity, dew_point, wet_bulb, rounds_taken)
+  rows, columns = temperature.dim
+  CArray.jit_for(rows, columns) { |j, i|
+    air = temperature[j, i]
+    saturation = 6.112 * Math.exp(17.67 * air / (air + 243.5))
+    vapour = saturation * humidity[j, i] / 100.0
+    gamma = Math.log(vapour / 6.112)
+    dew = 243.5 * gamma / (17.67 - gamma)
+    dew_point[j, i] = dew
+
+    # Newton on the psychrometric equation, started from the dew point.  The
+    # cap is not decoration: a `while` in a kernel has no interpreter to
+    # interrupt it, so a solver carries the bound it is allowed.
+    guess = dew
+    step = 1.0
+    taken = 0
+    while step.abs > TOLERANCE && taken < CAP
+      saturated = 6.112 * Math.exp(17.67 * guess / (guess + 243.5))
+      residual = saturated - 0.000665 * PRESSURE * (air - guess) - vapour
+      slope = saturated * 17.67 * 243.5 / ((guess + 243.5) * (guess + 243.5)) +
+              0.000665 * PRESSURE
+      step = residual / slope
+      guess = guess - step
+      taken = taken + 1
+    end
+    wet_bulb[j, i] = guess
+    rounds_taken[j, i] = taken
+  }
+end
+
+derive(temperature, humidity, dew_point, wet_bulb, rounds_taken)
+
+puts format("%d x %d grid, %d cells", ROWS, COLUMNS, ROWS * COLUMNS)
+puts "       T     RH       Td       Tw"
+[[180, 0], [360, 200], [360, 720], [540, 1000], [700, 30]].each do |j, i|
+  puts format("  %6.2f %6.1f %8.2f %8.2f",
+              temperature[j, i], humidity[j, i], dew_point[j, i], wet_bulb[j, i])
+end
+puts format("  the wet bulb is never above the air temperature  %s",
+            (wet_bulb - temperature).max <= 0.0)
+puts format("  and never below the dew point                    %s",
+            (wet_bulb - dew_point).min >= -TOLERANCE)
+
+# The part an expression cannot have: the cells did not agree on how long
+# this took.
+puts
+puts format("Newton steps per cell: %d at the least, %d at the most, %.2f on average",
+            rounds_taken.min, rounds_taken.max, rounds_taken.mean)
+
+# The same Newton iteration over whole arrays.  It cannot stop per cell, so it runs
+# the worst cell's count everywhere, and every line here is a pass over the
+# grid holding another grid.
+def derive_over_arrays (temperature, humidity, rounds)
+  saturation = (temperature * 17.67 / (temperature + 243.5)).exp * 6.112
+  vapour = saturation * humidity / 100.0
+  gamma = (vapour / 6.112).log
+  dew = gamma * 243.5 / (17.67 - gamma)
+  guess = dew.to_ca
+  rounds.times do
+    saturated = (guess * 17.67 / (guess + 243.5)).exp * 6.112
+    residual = saturated - (temperature - guess) * (0.000665 * PRESSURE) - vapour
+    slope = saturated * (17.67 * 243.5) / ((guess + 243.5) * (guess + 243.5)) +
+            0.000665 * PRESSURE
+    guess = guess - residual / slope
+  end
+  [dew, guess]
+end
+
+rounds = rounds_taken.max
+array_dew, array_wet = derive_over_arrays(temperature, humidity, rounds)
+puts format("  over whole arrays, everyone pays %d rounds", rounds)
+puts format("  and agrees with the kernel to %.1e  %s", TOLERANCE,
+            (array_wet - wet_bulb).abs.max < TOLERANCE)
+
+def timed (repeats = 3)
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  repeats.times { yield }
+  (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / repeats
+end
+
+compiled = timed { derive(temperature, humidity, dew_point, wet_bulb, rounds_taken) }
+whole = timed { derive_over_arrays(temperature, humidity, rounds) }
+
+puts
+puts format("  one kernel      %7.0f ms", compiled * 1e3)
+puts format("  whole arrays    %7.0f ms   %.1fx", whole * 1e3, whole / compiled)
+puts format("  %.2f Newton steps a cell here, %d for every cell there", rounds_taken.mean, rounds)
+# Each array operation in `derive_over_arrays` is its own walk over the grid
+# and its own array to hold the answer -- sixteen of them per round, counted
+# off the expression -- where the kernel walks the grid once and holds the
+# cell's `guess` in a register.
+puts format("  the grid is %.1f MB, and the array route builds %d of those and walks the grid %d times",
+            ROWS * COLUMNS * 8 / 1048576.0, 16 * rounds, 16 * rounds)

data/examples/features/10_complex.rb

@@ -48,15 +48,25 @@ CArray.jit_for(n) { |i| transformed[i] = signal[i].tanh }
 puts "  tanh matches the array operator #{transformed.to_a == signal.tanh.to_a}"
 
 # A reduction over complex cells: the accumulator starts from a complex zero.
+# The sum is split into partial ones, as every reduction here is, so the last
+# bits are not the serial loop's -- `reassociate: false` asks for that order
+# and gets it exactly.
 total = CArray.cmplx128(1)
 CArray.jit_for(1) { |i|
   running = Complex(0.0, 0.0)
   (0...n).each { |j| running = running + signal[j] }
   total[i] = running
 }
+in_order = CArray.cmplx128(1)
+CArray.jit_for(1, reassociate: false) { |i|
+  running = Complex(0.0, 0.0)
+  (0...n).each { |j| running = running + signal[j] }
+  in_order[i] = running
+}
 serial = (0...n).inject(Complex(0.0, 0.0)) { |sum, j| sum + signal[j] }
 puts "  sum               #{total[0].rectangular.map { |e| e.round(6) }.inspect}"
-puts "  matches Ruby      #{total[0] == serial}"
+puts "  split sum matches Ruby      #{total[0] == serial}   <- the partial sums"
+puts "  serial sum matches Ruby     #{in_order[0] == serial}   <- reassociate: false"
 
 # Where Ruby and C part company.  A real operand carries an exact Integer zero
 # as its imaginary part, and Ruby's own arithmetic returns the other operand
@@ -72,8 +82,8 @@ puts "  Ruby              #{(Complex(1.0, -0.0) + 2.0)}"
 puts "  the kernel        #{kept[0]}"
 puts "  widening first    #{Complex(1.0, -0.0) + Complex(2.0, 0.0)}   <- what C's + would give"
 
-# `**` is the one operation whose answer is not the Ruby loop's to the last
-# bit: Ruby raises a Complex to a power by binary powering, cpow goes round
+# Once the order is the same, `**` is the one operation whose answer is still
+# not the Ruby loop's to the last bit: Ruby raises a Complex to a power by binary powering, cpow goes round
 # through exp and log.  A few machine epsilons apart, growing with the
 # exponent -- and `z * z` is both exact and cheaper than the library call.
 cubed = CArray.cmplx128(n)
@@ -84,7 +94,7 @@ squared = CArray.cmplx128(n)
 CArray.jit_for(n) { |i| squared[i] = signal[i] * signal[i] }
 
 puts
-puts "the one inexact operation"
+puts "the one inexact operation, the order being equal"
 puts "  z ** 3 worst      #{(worst / Float::EPSILON).round(1)} machine epsilons"
 puts "  z * z  matches Ruby exactly #{(0...n).all? { |i| squared[i] == signal[i] * signal[i] }}"
 

data/examples/features/15_loops.rb

@@ -61,7 +61,13 @@ CArray.jit_for(n) { |i|
 
 puts
 puts "Newton, bounded by the extent"
-puts format("  worst relative error   %.1e", ((root ** 2 - a).abs / a).max)
+# Against Math.sqrt rather than against the loop's own residual: the residual
+# is what the break tested, so it can only come back at the tolerance.
+exact = CArray.double(n) { |i| Math.sqrt(a[i]) }
+puts format("  worst relative error   %.1e  (vs Math.sqrt)",
+            ((root - exact).abs / exact).max)
+puts format("  worst residual         %.1e  (what the break tested)",
+            ((root ** 2 - a).abs / a).max)
 puts "  passes taken           #{passes.min}..#{passes.max}"
 puts "  none ran out           #{passes.max < cap}"
 

data/lib/carray/jit/access.rb

@@ -0,0 +1,14 @@
+# The address basis a kernel is handed -- a pointer, and one byte stride per
+# axis, lent for the length of a block -- is knowledge about CArray's views
+# written against CArray's own C, and it lives there.  This gem carried it as
+# a second C extension until carray 3.0.2, which is why the old name is still
+# here; it goes at the next minor.
+#
+# The file stays rather than the alias moving into `carray/jit.rb`, because
+# this is what the light half loads.  A program whose sites are all answered
+# by a library built ahead of it never loads the compiler, and `CFunction`
+# still has to be handed an address -- see `carray/jit/call`.
+require "carray"
+require "carray/jit/version"
+
+CArray::JIT::Access = CArray::AddressBasis