carray 2.0.0 → 3.0.0

data/lib/carray/meld_reduce.rb

@@ -0,0 +1,289 @@
+# CAMeld reduce fast paths (per-parent decompose family).
+#
+# All decomposable reductions along the meld axis land at eager-entity
+# parity via the identity
+#   op(concat_k p_k) = combine_k op(p_k)
+# where op is sum/min/max/mean/etc. and combine_k is +, min, max, or the
+# Welford update (variance/stddev).  Each per-parent op runs on an entity,
+# hitting the fastest kernel_iterator path, and dodges the whole-view
+# SRC_ATTACH materialise (K per-parent xfer_all GET into scratch).
+#
+# Reductions along a non-meld axis (memo §7.4) also decompose: each
+# parent independently reduces the non-meld axis, and the K results are
+# concatenated back along the meld axis via `CArray.meld`.  Result is
+# materialised (`.copy`) to preserve the entity-returning semantic of
+# `CArray#sum`/`#mean`/etc.
+#
+# Fast path activates when:
+#   - axis kwarg is a single Integer (or absent for flat reduce)
+#   - no mask on CAMeld or any parent (skipna needs per-cell dispatch;
+#     the decompose would not see correct mask propagation across parents)
+#   - no non-:axis kwargs (min_count / fill_value / keep_axis / etc. punt
+#     to super; those change finalisation semantics)
+# When any condition fails the method falls through to super, landing on
+# the kernel_iterator SRC_ATTACH path (correct, just slower).
+#
+# Order statistics (median / percentile / quantile) do NOT decompose —
+# per-parent medians are not a function of the overall median — so those
+# stay on the SRC_ATTACH path, which is already essentially parity because
+# the sort cost dominates.
+#
+# See docs/objects/CAMeld.md and devel/bench_cameld_*.rb for numbers.
+
+class CAMeld
+
+  # ---------- monoid reductions (sum / mean / min / max) ----------
+
+  def sum(*args, **kw)
+    return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
+    axis = kw[:axis]
+    if axis.nil?
+      parents.map(&:sum).inject(:+)
+    elsif meld_axis_normalized?(axis)
+      parents.map { |p| p.sum(axis: axis) }.inject(:+)
+    else
+      non_meld_axis_decompose(:sum, axis)
+    end
+  end
+
+  # Same result as `CArray#mean`, obtained by reducing each parent and
+  # combining, so the melded array is never materialised.  Falls back to
+  # the generic path when the decomposition does not apply.
+  # @return [CArray, Numeric]
+  def mean(*args, **kw)
+    return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
+    axis = kw[:axis]
+    # `mean` has no identity: an empty set of contributors has no defined
+    # mean (0/0 = NaN).  Punt to super, which returns UNDEF: a reduction
+    # with no contributors yields the identity where one exists and UNDEF
+    # where none does, and never raises.
+    if axis.nil?
+      return super if parents.all? { |p| p.elements == 0 }
+      total_sum = parents.map(&:sum).inject(:+)
+      total_count = parents.map(&:elements).inject(:+)
+      total_sum / total_count.to_f
+    elsif meld_axis_normalized?(axis)
+      return super if parents.all? { |p| p.dim[meld_axis] == 0 }
+      total_sum = parents.map { |p| p.sum(axis: axis) }.inject(:+)
+      total_count = parents.map { |p| p.dim[meld_axis] }.inject(:+)
+      total_sum / total_count.to_f
+    else
+      non_meld_axis_decompose(:mean, axis)
+    end
+  end
+
+  # Same result as `CArray#min`, obtained by reducing each parent and
+  # combining, so the melded array is never materialised.  Falls back to
+  # the generic path when the decomposition does not apply.
+  # @return [CArray, Numeric]
+  def min(*args, **kw)
+    return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
+    axis = kw[:axis]
+    # `min` has no identity — empty parent list / all-empty parents punt to
+    # super for UNDEF.
+    if axis.nil?
+      return super if parents.all? { |p| p.elements == 0 }
+      parents.reject { |p| p.elements == 0 }.map(&:min).min
+    elsif meld_axis_normalized?(axis)
+      return super if parents.all? { |p| p.dim[meld_axis] == 0 }
+      nonempty = parents.reject { |p| p.dim[meld_axis] == 0 }
+      CArray.stack(nonempty.map { |p| p.min(axis: axis) }).min(axis: 0)
+    else
+      non_meld_axis_decompose(:min, axis)
+    end
+  end
+
+  # Same result as `CArray#max`, obtained by reducing each parent and
+  # combining, so the melded array is never materialised.  Falls back to
+  # the generic path when the decomposition does not apply.
+  # @return [CArray, Numeric]
+  def max(*args, **kw)
+    return super unless args.empty? && meld_reduce_fast_path_ok?(kw)
+    axis = kw[:axis]
+    if axis.nil?
+      return super if parents.all? { |p| p.elements == 0 }
+      parents.reject { |p| p.elements == 0 }.map(&:max).max
+    elsif meld_axis_normalized?(axis)
+      return super if parents.all? { |p| p.dim[meld_axis] == 0 }
+      nonempty = parents.reject { |p| p.dim[meld_axis] == 0 }
+      CArray.stack(nonempty.map { |p| p.max(axis: axis) }).max(axis: 0)
+    else
+      non_meld_axis_decompose(:max, axis)
+    end
+  end
+
+  # ---------- variance family (Welford combine along meld axis) ----------
+  #
+  # Chan / Welford parallel merge: each parent contributes (n_k, mean_k,
+  # M2_k = Σ (x - mean_k)^2).  Combine two chunks (n1, m1, M1) + (n2, m2, M2):
+  #   n = n1 + n2
+  #   δ = m2 - m1
+  #   mean = m1 + δ * n2 / n
+  #   M2   = M1 + M2 + δ² * (n1 * n2 / n)
+  # sample variance   = M2 / (n - 1)
+  # population variance = M2 / n
+  #
+  # M2 per parent is recovered from CArray's variance:
+  #   M2_k = variance_k * (n_k - 1)   [sample-variance CArray path]
+  # This inherits CArray's ε-close SIMD reduce contract (memo: reduction is
+  # ε-close, not bit-exact).  Falls through to super when any parent has
+  # n <= 1 along the axis (sample variance undefined).
+
+  def variance(*args, **kw)
+    variance_family(args, kw, sample: true, sqrt: false) { super }
+  end
+
+  # Same result as `CArray#variancep`, obtained by reducing each parent and
+  # combining, so the melded array is never materialised.  Falls back to
+  # the generic path when the decomposition does not apply.
+  # @return [CArray, Numeric]
+  def variancep(*args, **kw)
+    variance_family(args, kw, sample: false, sqrt: false) { super }
+  end
+
+  # Same result as `CArray#stddev`, obtained by reducing each parent and
+  # combining, so the melded array is never materialised.  Falls back to
+  # the generic path when the decomposition does not apply.
+  # @return [CArray, Numeric]
+  def stddev(*args, **kw)
+    variance_family(args, kw, sample: true, sqrt: true) { super }
+  end
+
+  # Same result as `CArray#stddevp`, obtained by reducing each parent and
+  # combining, so the melded array is never materialised.  Falls back to
+  # the generic path when the decomposition does not apply.
+  # @return [CArray, Numeric]
+  def stddevp(*args, **kw)
+    variance_family(args, kw, sample: false, sqrt: true) { super }
+  end
+
+  private
+
+  def meld_axis_normalized?(axis)
+    (axis < 0 ? axis + ndim : axis) == meld_axis
+  end
+
+  # Fast path fires when: no mask anywhere, no non-:axis kwargs, and axis
+  # (if given) is a valid single Integer within [-ndim, ndim).  Anything
+  # more elaborate (min_count / fill_value / keep_axis / multi-axis /
+  # mask propagation) punts to super.
+  def meld_reduce_fast_path_ok?(kw)
+    return false unless (kw.keys - [:axis]).empty?
+    axis = kw[:axis]
+    unless axis.nil?
+      return false unless axis.is_a?(Integer)
+      norm = axis < 0 ? axis + ndim : axis
+      return false unless norm >= 0 && norm < ndim
+    end
+    return false if has_mask?
+    parents.each { |p| return false if p.has_mask? }
+    true
+  end
+
+  # Non-meld-axis decompose: each parent reduces the same axis independently,
+  # then the K per-parent results are concatenated back along the meld axis.
+  # Materialised to entity (`.copy`) to match CArray#reduce entity semantics.
+  #
+  # Axis index in the reduced result: if the reduced axis is < meld_axis in
+  # the CAMeld frame, meld_axis shifts down by 1 in the per-parent result
+  # (post-reduce ndim = ndim - 1).  If reduced axis > meld_axis, meld_axis
+  # is unchanged.  (Reduced axis == meld_axis is handled by the callers'
+  # meld_axis branch and never reaches here.)
+  def non_meld_axis_decompose(op, axis)
+    parts = parents.map { |p| p.send(op, axis: axis) }
+    axis_norm = axis < 0 ? axis + ndim : axis
+    new_meld_axis = axis_norm < meld_axis ? meld_axis - 1 : meld_axis
+    CArray.meld(parts, axis: new_meld_axis).copy
+  end
+
+  def variance_family(args, kw, sample:, sqrt:)
+    return yield unless args.empty? && meld_reduce_fast_path_ok?(kw)
+    axis = kw[:axis]
+    # Empty-parent / short-parent handling — Welford needs n >= 2 per parent
+    # to recover m2 from p.variance for sample, n >= 1 for variancep (n=1
+    # gives m2=0, fine).  Any parent below its threshold punts to super,
+    # which handles UNDEF / 0-count per CLAUDE.md contract.
+    min_n = sample ? 2 : 1
+    if axis.nil?
+      return yield if parents.any? { |p| p.elements < min_n }
+      finalize_scalar(welford_flat, sample, sqrt)
+    elsif meld_axis_normalized?(axis)
+      return yield if parents.any? { |p| p.dim[meld_axis] < min_n }
+      finalize_vector(welford_axis(axis), sample, sqrt)
+    else
+      # Non-meld-axis: each parent's variance/stddev is independent along
+      # its own local axis; concatenate the K results along the meld axis.
+      op_super = sqrt ? (sample ? :stddev : :stddevp) : (sample ? :variance : :variancep)
+      non_meld_axis_decompose(op_super, axis)
+    end
+  end
+
+  # Flat Welford — reduces every parent fully; returns scalar (n_tot, mean, M2)
+  # trio in a shape suitable for finalize_scalar.  Returns [n_tot, M2].
+  # Preconditions (checked in variance_family): every parent has enough
+  # elements (>= 2 for sample, >= 1 for population).
+  def welford_flat
+    n_tot = 0
+    mean = nil
+    m2 = nil
+    parents.each do |p|
+      np = p.elements
+      mp = p.mean
+      # variance is undefined at n=1 (returns UNDEF / raises).  For
+      # variancep (min_n=1) with n=1, m2_p = 0 by definition; skip the
+      # p.variance call which would blow up.
+      m2p = np < 2 ? 0.0 : p.variance * (np - 1)
+      if mean.nil?
+        n_tot = np; mean = mp; m2 = m2p
+      else
+        delta = mp - mean
+        nn = n_tot + np
+        mean = mean + delta * np / nn.to_f
+        m2 = m2 + m2p + delta * delta * (n_tot * np / nn.to_f)
+        n_tot = nn
+      end
+    end
+    [n_tot, m2]
+  end
+
+  # Per-axis Welford — reduces every parent along the given (meld) axis and
+  # combines the vector-shaped (n_tot, mean, M2) trio.  Returns [n_tot, M2]
+  # (n_tot is scalar since the meld axis is what we're reducing; M2 is a
+  # CArray of the collapsed shape).
+  def welford_axis(axis)
+    n_tot = 0
+    mean = nil
+    m2 = nil
+    parents.each do |p|
+      np = p.dim[meld_axis]
+      mp = p.mean(axis: axis)
+      # variance is undefined at n=1; for variancep with n=1, m2_p = 0 by
+      # definition (variance_family already gated n >= min_n).
+      m2p = np < 2 ? mp * 0 : p.variance(axis: axis) * (np - 1)
+      if mean.nil?
+        n_tot = np; mean = mp; m2 = m2p
+      else
+        delta = mp - mean
+        nn = n_tot + np
+        mean = mean + delta * (np.to_f / nn)
+        m2 = m2 + m2p + delta * delta * (n_tot * np.to_f / nn)
+        n_tot = nn
+      end
+    end
+    [n_tot, m2]
+  end
+
+  def finalize_scalar(pair, sample, sqrt)
+    n_tot, m2 = pair
+    div = sample ? (n_tot - 1) : n_tot
+    v = m2 / div.to_f
+    sqrt ? Math.sqrt(v) : v
+  end
+
+  def finalize_vector(pair, sample, sqrt)
+    n_tot, m2 = pair
+    div = sample ? (n_tot - 1) : n_tot
+    v = m2 / div.to_f
+    sqrt ? v.sqrt : v
+  end
+end

