carray 3.0.0 → 3.0.2

data/lib/carray/methods/mask_duplicates.rb

@@ -1,3 +1,5 @@
+require "carray/methods/discovery_along"
+
 class CArray
 
   # @overload mask_duplicates(axis: nil)
@@ -23,14 +25,46 @@ class CArray
   #     `nil` uses flatten order.
   #   @return [CArray] shape-preserving copy of `self` with
   #     duplicates masked.
-  def mask_duplicates (axis: nil)
+  # @overload mask_duplicates(along: k)
+  #   Returns a shape-preserving copy of `self` with every cell of a
+  #   duplicated **sub-array** masked, comparing whole sub-arrays rather
+  #   than cells: `along: k` names the axis whose index enumerates them,
+  #   so `z.mask_duplicates(along: 0)` masks each repeated row of a 2-D
+  #   array and keeps the first occurrence.
+  #
+  #   Note the contrast with `axis:`, which names the axis a *fiber runs
+  #   along* and marks repeated values inside each fiber. The two cannot
+  #   be given together.
+  #
+  #   A sub-array holding a masked cell does not participate: it is
+  #   neither judged a duplicate nor able to make a later one, and its
+  #   cells keep the mask they came with. `object` arrays are refused,
+  #   because their cells hold Ruby references.
+  #
+  #   @param along [Integer] axis whose index enumerates the sub-arrays.
+  #   @return [CArray] shape-preserving copy of `self` with duplicated
+  #     sub-arrays masked.
+  def mask_duplicates (axis: nil, along: nil)
+    reject_axis_with_along(axis, along, "mask_duplicates")
+    if along
+      keys = fibers_as_cells(along, "mask_duplicates")
+      #  A sub-array that did not participate (it held a masked cell) is
+      #  masked in `keys` already; only the ones that did and repeated
+      #  are duplicates here.
+      repeated = keys.mask_duplicates.is_masked & keys.is_not_masked
+      args = [:_] * ndim
+      args[normalize_axis(along, "mask_duplicates")] = nil
+      spread = CArray.boolean(*shape)
+      spread[] = repeated[*args]
+      return mask_where(spread)
+    end
     dup =
       if axis.nil?
         # One seen-set over the flattened array, then restore shape.
         flatten.send(:__mask_duplicates__, 0).reshape(*shape)
       else
         # Per-fiber single-pass seen-set hash (C __mask_duplicates__): one lane
-        # per dtype family (integer widen, float bitwise key with NaN collapse,
+        # per data type family (integer widen, float bitwise key with NaN collapse,
         # object rb_hash + rb_eql, fixlen byte-hash + memcmp, boolean via the
         # uint8 lane). O(distinct) memory, no sort/gather/scatter buffers.
         __mask_duplicates__(normalize_axis(axis, "mask_duplicates"))

data/lib/carray/methods/meshgrid.rb

@@ -17,10 +17,9 @@ class CArray
   #   input order in both modes.
   #
   #   When `copy` is true (default) each output is a materialised
-  #   CArray; when false, view chains (CARepeat / CAUnboundRepeat)
-  #   are returned. When `sparse` is true the outputs are
-  #   CAUnboundRepeat views that broadcast on demand, saving memory
-  #   for large grids.
+  #   CArray; when false, a view is returned. When `sparse` is true
+  #   each output keeps a size-1 axis wherever the full grid would
+  #   repeat, and broadcasts on demand, saving memory for large grids.
   #
   #   If a block is given, yields the resulting arrays as splat
   #   arguments and returns the block's value.
@@ -77,7 +76,7 @@ class CArray
     list = axes.map.with_index do |axis, k|
       d = dest[k]
       idx = if sparse
-              Array.new(ndim) { |i| i == d ? nil : :* }
+              Array.new(ndim) { |i| i == d ? nil : :_ }
             else
               out_shape.dup.tap { |s| s[d] = :% }
             end

data/lib/carray/methods/mode.rb

@@ -33,7 +33,7 @@ class CArray
   #     the whole array.
   #   @return [CArray] boolean CArray of `self.shape`.
   def is_mode (axis: nil)
-    # Per-fiber two-pass frequency table (C __is_mode__), one lane per dtype
+    # Per-fiber two-pass frequency table (C __is_mode__), one lane per data type
     # family (numeric widen / NaN collapse, object rb_hash + rb_eql, fixlen
     # byte-hash + memcmp). Ties are all marked; masked cells stay false.
     if axis.nil?
