carray 3.0.1 → 3.0.2

data/ext/mkkernel.rb

@@ -360,6 +360,7 @@ module MkKernel
                   face_gate: nil,
                   object_escape: nil,
                   identity_on_empty: false,
+                  all_nan_result: nil,
                   outputs: 1,
                   # Two-pass centred algorithm (variance / stddev family).
                   # When algorithm: :two_pass_centred is set, `state / init /
@@ -465,6 +466,30 @@ module MkKernel
         end
       end
     end
+    # all_nan_result: what an extreme-value reduction answers when every
+    # contributing cell was NaN.  The `(v < acc) ? v : acc` reduce body is
+    # false for NaN, so acc is never updated and the init (+/-INFINITY)
+    # leaks out as the answer -- a value that is neither the minimum of
+    # anything nor a missing marker, and indistinguishable from data that
+    # genuinely held only +INFINITY.
+    #
+    #   :nan   -- answer NaN (C99 fmin folded: a lone non-NaN wins, two
+    #             NaNs give NaN).  For kernels whose output can hold it.
+    #   :undef -- answer UNDEF, by folding into the mask_policy trigger.
+    #             For kernels whose output is a position (argmin family):
+    #             an integer output cannot hold NaN, and index 0 would be
+    #             a lie about where the minimum is.
+    #
+    # Only the float srcs act on it; integers and boolean have no NaN and
+    # their init is a legitimate value.
+    unless all_nan_result.nil? || %i[nan undef].include?(all_nan_result)
+      raise "#{name}: all_nan_result #{all_nan_result.inspect} invalid " \
+            "(expected :nan, :undef, or nil)"
+    end
+    if all_nan_result == :undef && mask_policy.nil?
+      raise "#{name}: all_nan_result: :undef needs a mask_policy " \
+            "(UNDEF is written through the mask_policy trigger)"
+    end
     if value_arg
       raise "#{name}: value_arg must be a Hash" unless value_arg.is_a?(Hash)
       raise "#{name}: value_arg: target must be :T_IN" unless value_arg[:target] == :T_IN
@@ -478,16 +503,29 @@ module MkKernel
     # selects direction (:min / :max) and output kind:
     #   :min / :max       -> extremum blob, output data_type = CA_FIXLEN
     #   :argmin / :argmax -> position of the extremum, output i64
+    #   :count_equal      -> how many cells memcmp-equal value_arg, output i64
     # Author must also list :fixlen in source: (parallel to how :object
     # opts in via source: + an :object body).
+    #
+    # :count_equal is the one mode that takes a value_arg, and takes it as a
+    # byte blob rather than a scalar: the dispatcher packs the query with
+    # rb_ca_obj2ptr into a ca->bytes buffer, the same way the search family
+    # already does for a fixlen query (which is what makes a short query
+    # NUL-pad to the cell width instead of never matching).
     if fixlen
-      unless %i[min max argmin argmax].include?(fixlen)
-        raise "#{name}: fixlen: must be :min / :max / :argmin / :argmax (got #{fixlen.inspect})"
+      unless %i[min max argmin argmax count_equal].include?(fixlen)
+        raise "#{name}: fixlen: must be :min / :max / :argmin / :argmax / :count_equal (got #{fixlen.inspect})"
       end
       raise "#{name}: fixlen: requires :fixlen in source:" unless source.include?(:fixlen)
       raise "#{name}: fixlen: requires mask_policy: :min_count" unless mask_policy == :min_count
       raise "#{name}: fixlen: requires outputs: 1" unless outputs == 1
-      raise "#{name}: fixlen: does not support value_arg / array_arg" if value_arg || array_arg
+      raise "#{name}: fixlen: does not support array_arg" if array_arg
+      if value_arg && fixlen != :count_equal
+        raise "#{name}: fixlen: only :count_equal takes a value_arg"
+      end
+      if fixlen == :count_equal && !value_arg
+        raise "#{name}: fixlen: :count_equal requires value_arg"
+      end
     elsif source.include?(:fixlen)
       raise "#{name}: source includes :fixlen but no fixlen: spec given"
     end
@@ -612,6 +650,7 @@ module MkKernel
       face_gate:       face_gate,
       object_escape:   object_escape,
       identity_on_empty: identity_on_empty,
+      all_nan_result:  all_nan_result,
       outputs:         outputs,
       algorithm:       algorithm,
       divisor:         divisor,
@@ -1351,6 +1390,62 @@ module MkKernel
     io.puts "#undef #{expr_macro}"
   end
 
