carray 3.0.0 → 3.0.2

data/lib/carray/fusion.rb

@@ -0,0 +1,218 @@
+# ---------------------------------------------------------------------------
+#  Turning a lazy expression into a plan a compiler can read.
+#
+#  A lazy view is already a typed, closed expression graph, and the kernels
+#  already carry the C that computes each operation (CArray.__kernel_body__).
+#  What is missing between them is the reading: which operation each node is,
+#  what its mask does, and where the leaves are.  That is what a plan holds.
+#
+#  Nothing here compiles anything.  A plan is plain data, and CArray itself
+#  never needs one -- it can always walk the view.  What a plan is for is a
+#  second evaluator: hand it to one, and the answer must be the same.
+# ---------------------------------------------------------------------------
+
+class CArray
+
+  module Fusion
+
+    # One value per node, in evaluation order; the last is the result.
+    #
+    #   Op    an operation, reading the nodes named in `args`
+    #   Leaf  an array, the `index`-th of plan.leaves
+    #   Const a scalar written into the expression
+    Op    = Struct.new(:kind, :name, :data_type, :args, :body, :mask, :trapping)
+    Leaf  = Struct.new(:index, :data_type, :masked)
+    Const = Struct.new(:value, :data_type)
+
+    Plan  = Struct.new(:nodes, :leaves, :data_type, :dim, :masked, :signature)
+
+    LAZY_CLASSES = [CAMonOp, CABinOp, CATriOp, CAMonCmp, CABinCmp, CALazyMarker]
+
+    # A lazy node names its operation by an id and the kernels name it by a
+    # symbol.  These are the same operations, spelled the way each side
+    # spells them; the rest are spelled alike.
+    BINOP_NAMES = {
+      :+  => :add,        :-  => :sub,        :*  => :mul,
+      :/  => :div,        :** => :power,      :%  => :mod,
+      :&  => :bit_and_i,  :|  => :bit_or_i,   :^  => :bit_xor_i,
+      :<< => :bit_lshift, :>> => :bit_rshift,
+    }.freeze
+    TRIOP_NAMES = { :__clip_ki__ => :clip }.freeze
+
+    MONOP_BY_ID = CArray::LAZY_MONOP_OP_IDS.invert.freeze
+    BINOP_BY_ID = CArray::LAZY_BINOP_OP_IDS.invert.freeze
+    TRIOP_BY_ID = CArray::LAZY_TRIOP_OP_IDS.invert.freeze
+
+    # Integer division and its relatives raise on a zero divisor, so a cell
+    # the mask excludes must not be computed at all -- the divisor there is
+    # nobody's business (ca_binop_dispatch.c).
+    TRAPPING = %i[div mod quo_i fmod].freeze
+    INTEGERS = %i[int8 int16 int32 int64 uint8 uint16 uint32 uint64].freeze
+
+    class Refused < StandardError; end
+
+    # ---- who computes a plan --------------------------------------------
+    #
+    # CArray can always walk the expression, so nothing has to be registered
+    # and nothing changes when nothing is.  What a registered evaluator adds
+    # is a second way to arrive at the same answer; it is asked, and it may
+    # decline.  The dispatch point stays on CArray's side, which is what
+    # keeps the threshold below a decision about CArray's own walk rather
+    # than one that moves with whatever is installed.
+    #
+    # The evaluator itself is held by CArray (see carray/lazy.rb), so that
+    # materialising an expression need not reach for this file at all until
+    # something has been registered.
+
+    # Reaching a compiled kernel costs about the same whatever the array's
+    # size, and what it buys is the passes the walk would make.  Below this
+    # the walk is the faster answer.  The crossing moves with how wide the
+    # expression is -- measured, thirty thousand cells at one operation, six
+    # thousand at six -- and this brackets those: a one-operation expression
+    # loses a couple of microseconds here, a six-operation one wins ten.
+    THRESHOLD = 10_000
+
+    # Returns the array, or nil where nothing computed it.
+    def self.evaluate (view)
+      return nil unless askable?(view)
+      out = CArray.__alloc_uninit__(view.data_type, view.dim)
+      evaluate_into(view, out) ? out : nil
+    end
+
+    # Fills an array the caller already has.  Called from the store as well,
+    # where making one and copying it over would be most of the work.
+    # Returns true when something computed it.
+    def self.evaluate_into (view, out)
+      evaluator = CArray.expression_evaluator or return false
+      return false unless askable?(view)
+      plan = plan(view) or return false
+      # A marker over an array, or anything else with nothing to compute,
+      # is not worth handing over.
+      return false unless plan.nodes.any? { |n| n.is_a?(Op) }
+      out.mask = 0 if plan.masked && ! out.has_mask?
+      evaluator.call(plan, out) ? true : false
+    rescue StandardError => error
+      CArray.expression_evaluator = nil
+      warn "CArray: the registered expression evaluator raised " \
+           "(#{error.class}: #{error.message}); expressions will be walked " \
+           "from here on"
+      false
+    end
+
+    def self.askable? (view)
+      ! CArray.expression_evaluator.nil? && view.elements >= THRESHOLD
+    end
+
+    # Returns a Plan, or nil where the expression holds something a plan
+    # cannot describe.  Refusing is ordinary: the caller walks instead.
+    def self.plan (view)
+      build(view)
+    rescue Refused
+      nil
+    end
+
+    def self.build (view)
+      raise Refused, "not a lazy expression" unless lazy?(view)
+      w = Walk.new
+      w.visit(view)
+      Plan.new(w.nodes, w.leaves, view.data_type, view.dim,
+               w.leaves.any? { |a| a.has_mask? }, w.signature)
+    end
+
+    def self.lazy? (x)
+      LAZY_CLASSES.any? { |k| x.is_a?(k) }
+    end
+
+    # ---- the walk -------------------------------------------------------
+
+    class Walk
+      attr_reader :nodes, :leaves, :signature
+
+      def initialize
+        @nodes = []
+        @leaves = []
+        @seen = {}
+        @signature = +""
+      end
+
+      def visit (n)
+        @seen[n.object_id] ||= build(n)
+      end
+
+      private
+
+      def build (n)
+        case n
+        when CALazyMarker then visit(n.parent)
+        when CAMonOp      then unary(n)
+        when CABinOp      then binary(n)
+        when CATriOp      then ternary(n)
+        when CScalar      then constant(n)
+        when CArray       then leaf(n)
+        else raise Refused, "#{n.class} in an expression"
+        end
+      end
+
+      def unary (n)
+        name = spell(MONOP_BY_ID, n.__op_id__, {})
+        args = [visit(n.parent)]
+        # A view over one array is masked exactly where that array is
+        # (ca_obj_monop.c).
+        op(:monop, name, n.data_type, args, :pass)
+      end
+
+      def binary (n)
+        name = spell(BINOP_BY_ID, n.__op_id__, BINOP_NAMES)
+        args = [visit(n.parent), visit(n.__binop_right__)]
+        # Boolean `&` and `|` are three-valued: a masked cell whose known
+        # side settles the answer comes back unmasked (ca_obj_binop.c).
+        rule = if n.data_type == :boolean && name == :bit_or_i  then :kleene_or
+               elsif n.data_type == :boolean && name == :bit_and_i then :kleene_and
+               else :union
+               end
+        op(:binop, name, n.data_type, args, rule)
+      end
+
+      def ternary (n)
+        name = spell(TRIOP_BY_ID, n.__op_id__, TRIOP_NAMES)
+        args = [visit(n.parent), visit(n.__triop_op2__), visit(n.__triop_op3__)]
+        op(:triop, name, n.data_type, args, :union)
+      end
+
+      def op (kind, name, type, args, mask)
+        body = CArray.__kernel_body__(kind, name, type) or
+          raise Refused, "#{kind} #{name} has no body at #{type}"
+        note(kind.to_s[0], name, type)
+        push Op.new(kind, name, type, args, body, mask,
+                    TRAPPING.include?(name) && INTEGERS.include?(type))
+      end
+
+      def leaf (n)
+        note("a", n.data_type, n.has_mask? ? 1 : 0)
+        @leaves << n
+        push Leaf.new(@leaves.size - 1, n.data_type, n.has_mask?)
+      end
+
+      def constant (n)
+        note("k", n[0], n.data_type)
+        push Const.new(n[0], n.data_type)
+      end
+
+      def push (node)
+        @nodes << node
+        @nodes.size - 1
+      end
+
+      def spell (table, id, renames)
+        ruby = table[id] or raise Refused, "operation id #{id}"
+        renames.fetch(ruby, ruby)
+      end
+
+      # Two expressions of the same shape compute alike, whatever arrays
+      # they are over, so a consumer can keep one compiled kernel for both.
+      def note (*parts)
+        @signature << parts.join(":") << ";"
+      end
+    end
+  end
+end