@@ -112,7 +112,7 @@ class CArray
 
   private
 
-  # Flat mode: the distinct modal values ascending, 1-D CArray of self's dtype.
+  # Flat mode: the distinct modal values ascending, 1-D CArray of self's data type.
   # The single source of what counts as a mode (per-axis reuses it per fiber).
   # The distinct values with the maximum count, read from the frequency table
   # (value_counts, which covers numeric / object / fixlen), then sorted

data/lib/carray/methods/nunique.rb

@@ -1,3 +1,5 @@
+require "carray/methods/discovery_along"
+
 class CArray
 
   # @overload nunique(axis: nil, keep_axis: false)
@@ -29,8 +31,27 @@ class CArray
   #     axis as a length-1 axis instead of dropping it.
   #   @return [Integer, CArray] Integer for `axis: nil`, otherwise a
   #     reduced `CA_INT64` CArray.
-  def nunique (axis: nil, keep_axis: false)
-    # Per-fiber single-pass seen-set hash (C __nunique__), one lane per dtype
+  # @overload nunique(along: k)
+  #   Returns how many distinct **sub-arrays** `self` holds, comparing
+  #   whole sub-arrays rather than cells: `along: k` names the axis
+  #   whose index enumerates them, so `z.nunique(along: 0)` counts the
+  #   distinct rows of a 2-D array. This is `len(np.unique(z, axis=k))`.
+  #
+  #   Note the contrast with `axis:`, which names the axis a *fiber runs
+  #   along* and counts the distinct values inside each fiber -- one
+  #   count per fiber, not one count for the array. The two cannot be
+  #   given together.
+  #
+  #   Sub-arrays holding a masked cell do not participate and are not
+  #   counted. `object` arrays are refused, because their cells hold
+  #   Ruby references.
+  #
+  #   @param along [Integer] axis whose index enumerates the sub-arrays.
+  #   @return [Integer] the number of distinct sub-arrays.
+  def nunique (axis: nil, keep_axis: false, along: nil)
+    reject_axis_with_along(axis, along, "nunique")
+    return fibers_as_cells(along, "nunique").nunique if along
+    # Per-fiber single-pass seen-set hash (C __nunique__), one lane per data type
     # family (numeric widen / NaN collapse, object rb_hash + rb_eql, fixlen
     # byte-hash + memcmp). Masked cells are skipped; the accumulator is a no-op
     # (the distinct count is the interned-key count).

data/lib/carray/methods/repeat.rb