+  # State vars that start at the type's limit (T_LIMIT_HI / T_LIMIT_LO)
+  # and so can leak their init as an answer.  A position state (argmin's
+  # best_i, init "0") is deliberately not one of them: index 0 is a value
+  # a real minimum can legitimately produce.
+  def self.limit_init_state_vars(k, si, oi, src)
+    return [] unless k[:state]
+    k[:state].keys.filter_map do |var|
+      token = pick_family_string(k[:init][var], src, "init")
+      next unless %w[T_LIMIT_HI T_LIMIT_LO].include?(token)
+      [var, resolve_init_expr(k[:init][var], oi, si, src)]
+    end
+  end
+
+  # Emit the all-NaN fix-up for an extreme-value reduction (see the
+  # all_nan_result: validation in MkKernel.reduce for why it exists).
+  #
+  # The per-cell reduce body is left alone: it stays the SIMD-licensed
+  # ternary, so the 8-way horizontal split (reduce_8way_eligible?) and
+  # the `reduction(min:acc)` clause are untouched, and ordinary data pays
+  # one comparison per slab.  Carrying a "saw a number" flag as a second
+  # DSL state var was the alternative and costs more than it looks: it
+  # takes the kernel over reduce_8way_eligible?'s single-state gate and
+  # drops min / max back onto the legacy single-accumulator macro.
+  #
+  # acc still sitting at its init means either nothing updated it or the
+  # data genuinely held only +/-INFINITY.  Those are told apart by
+  # walking the slab once more for a non-NaN cell -- O(n), and only for
+  # a slab whose answer came out equal to the init.
+  #
+  # Returns true when it emitted anything.
+  def self.emit_all_nan_fixup(io, k, src, si, pairs, valid_guard,
+                              indent: "      ", flag_var: nil)
+    mode = k[:all_nan_result]
+    return false unless mode
+    return false unless FLOAT_DTYPES.include?(src)
+    cond = pairs.map { |var, init| "#{var} == (#{init})" }.join(" && ")
+    cond = "(#{cond}) && #{valid_guard}" if valid_guard
+    io.puts "#{indent}/* all-NaN fix-up (all_nan_result: #{mode.inspect}). */"
+    io.puts "#{indent}if ( #{cond} ) {"
+    io.puts "#{indent}  int64_t   __anf_seen = 0;"
+    io.puts "#{indent}  ca_size_t __anf_mc   = 0;"
+    io.puts "#{indent}  CA_SLAB_REDUCE_T_EX(#{si[:c]}, st, p, m, __anf_seen, 0, " \
+            "__anf_seen |= (v == v), __anf_mc);"
+    io.puts "#{indent}  (void) __anf_mc;"
+    io.puts "#{indent}  if ( ! __anf_seen ) {"
+    if mode == :nan
+      pairs.each { |var, _| io.puts "#{indent}    #{var} = (#{si[:c]}) NAN;" }
+    else
+      raise "#{k[:name]}: all_nan_result: :undef needs flag_var" unless flag_var
+      io.puts "#{indent}    #{flag_var} = 1;"
+    end
+    io.puts "#{indent}  }"
+    io.puts "#{indent}}"
+    true
+  end
+
   def self.reduce_macro_suffix(k, src = nil)
     # CA_OBJECT cannot ride the SIMD-licensed macros (= _PLUS / _MIN / _MAX
     # / _STAR), which assume C operators (= acc is a VALUE, so
@@ -1774,7 +1869,7 @@ module MkKernel
 
     if streamable
       emit_reduce_streaming(io, k, si, oi, ruby_wrap, acc_var, acc_init,
-                            decls, reduce_stmt, finish_expr, extra_args)
+                            decls, reduce_stmt, finish_expr, extra_args, src)
     end
 
     # L.1 / L.3 / L.4 (PROPOSAL_REDUCTION_LOOP_INTERCHANGE):
@@ -1934,6 +2029,17 @@ module MkKernel
         emit_reduce_slab_call(io, k, src, si, oi, suffix, acc_var, acc_init,
                               reduce_stmt, "masked_cnt", indent: "      ")
       end
+      all_nan_flag = nil
+      if k[:all_nan_result]
+        pairs = limit_init_state_vars(k, si, oi, src)
+        if k[:all_nan_result] == :undef && FLOAT_DTYPES.include?(src)
+          all_nan_flag = "__anf_all_nan"
+          io.puts "      int #{all_nan_flag} = 0;"
+        end
+        emit_all_nan_fixup(io, k, src, si, pairs,
+                           "masked_cnt < st.slab_elements",
+                           indent: "      ", flag_var: all_nan_flag)
+      end
       trigger = case k[:mask_policy]
                 when :strict     then "masked_cnt > 0"
                 when :all_masked then "masked_cnt == st.slab_elements"
@@ -1955,6 +2061,7 @@ module MkKernel
                       ": st.slab_elements - masked_cnt < min_count)"
                   end
                 end