data/lib/carray/methods/align_addr.rb

@@ -0,0 +1,116 @@
+class CArray
+
+  # @overload align_addr(*arrays, join: :outer)
+  #   Aligns several arrays onto one common set of coordinate values and
+  #   returns, for each array, the flat addresses that gather it onto that
+  #   common set. Symmetric N-ary counterpart of the instance method
+  #   {#locate_addr} (which is the asymmetric self-against-ref lookup).
+  #
+  #   Returns `[common, idx_0, idx_1, ...]`:
+  #   - `common` is a 1-D CArray of the common coordinate values, chosen by
+  #     `join:` (see below), in first-appearance order.
+  #   - `idx_k` is a `common`-shaped `:int64` CArray of flat addresses into
+  #     `arrays[k]`: `idx_k[j]` is where `common[j]` lives in `arrays[k]`, or
+  #     `UNDEF` when that array lacks the value. Each `idx_k` is exactly
+  #     `common.locate_addr(arrays[k])`.
+  #
+  #   Reindex each array onto the common grid with `project`, then compare
+  #   element-wise (missing coordinates come through masked):
+  #
+  #     common, idx_a, idx_b = CArray.align_addr(a_coord, b_coord, join: :outer)
+  #     a_on_grid = a_data.project(idx_a)   # common-shaped, UNDEF where a lacks it
+  #     b_on_grid = b_data.project(idx_b)
+  #
+  #   Because the addresses are returned (not the reindexed values), one
+  #   alignment serves any number of `arrays[k]`-shaped variables — compute the
+  #   idx once, project many.
+  #
+  #   `join:` selects the common coordinate set:
+  #   - `:outer` — union of the distinct values of every array.
+  #   - `:inner` — distinct values present in every array.
+  #   - `:left`  — the first array's distinct values.
+  #   - `:right` — the last array's distinct values.
+  #
+  #   Value equality follows the value-hash discovery family (numeric `==` with
+  #   NaN collapsed and `-0.0 == +0.0`; object `hash` / `eql?`; fixlen byte
+  #   equality). Arrays are coerced to the first array's dtype within the same
+  #   family (cross-family raises). Masked cells do not enter `common`.
+  #
+  #   @param arrays [Array<CArray>] two or more arrays (Array / Range coerced
+  #     via `to_ca`). One array is allowed (degenerate: `common` is its distinct
+  #     values).
+  #   @param join [:outer, :inner, :left, :right] how to build `common`.
+  #   @return [Array<CArray>] `[common, idx_0, idx_1, ...]`.
+  #   @raise [ArgumentError] when no array is given or `join` is not one of the
+  #     accepted symbols.
+  def self.align_addr (*arrays, join: :outer)
+    raise ArgumentError, "align_addr: need at least one array" if arrays.empty?
+    arrays = arrays.map { |a| a.is_a?(CArray) ? a : a.to_ca }
+    # Seed the fold with the first array's distinct values so N == 1 and the
+    # union/intersection folds all agree (a bare reduce over one element would
+    # return it with duplicates intact).
+    seed = arrays.first.unique
+    common = case join
+             when :outer then arrays[1..-1].reduce(seed) { |acc, a| acc.union(a) }
+             when :inner then arrays[1..-1].reduce(seed) { |acc, a| acc.intersection(a) }
+             when :left  then seed
+             when :right then arrays.last.unique
+             else
+               raise ArgumentError,
+                     "align_addr: join must be :outer / :inner / :left / :right " \
+                     "(got #{join.inspect})"
+             end
+    idxs = arrays.map { |a| common.locate_addr(a) }
+    [common, *idxs]
+  end
+
+  # @overload align_nearest_addr(*arrays, grid: nil, direction: :round, tolerance: nil)
+  #   Aligns several arrays onto one common coordinate grid by nearest match,
+  #   the ordered-lane (continuous) sibling of {align_addr}. Returns
+  #   `[common, idx_0, idx_1, ...]` with the same reindex contract: `idx_k` is a
+  #   `common`-shaped `:int64` array of flat addresses into `arrays[k]` giving,
+  #   for each grid point, the nearest value in that array — exactly
+  #   `common.locate_nearest_addr(arrays[k], direction:, tolerance:)`.
+  #
+  #   Unlike {align_addr}, the common grid is **not** built by a set union:
+  #   continuous coordinates rarely coincide exactly, so a union would merely
+  #   pile up near-duplicate points. Instead the grid is a reference axis —
+  #   `grid:` when given, otherwise the first array verbatim (kept as-is, not
+  #   deduplicated). Pass `grid: arrays.last` to align onto the last array's
+  #   axis. (`join:` has no meaning here and is not accepted; clustering nearby
+  #   coordinates into a synthesised grid is out of scope.)
+  #
+  #     common, ia, ib = CArray.align_nearest_addr(a_coord, b_coord, grid: ref)
+  #     a_on_grid = a_data.project(ia)   # each grid point <- nearest a value
+  #     b_on_grid = b_data.project(ib)
+  #
+  #   `direction:` (`:round` / `:floor` / `:ceil`) and `tolerance:` are
+  #   forwarded to {#locate_nearest_addr}: out-of-range grid points, and points
+  #   whose nearest value is farther than `tolerance`, come back masked.
+  #
+  #   @param arrays [Array<CArray>] one or more arrays (Array / Range coerced
+  #     via `to_ca`).
+  #   @param grid [CArray, Array, Range, nil] the reference coordinate grid;
+  #     `nil` uses the first array verbatim.
+  #   @param direction [:round, :floor, :ceil] rounding rule for the nearest
+  #     match.
+  #   @param tolerance [Numeric, nil] maximum accepted distance; farther grid
+  #     points are masked. `nil` disables the check.
+  #   @return [Array<CArray>] `[common, idx_0, idx_1, ...]`.
+  #   @raise [ArgumentError] when no array is given (or `direction` is invalid,
+  #     raised by {#locate_nearest_addr}).
+  def self.align_nearest_addr (*arrays, grid: nil, direction: :round, tolerance: nil)
+    raise ArgumentError, "align_nearest_addr: need at least one array" if arrays.empty?
+    arrays = arrays.map { |a| a.is_a?(CArray) ? a : a.to_ca }
+    common = if grid.nil?
+               arrays.first
+             else
+               grid.is_a?(CArray) ? grid : grid.to_ca
+             end
+    idxs = arrays.map { |a|
+      common.locate_nearest_addr(a, direction: direction, tolerance: tolerance)
+    }
+    [common, *idxs]
+  end
+
+end