@@ -0,0 +1,110 @@
+class CArray
+
+  # @overload repeat(count, axis: nil)
+  #   @overload repeat(counts, axis: nil)
+  #   Returns each element (or each sub-array) of `self` laid down
+  #   `count` times in place, one after another.
+  #
+  #   With an Integer, every element is repeated the same number of
+  #   times. With an array of counts -- one per element, or one per
+  #   sub-array when `axis:` is given -- each is repeated its own number
+  #   of times, and a count of 0 drops that one:
+  #
+  #     v = CA_INT([10, 20, 30])
+  #     v.repeat(2)              #  => [ 10, 10, 20, 20, 30, 30 ]
+  #     v.repeat([3, 1, 2])      #  => [ 10, 10, 10, 20, 30, 30 ]
+  #     v.repeat([2, 0, 1])      #  => [ 10, 10, 30 ]
+  #
+  #   This is `np.repeat`, and it is not {#tile}: `repeat` puts the
+  #   copies of one element next to each other, `tile` lays the whole
+  #   array down again -- `v.tile(2)` is `[10, 20, 30, 10, 20, 30]`.
+  #
+  #   `axis: k` repeats the sub-arrays enumerated by axis `k` rather
+  #   than the cells, so a 2-D array repeats whole rows and the result
+  #   keeps its shape apart from that axis:
+  #
+  #     t = CA_INT([[0, 1], [2, 3], [4, 5]])
+  #     t.repeat([2, 1, 1], axis: 0)
+  #     #  => [ [ 0, 1 ],
+  #     #       [ 0, 1 ],
+  #     #       [ 2, 3 ],
+  #     #       [ 4, 5 ] ]
+  #
+  #   Without `axis:` a multi-dimensional receiver is taken in flatten
+  #   (row-major) order and the result is 1-D, as `np.repeat` does.
+  #
+  #   The result is a **view** of `self` -- the same element named as
+  #   many times as it was repeated -- so nothing is copied and writing
+  #   through it reaches `self`, at every position that names the cell
+  #   written. Take a `copy` when that is not wanted.
+  #
+  #   Counts must be non-negative, and there must be exactly as many as
+  #   there are elements (or sub-arrays along `axis:`). A masked count
+  #   is refused: it names no number of repetitions.
+  #
+  #   @param count [Integer, CArray, Array] how many times to repeat --
+  #     one number for all, or one per element / sub-array.
+  #   @param axis [Integer, nil] axis whose index enumerates the
+  #     sub-arrays to repeat; `nil` repeats cells in flatten order.
+  #   @return [CArray] the repeated elements, as a view of `self`.
+  def repeat (count, axis: nil)
+    along = axis.nil? ? nil : normalize_axis(axis, "repeat")
+    width = along ? shape[along] : elements
+
+    counts =
+      case count
+      when Integer
+        if count < 0
+          raise ArgumentError, "repeat: count must not be negative (got #{count})"
+        end
+        CArray.int64(width).fill(count)
+      else
+        given = count.to_ca.int64
+        unless given.elements == width
+          raise ArgumentError,
+                "repeat: #{given.elements} counts for #{width} " \
+                "#{along ? "sub-arrays along axis #{along}" : 'elements'}"
+        end
+        if given.has_mask? and given.count_masked > 0
+          raise ArgumentError,
+                "repeat: a masked count names no number of repetitions"
+        end
+        if given.lt(0).any
+          raise ArgumentError, "repeat: counts must not be negative"
+        end
+        given.flatten
+      end
+
+    source = along ? self : (ndim > 1 ? flatten : self)
+    source[*gather_args(repeat_index(counts), along)]
+  end
+
+  #  The source index of every position in the result: element i appears
+  #  at the `counts[i]` positions starting at the exclusive prefix sum.
+  #
+  #  Marking those starts with +1 and running a cumulative sum turns the
+  #  marks back into indices, and does the right thing with a zero
+  #  count for free -- two elements then share a start, that position
+  #  carries 2, and the sum steps over the one that was asked for zero
+  #  times.
+  private def repeat_index (counts)
+    total = counts.sum.to_i
+    return CArray.int64(0) if total.zero?
+    starts = counts.cumsum.int64 - counts
+    marks  = CArray.int64(total)
+    #  A trailing zero count starts one past the end; it marks nothing,
+    #  which is what a zero count means.
+    marks.scatter_add!(starts[starts.lt(total)], 1)
+    marks.cumsum.int64 - 1
+  end
+
+  #  One index argument per axis: the gathered index on the axis being
+  #  repeated, whole axes everywhere else.
+  private def gather_args (index, along)
+    return [index] unless along
+    args = [nil] * ndim
+    args[along] = index
+    args
+  end
+
+end

data/lib/carray/methods/snap.rb

@@ -7,7 +7,7 @@ class CArray
   #   matching `CArray#round`; `:floor` snaps toward `-inf`, `:ceil`
   #   toward `+inf`).
   #
-  #   The output has the same dtype as `self` (integer input is coerced
+  #   The output has the same data type as `self` (integer input is coerced
   #   to float internally when `step` / `offset` are floats, following
   #   normal arithmetic promotion). NaN / Inf are preserved as a mask
   #   on the output; the rounding kernels map NaN to 0.0, which would
@@ -45,7 +45,12 @@ class CArray
     # Detect NaN / Inf before rounding (which maps NaN -> 0.0 silently).
     invalid_mask = scaled.float? ? scaled.is_invalid : nil
 
-    out = scaled.send(direction) * step + offset
+    snapped = case direction
+              when :round then scaled.round
+              when :floor then scaled.floor
+              when :ceil  then scaled.ceil
+              end
+    out = snapped * step + offset
 
     if invalid_mask && invalid_mask.count(true) > 0
       out.mask = out.has_mask? ? (out.mask | invalid_mask) : invalid_mask

data/lib/carray/methods/unique.rb

@@ -1,3 +1,5 @@
+require "carray/methods/discovery_along"
+
 class CArray
 
   # @overload unique(sort: false)