+      trigger = "(#{trigger}) || #{all_nan_flag}" if all_nan_flag
       finish_emit = view_flat \
         ? "(transform_active ? (outer_off + ((ca_size_t)(#{finish_expr})) * axis_vstride) : ((ca_size_t)(#{finish_expr})))" \
         : "(#{finish_expr})"
@@ -2037,13 +2144,15 @@ module MkKernel
   # the numeric argmin's best_i.  mask_policy is always :min_count here.
   def self.emit_reduce_native_fixlen(io, k, src)
     name      = k[:name]
+    counting  = k[:fixlen] == :count_equal
     want_max  = %i[max argmax].include?(k[:fixlen])
-    index_out = %i[argmin argmax].include?(k[:fixlen])
+    index_out = %i[argmin argmax].include?(k[:fixlen]) || counting
     cmp       = want_max ? ">" : "<"
+    varg      = counting ? ", const char *value_arg" : ""
 
     io.puts
     io.puts "static VALUE"
-    io.puts "#{name}_ki_native_fixlen (VALUE self, CArray *ca, int8_t *slab_axes, int8_t naxes, int keep_axis, ca_size_t min_count)"
+    io.puts "#{name}_ki_native_fixlen (VALUE self, CArray *ca, int8_t *slab_axes, int8_t naxes, int keep_axis#{varg}, ca_size_t min_count)"
     io.puts "{"
     io.puts "  ca_size_t K = ca->bytes;   /* uniform fixlen byte width */"
     if index_out
@@ -2064,9 +2173,13 @@ module MkKernel
     io.puts "  ca_size_t   out_i   = 0;"
     io.puts "  boolean8_t *op_mask = NULL;   /* lazily allocated on first UNDEF */"
     io.puts "  while ( ca_iter_state_next_slab_axes(&st, &p, &m) ) {"
-    io.puts "    const char *best   = NULL;"
-    io.puts "    ca_size_t   best_i = 0;"
-    io.puts "    (void) best_i;" unless index_out   # value output ignores the index
+    if counting
+      io.puts "    int64_t     cnt    = 0;"
+    else
+      io.puts "    const char *best   = NULL;"
+      io.puts "    ca_size_t   best_i = 0;"
+      io.puts "    (void) best_i;" unless index_out   # value output ignores the index
+    end
     io.puts "    ca_size_t   masked_cnt = 0;"
     io.puts "    int8_t      sndim   = st.slab_ndim;"
     io.puts "    ca_size_t   sidx[CA_RANK_MAX] = { 0 };"
@@ -2082,12 +2195,18 @@ module MkKernel
     io.puts "      }"
     io.puts "      else {"
     io.puts "        const char *q = (const char *) p + doff;"
-    io.puts "        if ( best == NULL ) {"
-    io.puts "          best = q; best_i = idx;"
-    io.puts "        }"
-    io.puts "        else if ( memcmp(q, best, (size_t) K) #{cmp} 0 ) {"
-    io.puts "          best = q; best_i = idx;"
-    io.puts "        }"
+    if counting
+      io.puts "        if ( memcmp(q, value_arg, (size_t) K) == 0 ) {"
+      io.puts "          cnt++;"
+      io.puts "        }"
+    else
+      io.puts "        if ( best == NULL ) {"
+      io.puts "          best = q; best_i = idx;"
+      io.puts "        }"
+      io.puts "        else if ( memcmp(q, best, (size_t) K) #{cmp} 0 ) {"
+      io.puts "          best = q; best_i = idx;"
+      io.puts "        }"
+    end
     io.puts "      }"
     io.puts "      /* row-major odometer (innermost slab axis fastest) so idx"
     io.puts "         matches CA_SLAB_REDUCE_T's flat slab index. */"
@@ -2096,8 +2215,16 @@ module MkKernel
     io.puts "        sidx[sk] = 0;"
     io.puts "      }"
     io.puts "    }"
-    io.puts "    if ( min_count < 0 ? masked_cnt == st.slab_elements"
-    io.puts "                       : st.slab_elements - masked_cnt < min_count ) {"
+    # ERI.0: a count over nothing is 0, not UNDEF -- so the default
+    # (min_count < 0) never fires the mask for :count_equal.  An explicit
+    # min_count: still does.
+    if counting
+      io.puts "    if ( min_count < 0 ? 0"
+      io.puts "                       : st.slab_elements - masked_cnt < min_count ) {"
+    else
+      io.puts "    if ( min_count < 0 ? masked_cnt == st.slab_elements"
+      io.puts "                       : st.slab_elements - masked_cnt < min_count ) {"
+    end
     io.puts "      if ( ! op_mask ) {"
     io.puts "        ca_create_mask(co);"
     io.puts "        op_mask = (boolean8_t *) co->mask->ptr;"