data/lib/carray/histogram.rb

@@ -94,8 +94,8 @@
 #  Each sample contributes `w[i]` instead of 1 to its target cell.
 #
 #  * **weights.shape** = chunk.shape minus the channel axis (= fiber + (A,)).
-#  * **dtype** is locked at construction (= the entry method's `weights:` kwarg
-#    fixes weighted vs unweighted; subsequent adds must match).  Counts dtype:
+#  * **The data type** is locked at construction (= the entry method's `weights:` kwarg
+#    fixes weighted vs unweighted; subsequent adds must match).  Counts type:
 #    int64 unweighted, float64 weighted.  Weighted counts are always float64:
 #    the fused scatter kernel requires float64 weights, so integer weights are
 #    taken as float64 (= integer weighted counts are not supported).
@@ -118,7 +118,7 @@
 #  ### Composition
 #
 #  `h1 + h2` returns a new Histogram with cells summed elementwise.  Both
-#  operands must agree on edges / fiber_shape / include_max / weighted dtype
+#  operands must agree on edges / fiber_shape / include_max / weighted data type
 #  (= the structure-level semantic guard); cells themselves are just
 #  integer / float tallies.  See the `+` method.
 #
@@ -135,7 +135,7 @@ class CArray
   # {BincountND} instead.
   class Histogram
 