@@ -16,7 +18,7 @@ class CArray
   #   Masked cells do not participate and never appear in the result;
   #   an all-masked array yields an empty CArray.
   #
-  #   Distinctness follows `==` for numeric dtypes, with two float
+  #   Distinctness follows `==` for numeric data types, with two float
   #   special cases so the result matches value-based expectations:
   #   all NaN collapse to a single distinct value (rather than one per
   #   cell) and -0.0 / +0.0 are the same value. The value kept for
@@ -32,10 +34,48 @@ class CArray
   #   its own unit: the distinct values are values, so the array comes back
   #   as itself rather than as raw storage ticks.
   #
-  #   @return [CArray] 1-D CArray of the distinct values, same dtype
+  #   @return [CArray] 1-D CArray of the distinct values, same data type
   #     as `self`.
-  def unique (sort: false)
-    # Single-pass seen-set hash (C __unique_flat__), one lane per dtype family:
+  #
+  # @overload unique(along: k)
+  #   Returns the distinct **sub-arrays** of `self`, comparing whole
+  #   sub-arrays rather than cells: `along: k` names the axis whose
+  #   index enumerates them, so `z.unique(along: 0)` gives the distinct
+  #   rows of a 2-D array, in first-appearance order. This is
+  #   `np.unique(z, axis=k)`.
+  #
+  #   Note the contrast with `axis:` on {#nunique} and
+  #   {#mask_duplicates}, which names the axis a *fiber runs along* and
+  #   asks about the values inside each fiber. The two cannot be given
+  #   together.
+  #
+  #   Distinctness is the family's, widened from a cell to a sub-array:
+  #   two sub-arrays are the same when every cell is, with all NaN one
+  #   value and -0.0 == +0.0. A sub-array holding a masked cell does not
+  #   participate and never appears in the result.
+  #
+  #   The result is a **view** of `self` -- the surviving sub-arrays,
+  #   not copies of them -- so writing through it reaches `self`. Take a
+  #   `copy` when that is not wanted. `sort:` is not available here:
+  #   sub-arrays have no order to sort by. `object` arrays are refused,
+  #   because their cells hold Ruby references.
+  #
+  #   @param along [Integer] axis whose index enumerates the sub-arrays.
+  #   @return [CArray] the distinct sub-arrays, same shape as `self`
+  #     except along `along`.
+  def unique (sort: false, along: nil)
+    if along
+      if sort
+        raise ArgumentError,
+              "unique: sort: is not available with along: -- sub-arrays have " \
+              "no order to sort by; the result is in first-appearance order"
+      end
+      keys = fibers_as_cells(along, "unique")
+      args = [nil] * ndim
+      args[normalize_axis(along, "unique")] = keys.mask_duplicates.is_not_masked
+      return self[*args]
+    end
+    # Single-pass seen-set hash (C __unique_flat__), one lane per data type family:
     # integer widens to a 64-bit key; float uses the bitwise key with all-NaN
     # collapsed and -0.0 / +0.0 normalized; object keys on rb_hash + rb_eql and
     # fixlen on a byte-hash + memcmp, both reproducing Ruby Hash distinctness.

data/lib/carray/methods/value_counts.rb

@@ -3,7 +3,7 @@ class CArray
   # @overload value_counts(sort: false)
   #   Returns `[values, counts]`, the distinct values of `self` paired
   #   with the number of times each occurs. `values` is a 1-D CArray of
-  #   `self`'s dtype; `counts` is a 1-D `CA_INT64` where `counts[i]` is
+  #   `self`'s data type; `counts` is a 1-D `CA_INT64` where `counts[i]` is
   #   the number of occurrences of `values[i]`. This is the frequency-
   #   table member of the value-hash discovery family ({#unique},
   #   {#mask_duplicates}, {#nunique}); like {#unique} it always
@@ -39,7 +39,7 @@ class CArray
       raise ArgumentError, "value_counts: sort must be false, :count, or :value"
     end
     # Single-pass frequency-table hash (C __value_counts_flat__), one lane per
-    # dtype family: integer widens to a 64-bit key; float uses the bitwise key
+    # data type family: integer widens to a 64-bit key; float uses the bitwise key
     # with all NaN collapsed and -0.0 / +0.0 normalized; object keys on rb_hash +
     # rb_eql and fixlen on a byte-hash + memcmp, both reproducing Ruby Hash
     # distinctness. Masked cells are skipped in the kernel.