@@ -2111,7 +2238,9 @@ module MkKernel
     io.puts "      out_i++;"
     io.puts "    }"
     io.puts "    else {"
-    if index_out
+    if counting
+      io.puts "      ((int64_t *) op)[out_i] = cnt;"
+    elsif index_out
       io.puts "      ((int64_t *) op)[out_i] = (int64_t) best_i;"
     else
       io.puts "      memcpy(op + out_i * K, best, (size_t) K);"
@@ -2439,6 +2568,49 @@ module MkKernel
     buf_decls = plus_info.map do |pi|
       "          #{pi[:c_type]}  #{pi[:buf]}[512];\n"
     end.join
+
+    # all-NaN fix-up for the tiled core (see emit_all_nan_fixup for the
+    # reduction counterpart).  Each output cell of a tile has its own
+    # accumulator, so the check is per column: a column whose accumulator
+    # is still at the init either saw only NaN or only +/-INFINITY.
+    #
+    # The `_Pragma("omp simd")` j-loop is left alone -- carrying a
+    # "saw a number" flag beside the accumulator would double its loads
+    # and stores on every cell of every column.  Instead the tile is
+    # tested once after the M loop (tile_len comparisons against M *
+    # tile_len already done), and only a tile that holds a suspicious
+    # column re-reads its rows.
+    li_nan_fixup =
+      if k[:all_nan_result] == :nan && FLOAT_DTYPES.include?(src) &&
+         plus_info.size == 1
+        pi = plus_info.first
+        seen_buf = "__li_buf_seen"
+        lambda do |m_step|
+          <<~C.rstrip
+                    {
+                      int __li_susp = 0;
+                      for ( ca_size_t __j = 0; __j < __li_tile_len; __j++ ) {
+                        if ( #{pi[:buf]}[__j] == (#{pi[:c_type]}) (#{pi[:init]}) ) { __li_susp = 1; break; }
+                      }
+                      if ( __li_susp ) {
+                        int8_t #{seen_buf}[512];
+                        for ( ca_size_t __j = 0; __j < __li_tile_len; __j++ ) #{seen_buf}[__j] = 0;
+                        for ( ca_size_t __li_i = 0; __li_i < __li_M; __li_i++ ) {
+                          const #{si[:c]} *__li_row = __li_plane + __li_i * #{m_step} + __li_tile;
+                          for ( ca_size_t __j = 0; __j < __li_tile_len; __j++ ) {
+                            #{seen_buf}[__j] |= (__li_row[__j] == __li_row[__j]);
+                          }
+                        }
+                        for ( ca_size_t __j = 0; __j < __li_tile_len; __j++ ) {
+                          if ( ! #{seen_buf}[__j] ) #{pi[:buf]}[__j] = (#{pi[:c_type]}) NAN;
+                        }
+                      }
+                    }
+          C
+        end
+      else
+        lambda { |_m_step| "" }
+      end
     init_loops = plus_info.map do |pi|
       "              for ( ca_size_t __j = 0; __j < __li_tile_len; __j++ ) {\n" \
       "                #{pi[:buf]}[__j] = (#{pi[:c_type]}) (#{pi[:init]});\n" \
@@ -2468,6 +2640,7 @@ module MkKernel
                         (void) v;
                       }
                     }
+        #{li_nan_fixup.call("__li_INNER")}
                     for ( ca_size_t __j = 0; __j < __li_tile_len; __j++ ) {
                       #{opv}[__li_o * __li_INNER + __li_tile + __j] = (#{oi[:c]}) (#{finish_li});
                     }
@@ -2688,6 +2861,7 @@ module MkKernel
                       (void) v;
                     }
                   }
+        #{li_nan_fixup.call("__li_INNER")}
                   for ( ca_size_t __j = 0; __j < __li_tile_len; __j++ ) {
                     __li_op_k[__li_tile + __j] = (#{oi[:c]}) (#{finish_li});
                   }
@@ -2846,6 +3020,7 @@ module MkKernel
                       (void) v;
                     }
                   }