-    # @overload initialize(edges:, fiber_shape: [], include_max: false, weights_dtype: nil)
+    # @overload initialize(edges:, fiber_shape: [], include_max: false, weights_data_type: nil)
     #   Allocates a new histogram accumulator.
     #   @param edges [Array<CArray, Array<Numeric>>] one edges array
     #     per histogram dimension; each must be 1-D sorted ascending
@@ -145,11 +145,11 @@ class CArray
     #   @param include_max [Boolean, Array<Boolean>] whether values
     #     equal to the last edge fold into the last bin; a scalar
     #     broadcasts across dimensions.
-    #   @param weights_dtype [Symbol, nil] `data_type` of the
+    #   @param weights_data_type [Symbol, nil] `data_type` of the
     #     accumulator when weighted; `nil` for a count-only
     #     accumulator (int64 counts).
     #   @return [Histogram]
-    def initialize (edges:, fiber_shape: [], include_max: false, weights_dtype: nil)
+    def initialize (edges:, fiber_shape: [], include_max: false, weights_data_type: nil)
       @edges_list = edges.map { |e| CArray.wrap_readonly(e, :float64) }
       raise ArgumentError, "edges must be a non-empty list" if @edges_list.empty?
       @edges_list.each_with_index do |e, k|
@@ -166,11 +166,11 @@ class CArray
                      else
                        [!!include_max] * @m
                      end
-      @weighted = !weights_dtype.nil?
-      @counts_dtype = @weighted ? weights_dtype : :int64
+      @weighted = !weights_data_type.nil?
+      @counts_data_type = @weighted ? weights_data_type : :int64
       ext_dims = @n_list.map { |n| n + 2 }
       ext_shape = @fiber_shape + ext_dims
-      @full_counts = CArray.public_send(@counts_dtype, *ext_shape).fill(0)
+      @full_counts = CArray.public_send(@counts_data_type, *ext_shape).fill(0)
       @sample_axis  = nil
       @channel_axis = nil
     end
@@ -321,7 +321,7 @@ class CArray
 
       if weights
         raise ArgumentError, "weights given but accumulator is unweighted" unless @weighted
-        weights = CArray.wrap_readonly(weights, @counts_dtype)
+        weights = CArray.wrap_readonly(weights, @counts_data_type)
         expected_w_shape = chunk.shape.dup
         expected_w_shape.delete_at(channel_ax)
         unless weights.shape == expected_w_shape
@@ -379,7 +379,7 @@ class CArray
                                edges: @edges_list,
                                fiber_shape: @fiber_shape,
                                include_max: @include_max,
-                               weights_dtype: @weighted ? @counts_dtype : nil)
+                               weights_data_type: @weighted ? @counts_data_type : nil)
       rf = result.instance_variable_get(:@full_counts)
       rf[] = @full_counts + other.full_counts
       result.instance_variable_set(:@sample_axis, @sample_axis)
