Contents

BNNSClipByGlobalNorm(_:_:_:_:_:)

Clips a tensor’s values to a maximum global Euclidean norm.

Declaration

func BNNSClipByGlobalNorm(_ dest: UnsafeMutablePointer<UnsafeMutablePointer<BNNSNDArrayDescriptor>>, _ src: UnsafeMutablePointer<UnsafePointer<BNNSNDArrayDescriptor>>, _ count: Int, _ max_norm: Float, _ use_norm: Float) -> Int32

Parameters

  • dest:

    An array of output descriptors.

  • src:

    An array of input descriptors.

  • count:

    The number of input and output descriptors.

  • max_norm:

    The maximum global Euclidean norm.

  • use_norm:

    An optional value for a known global Euclidean norm. Set to 0 to specify that the function computes the norm from the input descriptors.

Discussion

Use this function to clip the values in an array of input tensors to a maximum Euclidean norm. If you know the global norm of the input tensors, pass this value as the use_norm. Otherwise, pass 0 to specify that the function calculates the norm.

The Euclidean norm is the square root of the sum of squares of the two tensors. The following code clips the Euclidean norm of two input tensors to half of the global Euclidean norm:

static func clipToGlobalNorm() {
    
    let inputOneData = UnsafeMutableBufferPointer<Float>.allocate(capacity: 4)
    _ = inputOneData.initialize(from: [1, 2, 3, 4])
    let inputOneDescriptor = BNNSNDArrayDescriptor(flags: BNNSNDArrayFlags(0),
                                                   layout: BNNSDataLayoutVector,
                                                   size: (4, 0, 0, 0, 0, 0, 0, 0),
                                                   stride: (0, 0, 0, 0, 0, 0, 0, 0),
                                                   data: inputOneData.baseAddress!,
                                                   data_type: BNNSDataType.float,
                                                   table_data: nil,
                                                   table_data_type: BNNSDataType.float,
                                                   data_scale: 1, data_bias: 0)
    
    let inputTwoData = UnsafeMutableBufferPointer<Float>.allocate(capacity: 4)
    _ = inputTwoData.initialize(from: [5, 6, 7, 8])
    let inputTwoDescriptor = BNNSNDArrayDescriptor(flags: BNNSNDArrayFlags(0),
                                                   layout: BNNSDataLayoutVector,
                                                   size: (4, 0, 0, 0, 0, 0, 0, 0),
                                                   stride: (0, 0, 0, 0, 0, 0, 0, 0),
                                                   data: inputTwoData.baseAddress!,
                                                   data_type: BNNSDataType.float,
                                                   table_data: nil,
                                                   table_data_type: BNNSDataType.float,
                                                   data_scale: 1, data_bias: 0)
    
    let outputOneData = UnsafeMutableBufferPointer<Float>.allocate(capacity: 4)
    let outputOneDescriptor = BNNSNDArrayDescriptor(flags: BNNSNDArrayFlags(0),
                                                    layout: BNNSDataLayoutVector,
                                                    size: (4, 0, 0, 0, 0, 0, 0, 0),
                                                    stride: (0, 0, 0, 0, 0, 0, 0, 0),
                                                    data: outputOneData.baseAddress!,
                                                    data_type: BNNSDataType.float,
                                                    table_data: nil,
                                                    table_data_type: BNNSDataType.float,
                                                    data_scale: 1, data_bias: 0)
    
    let outputTwoData = UnsafeMutableBufferPointer<Float>.allocate(capacity: 4)
    let outputTwoDescriptor = BNNSNDArrayDescriptor(flags: BNNSNDArrayFlags(0),
                                                    layout: BNNSDataLayoutVector,
                                                    size: (4, 0, 0, 0, 0, 0, 0, 0),
                                                    stride: (0, 0, 0, 0, 0, 0, 0, 0),
                                                    data: outputTwoData.baseAddress!,
                                                    data_type: BNNSDataType.float,
                                                    table_data: nil,
                                                    table_data_type: BNNSDataType.float,
                                                    data_scale: 1, data_bias: 0)
    
    let inputs = [inputOneDescriptor, inputTwoDescriptor]
    var inputsPointers: [UnsafePointer<BNNSNDArrayDescriptor>] = inputs.map { input in
        var descriptor = input
        
        let inputPtr = UnsafeMutablePointer<BNNSNDArrayDescriptor>.allocate(capacity: 1)
        inputPtr.initialize(from: &descriptor, count: 1)
        
        return UnsafePointer(inputPtr)
    }
    
    let outputs = [outputOneDescriptor, outputTwoDescriptor]
    var outputsPointers: [UnsafeMutablePointer<BNNSNDArrayDescriptor>] = outputs.map { output in
        var descriptor = output
        
        let outputPtr = UnsafeMutablePointer<BNNSNDArrayDescriptor>.allocate(capacity: 1)
        outputPtr.initialize(from: &descriptor, count: 1)
        
        return outputPtr
    }
    
    BNNSClipByGlobalNorm(&outputsPointers,
                         &inputsPointers,
                         2,
                         0.5 * 14.2828568570857,
                         0)
    
    // Prints: `[0.5, 1.0, 1.5, 2.0]`
    print(Array(outputOneData))
    
    // Prints: `[2.5, 3.0, 3.5, 4.0]`
    print(Array(outputTwoData))
    
    inputOneData.deallocate()
    inputTwoData.deallocate()
    outputOneData.deallocate()
    outputTwoData.deallocate()
}

On return, outputOne contains the values [0.5, 1.0, 1.5, 2.0], and outputTwo contains the values [2.5, 3.0, 3.5, 4.0].

See Also

Utility functions