+        #{li_nan_fixup.call("__li_M_stride")}
                   for ( ca_size_t __j = 0; __j < __li_tile_len; __j++ ) {
                     __li_op_k[__li_tile + __j] = (#{oi[:c]}) (#{finish_li});
                   }
@@ -2937,6 +3112,10 @@ module MkKernel
     if min_count
       io.puts "      ca_size_t masked_cnt = 0;"
       io.puts "      CA_SLAB_REDUCE_T_EX(#{si[:c]}, st, p, m, #{acc_var}, #{acc_init}, #{reduce_stmt}, masked_cnt);"
+      if k[:all_nan_result]
+        emit_all_nan_fixup(io, k, src, si, limit_init_state_vars(k, si, oi, src),
+                           "masked_cnt < st.slab_elements", indent: "      ")
+      end
       # Same trigger as single-output :min_count: legacy default (all_masked)
       # when min_count < 0, otherwise need at least min_count valid cells.
       trigger = "(min_count < 0 ? masked_cnt == st.slab_elements " \
@@ -3012,7 +3191,7 @@ module MkKernel
   #   - mask present: ca_has_mask(ca)
   def self.emit_reduce_streaming(io, k, si, oi, ruby_wrap, acc_var,
                                   acc_init, decls, reduce_stmt,
-                                  finish_expr, extra_args)
+                                  finish_expr, extra_args, src)
     name      = k[:name]
     min_count = (k[:mask_policy] == :min_count)
     has_mp    = !k[:mask_policy].nil?
@@ -3043,6 +3222,14 @@ module MkKernel
     # acc_var requires explicit init (= the macro normally does this).
     # Other state vars in decls already include `= init` per line.
     io.puts "      #{acc_var} = (#{acc_init});"
+    # all-NaN fix-up, streaming variant.  The other two paths confirm a
+    # suspicious answer by re-reading the data; here re-reading means
+    # evaluating the lazy chain a second time, so the flag rides along in
+    # the chunk loop instead.  The loop already pays for producing each
+    # cell, which is what makes one more compare affordable here and not
+    # in the tiled core.
+    all_nan_stream = k[:all_nan_result] == :nan && FLOAT_DTYPES.include?(src)
+    io.puts "      int64_t __anf_seen = 0;" if all_nan_stream
     if has_mp
       # Mask-policy reductions need masked_cnt to satisfy the macro/
       # finish_expr signature.  On streaming we have no mask, so it's
@@ -3070,11 +3257,15 @@ module MkKernel
     io.puts "        for ( __i = 0; __i < __n; __i++ ) {"
     io.puts "          #{si[:c]} v = __chunk[__i];"
     io.puts "          #{reduce_stmt};"
+    io.puts "          __anf_seen |= (v == v);" if all_nan_stream
     io.puts "        }"
     io.puts "        __outer_off += __r;"
     io.puts "      }"
     io.puts "      ca_lazy_arena_release(__chunk);"
     io.puts "      ca_lazy_arena_exit();"
+    if all_nan_stream
+      io.puts "      if ( ! __anf_seen && ca->elements > 0 ) #{acc_var} = (#{si[:c]}) NAN;"
+    end
     if has_mp
       # Streaming path has no mask source, so masked_cnt is 0; min_count
       # / strict / all_masked triggers all evaluate to false except
@@ -3318,7 +3509,17 @@ module MkKernel
     k[:source].each do |s|
       si = DTYPES[s]
       # Per-src value_arg cast: NUM2LL / NUM2ULL / NUM2DBL -> (T_IN).
-      varg_decl = has_varg ? "      #{si[:c]} value_arg = (#{si[:c]}) #{si[:num2c]}(rval);\n" : ""
+      varg_decl = if !has_varg
+                    ""
+                  elsif s == :fixlen
+                    # A fixlen query is a runtime-width byte blob with no
+                    # scalar cast; pack it the way the search family does,
+                    # which NUL-pads a short String to the cell width.
+                    "      char *value_arg = ALLOCA_N(char, src->bytes);\n" \
+                    "      rb_ca_obj2ptr(self, rval, value_arg);\n"
+                  else
+                    "      #{si[:c]} value_arg = (#{si[:c]}) #{si[:num2c]}(rval);\n"
+                  end
       if use_result_var || has_varg
         io.puts "    case #{si[:ca]}: {"
         io.print varg_decl unless varg_decl.empty?
@@ -5333,7 +5534,7 @@ module MkKernel
     io.puts "    }"
     io.puts "    if ( self_face_comparable ) {"
     io.puts "      if ( rval_is_face ) {"
-    io.puts "        rval = rb_ca_strip_face_value(rval);"
+    io.puts %Q[        rval = ca_face_operand_descend(rval, "#{name}_ki");]
     io.puts "      }"
     io.puts "    } else if ( self_was_face ) {"
     io.puts "      if ( rb_respond_to(self_ref, rb_intern(\"to_comparable\")) ) {"
@@ -6443,6 +6644,7 @@ MkKernel.reduce :min,
                      bool:    "acc = ((uint64_t) v < acc) ? (uint64_t) v : acc",
                      object:  'if (acc == Qundef) acc = v; else if (RTEST(rb_funcall(v, rb_intern("<"), 1, acc))) acc = v;' },
   reduction_kind:  :min,     # SL.1.2
+  all_nan_result:  :nan,
   # CA_FIXLEN: memcmp lexicographic min (byte order == the fixlen sort
   # order); the numeric reduce/init above are unused for fixlen (bespoke
   # slab walk, see the fixlen: option in MkKernel.reduce).