@@ -401,7 +401,7 @@ class CArray
     # arr.shape = fiber_shape + (last M bin axes).
     # Reduce along the last M axes, returns shape fiber_shape (or scalar).
     #
-    # `accumulate` preserves dtype (= int64 stays int64, float64 stays float64),
+    # `accumulate` preserves the data type (= int64 stays int64, float64 stays float64),
     # unlike `sum` which always lifts to float64.  Caveat: int64 overflows at
     # ~9.2e18 (silent wrap); weighted float64 loses precision past 2^53 but
     # does not overflow.  Realistic histograms do not hit these limits.
@@ -497,15 +497,15 @@ class CArray
     [sample_ax, channel_ax].sort.reverse.each { |p| fiber_shape.delete_at(p) }
 
     # Weighted counts are float64-only (the fused scatter kernel requires
-    # float64 weights and float64 counts), so the dtype is fixed here rather
-    # than derived from the weights' own dtype.
-    weights_dtype = (:float64 if weights)
+    # float64 weights and float64 counts), so the type is fixed here rather
+    # than derived from the weights' own type.
+    weights_data_type = (:float64 if weights)
 
     h = Histogram.send(:new,
                       edges: edges,
                       fiber_shape: fiber_shape,
                       include_max: include_max,
-                      weights_dtype: weights_dtype)
+                      weights_data_type: weights_data_type)
     h.add(arr, axis: axis, weights: weights)
     h
   end

data/lib/carray/inspect.rb

@@ -7,7 +7,12 @@ class CArray::Inspector  # :nodoc:
   end
 
   # @!visibility private
-  def inspect_string
+  #
+  #  `abbrev` false renders every element instead of eliding with `...`.
+  #  It is the one difference between #inspect and #inspect_full: the
+  #  header and the layout are the same, so there is one renderer rather
+  #  than two that could drift apart.
+  def inspect_string (abbrev: true)
     if @carray.ndim == 0
       raise "can't inspect CArray of ndim == 0"
     end
@@ -15,7 +20,7 @@ class CArray::Inspector  # :nodoc:
     class_name = get_class_name()
     type_name  = get_type_name()
     shape      = get_shape()