data/lib/carray/rng.rb

@@ -0,0 +1,86 @@
+class CArray
+
+  # A random number generator with its own state.
+  #
+  # `Rng` rather than `Random`: a `CArray::Random` would shadow `::Random`
+  # for every bare `Random` written inside `class CArray`, and the two mean
+  # different generators -- `random!(rng: Random.new(4))` draws through
+  # Ruby's MT19937 and `random!(rng: CArray::Rng.new(seed: 4))` through the
+  # one below.  Two names that different should not look alike.
+  #
+  # The class itself is defined in ext/carray_random.c, which is where the
+  # state is advanced.  What is added here is the generator's source text,
+  # so that another gem can run the same code rather than a second
+  # implementation of it.
+  class Rng
+
+    # The generators this carray knows, and how many int64 cells each one
+    # keeps its state in.
+    STATE_CELLS = {
+      :xoshiro256pp => 4,
+    }.freeze
+
+    GENERATORS = STATE_CELLS.keys.freeze
+
+    # Where a generator's C lives.  Shipped: the gemspec takes ext/*.h,
+    # and `ext` is a require path, so this resolves in a checkout and in
+    # an installed gem alike -- lib/ and ext/ are siblings in both.
+    SOURCE_FILES = {
+      :xoshiro256pp => File.expand_path("../../ext/ca_rng_xoshiro256pp.h",
+                                        __dir__),
+    }.freeze
+
+    # The C each generator is, as text.
+    #
+    #   CArray::Rng::SOURCE[:xoshiro256pp]   #=> "/* ---- ... */\n..."
+    #
+    # This is the same text the extension compiled -- the file below is
+    # `#include`d by ext/carray_random.c -- which is the point of handing
+    # it out.  A caller that pastes it into a translation unit of its own
+    # gets a generator that continues a sequence this one started, because
+    # it is running the code this one ran and not a copy of it.
+    #
+    # carray-jit is the caller this exists for: a kernel's `random(rng:)`
+    # pastes the text beside the helpers its own compiler emits, so a
+    # kernel draws from the CArray::Rng it was handed.  The text needs
+    # nothing but <stdint.h> and defines only `static inline` functions
+    # under a `ca_` prefix.
+    #
+    # It is read once, when this file is first required.
+    SOURCE = SOURCE_FILES.transform_values { |path|
+      File.read(path, :encoding => "UTF-8")
+    }.freeze
+
+    # What every generator's text needs beside it, and what none of them
+    # owns: turning uniforms into a normal is the same arithmetic whichever
+    # generator the uniforms came from.
+    #
+    # Handed out apart from SOURCE because whoever pastes it pastes it once,
+    # however many generators are drawing.  Folded into each generator's own
+    # text instead, two generators in one translation unit would define it
+    # twice.
+    COMMON_SOURCE = File.read(
+      File.expand_path("../../ext/ca_rng_normal.h", __dir__), :encoding => "UTF-8"
+    ).freeze
+
+    # The functions in SOURCE a caller may reach, by generator and by what
+    # the draw answers: `:random` a double in [0.0, 1.0), `:randomn` a
+    # standard normal, `:bits` the raw word a draw came from.  Each takes the
+    # state and advances it -- `:randomn` by two draws, the other two by one.
+    #
+    # Named here rather than worked out by whoever pastes the text: which
+    # symbols are the entry points is a fact about the generator, and the
+    # generator is CArray's.  These are the three `#random`, `#randomn`
+    # and `#bits` call, so a caller pasting the text draws the sequence
+    # this one draws.
+    DRAW_FUNCTIONS = {
+      :xoshiro256pp => {
+        :random  => "ca_xoshiro256pp_next_real",
+        :randomn => "ca_xoshiro256pp_next_normal",
+        :bits    => "ca_xoshiro256pp_next",
+      }.freeze,
+    }.freeze
+
+  end
+
+end

data/lib/carray/runtime.rb

@@ -87,22 +87,3 @@ class CArray
 
 end
 