@@ -6467,6 +6669,7 @@ MkKernel.reduce :max,
                      bool:    "acc = ((uint64_t) v > acc) ? (uint64_t) v : acc",
                      object:  'if (acc == Qundef) acc = v; else if (RTEST(rb_funcall(v, rb_intern(">"), 1, acc))) acc = v;' },
   reduction_kind:  :max,     # SL.1.2
+  all_nan_result:  :nan,
   # CA_FIXLEN: memcmp lexicographic max (byte order == the fixlen sort order).
   fixlen:          :max,
   source:          MkKernel::ALL_NUMERIC + [:bool, :object, :fixlen],
@@ -6692,6 +6895,7 @@ MkKernel.reduce :minmax,
                      # together on init, get set together on first reduce).
                      object:  'if (lo == Qundef) { lo = v; hi = v; } else { if (RTEST(rb_funcall(v, rb_intern("<"), 1, lo))) lo = v; if (RTEST(rb_funcall(v, rb_intern(">"), 1, hi))) hi = v; }' },
   outputs:         2,
+  all_nan_result:  :nan,
   finish:          { min: "lo", max: "hi" },
   source:          MkKernel::ALL_NUMERIC + [:bool, :object],
   # bool: u64 (Integer 0/1) so minmax returns [0/1, 0/1], not
@@ -6740,6 +6944,7 @@ MkKernel.reduce :argmin,
   # An ORDERABLE Face descends to its numeric storage (position output needs
   # no re-lift; the axis-local index is identical for Face and storage).
   face_gate:       :strip,
+  all_nan_result:  :undef,
   public_method: :min_index
 
 MkKernel.reduce :argmax,
@@ -6758,6 +6963,7 @@ MkKernel.reduce :argmax,
   fallback:        :raise,
   mask_policy:     :min_count,
   face_gate:       :strip,
+  all_nan_result:  :undef,
   public_method: :max_index
 
 # ---- argmin_addr / argmax_addr (view-flat address variants) ---------
@@ -6801,6 +7007,7 @@ MkKernel.reduce :argmin_addr,
   mask_policy:     :min_count,
   semantics:       :view_flat,
   face_gate:       :strip,
+  all_nan_result:  :undef,
   public_method: :min_addr
 
 MkKernel.reduce :argmax_addr,
@@ -6818,6 +7025,7 @@ MkKernel.reduce :argmax_addr,
   mask_policy:     :min_count,
   semantics:       :view_flat,
   face_gate:       :strip,
+  all_nan_result:  :undef,
   public_method: :max_addr
 
 # ---- mask_policy demos ------------------------------------------------
@@ -6945,9 +7153,13 @@ MkKernel.reduce :count_false,
 
 MkKernel.reduce :count_equal,
   init:        "0",
-  reduce:      "if (v == value_arg) acc += 1",
+  # The object lane compares with rb_equal (= Ruby ==), not the C ==, which
+  # on two VALUEs would ask whether they are the same object.
+  reduce:      { numeric: "if (v == value_arg) acc += 1",
+                 object:  "if (RTEST(rb_equal(v, value_arg))) acc += 1" },
   reduction_kind: :plus,         # SL.1.4 (conditional predication; clang predicates safely under reduction(+:acc))
-  source:      MkKernel::ALL_NUMERIC,
+  source:      MkKernel::ALL_NUMERIC + [:object, :fixlen],
+  fixlen:      :count_equal,   # bespoke memcmp walk (a blob has no scalar C type)
   output:      :i64,
   ruby_scalar: :LL2NUM,
   fallback:    :raise,
@@ -7140,22 +7352,38 @@ MkKernel.scan :cumprod,
 # init Qnil is the "no running extremum yet" sentinel, also never leaked
 # (unseen cells are masked).  First unmasked cell adopts v as acc;
 # subsequent unmasked cells compare via rb_funcall(:>) / rb_funcall(:<).
+# The float lane starts at NaN and folds with C99 fmin / fmax, whose
+# rule is exactly the one wanted: a lone number beats NaN, two NaNs give
+# NaN.  So a prefix that has seen only NaN answers NaN instead of leaking
+# +/-INFINITY -- the running form of the rule min / max follow
+# (all_nan_result:).  fmin / fmax are exact on a float at either width,
+# so the f32 lane needs no narrowing.  Integer and boolean have no NaN
+# and keep the limit init and the plain compare.
 MkKernel.scan :cummax,
   source:       MkKernel::ALL_NUMERIC + [:bool, :object],
   output:       { bool: :u64, default: :preserve },