data/lib/carray/methods/bin.rb

@@ -0,0 +1,128 @@
+class CArray
+
+  # @overload bin(vmin, vmax, step = nil, bins: nil, lfill: nil, ufill: nil, include_max: true)
+  #   Returns each element's bin index for equal-width, half-open bins
+  #   over `[vmin, vmax]`. Bin `k` covers `[vmin + k*w, vmin + (k+1)*w)`
+  #   where `w = (vmax - vmin) / n`. The number of bins is set either by
+  #   `step` (positional; bin width, matching `snap`'s step) or by
+  #   `bins:` (kwarg; count of bins, matching histogram convention);
+  #   exactly one must be given.
+  #
+  #   Because `[vmin, vmax]` is a user-declared inclusive range, values
+  #   exactly equal to `vmax` land in the last bin by default
+  #   (`include_max: true`); this differs from `bin_to`, where the
+  #   user-supplied edges are treated as-is (half-open, default `false`).
+  #
+  #   Out-of-range convention follows `bin_to` / `project`: `lfill` for
+  #   below-range, `ufill` for above-range; `nil` on either side masks
+  #   that side. NaN / masked input cells are always masked in the
+  #   output, independently of `lfill` / `ufill`.
+  #
+  #   Use `snap(step, offset:)` when the desired output is the snapped
+  #   value; use `bin_to(edges)` when the edges are non-uniform.
+  #
+  #   @param vmin [Numeric] range lower bound.
+  #   @param vmax [Numeric] range upper bound; must be `>= vmin`.
+  #   @param step [Numeric, nil] bin width. The number of bins is
+  #     `((vmax - vmin) / step).round` (silent FP rounding, standard
+  #     numeric convention).
+  #   @param bins [Integer, nil] number of bins (alternative to `step`);
+  #     must be `>= 1`.
+  #   @param lfill [Integer, nil] fill for below-range cells.
+  #   @param ufill [Integer, nil] fill for above-range cells.
+  #   @param include_max [Boolean] fold values equal to `vmax` into the
+  #     last bin instead of treating them as above-range.
+  #   @return [CArray] `CA_INT64` bin indices in `[0, n-1]`, same
+  #     shape as `self`.
+  #   @raise [ArgumentError] when neither / both of `step` and `bins:`
+  #     are given, `bins < 1`, or `vmin > vmax`.
+  #   @example
+  #     temp.bin(270, 300, 0.5)               # 60 uniform bins every 0.5 K
+  #     temp.bin(0, 1, bins: 100)             # 100 equal-width bins over [0, 1]
+  #     temp.bin(0, 9, 1, lfill: 0, ufill: 8) # clamp OOB to end bins
+  def bin(vmin, vmax, step = nil, bins: nil, lfill: nil, ufill: nil, include_max: true)
+    if step.nil? == bins.nil?
+      raise ArgumentError, "bin: give exactly one of `step` or `bins:`"
+    end
+    raise ArgumentError, "bin: vmin > vmax" if vmin > vmax
+
+    n = bins || ((vmax - vmin).to_f / step).round
+    raise ArgumentError, "bin: n must be >= 1" if n < 1
+
+    if vmin == vmax
+      # Degenerate: zero interval → all cells fall on the single edge;
+      # with include_max: true they land in bin 0.
+      out = CArray.int64(*shape) { 0 }
+      out.mask = self.mask.to_ca if self.has_mask?
+      if self.float?
+        inv = self.is_invalid
+        if inv.count(true) > 0
+          out.mask = out.has_mask? ? (out.mask | inv) : inv
+        end
+      end
+      return out
+    end
+
+    # Delegate to `bin_to` with generated uniform edges — same kernel
+    # (`histbin_ki`) as `histogram`, so semantics are identical.
+    edges = CArray.float64(n + 1).span(vmin..vmax)
+    bin_to(edges, lfill: lfill, ufill: ufill, include_max: include_max)
+  end
+
+  # @overload bin_to(edges, lfill: nil, ufill: nil, include_max: false)
+  #   Returns each element's bin index against an explicit ascending
+  #   `edges` array (non-uniform binning). Sibling of `bin` (uniform,
+  #   range + step) and `snap_to` (nearest-value snap to the same shape
+  #   of grid).
+  #
+  #   `edges` are `N+1` ascending boundaries defining `N` bins; bin
+  #   `k` covers the half-open interval `[edges[k], edges[k+1])`.
+  #   Out-of-range values follow the `bin` / `project` convention:
+  #   a value below `edges[0]` becomes `lfill`, a value at or above
+  #   `edges[-1]` becomes `ufill`; `nil` on either side masks that
+  #   side. When `include_max` is true, a value exactly equal to
+  #   `edges[-1]` lands in the last bin `N-1` instead of being
+  #   treated as above-range. NaN or masked input cells are masked
+  #   in the output, independently of `lfill` / `ufill`.
+  #
+  #   The inner binning kernel is shared with `histogram`, which counts
+  #   how many values land in each bin.
+  #
+  #   @param edges [CArray, Array<Numeric>] 1-D ascending boundaries
+  #     with at least 2 values.
+  #   @param lfill [Integer, nil] fill for below-range cells; `nil`
+  #     masks them.
+  #   @param ufill [Integer, nil] fill for above-range cells; `nil`
+  #     masks them.
+  #   @param include_max [Boolean] fold values equal to `edges[-1]`
+  #     into the last bin instead of treating them as above-range.
+  #   @return [CArray] `CA_INT64` array with the same shape as `self`
+  #     holding bin indices in `[0, N-1]` (or the fill values / mask
+  #     for out-of-range and masked cells).
+  #   @raise [ArgumentError] when `edges` is not 1-D or has fewer
+  #     than 2 values.
+  #   @example
+  #     e = CA_FLOAT64([0, 1, 10, 100])
+  #     v = CA_FLOAT64([0.5, 5.0, 50.0, -1.0, 200.0])
+  #     v.bin_to(e)                  # => [0, 1, 2, UNDEF, UNDEF]
+  #     v.bin_to(e, lfill: 0, ufill: 2)
+  #                                  # => [0, 1, 2, 0, 2]
+  def bin_to(edges, lfill: nil, ufill: nil, include_max: false)
+    e = CArray.wrap_readonly(edges, :float64)
+    raise ArgumentError, "bin_to: edges must be 1-D" unless e.ndim == 1
+    raise ArgumentError, "bin_to: edges needs at least 2 values" if e.elements < 2
+    n = e.elements - 1                                  # number of bins
+
+    src = data_type == CA_FLOAT64 ? self : CArray.wrap_readonly(self, :float64)
+
+    # histbin_ki returns the extended index (0 = under, 1..N = in-range bins,
+    # N+1 = over; NaN / masked -> masked).  Shift to the in-range convention:
+    # under -> -1, in-range -> 0..N-1, over -> N.
+    out = src.send(:histbin_ki, e, include_max) - 1
+
+    out[:eq, -1] = lfill.nil? ? UNDEF : lfill          # under
+    out[:eq, n]  = ufill.nil? ? UNDEF : ufill          # over
+    out
+  end
+
+end

