Contents

BNNSGatherND(_:_:_:_:)

Gathers the slices of a tensor.

Declaration

func BNNSGatherND(_ input: UnsafePointer<BNNSNDArrayDescriptor>, _ indices: UnsafePointer<BNNSNDArrayDescriptor>, _ output: UnsafeMutablePointer<BNNSNDArrayDescriptor>, _ filter_params: UnsafePointer<BNNSFilterParameters>?) -> Int32

Parameters

  • input:

    A pointer to the input descriptor.

  • indices:

    A pointer to the indices descriptor.

  • output:

    A pointer to the output descriptor.

  • filter_params:

    The filter runtime parameters.

Discussion

Use BNNSGatherND(_:_:_:_:) to gather slices — that you specify by index — into an output tensor.

The function interprets the indices array as a k - 1 dimensional set of lookup vectors, therefore, the indices tensor must have (k - 1) + 1 or k dimensions.

If the lookup vectors don’t define a full set of indices, the function treats the undefined indices as a slice.

For example, given the following input values:

let values: [Float] = [10, 11,
                       12, 13,
                       
                       20, 21,
                       22, 23,
                       
                       30, 31,
                       32, 33]

var inputDescriptor = BNNSNDArrayDescriptor.allocate(
    initializingFrom: values,
    shape: .tensor3DFirstMajor(3, 2, 2))

The following code shows that a scalar index gathers a 2D slice:

let indices: [Int32] = [1] // Elements `20, 21, 22, 23` from slice `1`
var indicesDescriptor = BNNSNDArrayDescriptor.allocate(
    initializingFrom: indices,
    shape: .vector(1))

var outputDescriptor = BNNSNDArrayDescriptor.allocateUninitialized(
    scalarType: Float.self,
    shape: .matrixFirstMajor(2, 2))

let error = BNNSGatherND(&inputDescriptor,
                         &indicesDescriptor,
                         &outputDescriptor,
                         nil)
                         
// `outputDescriptor` contains `[20.0, 21.0, 22.0, 23.0]`

The following code shows that a 2D index gathers a 1D slice:

let indices: [Int32] = [1, 0] // Elements `20, 21` from row `0` of slice `1`
var indicesDescriptor = BNNSNDArrayDescriptor.allocate(
    initializingFrom: indices,
    shape: .matrixFirstMajor(1, 2))

var outputDescriptor = BNNSNDArrayDescriptor.allocateUninitialized(
    scalarType: Float.self,
    shape: .matrixFirstMajor(1, 2))

let error = BNNSGatherND(&inputDescriptor,
                         &indicesDescriptor,
                         &outputDescriptor,
                         nil)

// `outputDescriptor` contains `[20.0, 21.0]`

The following code shows that a 3D index gathers a single element:

let indices: [Int32] = [1, 1, 1] // Element `23` (index `1`) from row `1` of slice `1`
var indicesDescriptor = BNNSNDArrayDescriptor.allocate(
    initializingFrom: indices,
    shape: .tensor3DFirstMajor(1, 1, 3))

var outputDescriptor = BNNSNDArrayDescriptor.allocateUninitialized(
    scalarType: Float.self,
    shape: .matrixFirstMajor(1, 1))

let error = BNNSGatherND(&inputDescriptor,
                         &indicesDescriptor,
                         &outputDescriptor,
                         nil)
                         
// `outputDescriptor` contains `[23.0]`

See Also

Gather and scatter operations