-  init:         { numeric: "T_LIMIT_LO", bool: "T_LIMIT_LO", object: "Qnil" },
-  step:         { numeric: "if (v > acc) acc = v; r = acc",
+  init:         { float: "NAN", numeric: "T_LIMIT_LO", bool: "T_LIMIT_LO", object: "Qnil" },
+  step:         { float: "acc = fmax(acc, v); r = acc",
+                  numeric: "if (v > acc) acc = v; r = acc",
                   bool:    "if ((uint64_t) v > acc) acc = v; r = acc",
                   object:  'if (acc == Qnil) acc = v; else if (RTEST(rb_funcall(v, rb_intern(">"), 1, acc))) acc = v; r = acc' },
   fallback:     :raise,
   axis_default: :flatten,
   empty:        :undef
 
+# The float lane starts at NaN and folds with C99 fmin / fmax, whose
+# rule is exactly the one wanted: a lone number beats NaN, two NaNs give
+# NaN.  So a prefix that has seen only NaN answers NaN instead of leaking
+# +/-INFINITY -- the running form of the rule min / max follow
+# (all_nan_result:).  fmin / fmax are exact on a float at either width,
+# so the f32 lane needs no narrowing.  Integer and boolean have no NaN
+# and keep the limit init and the plain compare.
 MkKernel.scan :cummin,
   source:       MkKernel::ALL_NUMERIC + [:bool, :object],
   output:       { bool: :u64, default: :preserve },
-  init:         { numeric: "T_LIMIT_HI", bool: "T_LIMIT_HI", object: "Qnil" },
-  step:         { numeric: "if (v < acc) acc = v; r = acc",
+  init:         { float: "NAN", numeric: "T_LIMIT_HI", bool: "T_LIMIT_HI", object: "Qnil" },
+  step:         { float: "acc = fmin(acc, v); r = acc",
+                  numeric: "if (v < acc) acc = v; r = acc",
                   bool:    "if ((uint64_t) v < acc) acc = v; r = acc",
                   object:  'if (acc == Qnil) acc = v; else if (RTEST(rb_funcall(v, rb_intern("<"), 1, acc))) acc = v; r = acc' },
   fallback:     :raise,
@@ -7543,12 +7771,32 @@ MkKernel.search :search_nearest,
     object: <<~C,
       /* CA_OBJECT nearest: minimum of query_val.distance(cell), compared
          with `<` (matches the legacy flat proc_nearest_addr_VALUE). */
+      /* Nearest needs a metric.  #distance is the protocol the 2.0 flat
+         kernel used, back when Numeric#distance was a monkey patch; it
+         is an opt-in refinement now, and a refinement does not reach an
+         rb_funcall from C -- so a number reaching here answers no more
+         than a String does.  Measure a number the way #distance itself
+         does, keep #distance for anything that defines a real one, and
+         refuse the rest by name rather than let a bare NoMethodError out
+         of the loop below. */
+      ID nearest_id = rb_intern("distance");
+      int nearest_by_distance = rb_respond_to(query_val, nearest_id);
+      if ( ! nearest_by_distance && ! rb_obj_is_kind_of(query_val, rb_cNumeric) ) {
+        rb_raise(rb_eCADataTypeError,
+                 "search_nearest: nearest needs a distance, and %s is neither a "
+                 "number nor answers #distance (define one on the stored "
+                 "objects, or use search / bsearch for an exact match)",
+                 rb_obj_classname(query_val));
+      }
       result = (ca_size_t) -1;
       VALUE best = Qnil;
       for ( ca_size_t i = 0; i < slab_n; i++ ) {
         if ( mask_in && mask_in[i * slab_mask_stride] ) continue;
         T_LOAD v = *(T_LOAD *)(slab_ptr + i * slab_stride);
-        VALUE dist = rb_funcall(query_val, rb_intern("distance"), 1, v);
+        VALUE dist = nearest_by_distance
+                   ? rb_funcall(query_val, nearest_id, 1, v)
+                   : rb_funcall(rb_funcall(query_val, '-', 1, v),
+                                rb_intern("abs"), 0);
         if ( NIL_P(best) || RTEST(rb_funcall(dist, rb_intern("<"), 1, best)) ) {
           best = dist; result = i;
         }
@@ -7724,12 +7972,32 @@ MkKernel.search :search_nearest_addr,
     object: <<~C,
       /* CA_OBJECT nearest (view_flat addr): minimum of
          query_val.distance(cell), compared with `<`. */
+      /* Nearest needs a metric.  #distance is the protocol the 2.0 flat
+         kernel used, back when Numeric#distance was a monkey patch; it
+         is an opt-in refinement now, and a refinement does not reach an
+         rb_funcall from C -- so a number reaching here answers no more
+         than a String does.  Measure a number the way #distance itself
+         does, keep #distance for anything that defines a real one, and
+         refuse the rest by name rather than let a bare NoMethodError out
+         of the loop below. */
+      ID nearest_id = rb_intern("distance");
+      int nearest_by_distance = rb_respond_to(query_val, nearest_id);
+      if ( ! nearest_by_distance && ! rb_obj_is_kind_of(query_val, rb_cNumeric) ) {
+        rb_raise(rb_eCADataTypeError,
+                 "search_nearest_addr: nearest needs a distance, and %s is neither a "
+                 "number nor answers #distance (define one on the stored "
+                 "objects, or use search / bsearch for an exact match)",
+                 rb_obj_classname(query_val));
+      }
       result = (ca_size_t) -1;
       VALUE best = Qnil;
       for ( ca_size_t i = 0; i < slab_n; i++ ) {
         if ( mask_in && mask_in[i * slab_mask_stride] ) continue;
         T_LOAD v = *(T_LOAD *)(slab_ptr + i * slab_stride);
-        VALUE dist = rb_funcall(query_val, rb_intern("distance"), 1, v);
+        VALUE dist = nearest_by_distance
+                   ? rb_funcall(query_val, nearest_id, 1, v)
+                   : rb_funcall(rb_funcall(query_val, '-', 1, v),
+                                rb_intern("abs"), 0);
         if ( NIL_P(best) || RTEST(rb_funcall(dist, rb_intern("<"), 1, best)) ) {
           best = dist; result = i;
         }

data/ext/ruby_carray.c

@@ -121,6 +121,13 @@ void Init_ca_kernel_iterator ();
 
 void Init_carray_slab ();
 
+void Init_carray_address_basis (); /* CArray::AddressBasis: pointer + byte
+                                      strides lent for the length of a block,
+                                      for code that addresses cells itself.
+                                      A runtime facility at the ca_attach
+                                      layer, not a user surface; see
+                                      guides/devel/21_address_basis.md */
+
 void
 Init_carray_ext (void)
 {
@@ -310,7 +317,7 @@ Init_carray_ext (void)
   Init_ca_obj_refer();
   Init_ca_obj_stride();       /* CAREFUL: must precede CAStride subclasses
                                  (farray / block / transpose / repeat /
-                                 unbound_repeat / field). */
+                                 field). */
   Init_ca_obj_farray();
   Init_ca_obj_block();
   Init_ca_obj_select();
@@ -373,5 +380,7 @@ Init_carray_ext (void)
   Init_ca_kernel_iterator();
 
   Init_carray_slab();
+
+  Init_carray_address_basis();
 }
 

data/ext/version.h

@@ -1,6 +1,6 @@
-#define CA_VERSION "3.0.1"
-#define CA_VERSION_CODE 301
+#define CA_VERSION "3.0.2"
+#define CA_VERSION_CODE 302
 #define CA_VERSION_MAJOR 3
 #define CA_VERSION_MINOR 0
-#define CA_VERSION_TEENY 1
-#define CA_VERSION_DATE "2026/09/07"
+#define CA_VERSION_TEENY 2
+#define CA_VERSION_DATE "2026/09/24"

data/lib/carray/autoload_carray.rb

@@ -30,8 +30,9 @@
 
 class CArray
   inspect_rb = "carray/inspect"
-  autoload_method "inspect",     inspect_rb
-  autoload_method "source_code", inspect_rb
+  autoload_method "inspect",      inspect_rb
+  autoload_method "inspect_full", inspect_rb
+  autoload_method "source_code",  inspect_rb
 end
 
 # ---- Serializer / Marshal / dump / load ------------------------------------
@@ -42,7 +43,6 @@ class CArray
   autoload_method "self.save",           serialize_rb
   autoload_method "self.load",           serialize_rb
   autoload_method "self.dump",           serialize_rb
-  autoload_method "self.load_from_file", serialize_rb
   autoload_method "marshal_dump",        serialize_rb
   autoload_method "marshal_load",        serialize_rb
 end
@@ -201,11 +201,13 @@ class CArray
   autoload_method "self.meshgrid",  "carray/methods/meshgrid"
 
   autoload_method "bincount",       "carray/methods/bincount"
+  autoload_method "repeat",         "carray/methods/repeat"
   autoload_method "self.broadcast", "carray/methods/broadcast"
   autoload_method "gather_nd",      "carray/methods/gather_nd"
   autoload_method "put_nd",         "carray/methods/gather_nd"
   autoload_method "mask_duplicates", "carray/methods/mask_duplicates"
   autoload_method "unique",          "carray/methods/unique"
+  autoload_method "factorize",       "carray/methods/factorize"
   autoload_method "is_in",           "carray/methods/is_in"
   autoload_method "intersection",    "carray/methods/is_in"
   autoload_method "difference",      "carray/methods/is_in"