-class CAUnboundRepeat
-  # Overrides {CArray#template} for unbound-repeat views.
-  #
-  # The C-level `CArray#template` allocates an entity sized to `self.shape`,
-  # which for a CAUnboundRepeat would include the inflated unbound (`:*`)
-  # axes — semantically wrong (unbound axes are not yet bound to a size)
-  # and a memory bomb on broadcast patterns.  Required for correctness.
-  #
-  # This override allocates at the **parent's compact shape** instead, then
-  # rewraps the result with the same `spec` so the returned view preserves
-  # the unbound broadcast pattern.
-  #
-  # @param argv [Array] forwarded to {CArray#template} (data_type, bytes:, ...)
-  # @yield forwarded to {CArray#template}
-  # @return [CAUnboundRepeat] new entity wrapped with the original unbound spec
-  def template (*argv, &block)
-    return parent.template(*argv,&block)[*spec.map{|x| x != :* ? nil : x}]
-  end
-end

data/lib/carray/slab_iterator.rb

@@ -90,22 +90,76 @@ class CASlabIterator < CAIterator
   # A per-slab reduction that folds each slab to one value is exactly the core
   # per-axis reduction over the slab axes, so every reduction is a direct
   # delegation to `reference.<op>(axis: slab_axes)`. This inherits the core
-  # dtype, mask, empty/all-masked (identity vs UNDEF) and epsilon-close
+  # data type, mask, empty/all-masked (identity vs UNDEF) and epsilon-close
   # contracts unchanged -- there is no separate slab reduction kernel. (Unlike
   # the map / reduce block surface, these are mask-aware: they route through the
   # core reduction, which handles masked sources.)
 