data/lib/carray/methods/bincount.rb

@@ -0,0 +1,87 @@
+# Ruby front-end for CArray#bincount.  Validates inputs, picks the
+# output length, and dispatches to the dedicated C kernels in
+# ext/carray_bincount.c (`__bincount_count__` / `__bincount_weighted__`).
+
+class CArray
+
+  # @overload bincount(weights: nil, length: 0)
+  #   Returns occurrence counts per non-negative integer label in
+  #   `self`, or a per-label sum of `weights`.
+  #
+  #   Masked labels are skipped (not counted). Masked weights are
+  #   skipped too (their label contributes 0).
+  #
+  #   @param weights [CArray, nil] when given, sums weights per
+  #     label instead of counting; length must equal `self.elements`
+  #     and the output `data_type` is inherited from `weights`.
+  #     When `nil` (default), counts occurrences and returns
+  #     `CA_UINT32` (or `CA_UINT64` if `length >= 2^32`).
+  #   @param length [Integer] minimum output length; the actual
+  #     length is `max(length, self.max + 1)`.
+  #   @return [CArray] 1-D output of length `max(length, self.max + 1)`.
+  #   @raise [CArray::DataTypeError] when `self` is not an integer
+  #     `data_type`.
+  #   @raise [ArgumentError] when a label is negative or `weights`
+  #     length disagrees with `self.elements`.
+  #   @example
+  #     labels = CA_INT32([0, 1, 1, 2, 0, 1])
+  #     labels.bincount                    # => CA_UINT32([2, 3, 1])
+  #     labels.bincount(length: 5)         # => CA_UINT32([2, 3, 1, 0, 0])
+  #     weights = CA_DOUBLE([1, 2, 3, 4, 5, 6])
+  #     labels.bincount(weights: weights)  # => CA_DOUBLE([6, 11, 4])
+  def bincount(weights: nil, length: 0)
+    unless [CA_INT8, CA_INT16, CA_INT32, CA_INT64,
+            CA_UINT8, CA_UINT16, CA_UINT32, CA_UINT64].include?(data_type)
+      raise CArray::DataTypeError,
+            "bincount requires an integer label array (got #{data_type_name})"
+    end
+
+    if elements.zero?
+      if weights
+        out = CArray.new(weights.data_type, [length])
+      else
+        out_type = (length > 0xFFFFFFFF) ? CA_UINT64 : CA_UINT32
+        out = CArray.new(out_type, [length])
+      end
+      out.fill(0) unless length.zero?
+      return out
+    end
+
+    # Single-pass fused min+max so the prereq scan over labels costs
+    # one walk instead of two.
+    label_min, label_max = minmax
+    if label_min.equal?(UNDEF)
+      # Every cell is masked: no labels to count, same result as an empty
+      # input (all-zero output of the requested minimum length).
+      if weights
+        out = CArray.new(weights.data_type, [length])
+      else
+        out_type = (length > 0xFFFFFFFF) ? CA_UINT64 : CA_UINT32
+        out = CArray.new(out_type, [length])
+      end
+      out.fill(0) unless length.zero?
+      return out
+    end
+    if label_min < 0
+      raise ArgumentError,
+            "bincount: negative label not allowed (got #{label_min})"
+    end
+
+    n = [length, label_max + 1].max
+
+    if weights
+      unless weights.is_a?(CArray)
+        raise ArgumentError, "bincount: weights must be a CArray"
+      end
+      if weights.elements != elements
+        raise ArgumentError,
+              "bincount: weights length (#{weights.elements}) doesn't " \
+              "match labels length (#{elements})"
+      end
+      __bincount_weighted__(weights, n)
+    else
+      __bincount_count__(n)
+    end
+  end
+
+end