cumo 0.5.8 → 0.5.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12027799f8203c1e08409de1fdec1b550e26511547bbaee2a938488ecd19e079
-  data.tar.gz: 399daea2a183febf70ceeb1e6492479fd3a34ae29e994265c4da9f89644c3c4d
+  metadata.gz: f211eb1858b22b8418a8494efb431afeca60f023de409d74e6bdb1ae1fc3753a
+  data.tar.gz: '085be7ea42f37e235945e62783c51522c206c22eb539557b965812cc71ce422d'
 SHA512:
-  metadata.gz: d12b0fa56578c8ffd309aa314ab40c98d3b983375d7ddd33b0909ac47092d52b48ea1b53173ea843701587a0fb50442a907b459bd558a8c92e4525eedd1531fd
-  data.tar.gz: ba1b2bac6afb811d790c3f8d90906f3e7f571cbbdb8dc59e3ff6141fa54aa5b8f8a8d6e597ff3045e001c9ae5ff0cab6d9e6679ee6b8f5bbdb1642f203ba19b1
+  metadata.gz: 19a6ca3c65b190e2347624232fa33302f4485e84d90df7de6972d727d76353e20a15a00bf8a7c8c96d281a97bbd7f8084016b8c2961e6781e4d94b00b17287d1
+  data.tar.gz: 2df512d0a5e2b201cd82cc91d4dc258f4d3463097e2969250ab0aa81ba591abaaa89ea0c6d1e818d8b85f32d698a6b9cc529d961a8e432be540fb7f4144f2e70

data/CHANGELOG.md