-  # @overload sum
-  #   Per-slab sum, delegating to `reference.sum(axis: slab_axes)`.
-  #   @return [CArray] one value per slab (shape = self.dim minus the slab axes)
-  # The rest are analogous: prod / mean / min / max, sample and population
-  # variance / stddev, all / any, fused minmax ([min, max] pair), the axis-local
-  # position min_index / max_index (index within the slab axes), and the flat
-  # source address min_addr / max_addr (which source cell holds the extremum).
-  [:sum, :prod, :mean, :min, :max, :variance, :stddev, :all, :any,
+  # Each reduction below delegates to `reference.<op>(axis: slab_axes)`, so it
+  # inherits the core data type, mask, empty / all-masked and epsilon-close
+  # contracts unchanged.  See {CAIterator} for what each one computes.
+  #
+  # @!method sum
+  #   Per-slab sum.
+  #   @return [CArray] one value per slab (shape = {#shape}).
+  # @!method accumulate
+  #   Per-slab sum kept in the source's own data type, wrapping at its width,
+  #   as the core `accumulate` does -- `sum` answers in the type the core
+  #   promotes to (float64 for integers).
+  #   @return [CArray] one value per slab
+  # @!method prod
+  #   Per-slab product.
+  #   @return [CArray] one value per slab
+  # @!method mean
+  #   Per-slab arithmetic mean.
+  #   @return [CArray] one value per slab
+  # @!method min
+  #   Per-slab minimum.
+  #   @return [CArray] one value per slab
+  # @!method max
+  #   Per-slab maximum.
+  #   @return [CArray] one value per slab
+  # @!method variance
+  #   Per-slab sample variance (divisor `n - 1`).
+  #   @return [CArray] one value per slab
+  # @!method stddev
+  #   Per-slab sample standard deviation (divisor `n - 1`).
+  #   @return [CArray] one value per slab
+  # @!method variancep
+  #   Per-slab population variance (divisor `n`).
+  #   @return [CArray] one value per slab
+  # @!method stddevp
+  #   Per-slab population standard deviation (divisor `n`).
+  #   @return [CArray] one value per slab
+  # @!method all
+  #   Whether every cell of each slab is true.
+  #   @return [CArray] `:boolean`, one value per slab
+  # @!method any
+  #   Whether any cell of each slab is true.
+  #   @return [CArray] `:boolean`, one value per slab
+  # @!method minmax
+  #   Per-slab minimum and maximum, found in one pass.
+  #   @return [Array<CArray>] the pair `[min, max]`
+  # @!method min_index
+  #   Per-slab position of the minimum, local to the slab axes.
+  #   @return [CArray] one index per slab
+  # @!method max_index
+  #   Per-slab position of the maximum, local to the slab axes.
+  #   @return [CArray] one index per slab
+  # @!method min_addr
+  #   Per-slab flat source address of the minimum -- which source cell holds it.
+  #   @return [CArray] one flat address per slab
+  # @!method max_addr
+  #   Per-slab flat source address of the maximum.
+  #   @return [CArray] one flat address per slab
+  [:sum, :accumulate, :prod, :mean, :min, :max, :variance, :stddev, :all, :any,
    :variancep, :stddevp, :minmax, :min_index, :max_index,
    :min_addr, :max_addr].each do |op|
-    define_method(op) { @reference.send(op, axis: @slab_axes) }
+    class_eval <<~RUBY, __FILE__, __LINE__ + 1
+      def #{op}
+        @reference.#{op}(axis: @slab_axes)
+      end
+    RUBY
   end
 
   # @overload count(v = <none>)
@@ -243,7 +297,7 @@ class CASlabIterator < CAIterator
   #
   # A per-slab running accumulation along the slab axis is exactly the core
   # per-axis cumulative over that axis, so every scan delegates to
-  # `reference.<op>(axis: slab_axis)`, inheriting the core dtype / mask (masked
+  # `reference.<op>(axis: slab_axis)`, inheriting the core data type / mask (masked
   # cells hold the running total, output unmasked) contracts unchanged. Each
   # cell is in exactly one slab (a partition), so the running value is
   # well-defined; the surface is uniform with the family even though it
@@ -251,23 +305,27 @@ class CASlabIterator < CAIterator
   # multi-axis running accumulation is ambiguous), so a multi-axis slab raises --
   # scan one axis at a time, like the order surface.
 
-  # @overload cumsum
+  # @!method cumsum
   #   Per-slab inclusive running sum (float64), reference-shaped.
   #   @return [CArray]
-  # @overload cumprod
+  # @!method cumprod
   #   Per-slab inclusive running product (float64), reference-shaped.
   #   @return [CArray]
-  # @overload cummax
-  #   Per-slab inclusive running maximum (reference dtype), reference-shaped.
+  # @!method cummax
+  #   Per-slab inclusive running maximum (reference data type), reference-shaped.
   #   @return [CArray]
-  # @overload cummin
-  #   Per-slab inclusive running minimum (reference dtype), reference-shaped.
+  # @!method cummin
+  #   Per-slab inclusive running minimum (reference data type), reference-shaped.
   #   @return [CArray]
-  # @overload cumcount
+  # @!method cumcount
   #   Per-slab running count of present cells (int64), reference-shaped.
   #   @return [CArray]
   [:cumsum, :cumprod, :cummax, :cummin, :cumcount].each do |op|
-    define_method(op) { @reference.send(op, axis: single_scan_axis(op)) }
+    class_eval <<~RUBY, __FILE__, __LINE__ + 1
+      def #{op}
+        @reference.#{op}(axis: single_scan_axis(:#{op}))
+      end
+    RUBY
   end
 
   private

data/lib/carray/string_operation_extension.rb

@@ -26,18 +26,18 @@ class CArray
   #   Boolean result  -> :boolean CArray
   module StringOperationMixin
 
-    # Per-cell map through the Face's scalar fetch.  `dtype` nil returns a
-    # CAString (string results); an explicit dtype returns a plain typed array
+    # Per-cell map through the Face's scalar fetch.  A nil `data_type` returns a
+    # CAString (string results); an explicit one returns a plain typed array
     # (integer / boolean results).  Shape and mask are carried.
-    def string_map (dtype = nil) # :nodoc:
-      out = dtype ? template(dtype) : CArray.object(*shape)
+    def string_map (data_type = nil) # :nodoc:
+      out = data_type ? template(data_type) : CArray.object(*shape)
       if has_mask?
         m = is_masked
         elements.times { |i| out[i] = (m[i] ? UNDEF : yield(self[i])) }
       else
         elements.times { |i| out[i] = yield(self[i]) }
       end
-      dtype ? out : CAString.wrap(out)
+      data_type ? out : CAString.wrap(out)
     end
     private :string_map
 
@@ -229,7 +229,11 @@ class CArray
       else
         values = Array.new(elements) { |i| self[i] }
       end
-      CArray.const_string(values, encoding: encoding)
+      out = CArray.const_string(values, encoding: encoding)
+      # The builder takes a flat list, so give the shape back -- as
+      # to_fixlen_string above already does.  Without this an N-D column
+      # came back 1-D.
+      ndim > 1 ? out.reshape(*shape) : out
     end
 
     # In-place transforms, mixed into the mutable Faces only (CAString /