carray 2.0.0 → 3.0.0

data/lib/carray/methods/bit_string.rb

@@ -0,0 +1,92 @@
+# Pack / unpack an integer CArray to and from a packed-bit byte string,
+# +nb+ bits per element.
+
+class CArray
+
+  # @overload to_bit_string(nb)
+  #   Returns a packed-bit byte string built from `self`, using `nb`
+  #   bits per element.
+  #   @param nb [Integer] bits per element.
+  #   @return [String] byte string of length `ceil(nb * elements / 8)`.
+  def to_bit_string (nb)
+    hex = CArray.uint8(((nb*elements)/8.0).ceil)
+    hex.bits[nil].paste([0], self.bits[false,[(nb-1)..0]].flatten)
+    hex.bits[] = hex.bits[nil,[-1..0]]
+    return hex.to_s
+  end
+
+  # @overload from_bit_string(bstr, nb)
+  #   Sets `self` by unpacking `bstr` as a packed-bit byte string
+  #   with `nb` bits per element.
+  #   @param bstr [String] packed byte string.
+  #   @param nb [Integer] bits per element.
+  #   @return [self]
+  def from_bit_string (bstr, nb)
+    hex = CArray.uint8(bstr.length).load_binary(bstr)
+    hex.bits[] = hex.bits[nil,[-1..0]]
+    bits = hex.bits.flatten
+    self.bits[false,[(nb-1)..0]][nil].paste([0], bits)
+    return self
+  end
+
+  # @overload from_bit_string(bstr, nb, data_type = CA_INT32, dim = nil)
+  #   Returns a new CArray built by unpacking `bstr` as a packed-bit
+  #   byte string with `nb` bits per element.
+  #   @param bstr [String] packed byte string.
+  #   @param nb [Integer] bits per element.
+  #   @param data_type [Symbol, Integer] result `data_type`.
+  #   @param dim [Array<Integer>, nil] result shape; when `nil` the
+  #     length is `floor(bstr.length * 8 / nb)`.
+  #   @return [CArray]
+  def self.from_bit_string (bstr, nb, data_type=CA_INT32, dim=nil)
+    if dim
+      obj = CArray.new(data_type, dim)
+    else
+      dim0 = ((bstr.length*8)/nb.to_f).floor
+      obj = CArray.new(data_type, [dim0])
+    end
+    obj.from_bit_string(bstr, nb)
+    return obj
+  end
+
+  # @overload pack_bits
+  #   Packs a 1-D boolean / 0-1 uint8 CArray of length `n` into a uint8
+  #   CArray of `ceil(n / 8)` bytes, LSB-first within each byte. Exact
+  #   inverse of the `.bitarray` view's unpack direction: for any packed
+  #   uint8 array `p`, `p.bitarray.reshape(-1)[0...p.elements * 8].pack_bits`
+  #   round-trips to `p`. Tail bits of the last byte (when `n` is not a
+  #   multiple of 8) are zero-filled. The byte order matches the packed-bit
+  #   convention used by Apache Arrow validity bitmaps and PEP 3118 `?` /
+  #   `_Bool` at the bit level.
+  #   @return [CArray] uint8 CArray of shape `[ceil(n / 8)]`.
+  #   @raise [ArgumentError] when the receiver is not 1-D or its
+  #     `data_type` is not one of `CA_BOOLEAN` / `CA_UINT8` / `CA_INT8`.
+  def pack_bits
+    unless data_type == CA_BOOLEAN || data_type == CA_UINT8 || data_type == CA_INT8
+      raise ArgumentError,
+        "pack_bits: expected CA_BOOLEAN / CA_UINT8 / CA_INT8 (got #{data_type_name})"
+    end
+    raise ArgumentError, "pack_bits: 1-D CArray expected (got rank #{rank})" unless rank == 1
+    n = elements
+    n_bytes = (n + 7) / 8
+    packed = CArray.uint8(n_bytes) { 0 }
+    return packed if n == 0
+    packed.bitarray.reshape(-1)[0..n-1] = self
+    packed
+  end
+
+  # @overload validity_bits
+  #   Returns a packed uint8 CArray where bit `i` is 1 iff cell `i` of the
+  #   receiver is *not* masked (LSB-first, length `ceil(elements / 8)`).
+  #   Returns `nil` when the receiver has no mask; consumers such as Arrow
+  #   treat a missing bitmap as "all valid", so `nil` is the correct
+  #   omission-signalling value.
+  #   Equivalent to `is_not_masked.pack_bits` when a mask is present.
+  #   @return [CArray, nil] uint8 CArray of shape `[ceil(elements / 8)]`,
+  #     or `nil` when no mask is set.
+  def validity_bits
+    return nil unless has_mask?
+    is_not_masked.reshape(-1).pack_bits
+  end
+
+end