@@ -1,3 +1,39 @@
+# 0.5.9 (2026/08/20)
+
+Breaking changes:
+
+* `sort_index` resolves ties to the lowest index, the GPU sort being stable, where the host quicksort left them in whatever order it produced (PR #261)
+
+Fixes:
+
+* Fix `a[[2, 1], true].store(array)` writing every row onto row 0, on every dtype: ndloop read the index array on the host before the kernel that fills it had run (PR #265)
+* Fix a segmentation fault storing a Ruby Array into a reversed `Cumo::Bit` view that starts past the first word (PR #266)
+* Fix `sort` in place of a view backed by an index array reading row 0 for every row (PR #262)
+* Fix a `Cumo::RObject` store reading an index array before the kernel writes it, which answered zeroes from the second store onwards (PR #258)
+* Fix a store of an Array of narrays into an indexed destination writing one element per row (PR #257)
+* Fix the zero fill of a row stored from a shorter narray starting one element too far (PR #256)
+* Fix grid-stride kernels hanging from about 2**32 elements, the step wrapping to zero (PR #240)
+* Fix `Cumo::Bit` views with a negative step reading out of bounds (PR #238)
+* Fix index reductions answering a later index on ties, where `Numo::NArray` answers the first (PR #236)
+* Fix wrong values from reductions with `nan: true` (PR #234)
+
+Changes:
+
+* Run `sort`, `sort_index` and `median` on the GPU with `cub::DeviceSegmentedRadixSort`; 1M `SFloat` `sort` 115.7 -> 0.47 ms, `median` 107.8 -> 0.13 ms, `sort_index` 115.8 -> 1.69 ms (PR #259, PR #260, PR #261)
+* Run `poly` on the GPU, which had called its iterator once per element behind a synchronization; 2^20 `DFloat` 163.8 -> 0.021 ms (PR #263)
+* Run `bincount` on the GPU; 1M `Int32` 1.62 -> 0.05 ms (PR #255)
+* Run `cumsum` and `cumprod` on the GPU (PR #242)
+* Run `minmax`, `abs`, `isnan` and the rest of `cond_unary`, `modf` and `frexp` on the GPU (PR #230, PR #231, PR #232, PR #233)
+* Run the `Cumo::Bit` operators, reductions, `where`, `where2`, `fill` and the stores on the GPU (PR #237, PR #239, PR #241, PR #252, PR #254, PR #264, PR #266)
+* Run complex `real=` and `imag=` on the GPU; 2^22 `DComplex` 4.63 -> 0.45 ms (PR #267)
+* Run the accumulating reductions and `mulsum` on more than one GPU thread, where they had been running device-side thrust in a single thread (PR #243, PR #244)
+* Address a whole non-contiguous view in one kernel launch instead of one per row, in the elementwise templates, the stores, the copies and the Bit operands (PR #245, PR #246, PR #249, PR #251, PR #252)
+* Read a flat reduction operand without the indexer, and reduce over an outer axis with host-side addressing; `sum(axis: 0)` on 4096x4096 2.01 -> 0.017 ms (PR #248, PR #253)
+* Split a reduction with too few outputs across more blocks (PR #235)
+* Build the C++ and CUDA sources with optimization: mkmf leaves `$(optflags)` out of `CXXFLAGS`, so every `.cpp` and the host half of every `.cu` had been built at `-O0`; `a + b` 2.86 -> 2.00 us (PR #250)
+* Warn about the synchronization `a[idx]` and `inspect` perform (PR #247)
+* Add benchmark scripts under `bench/` for a transformer block, k-means, a 2D Ising model, conjugate gradient, a particle simulation and the CPU/GPU crossover, and two probes for calls that synchronize or launch one kernel per row
+
 # 0.5.8 (2026/08/17)
 
 Breaking changes:

data/bench/cg_bench.rb

@@ -0,0 +1,271 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# ---------------------------------------------------------------------------
+# Conjugate gradient, to price what a host readback costs.
+#
+#   ruby cg_bench.rb
+#   GPU=1 ruby cg_bench.rb                        # the plain way: readbacks every iteration
+#   GPU=1 SCALAR=device ruby cg_bench.rb          # keep alpha and beta on the device
+#   GPU=1 SCALAR=device CHECK=20 ruby cg_bench.rb # and test convergence rarely
+#   GPU=1 OP=dense N=4096 ruby cg_bench.rb        # heavier arithmetic per iteration
+#
+# CG makes two scalars an iteration, alpha and beta, and multiplies arrays by
+# them. Written plainly that reads them back to the host every iteration, and
+# the convergence test reads a third, each one waiting for the queue to drain.
+# An iteration is not much arithmetic, so the waiting is what shows.
+#
+#   SCALAR=host   alpha and beta become Ruby Floats, as one would write it
+#   SCALAR=device they stay as the 0-dimensional NArray sum answers, and are
+#                 never read (Cumo returns 0-dim; on Numo sum is a Float
+#                 already, so the setting makes no difference there)
+#   CHECK=k       test convergence every k iterations, 0 to never test
+#
+# A readback does not cost a fixed amount. What it costs is however much work
+# is queued when it happens, so it is better read as a cap on how deep the
+# pipeline is allowed to get than as a price per call. Several shallow drains
+# an iteration cost little each; the last one costs a lot, because until it is
+# gone no iteration can overlap the next.
+#
+# On the host path the floor is two readbacks an iteration whatever CHECK is
+# set to, since alpha needs pap and beta needs rs_new as Floats. Keeping the
+# scalars on the device is what makes fewer than that possible, and thinning
+# the convergence test only pays once they are there.
+#
+# Correctness is checked against a known solution: x_true is chosen first and
+# b = A x_true built from it, so the answer has something to be compared to.
+#
+# Timings vary by a factor of a few between runs. Take the best of several.
+# ---------------------------------------------------------------------------
+
+GPU = !%w[0 false].include?(ENV['GPU'].to_s.downcase) && !ENV['GPU'].to_s.empty?
+
+if GPU
+  require 'cumo/narray'
+  XM = Cumo
+else
+  require 'numo/narray'
+  XM = Numo
+end
+
+OP      = (ENV['OP']      || 'stencil')  # stencil | dense
+GRID    = (ENV['GRID']    || 512).to_i   # side of the grid, for stencil
+N       = (ENV['N']       || 2048).to_i  # number of unknowns, for dense
+MAXITER = (ENV['MAXITER'] || 200).to_i
+SCALAR  = (ENV['SCALAR']  || 'host')     # host | device
+CHECK   = (ENV['CHECK']   || 1).to_i     # test convergence every CHECK, 0 to never
+TOL     = (ENV['TOL']     || 1.0e-6).to_f
+DOT     = (ENV['DOT']     || 'sum')      # sum | blas
+DETAIL  = ENV['DETAIL'] != '0'
+REPEAT  = (ENV['REPEAT']  || 3).to_i     # solve this many times, keep the fastest
+SEED    = (ENV['SEED'] || 42).to_i
+
+TIMES = Hash.new(0.0)
+READBACKS = [0]
+
+def sync
+  XM::CUDA::Runtime.cudaDeviceSynchronize if GPU
+end
+
+# A readback, which is where the host waits. Counted, since that is the point.
+def scalar(v)
+  READBACKS[0] += 1
+  return v if v.is_a?(Numeric)
+
+  v.respond_to?(:extract_cpu) ? v.extract_cpu : v.extract
+end
+
+def timed(key)
+  return yield unless DETAIL
+
+  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  r = yield
+  sync
+  TIMES[key] += Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+  r
+end
+
+def dotp(a, b)
+  if DOT == 'blas'
+    a.reshape(a.size).dot(b.reshape(b.size))
+  else
+    (a * b).sum
+  end
+end
+
+# --- the operator ----------------------------------------------------------
+
+# The five-point Laplacian, negated to be positive definite. The border stays
+# zero and is never touched.
+def apply_stencil(p)
+  out = XM::SFloat.zeros(GRID, GRID)
+  out[1..-2, 1..-2] =
+    4.0 * p[1..-2, 1..-2] -
+    p[0..-3, 1..-2] - p[2..-1, 1..-2] -
+    p[1..-2, 0..-3] - p[1..-2, 2..-1]
+  out
+end
+
+# A diagonally dominant symmetric matrix. The identity is built with
+# arithmetic rather than a fancy index.
+def build_dense
+  r = XM::SFloat.new(N, N).rand * 2.0 - 1.0
+  sym = (r + r.transpose) * 0.5
+  i = XM::SFloat.new(N, 1).seq
+  j = XM::SFloat.new(1, N).seq
+  off = (XM::SFloat.zeros(N, N) + (i - j)).abs.clip(0.0, 1.0).ceil # 0 on the diagonal
+  sym + (1.0 - off) * (N * 1.0)
+end
+
+# --- setup -----------------------------------------------------------------
+
+version = begin
+  XM::NArray::VERSION
+rescue StandardError
+  'unknown'
+end
+
+begin
+  XM::NArray.srand(SEED)
+rescue StandardError
+  nil
+end
+
+if OP == 'dense'
+  amat = build_dense
+  x_true = XM::SFloat.new(N).rand * 2.0 - 1.0
+  apply = ->(p) { amat.dot(p) }
+  unknowns = N
+else
+  x_true = XM::SFloat.zeros(GRID, GRID)
+  x_true[1..-2, 1..-2] = XM::SFloat.new(GRID - 2, GRID - 2).rand * 2.0 - 1.0
+  apply = ->(p) { apply_stencil(p) }
+  unknowns = (GRID - 2) * (GRID - 2)
+end
+
+b = apply.call(x_true)
+
+puts "ruby      : #{RUBY_VERSION} (#{RUBY_PLATFORM})"
+puts "backend   : #{XM} #{version}"
+puts "problem   : OP=#{OP} unknowns=#{unknowns} MAXITER=#{MAXITER}"
+puts "scalar    : SCALAR=#{SCALAR} CHECK=#{CHECK} DOT=#{DOT}"
+puts
+
+# Warm up
+warm = XM::SFloat.new(64, 64).seq
+warm_sum = (warm * warm).sum
+warm_sum = warm_sum.extract if warm_sum.respond_to?(:extract)
+sync
+GC.start
+READBACKS[0] = 0
+
+# --- CG --------------------------------------------------------------------
+
+# Each distinct scalar is read at most once an iteration. Reading rs_old in
+# both alpha and beta, and rs_new in both the convergence test and beta, would
+# wait twice for a value already in hand.
+def solve(apply, b, rs0, shape)
+  x = XM::SFloat.zeros(*shape)
+  r = b + 0.0 # a copy
+  p_dir = r + 0.0
+  rs_old = timed(:dot) { dotp(r, r) }
+  rs_old_h = SCALAR == 'device' ? nil : rs0
+  iters = 0
+  converged = nil
+
+  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  MAXITER.times do |it|
+    iters = it + 1
+
+    ap = timed(:apply) { apply.call(p_dir) }
+    pap = timed(:dot) { dotp(p_dir, ap) }
+
+    alpha = timed(:alpha) do
+      SCALAR == 'device' ? rs_old / pap : rs_old_h / scalar(pap).to_f
+    end
+
+    timed(:axpy) do
+      x += p_dir * alpha
+      r -= ap * alpha
+    end
+
+    rs_new = timed(:dot) { dotp(r, r) }
+    rs_new_h = SCALAR == 'device' ? nil : scalar(rs_new).to_f
+
+    if CHECK.positive? && (iters % CHECK).zero?
+      rel = Math.sqrt((rs_new_h || scalar(rs_new).to_f) / rs0)
+      if rel < TOL
+        converged = rel
+        break
+      end
+    end
+
+    beta = timed(:beta) do
+      SCALAR == 'device' ? rs_new / rs_old : rs_new_h / rs_old_h
+    end
+
+    timed(:update_p) { p_dir = r + p_dir * beta }
+    rs_old = rs_new
+    rs_old_h = rs_new_h
+  end
+  sync
+  { x: x, iters: iters, converged: converged,
+    elapsed: Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0 }
+end
+
+shape = OP == 'dense' ? [N] : [GRID, GRID]
+rs0 = scalar(dotp(b, b)).to_f # the reference for the relative residual, read once
+
+# Solve it a few times and keep the fastest. A single timing here varies by a
+# factor of a few, which is enough to invent a trend that is not there.
+best = nil
+REPEAT.times do
+  TIMES.clear
+  READBACKS[0] = 0
+  run = solve(apply, b, rs0, shape)
+  run[:times] = TIMES.dup
+  run[:readbacks] = READBACKS[0]
+  best = run if best.nil? || run[:elapsed] < best[:elapsed]
+end
+x = best[:x]
+iters = best[:iters]
+elapsed = best[:elapsed]
+TIMES.replace(best[:times])
+READBACKS[0] = best[:readbacks]
+puts format('  converged at iter %d, relative residual %.3e', iters, best[:converged]) if best[:converged]
+
+# --- results ---------------------------------------------------------------
+
+res = apply.call(x) - b
+rel_res = Math.sqrt(scalar((res * res).sum).to_f / rs0)
+err = x - x_true
+rel_err = Math.sqrt(scalar((err * err).sum).to_f) /
+          Math.sqrt(scalar((x_true * x_true).sum).to_f)
+
+puts format('  iterations     : %d', iters)
+puts format('  rel. residual  : %.3e', rel_res)
+puts format('  rel. error     : %.3e  (against the known x_true)', rel_err)
+puts format('  time           : %.4f s  (%.1f us/iter, best of %d)',
+            elapsed, elapsed / iters * 1e6, REPEAT)
+puts format('  readbacks      : %d  (%.2f per iteration)',
+            READBACKS[0], READBACKS[0].to_f / iters)
+
+if DETAIL
+  puts
+  measured = TIMES.values.sum
+  puts 'breakdown (per iteration):'
+  TIMES.sort_by { |_, v| -v }.each do |key, v|
+    puts format('  %-10s %9.1f us  %5.1f%%', key, v / iters * 1e6, 100.0 * v / measured)
+  end
+  puts '  (these sections synchronize, so they add up to more than us/iter above,'
+  puts '   and DETAIL=1 is much noisier than DETAIL=0 because of it)'
+end
+
+puts
+puts '  What to compare:'
+puts '    SCALAR=host   CHECK=1   the plain way, several readbacks an iteration'
+puts '    SCALAR=device CHECK=1   alpha and beta stay on the device, one readback'
+puts '    SCALAR=device CHECK=20  the convergence test thinned out too'
+puts '    SCALAR=device CHECK=0   no readback at all inside the loop'
+puts '  Thinning the test on its own changes nothing: the host path still reads'
+puts '  pap and rs_new every iteration. The two settings only pay together.'

data/bench/crossover_bench.rb

@@ -0,0 +1,374 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# ---------------------------------------------------------------------------
+# Crossover sweep - the element count at which Cumo overtakes Numo, per kind of
+# operation.
+#
+#   ruby crossover_bench.rb                     # both in one process
+#   ONLY=cumo JSON=cumo.json ruby crossover_bench.rb
+#   ONLY=numo JSON=numo.json ruby crossover_bench.rb
+#   MERGE=numo.json,cumo.json ruby crossover_bench.rb   # combine separate runs
+#
+#   SIZES=1024,4096,16384 TIME_CAP=0.5 ruby crossover_bench.rb
+#
+# This asks "how small is too small", not "how many times faster on a big
+# array". The element count that pays back Cumo's per-operation fixed cost
+# (launch + Ruby + ndloop) differs by operation, and that point is the
+# guidance a user actually needs.
+#
+# Every point is measured two ways:
+#   pipelined  BATCH operations with a single synchronize at the end. This is
+#              the per-operation cost of a run of work, and what the crossover
+#              is computed from.
+#   per-op     one synchronize after every operation, for code that reads the
+#              result straight back.
+# Cumo cannot overlap the next launch with the previous operation once a
+# synchronize sits between them, so the two differ by 2-4x on the same work.
+#
+# Timing is best-of-N, and the GPU is spun for a second first so that a
+# laptop's clock ramp stays out of the measurement.
+#
+# Numo's times swing several-fold with the history of the process: above
+# glibc's 128 KB mmap threshold every allocation takes page faults. Read the
+# crossover as an order of magnitude, and split the processes with ONLY and
+# MERGE when it matters.
+# ---------------------------------------------------------------------------
+
+require 'json'
+
+ONLY      = ENV['ONLY']
+JSON_OUT  = ENV['JSON']
+MERGE     = ENV['MERGE']
+TIME_CAP  = (ENV['TIME_CAP'] || 1.0).to_f  # stop a sweep once one run exceeds this
+WARMUP    = (ENV['WARMUP']   || 1.0).to_f  # seconds of idle work to raise the GPU clock
+MIN_REPS  = 3
+MAX_REPS  = 30
+MIN_TOTAL = 0.15                            # roughly how long to spend on a point
+MAX_BATCH = (ENV['BATCH'] || 64).to_i       # most operations to pipeline at once
+# The outputs cannot be held on to while pipelining, or the pool has nothing to
+# reuse, so each one is freed as it is produced. Allocation and free are part of
+# the pipelined number for that reason.
+BATCH_BYTES = (ENV['BATCH_BYTES'] || (64 << 20)).to_i
+
+SIZES = (ENV['SIZES'] || '256,1024,4096,16384,65536,262144,1048576,4194304,16777216,67108864')
+        .split(',').map(&:to_i)
+
+def clock
+  Process.clock_gettime(Process::CLOCK_MONOTONIC)
+end
+
+# --- backends --------------------------------------------------------------
+# Numo and Cumo have separate namespaces, so both can live in one process.
+
+BACKENDS = {}
+
+unless ONLY == 'cumo'
+  begin
+    require 'numo/narray'
+    BACKENDS[:numo] = { mod: Numo, sync: -> {} }
+  rescue LoadError => e
+    warn "cannot load numo-narray: #{e.message}"
+  end
+end
+
+unless ONLY == 'numo'
+  begin
+    require 'cumo/narray'
+    BACKENDS[:cumo] = { mod: Cumo, sync: -> { Cumo::CUDA::Runtime.cudaDeviceSynchronize } }
+  rescue LoadError => e
+    warn "cannot load cumo: #{e.message}"
+  end
+end
+
+# --- timing ----------------------------------------------------------------
+
+def best_of(&block)
+  best = Float::INFINITY
+  reps = 0
+  t_start = clock
+  loop do
+    t0 = clock
+    block.call
+    dt = clock - t0
+    best = dt if dt < best
+    reps += 1
+    break if reps >= MIN_REPS && (reps >= MAX_REPS || (clock - t_start) > MIN_TOTAL)
+  end
+  best
+end
+
+# Holding on to the outputs leaves the pool nothing to reuse and every
+# allocation is a fresh one, so both ways of measuring free alike. The two
+# columns then differ by the synchronize and nothing else.
+def run_once(callable, frees)
+  r = callable.call
+  r.free if frees && r.respond_to?(:free)
+end
+
+# One synchronize per operation, for code that reads the result straight back.
+def measure_sync(callable, sync, frees)
+  run_once(callable, frees)
+  sync.call
+  best_of do
+    run_once(callable, frees)
+    sync.call
+  end
+end
+
+# batch operations with a single synchronize at the end, reported per operation.
+def measure_pipelined(callable, sync, batch, frees)
+  run_once(callable, frees)
+  sync.call
+  return measure_sync(callable, sync, frees) if batch <= 1
+
+  t = best_of do
+    batch.times { run_once(callable, frees) }
+    sync.call
+  end
+  t / batch
+end
+
+# Pipeline as many as fit in BATCH_BYTES of live output.
+def batch_for(bytes)
+  return MAX_BATCH if bytes <= 0
+
+  (BATCH_BYTES / bytes).clamp(1, MAX_BATCH)
+end
+
+# --- operations ------------------------------------------------------------
+# The two-dimensional ones use a square of side sqrt(n).
+
+OPS = [
+  {
+    name: 'mul scalar', dims: 1, out_bytes: ->(n) { n * 4 },
+    setup: lambda { |xm, n|
+      a = xm::SFloat.new(n).seq
+      -> { a * 2.0 }
+    }
+  },
+  {
+    name: 'add arrays', dims: 1, out_bytes: ->(n) { n * 4 },
+    setup: lambda { |xm, n|
+      a = xm::SFloat.new(n).seq
+      b = xm::SFloat.new(n).seq
+      -> { a + b }
+    }
+  },
+  {
+    name: 'exp', dims: 1, out_bytes: ->(n) { n * 4 },
+    setup: lambda { |xm, n|
+      a = xm::SFloat.new(n).seq * 1.0e-6
+      -> { xm::NMath.exp(a) }
+    }
+  },
+  {
+    name: 'sum all', dims: 1, out_bytes: ->(_n) { 4 },
+    setup: lambda { |xm, n|
+      a = xm::SFloat.new(n).seq
+      -> { a.sum }
+    }
+  },
+  {
+    name: 'sum axis1', dims: 2, out_bytes: ->(n) { Integer(Math.sqrt(n)) * 4 },
+    setup: lambda { |xm, n|
+      s = Integer(Math.sqrt(n))
+      a = xm::SFloat.new(s, s).seq
+      -> { a.sum(axis: 1) }
+    }
+  },
+  {
+    # store returns the destination itself, which must not be freed
+    name: 'store colslice', dims: 2, out_bytes: ->(_n) { 0 }, frees: false,
+    setup: lambda { |xm, n|
+      s = Integer(Math.sqrt(n))
+      src = xm::SFloat.new(s, s * 2).seq
+      dst = xm::SFloat.zeros(s, s)
+      v = src[true, 0...s]
+      -> { dst.store(v) }
+    }
+  },
+  {
+    name: 'dot (GEMM)', dims: 2, out_bytes: ->(n) { n * 4 },
+    setup: lambda { |xm, n|
+      s = Integer(Math.sqrt(n))
+      a = xm::SFloat.new(s, s).seq * 0.001
+      b = xm::SFloat.new(s, s).seq * 0.001
+      -> { a.dot(b) }
+    }
+  }
+].freeze
+
+# --- run -------------------------------------------------------------------
+
+results = Hash.new { |h, k| h[k] = Hash.new { |h2, k2| h2[k2] = {} } }
+
+if MERGE
+  MERGE.split(',').each do |path|
+    JSON.parse(File.read(path)).each do |backend, ops|
+      ops.each do |op, points|
+        points.each { |n, t| results[backend.to_sym][op][n.to_i] = t }
+      end
+    end
+  end
+  puts "merged    : #{MERGE}"
+else
+  puts "ruby      : #{RUBY_VERSION} (#{RUBY_PLATFORM})"
+  BACKENDS.each do |key, be|
+    version = begin
+      be[:mod]::NArray::VERSION
+    rescue StandardError
+      'unknown'
+    end
+    puts format('%-10s: %s %s', key, be[:mod], version)
+  end
+  puts "sizes     : #{SIZES.first} .. #{SIZES.last} (#{SIZES.size} points)"
+  puts "params    : TIME_CAP=#{TIME_CAP}s WARMUP=#{WARMUP}s"
+  puts
+
+  # raise the GPU clock before measuring anything
+  if BACKENDS[:cumo] && WARMUP.positive?
+    a = Cumo::SFloat.new(4_000_000).seq
+    t0 = clock
+    (a * 1.0001).free while clock - t0 < WARMUP
+    BACKENDS[:cumo][:sync].call
+    puts format('  warmed up for %.1f s', WARMUP)
+    puts
+  end
+
+  # Whichever operation is measured first carries the process's one-time setup,
+  # so every one of them gets a discarded pass first.
+  BACKENDS.each do |key, be|
+    OPS.each do |op|
+      call = op[:setup].call(be[:mod], SIZES.first)
+      3.times { run_once(call, op.fetch(:frees, true)) }
+      be[:sync].call
+    rescue StandardError => e
+      warn format('  discarded pass %s / %s: %s', key, op[:name], e.class)
+    end
+  end
+
+  BACKENDS.each do |key, be|
+    OPS.each do |op|
+      frees = op.fetch(:frees, true)
+      SIZES.each do |n|
+        call = op[:setup].call(be[:mod], n)
+        t_sync = measure_sync(call, be[:sync], frees)
+        t_pipe = measure_pipelined(call, be[:sync], batch_for(op[:out_bytes].call(n)), frees)
+        results[key][op[:name]][n] = [t_sync, t_pipe]
+        GC.start
+        break if t_sync > TIME_CAP # anything larger takes too long to be useful
+      rescue StandardError, NoMemoryError => e
+        warn format('  %s / %s / n=%d: %s', key, op[:name], n, e.class)
+        break
+      end
+    end
+  end
+
+  if JSON_OUT
+    File.write(JSON_OUT, JSON.pretty_generate(results))
+    puts "  -> #{JSON_OUT}"
+  end
+end
+
+# --- report ----------------------------------------------------------------
+
+def fmt_time(t)
+  return '        -' unless t
+
+  if t < 1.0e-3
+    format('%7.2f us', t * 1e6)
+  else
+    format('%7.2f ms', t * 1e3)
+  end
+end
+
+# Interpolate the interval where the ratio crosses 1, in log space.
+def crossover(points)
+  bracket = points.each_cons(2).find { |(_, r1), (_, r2)| r1 < 1.0 && r2 >= 1.0 }
+  return nil unless bracket
+
+  (n1, r1), (n2, r2) = bracket
+  f = Math.log(r1) / (Math.log(r1) - Math.log(r2))
+  Math.exp(Math.log(n1) + (f * (Math.log(n2) - Math.log(n1))))
+end
+
+# A point is [time with a synchronize per operation, time per operation pipelined]
+def pipe(points, n)
+  v = points[n]
+  v.is_a?(Array) ? v[1] : v
+end
+
+def syncd(points, n)
+  v = points[n]
+  v.is_a?(Array) ? v[0] : nil
+end
+
+summary = []
+
+OPS.each do |op|
+  numo = results[:numo][op[:name]]
+  cumo = results[:cumo][op[:name]]
+  next if numo.empty? && cumo.empty?
+
+  puts "[#{op[:name]}]"
+  puts format('  %12s %11s %11s %10s %13s', 'elements', 'numo', 'cumo', 'numo/cumo', 'cumo per-op')
+
+  ratios = []
+  marked = false
+  SIZES.each do |n|
+    tn = pipe(numo, n)
+    tc = pipe(cumo, n)
+    ratio = (tn && tc) ? tn / tc : nil
+    ratios << [n, ratio] if ratio
+    mark = if ratio && ratio >= 1.0 && !marked
+             marked = true
+             '  <== Cumo wins from here'
+           else
+             ''
+           end
+    next unless tn || tc
+
+    puts format('  %12d %11s %11s %10s %13s%s', n, fmt_time(tn), fmt_time(tc),
+                ratio ? format('%.2f', ratio) : '-', fmt_time(syncd(cumo, n)), mark)
+  end
+
+  cross = crossover(ratios)
+  small = cumo.keys.min
+  fixed = small ? pipe(cumo, small) : nil
+  fixed_sync = small ? syncd(cumo, small) : nil
+  best = ratios.map(&:last).compact.max
+  summary << [op[:name], cross, fixed, fixed_sync, best]
+  puts
+end
+
+puts '== summary'
+puts format('  %-16s %14s %12s %12s %10s',
+            'operation', 'crossover', 'cumo fixed', 'with sync', 'best ratio')
+summary.each do |name, cross, fixed, fixed_sync, best|
+  puts format('  %-16s %14s %12s %12s %10s',
+              name,
+              cross ? format('~%d', cross.round) : '-',
+              fixed ? format('%.2f us', fixed * 1e6) : '-',
+              fixed_sync ? format('%.2f us', fixed_sync * 1e6) : '-',
+              best ? format('%.1fx', best) : '-')
+end
+
+puts
+puts '  The cumo column and the crossover are the pipelined numbers.'
+puts '  "cumo fixed" is the per-operation cost at the smallest size, which is'
+puts '  the floor of launch + Ruby + ndloop. "with sync" waits for each'
+puts '  operation to finish; the difference is not what a synchronize costs but'
+puts '  what it prevents, namely overlapping the next launch with this one.'
+puts '  The crossover is where the CPU takes longer than that fixed cost, so it'
+puts '  moves left as the fixed cost falls or the work per operation grows.'
+puts '  An operation with no crossover had one side ahead over the whole range.'
+puts
+if results[:numo].key?('dot (GEMM)') && !defined?(Numo::Linalg)
+  puts '  Note: without numo-linalg, dot runs against the built-in Numo'
+  puts '  implementation. With BLAS its crossover moves far to the right.'
+end
+puts '  Note: Numo swings several-fold with the history of the process, since'
+puts '  above glibc\'s 128 KB mmap threshold every allocation takes page faults.'
+puts '  Read the crossover as an order of magnitude, and split the processes'
+puts '  with ONLY and MERGE when the number has to be tight.'