-    data_spec  = get_data_spec(0, Array.new(@carray.ndim){0}, formatter)
+    data_spec  = get_data_spec(0, Array.new(@carray.ndim){0}, formatter, abbrev)
     info_list  = get_info_list()
     output = ["<",
               format("%s.%s(%s)", class_name, type_name, shape.join(",")),
@@ -49,13 +54,7 @@ class CArray::Inspector  # :nodoc:
   end
 
   def get_shape
-    case @carray.obj_type
-    when CA_OBJ_UNBOUND_REPEAT
-      dim = @carray.spec
-    else
-      dim = @carray.shape
-    end
-    return dim
+    return @carray.shape
   end
 
   def get_info_list
@@ -152,7 +151,7 @@ class CArray::Inspector  # :nodoc:
     end
   end
 
-  def get_data_spec (level, idx, formatter)
+  def get_data_spec (level, idx, formatter, abbrev = true)
     io = +"[ "  # mutable buffer; `<<` below appends into it
     ndim = @carray.ndim
     dim  = @carray.shape
@@ -169,7 +168,7 @@ class CArray::Inspector  # :nodoc:
         if i != dim[level] - 1
           io << ", "
         end
-        if io.length > 48 - 2*level
+        if abbrev and io.length > 48 - 2*level
           if i < dim[level] - 1
             io << "..."
             over = true
@@ -188,24 +187,24 @@ class CArray::Inspector  # :nodoc:
       end
     else
       over = false
-      show = [dim[level], 5].min
+      show = abbrev ? [dim[level], 5].min : dim[level]
       show.times do |i|
         idx[level] = i
-        io << get_data_spec(level+1, idx, formatter)
+        io << get_data_spec(level+1, idx, formatter, abbrev)
         if i < show - 1
           io << ",\n" + "  " * (level+1)
         end
-        if i >= 2 and dim[level] > 5
+        if abbrev and i >= 2 and dim[level] > 5
           break
         end
       end
-      if dim[level] > 5
+      if abbrev and dim[level] > 5
         io << "... ... ..."
         over = true
       end
       if over
         idx[level] = dim[level] - 1
-        io << "\n"+ "  " * (level+1) + get_data_spec(level+1, idx, formatter)
+        io << "\n"+ "  " * (level+1) + get_data_spec(level+1, idx, formatter, abbrev)
       end
     end
     io << " ]"
@@ -225,6 +224,34 @@ class CArray
     return CArray::Inspector.new(self).inspect_string
   end
 
+  # @overload inspect_full
+  #   The same description as {#inspect}, with every element rendered
+  #   instead of the `...` preview.
+  #
+  #   `inspect` abbreviates on purpose -- it is what `p`, `irb` and an
+  #   error message call, and a million-cell array has to stay readable
+  #   there. `inspect_full` is for the other moment, when the whole
+  #   array is the thing you came to look at:
+  #
+  #     puts a.inspect_full
+  #
+  #   The header, the layout and the `_` for a masked cell are
+  #   `inspect`'s; only the eliding is dropped, so for an array small
+  #   enough that `inspect` was not abbreviating anything the two give
+  #   the same string.
+  #
+  #   Note that neither of these is `to_s`, which returns the **raw
+  #   bytes** of the storage rather than anything printable.
+  #
+  #   The result is one String holding every element, so it is as large
+  #   as the array is: nothing here is streamed, and a line is as long
+  #   as the last axis makes it.
+  #
+  #   @return [String]
+  def inspect_full
+    return CArray::Inspector.new(self).inspect_string(abbrev: false)
+  end
+
   private
 
   def desc  

data/lib/carray/iterator.rb

@@ -14,8 +14,8 @@
 #  those are NOT part of the common contract because some members legitimately
 #  omit them (a window has no map, a group has no within-piece min_index).
 #
-#  The retired 2.0 generic dispatch (calculate / filter / evaluate over a
-#  kernel_at_addr slot) is preserved at `samples/caiterator/iterator.{rb,c}`.
+#  The 2.0 generic dispatch (calculate / filter / evaluate over a
+#  kernel_at_addr slot) was retired in 3.0.
 #
 # ----------------------------------------------------------------------------
 
@@ -36,8 +36,117 @@ class CAIterator
   # rather than reading as "no such method" -- that gap is the member's to close.
   # A member that genuinely cannot provide one overrides it to raise with its
   # own reason.
+  # The methods below are declared here, so that the family surface is
+  # documented in one place; each member generates its own implementation and
+  # a member for which one is ill-defined overrides it to raise with a reason.
+  # "Piece" is the unit a member iterates over: a slab, a window, a block, a
+  # category, or a group.
+  #
+  # @!method sum
+  #   Returns the sum of each piece.
+  #   @return [CArray] one value per piece, shaped {#shape}.
+  # @!method accumulate
+  #   Returns the sum of each piece kept in the source's own `data_type`,
+  #   wrapping at its width, where {#sum} answers in the type the core
+  #   promotes to (`:float64` for integers).
+  #   @return [CArray] one value per piece.
+  # @!method prod
+  #   Returns the product of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method mean
+  #   Returns the arithmetic mean of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method min
+  #   Returns the smallest value in each piece.
+  #   @return [CArray] one value per piece.
+  # @!method max
+  #   Returns the largest value in each piece.
+  #   @return [CArray] one value per piece.
+  # @!method minmax
+  #   Returns the smallest and largest value of each piece, found in one pass.
+  #   @return [Array<CArray>] the pair `[min, max]`.
+  # @!method variance
+  #   Returns the sample variance (divisor `n - 1`) of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method variancep
+  #   Returns the population variance (divisor `n`) of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method stddev
+  #   Returns the sample standard deviation (divisor `n - 1`) of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method stddevp
+  #   Returns the population standard deviation (divisor `n`) of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method all
+  #   Returns whether every cell of each piece is true.
+  #   @return [CArray] `:boolean`, one value per piece.
+  # @!method any
+  #   Returns whether any cell of each piece is true.
+  #   @return [CArray] `:boolean`, one value per piece.
+  # @!method min_index
+  #   Returns the position of the smallest value **within** each piece.
+  #   @return [CArray] one index per piece.
+  # @!method max_index
+  #   Returns the position of the largest value within each piece.
+  #   @return [CArray] one index per piece.
+  # @!method min_addr
+  #   Returns the flat address **in the source** of the smallest value of each
+  #   piece -- which source cell holds it, rather than where it sits inside the
+  #   piece. Use it to read the same cell out of another source-shaped array.
+  #   @return [CArray] one flat address per piece.
+  # @!method max_addr
+  #   Returns the flat address in the source of the largest value of each piece.
+  #   @return [CArray] one flat address per piece.
+  # @!method wsum(weights)
+  #   Returns the weighted sum of each piece.
+  #   @param weights [CArray] one weight per source cell, shaped like the source.
+  #   @return [CArray] one value per piece.
+  # @!method wmean(weights)
+  #   Returns the weighted mean of each piece.
+  #   @param weights [CArray] one weight per source cell, shaped like the source.
+  #   @return [CArray] one value per piece.
+  # @!method median
+  #   Returns the median of each piece.
+  #   @return [CArray] one value per piece.
+  # @!method percentile(*pers)
+  #   Returns the requested percentile(s) of each piece.
+  #   @param pers [Array<Numeric>] percentile positions in `0..100`.
+  #   @return [CArray, Array<CArray>] one array per requested position; a
+  #     single position returns that array directly.
+  # @!method quantile
+  #   Returns the five-number summary of each piece,
+  #   `[min, Q1, median, Q3, max]`.
+  #   @return [Array<CArray>] five arrays, one per position.
+  # @!method count(value = nil)
+  #   Returns a count per piece: with no argument the cells that are not
+  #   masked, with `UNDEF` the masked cells, and with any other value the
+  #   cells equal to it.
+  #   @param value [Object] value to match, or `UNDEF`.
+  #   @return [CArray] one count per piece.
+  # @!method count_not_masked
+  #   Returns the number of cells of each piece that are not masked.
+  #   @return [CArray] one count per piece.
+  # @!method count_masked
+  #   Returns the number of masked cells of each piece.
+  #   @return [CArray] one count per piece.
+  # @!method elements
+  #   Returns the total number of cells in each piece, masked or not.
+  #   @return [CArray] one count per piece.
+  # @!method each
+  #   Yields each piece in turn as a CArray.
+  #   @yieldparam piece [CArray]
+  #   @return [Enumerator, self] an Enumerator when no block is given.
+  # @!method reduce(init = nil)
+  #   Folds the pieces with a block, for a reduction the family does not name.
+  #   Without `init` the first piece seeds the accumulator.
+  #   @param init [Object] initial accumulator value.
+  #   @yieldparam acc [Object] running accumulator.
+  #   @yieldparam piece [CArray] next piece.
+  #   @yieldreturn [Object] updated accumulator.
+  #   @return [Object] the final accumulator.
   [
-    :sum, :prod, :mean, :min, :max, :variance, :stddev, :all, :any,   # tier 1
+    :sum, :accumulate, :prod, :mean, :min, :max,                      # tier 1
+    :variance, :stddev, :all, :any,
     :variancep, :stddevp, :minmax,                                    # tier 2
     :min_index, :max_index, :min_addr, :max_addr,                     # position
     :wsum, :wmean,                                                    # weighted
@@ -65,6 +174,41 @@ class CAIterator
   # sort_addr.  Un-overridden each is simply unavailable, not a contract
   # violation.  min_addr / max_addr stay required: a single winner address is
   # well-defined even for an overlapping window.
+  # @!method map
+  #   Returns a source-shaped array built by applying the block to each piece
+  #   and scattering the result back into that piece's cells.
+  #   @yieldparam piece [CArray]
+  #   @yieldreturn [CArray, Numeric] replacement values for the piece.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap, where a
+  #     cell would receive more than one value.
+  # @!method sort_addr
+  #   Returns a source-shaped array whose cells, read piece by piece, give the
+  #   flat source addresses that put that piece in ascending order.
+  #   @return [CArray] `:int64`, shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap.
+  # @!method cumsum
+  #   Returns a source-shaped array of the running sum within each piece.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap, where a
+  #     cell has no single running value.
+  # @!method cumprod
+  #   Returns a source-shaped array of the running product within each piece.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap.
+  # @!method cummax
+  #   Returns a source-shaped array of the running maximum within each piece.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap.
+  # @!method cummin
+  #   Returns a source-shaped array of the running minimum within each piece.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap.
+  # @!method cumcount
+  #   Returns a source-shaped array of the running count of cells that are not
+  #   masked within each piece.
+  #   @return [CArray] shaped like the source.
+  #   @raise [NotImplementedError] for a member whose pieces overlap.
   [:map, :sort_addr,
    :cumsum, :cumprod, :cummax, :cummin, :cumcount].each do |name|
     define_method(name) do |*, **, &_blk|