data/lib/carray/methods/broadcast.rb

@@ -0,0 +1,63 @@
+class CArray
+
+  # @overload broadcast(*argv, expand_scalar: false)
+  #   Returns each CArray argument broadcast to the common shape, or
+  #   yields the broadcast tuple to a block.
+  #
+  #   Non-CArray arguments (Float / Integer) pass through unchanged
+  #   unless `expand_scalar` is true. CScalar instances are treated
+  #   as ndim-0 scalars and excluded from the ndim check.
+  #
+  #   All real CArray arguments must share the same `ndim`; implicit
+  #   cross-ndim trailing-align is rejected. Insert size-1 axes with
+  #   `:_` to align explicitly, e.g. `arg[:_, nil]` turns `(N,)` into
+  #   `(1, N)` (row vector) and `arg[nil, :_]` turns it into `(N, 1)`
+  #   (column vector).
+  #
+  #   @param argv [Array<CArray, Numeric>] arguments to broadcast.
+  #   @param expand_scalar [Boolean] when true, also expand CScalar
+  #     and pass-through scalar arguments to the common shape.
+  #   @yieldparam broadcast [Array<CArray, Numeric>] the broadcast
+  #     arguments in input order.
+  #   @return [Array<CArray, Numeric>] broadcast arguments, or the
+  #     block's return value when a block is given.
+  #   @raise [ArgumentError] when CArray arguments differ in `ndim`.
+  def CArray.broadcast (*argv, expand_scalar: false, &block)
+
+    sel = argv.select { |arg| arg.is_a?(CArray) && !arg.is_a?(CScalar) }
+    return argv if sel.empty?
+
+    ndims = sel.map(&:ndim).uniq
+    if ndims.size > 1
+      shapes = argv.each_with_index
+                    .select { |a, _| a.is_a?(CArray) && !a.is_a?(CScalar) }
+                    .map { |a, i| "  arg[#{i}]: shape=(#{a.shape.join(', ')})" }
+      raise ArgumentError, <<~MSG.strip
+        CArray.broadcast: ndim mismatch (got #{ndims.sort.join(' and ')})
+        #{shapes.join("\n")}
+        CArray does not implicit-broadcast across ndim.  Insert a size-1
+        axis with :_ to align explicitly, e.g.
+          arg[:_, nil]   # (N,) -> (1, N)   row-vector
+          arg[nil, :_]   # (N,) -> (N, 1)   column-vector
+      MSG
+    end
+
+    ndim = sel.first.ndim
+    dim = (0...ndim).map { |k| sel.map { |a| a.shape[k] }.max }
+
+    list = argv.map do |arg|
+      case arg
+      when CScalar
+        expand_scalar ? arg.broadcast_to(*dim) : arg
+      when CArray
+        arg.broadcast_to(*dim)
+      else
+        expand_scalar ? arg : arg
+      end
+    end
+
+    return block.call(*list) if block
+    return list
+  end
+
+end

data/lib/carray/methods/choose.rb

@@ -0,0 +1,39 @@
+class CArray
+
+  # @overload choose(choices, data_type: nil)
+  #   Returns label-based per-cell selection: `self` is an integer
+  #   label array, and `choices` is a list indexed by those labels.
+  #
+  #   Where `self == i`, the result takes `choices[i]` -- a scalar
+  #   fills those cells, a CArray contributes its corresponding
+  #   cells. The result has the same shape as `self`.
+  #
+  #   @param choices [Array<CArray, Object>] values indexed by the
+  #     labels in `self`; each entry is either a same-shape CArray
+  #     or a scalar fill.
+  #   @param data_type [Symbol, Integer, nil] result `data_type`.
+  #     When `nil` it is inferred: `CArray.result_type` of the CArray
+  #     choices, or `CA_OBJECT` when every choice is a scalar.
+  #   @return [CArray] new CArray with the shape of `self` holding
+  #     the chosen values.
+  #   @example
+  #     ref = CA_INT([[0, 1, 2], [1, 2, 0], [2, 0, 1]])
+  #     a = CArray.int(3, 3).seq(1)
+  #     b = CArray.int(3, 3).seq(11)
+  #     c = CArray.int(3, 3).seq(21)
+  #     ref.choose([a, b, c])       # per-cell pick from a / b / c
+  #     ref.choose(["a", "b", "c"]) # recode labels to values
+  def choose (choices, data_type: nil)
+    unless data_type
+      ca = choices.select { |v| v.is_a?(CArray) }
+      data_type = ca.empty? ? CA_OBJECT : CArray.result_type(*ca)
+    end
+    out = template(data_type)
+    choices.each_with_index do |v, i|
+      s = self.eq(i)
+      out[s] = v.is_a?(CArray) ? v[s] : v
+    end
+    out
+  end
+
+end

data/lib/carray/methods/composition.rb

@@ -0,0 +1,280 @@
+# Composition methods cheat sheet (CArray 3.0 surface)
+#
+# The three class methods `meld` / `stack` / `montage` form a uniform-input
+# view-default surface; their ragged eager counterparts `concatenate` / --
+# / `mosaic` accept non-uniform pieces.
+#
+# This file holds the eager ragged family (`concatenate` / `mosaic`) and
+# the 1-D column bundler (`tabulate`).  `split` (the inverse of stack) lives
+# in carray/stack.rb; the sub-region copy pair (`paste` / `crop`) lives in
+# carray/basics.rb; the shape-edit helpers (`resize`, `insert_block` /
+# `delete_block`) live in carray/methods/.  The CAStack view-default trio
+# (`stack` / `meld` / `montage`, plus `CArray#stack` and `CAStack#append`)
+# lives in carray/stack.rb.  The cheat sheet below covers the whole family.
+#
+#                       | view (same dtype)      | eager (auto-cast)
+#   -------------------+------------------------+-----------------------
+#   concat existing    | meld  (CAMeld view)    | concatenate (materialised)
+#   axis (ndim same)   |                        |
+#   -------------------+------------------------+-----------------------
+#   add new axis       | stack (CAStack view)   | (= ragged impossible)
+#   (ndim grows)       |                        |
+#   -------------------+------------------------+-----------------------
+#   tile grid          | montage                | mosaic (materialised)
+#   (ndim same, axes   |                        |
+#   extend by tdim)    |                        |
+#
+# `meld` (CAMeld view) is the unified surface for concatenation along an
+# existing axis: it handles both uniform and ragged pieces and returns a
+# CAMeld view.  Parents must agree on data_type — cast beforehand or use
+# `concatenate` (eager, auto-casts).
+#
+# Vocabulary:
+#   meld    = melt + weld; pieces dissolve their boundaries along the
+#             named axis and are regarded as one; returns a CAMeld view
+#   stack   = K parents pushed onto a new K axis (CAStack view)
+#   montage = uniform tiles arranged in a regular grid (ImageMagick)
+#   concatenate = 1-axis concat, eager materialised copy with auto-cast
+#   mosaic  = irregular pieces fitted into a grid (art-form analog)
+#
+# Examples (a, b, c are each shape [3, 4]):
+#
+#   CArray.meld([a, b, c])                        #=> view, shape (9, 4)
+#   CArray.meld([a, b, c], axis: 1)               #=> view, shape (3, 12)
+#   CArray.meld([a, b, c]).to_ca                  #=> eager CArray, shape (9, 4)
+#   CArray.stack([a, b, c])                       #=> view, shape (3, 3, 4)   (K outermost)
+#   CArray.stack([a, b, c], axis: -1)             #=> view, shape (3, 4, 3)   (RGB pattern)
+#   CArray.montage([a, b, c, d], [2, 2], axis: 0) #=> view, shape (6, 8) (2x2 image tile)
+#
+#   # data_type is a kwarg (= 3.0 breaking); omitted = result_type auto-infer
+#   CArray.meld([a, b, c], axis: 0, data_type: :float64)
+#   CArray.meld([a, b, c])                        # data_type inferred
+#
+# `tabulate` bundles a list of 1-D arrays into a 2-D table (one column
+# each).  Block-matrix assembly is `mosaic`; vertical stacking of 2-D
+# tables is `concatenate(axis: 0)`.  (The old `join` / block-style
+# helper was retired in 3.0 -- its column-major nesting was confusing and
+# `mosaic` covers block assembly correctly.)
+#
+# Known limitation: scalar indexing on a CAStack-rooted view drops ndim
+# and triggers a full materialise fallback.  Use range indexing (e.g.
+# `meld(...)[k..k, nil]` instead of `meld(...)[k, nil]`) for partial-use
+# perf, or `.to_ca` upfront to materialise eagerly.
+
+class CArray
+
+  # CArray#paste / #crop (sub-region copy) live in carray/basics.rb.
+
+  # ---------------------------------------------------------------- eager ragged 2
+
+  # @overload concatenate(list, axis: 0, data_type: nil)
+  #   Returns `list` concatenated along a single existing axis. Eager
+  #   (returns a fresh CArray) and accepts non-uniform pieces (varying
+  #   sizes along the `axis`); non-tile axes must agree across pieces.
+  #
+  #   Use `CArray.meld` for the uniform-shape view-default counterpart.
+  #
+  #   @param list [Array<CArray>] pieces to concatenate.
+  #   @param axis [Integer] axis to concatenate along.
+  #   @param data_type [Symbol, Integer, nil] result `data_type`;
+  #     inferred via `result_type` when `nil`.
+  #   @return [CArray] fresh CArray with per-piece `axis` sizes summed.
+  #   @raise [ArgumentError] when `list` is empty or piece shapes are
+  #     inconsistent.
+  def self.concatenate (list, axis: 0, data_type: nil)
+    raise ArgumentError, "concatenate: list must not be empty" if list.empty?
+    __ragged_paste(list, [list.size], axis, data_type)
+  end
+
+  # @overload concatenate(*others, axis: 0, data_type: nil)
+  #   Instance form of {CArray.concatenate}: returns `[self, *others]`
+  #   concatenated along `axis` as a fresh CArray. Eager auto-cast
+  #   counterpart of `#meld` (view).
+  #
+  #   @param others [Array<CArray>] additional pieces.
+  #   @param axis [Integer] axis to concatenate along.
+  #   @param data_type [Symbol, Integer, nil] result `data_type`;
+  #     inferred via `result_type` when `nil`.
+  #   @return [CArray] fresh CArray.
+  #   @raise [ArgumentError] when no `others` are given.
+  def concatenate (*others, axis: 0, data_type: nil)
+    raise ArgumentError, "concatenate: at least one other array required" if others.empty?
+    CArray.concatenate([self, *others], axis: axis, data_type: data_type)
+  end
+
+  # @overload mosaic(list, tdim, axis: 0, data_type: nil)
+  #   Returns `list` tiled into an N-D grid layout described by
+  #   `tdim`. Eager (returns a fresh CArray), accepts non-uniform
+  #   sizes along the tile axes with block-matrix consistency
+  #   (row-by-row / column-by-column agreement).
+  #
+  #   @param list [Array<CArray>] pieces to tile; length must equal
+  #     the product of `tdim`.
+  #   @param tdim [Array<Integer>] tile grid shape.
+  #   @param axis [Integer] first tile axis in the result.
+  #   @param data_type [Symbol, Integer, nil] result `data_type`;
+  #     inferred when `nil`.
+  #   @return [CArray] fresh CArray with tile axes extended by summed
+  #     per-tile sizes.
+  #   @raise [ArgumentError] when `list` is empty, `tdim` is
+  #     ill-formed, or piece shapes violate block-matrix consistency.
+  def self.mosaic (list, tdim, axis: 0, data_type: nil)
+    raise ArgumentError, "mosaic: list must not be empty" if list.empty?
+    unless tdim.is_a?(Array) && tdim.size > 0
+      raise ArgumentError, "mosaic: tdim must be a non-empty Array of Integer"
+    end
+    expected = tdim.inject(1, :*)
+    unless expected == list.size
+      raise ArgumentError,
+            "mosaic: tdim product (#{expected}) must equal list size (#{list.size})"
+    end
+    __ragged_paste(list, tdim, axis, data_type)
+  end
+
+  # Shared eager paste-loop helper (= ex-`combine` paste implementation,
+  # preserved verbatim for concatenate / mosaic).  Returns a fresh CArray of
+  # shape obtained by tiling `list` over `tdim` starting at `axis`, with
+  # per-piece dim sizes summed along each tile axis (= block-matrix
+  # consistency required across rows / columns).
+  def self.__ragged_paste (list, tdim, axis, data_type)
+    list = CArray.promote_list(list, data_type: data_type)
+    # promote_list has already enforced homogeneity (= common data_type, and
+    # for Face elements: same Face class + portable + state-compatible).  So,
+    # mirroring CArray.stack, paste at the storage level and re-wrap the
+    # result with face_lift, rather than special-casing data_class / DATA_SIZE
+    # here (= which only ever handled CARecord and silently corrupted plain
+    # fixlen / numeric Faces by leaving bytes nil).
+    face_parent = list[0].face? ? list[0] : nil
+    if face_parent
+      list = list.map { |x| s = x; s = s.parent while s.face?; s }
+    end
+    data_type = list[0].data_type
+    bytes     = (data_type == :fixlen) ? list[0].bytes : nil
+    # promote_list guarantees a non-empty list of CArrays, so the reference
+    # shape is simply the first element (a CScalar carries shape [1], so a
+    # leading scalar is fine; the scalar-expansion pass below broadcasts it).
+    ref  = list[0]
+    dim   = ref.shape
+    ndim  = ref.ndim
+    tndim = tdim.size
+    axis = CArray.normalize_axis(axis, ndim - tndim + 1, "concatenate/mosaic")
+
+    list = list.map do |x|
+      if x.scalar?
+        rdim = dim.clone
+        rdim[axis] = :%
+        x = x[*rdim]
+      end
+      x
+    end
+
+    block = CArray.object(*tdim).tap { |a| a[] = list }
+    # Measure the per-tile-axis sizes from the representative line (= all
+    # other tile coords 0).  Tile axes may be ragged, but every piece must
+    # then be block-matrix consistent (= same size along a tile axis as its
+    # line) and must agree with the reference on each non-tile axis.
+    edim = tdim.clone
+    tile_sizes = Array.new(tndim) { [] }
+    offset = Array.new(tndim) { [] }
+    probe  = Array.new(tndim, 0)
+    tndim.times do |i|
+      edim[i] = 0
+      probe.map! { 0 }
+      probe[i] = nil
+      block[*probe].each do |e|
+        offset[i] << edim[i]
+        tile_sizes[i] << e.shape[axis + i]
+        edim[i] += e.shape[axis + i]
+      end
+    end
+    block.each_with_index do |item, *tidx|
+      unless item.ndim == ndim
+        raise ArgumentError,
+              "concatenate/mosaic: piece at tile #{tidx.inspect} has ndim " \
+              "#{item.ndim} (expected #{ndim})"
+      end
+      ndim.times do |d|
+        i = d - axis
+        on_tile  = (i >= 0 && i < tndim)
+        expected = on_tile ? tile_sizes[i][tidx[i]] : dim[d]
+        unless item.shape[d] == expected
+          raise ArgumentError,
+                "concatenate/mosaic: piece at tile #{tidx.inspect} has " \
+                "#{on_tile ? 'tile' : 'non-tile'} axis #{d} size " \
+                "#{item.shape[d]} (expected #{expected}); pieces must agree " \
+                "on non-tile axes and be block-matrix consistent along tile axes"
+        end
+      end
+    end
+    newdim = dim.clone
+    newdim[axis, tndim] = edim
+    obj = CArray.new(data_type, newdim, bytes: bytes)
+    idx = newdim.map { 0 }
+    block.each_with_index do |item, *tidx|
+      (axis...axis + tndim).each_with_index do |d, i|
+        idx[d] = offset[i][tidx[i]]
+      end
+      obj.paste(idx, item)
+    end
+    obj = obj.face_lift(face_parent) if face_parent
+    obj
+  end
+  private_class_method :__ragged_paste
+
+  # ---------------------------------------------------------------- tabulate
+
+  # @overload tabulate(columns, data_type: nil)
+  #   Returns a 2-D table assembled from a list of column blocks,
+  #   coerced to a common `data_type`. Eager (returns a fresh, owned
+  #   CArray) -- the point is to materialise a typed table, not a view.
+  #
+  #   Each entry is a 1-D array (one column, length L) or a 2-D array
+  #   (a block of `L x k` columns). All entries must share the same
+  #   length L; `tabulate` does not pad ragged lengths. Column counts
+  #   may differ: entries are concatenated along the column axis, so
+  #   a 1-column, a 3-column and a 2-column block produce a 6-column
+  #   table. The result `data_type` is inferred (`result_type` of the
+  #   entries) unless `data_type` is given.
+  #
+  #   For block-matrix assembly use `mosaic`; to stack 2-D tables
+  #   vertically use `concatenate(axis: 0)`.
+  #
+  #   @param columns [Array<CArray>] 1-D columns and/or 2-D column
+  #     blocks, all of equal length `L`.
+  #   @param data_type [Symbol, Integer, nil] result `data_type`;
+  #     inferred when `nil`.
+  #   @return [CArray] 2-D CArray of shape `(L, total column count)`.
+  #   @raise [ArgumentError] when `columns` is empty, entries are
+  #     not 1-D or 2-D CArrays, or row counts disagree.
+  #   @example
+  #     c1 = CA_INT([1, 2, 3])
+  #     c2 = CA_DOUBLE([4.5, 5.5, 6.5])
+  #     CArray.tabulate([c1, c2])                      # float64 (3, 2)
+  #     CArray.tabulate([c1, c2], data_type: :int32)   # int32 (3, 2)
+  def self.tabulate (columns, data_type: nil)
+    raise ArgumentError, "tabulate: columns must not be empty" if columns.empty?
+    blocks = columns.map do |c|
+      unless c.is_a?(CArray) && (c.ndim == 1 || c.ndim == 2)
+        raise ArgumentError, "tabulate: each column must be a 1-D or 2-D CArray"
+      end
+      c.ndim == 1 ? c[nil, :_] : c          # promote a bare column to (L, 1)
+    end
+    len = blocks[0].shape[0]
+    blocks.each_with_index do |b, i|
+      unless b.shape[0] == len
+        raise ArgumentError,
+              "tabulate: all columns must have equal length (row count) " \
+              "(column 0 has length #{len}, column #{i} has length " \
+              "#{b.shape[0]}); tabulate does not pad ragged lengths"
+      end
+    end
+    # Equal-length blocks, ragged column counts -> concatenate along the
+    # column axis with a common (coerced or inferred) data_type.
+    concatenate(blocks, axis: 1, data_type: data_type)
+  end
+
+  # CArray#split (the inverse of CArray.stack) lives in carray/stack.rb,
+  # next to stack.  CArray#resize / #insert_block / #delete_block live in
+  # carray/methods/ (resize.rb, insert_block.rb), autoloaded.
+
+end

data/lib/carray/methods/gather_nd.rb

@@ -0,0 +1,206 @@
+#  N-D arbitrary-position gather / scatter (CArray implementation of
+#  TensorFlow `gather_nd` / `scatter_nd_update`).
+#
+#  Natural N-D extension of `take_along_axis` (= fiber-aligned gather along axis).
+#  Treats the trailing K axes of `indices.shape = (..., K)` as coordinate tuples
+#  and consumes the first K axes of params while carrying the remaining axes (= rest).
+#
+#  Implementation goes through a CAMapping view of the flattened array:
+#  `params.flatten[flat_addr]`.  Pure Ruby, no additional framework, composed
+#  entirely from existing indexers as in `take_along_axis`.  Since CAMapping is
+#  writable, write-through via `put_nd` uses last-write-wins semantics (= last
+#  value wins on duplicate indices, same contract as `put_along_axis`).  For
+#  accumulate semantics, route to the `scatter_*!` family instead.
+
+class CArray
+
+  # @overload gather_nd(indices)
+  #   Returns elements (or sub-arrays) gathered from `self` at the
+  #   N-D coordinates given by `indices`.
+  #
+  #   `indices` accepts two equivalent forms:
+  #
+  #   * **stacked** — a single CArray whose last axis enumerates a
+  #     K-dimensional coordinate tuple into the first K axes of `self`.
+  #   * **per-axis** — an `Array` of K coordinate CArrays (one per
+  #     consumed axis).  The per-axis arrays are broadcast together
+  #     (via {CArray.broadcast}) and stacked along a new trailing axis,
+  #     so `gather_nd([i, j])` == `gather_nd(CArray.stack([i, j], axis: -1))`.
+  #     An Integer scalar is accepted for a constant axis and broadcast
+  #     to the common shape.  Entries must be CArray or Integer: Ruby
+  #     Array literals are rejected (wrap them with `CA_INT64(...)`
+  #     yourself), keeping this a copy-free gather path.
+  #
+  #   The remaining `self.shape[K..-1]` axes (called `rest`) are carried
+  #   through:
+  #
+  #       self.shape    = (D0, ..., D_{K-1}, *rest)
+  #       indices.shape = (*outer, K)          # stacked form
+  #       result.shape  = (*outer, *rest)
+  #
+  #   In the fully-degenerate case where both `outer` and `rest` are
+  #   empty (a single full coordinate via 1-D `indices` of shape `(K,)`
+  #   with `K == ndim`), the result is a 1-element `(1,)` CArray,
+  #   following CArray's scalar model (CScalar carries shape `[1]`),
+  #   not a 0-dim array.
+  #
+  #   The result is a fresh materialised CArray. Negative indices on
+  #   each coordinate axis follow CArray's standard wrap rule
+  #   (`-1` == last); out-of-range indices raise. Duplicate
+  #   coordinates in `indices` are fine on gather: the same value is
+  #   picked multiple times. See {#put_nd} for the duplicate-write
+  #   story.
+  #
+  #   @param indices [CArray, Array<CArray, Integer>] stacked integer
+  #     CArray with `ndim >= 1` and last axis size `K` in `[1, ndim]`,
+  #     or an Array of K per-axis coordinate CArrays (Integer scalars
+  #     allowed per axis).
+  #   @return [CArray] materialised result with shape `outer + rest`.
+  #   @raise [ArgumentError] when `indices` is neither a CArray nor an
+  #     Array, is 0-dim, is non-integer, or has a last-axis size
+  #     outside `[1, ndim]`.
+  #   @raise [IndexError] when a coordinate is out of range on any axis.
+  def gather_nd (indices)
+    flat_addr, outer, rest = gather_nd_flat_addr(indices, "gather_nd")
+    out_shape = outer + rest
+    # flatten + 1-D fancy indexing -> CAMapping view -> materialise via .copy.
+    result = self.flatten[flat_addr].copy
+    out_shape.empty? ? result : result.reshape(*out_shape)
+  end
+
+  # @overload put_nd(indices, values)
+  #   Sets `self` at the N-D coordinates given by `indices` to
+  #   `values`. Inverse of {#gather_nd}.
+  #
+  #       self.shape    = (D0, ..., D_{K-1}, *rest)
+  #       indices.shape = (*outer, K)
+  #       values          broadcast to (*outer, *rest)
+  #
+  #   Duplicate coordinates in `indices` use **last-write-wins**
+  #   semantics, matching `put_along_axis`. Accumulate semantics
+  #   (`+=`) are not provided here; route to the `scatter_*!`
+  #   family instead (e.g. `self.flatten.scatter_add!(flat_addr, vals)`).
+  #
+  #   @param indices [CArray, Array<CArray, Integer>] stacked integer
+  #     CArray shaped `(*outer, K)`, or an Array of K per-axis
+  #     coordinate arrays (same forms as {#gather_nd}).
+  #   @param values [CArray, Numeric] values broadcastable to
+  #     `(*outer, *rest)`.
+  #   @return [self]
+  #   @raise [ArgumentError] on the same conditions as {#gather_nd}.
+  #   @raise [IndexError] when a coordinate is out of range on any axis.
+  def put_nd (indices, values)
+    flat_addr, _outer, _rest = gather_nd_flat_addr(indices, "put_nd")
+    self.flatten[flat_addr] = values
+    self
+  end
+
+  private
+
+  # Shared helper: compute the flat-address CArray (shape = outer + rest)
+  # for both `gather_nd` and `put_nd`.  Returns `[flat_addr, outer, rest]`.
+  def gather_nd_flat_addr (indices, name)
+    # Per-axis form: an Array of K coordinate arrays.  Broadcast them to a
+    # common outer shape and stack along a new trailing axis, yielding the
+    # (*outer, K) stacked form the rest of this helper already handles.
+    indices = gather_nd_stack_axes(indices, name) if indices.is_a?(Array)
+
+    unless indices.is_a?(CArray)
+      raise ArgumentError, "#{name}: indices must be a CArray or an Array of per-axis CArrays"
+    end
+    if indices.ndim == 0
+      raise ArgumentError, "#{name}: indices must have at least 1 dimension"
+    end
+    unless indices.integer?
+      raise ArgumentError,
+            "#{name}: indices must be an integer CArray (got #{indices.data_type})"
+    end
+
+    k = indices.shape[-1]
+    unless k.is_a?(Integer) && k >= 1 && k <= ndim
+      raise ArgumentError,
+            "#{name}: indices last-axis size #{k} out of [1, #{ndim}]"
+    end
+
+    outer = indices.shape[0..-2]            # may be []
+    rest  = (k < ndim) ? shape[k..-1] : []  # may be []
+    m     = outer.empty? ? 1 : outer.inject(:*)
+    rest_size = rest.empty? ? 1 : rest.inject(:*)
+
+    # Stride per consumed axis i = product of params.shape[(i+1)..-1]
+    # (covers remaining consumed axes + all rest axes).
+    strides_a = (0...k).map { |i| shape[(i+1)..-1].inject(1, :*) }
+    strides   = CA_INT64(strides_a).reshape(1, k)
+
+    # Per-axis dimension for negative-index normalize + OOB check.
+    dims = CA_INT64(shape[0...k]).reshape(1, k)
+
+    flat_idx_raw = indices.reshape(m, k)
+
+    # OOB check (per-axis): require -dim <= idx < dim on every coordinate.
+    if (flat_idx_raw >= dims).any
+      raise IndexError, "#{name}: coordinate >= dim on some axis"
+    end
+    if (flat_idx_raw < -dims).any
+      raise IndexError, "#{name}: coordinate < -dim on some axis"
+    end
+
+    # Wrap negatives: (-dim..-1) -> (0..dim-1) via (idx + dim) % dim.
+    # Safe under -dim <= idx < dim (just checked).
+    flat_idx = (flat_idx_raw + dims) % dims
+
+    base     = (flat_idx * strides).sum(axis: 1).int64.reshape(m)  # (M,)
+
+    flat_addr =
+      if rest.empty?
+        base                                # (M,)
+      else
+        offsets = CArray.int64(rest_size).seq
+        base.reshape(m, 1) + offsets.reshape(1, rest_size)  # (M, rest_size)
+      end
+
+    [flat_addr, outer, rest]
+  end
+
+  # Convert the per-axis form (an Array of K coordinate arrays) into the
+  # stacked `(*outer, K)` CArray.  Coordinate arrays are broadcast to a
+  # common `outer` shape (via CArray.broadcast, which rejects cross-ndim
+  # implicit align) and stacked along a new trailing axis.  Integer
+  # scalars are accepted per axis and expand to the common shape; an
+  # all-scalar list yields the 1-D `(K,)` single-coordinate form.
+  def gather_nd_stack_axes (list, name)
+    if list.empty?
+      raise ArgumentError, "#{name}: coordinate list must not be empty"
+    end
+
+    # This is a high-performance gather path: per-axis entries must be
+    # CArray coordinate arrays (or a bare Integer scalar for a constant
+    # axis).  Ruby Arrays are rejected on purpose -- coercing them via
+    # CA_INT64 on every call would defeat the point of the API; wrap them
+    # yourself once (CA_INT64(...)) if you have array literals.
+    list.each do |c|
+      unless c.is_a?(CArray) || c.is_a?(Integer)
+        raise ArgumentError,
+              "#{name}: per-axis coordinate must be a CArray or Integer (got #{c.class})"
+      end
+    end
+
+    # All scalars -> a single K-coordinate tuple (degenerate stacked form).
+    if list.none? { |c| c.is_a?(CArray) }
+      return CA_INT64(list)
+    end
+
+    coords = CArray.broadcast(*list, expand_scalar: true)
+    ref    = coords.find { |c| c.is_a?(CArray) && !c.is_a?(CScalar) }
+    coords = coords.map do |c|
+      case c
+      when CArray
+        c
+      else                       # Integer scalar on this axis
+        CArray.int64(*ref.shape) { c }
+      end
+    end
+    CArray.stack(coords, axis: -1)
+  end
+
+end