Contents

clipByNorm(threshold:input:output:axes:)

Clips the input tensor to a Euclidean norm and writes the result to the output tensor.

Declaration

static func clipByNorm(threshold: Float, input: BNNSNDArrayDescriptor, output: BNNSNDArrayDescriptor, axes: [Int]? = nil) throws

Parameters

  • threshold:

    The maximum Euclidean norm to clip the gradient to.

  • input:

    The descriptor of the input.

  • output:

    The descriptor of the output.

  • axes:

    The dimensions that the function uses to compute the Euclidean norm. Set to 0 to specify that the function computes the norm over all dimensions.

Discussion

Use this function to clip the values in an input tensor to a maximum Euclidean norm. The Euclidean norm is the square root of the sum of squares of the two tensors.

The function supports clipping across the entire tensor or by the norms of a dimension.

The following code clips the values on axis 1 to a Euclidean norm of 10. The Euclidean norms of [1, 2, 3] and [4, 5, 6] are both less than 10 and function returns them unchanged. However, the Euclidean norm of [7, 8, 9] is greater than 10 and the function returns them scaled accordingly.

static func clipToNorm() {
    let inputValues: [Float] = [1, 2, 3,
                                4, 5, 6,
                                7, 8, 9]
    
    let input = BNNSNDArrayDescriptor.allocate(
        initializingFrom: inputValues,
        shape: .matrixRowMajor(3, 3))
    let output = BNNSNDArrayDescriptor.allocateUninitialized(
        scalarType: Float.self,
        shape: input.shape)
    
    try? BNNS.clipByNorm(threshold: 10,
                        input: input,
                        output: output,
                        axes: [1])
    
    // Prints `[1.0, 2.0, 3.0,
    //          4.0, 5.0, 6.0,
    //          5.0257072, 5.743665, 6.461623]`
    print(output.makeArray(of: Float.self)!)

    input.deallocate()
    output.deallocate()
}

See Also

Utility functions