Package apple.metalperformanceshaders

Class MPSRNNMatrixTrainingLayer

  • All Implemented Interfaces:
    NSCoding, NSCopying, NSSecureCoding, NSObject
    public class MPSRNNMatrixTrainingLayer
extends MPSKernel
    MPSRNNMatrixTrainingLayer [@dependency] This depends on Metal.framework The MPSRNNMatrixTrainingLayer specifies a recurrent neural network layer for training on MPSMatrices. A MPSRNNMatrixTrainingLayer is initialized using a @ref MPSRNNLayerDescriptor, which further specifies the recurrent network layer. The input and output vectors in encode calls are stored as rows of the input and output matrices and MPSRNNMatrixTrainingLayer supports matrices with decreasing number of rows: The row-indices identify the different sequences that may be of different lengths - for example if we have three sequences: ( x1, x2, x3 ), ( y1, y2, y3, y4 ) and ( z1, z2 ) of vectors xi, yi and zi, then these can be inserted together as a batch to the sequence encoding kernel by using the matrices: [@code] ( y1 ) ( y2 ) ( y3 ) ( y4 ) m1 = ( x1 ), m2 = ( x2 ), m3 = ( x3 ), m4 = ( z1 ) ( z2 ) [@endcode] The gradient computation pass is then achieved by passing the corresponding gradient sequence from the previous layer ( dx1, dx2, dx3 ), ( dy1, dy2, dy3, dy4 ) and ( dz1, dz2 ) as matrices [@code] ( dy1 ) ( dy2 ) ( dy3 ) ( dy4 ) dm1 = ( dx1 ), dm2 = ( dx2 ), dm3 = ( dx3 ), dm4 = ( dz1 ) ( dz2 ) [@endcode] The mathematical operation described in the linear transformations of @ref MPSRNNSingleGateDescriptor [@ref] MPSLSTMDescriptor and @ref MPSGRUDescriptor are y^T = W x^T <=> y = x W^T, where x is the matrix containing the input vectors as rows, y is the matrix containing the output vectors as rows and W is the weight matrix.

    • Constructor Detail

      • MPSRNNMatrixTrainingLayer

        protected MPSRNNMatrixTrainingLayer​(org.moe.natj.general.Pointer peer)

    • Method Detail

      • accessInstanceVariablesDirectly

        public static boolean accessInstanceVariablesDirectly()

      • accumulateWeightGradients

        public boolean accumulateWeightGradients()
        [@property] accumulateWeightGradients If yes then the computed weight gradients are accumulated on top of existing values in calls to the gradient computation functions: encodeGradientSequenceToCommandBuffer. Defaults to NO.

      • allocWithZone

        public static java.lang.Object allocWithZone​(org.moe.natj.general.ptr.VoidPtr zone)

      • automaticallyNotifiesObserversForKey

        public static boolean automaticallyNotifiesObserversForKey​(java.lang.String key)

      • cancelPreviousPerformRequestsWithTarget

        public static void cancelPreviousPerformRequestsWithTarget​(java.lang.Object aTarget)

      • cancelPreviousPerformRequestsWithTargetSelectorObject

        public static void cancelPreviousPerformRequestsWithTargetSelectorObject​(java.lang.Object aTarget,
                                                                         org.moe.natj.objc.SEL aSelector,
                                                                         java.lang.Object anArgument)

      • classFallbacksForKeyedArchiver

        public static NSArray<java.lang.String> classFallbacksForKeyedArchiver()

      • classForKeyedUnarchiver

        public static org.moe.natj.objc.Class classForKeyedUnarchiver()

      • copyWithZoneDevice

        public java.lang.Object copyWithZoneDevice​(org.moe.natj.general.ptr.VoidPtr zone,
                                           MTLDevice device)
        Make a copy of this kernel for a new device - @see MPSKernel
        Overrides:
        copyWithZoneDevice in class MPSKernel
        Parameters:
        zone - The NSZone in which to allocate the object
        device - The device for the new MPSKernel. If nil, then use self.device.
        Returns:
        a pointer to a copy of this MPSKernel. This will fail, returning nil if the device is not supported. Devices must be MTLFeatureSet_iOS_GPUFamily2_v1 or later.

      • createTemporaryWeightGradientMatricesDataTypeCommandBuffer

        public void createTemporaryWeightGradientMatricesDataTypeCommandBuffer​(NSMutableArray<MPSMatrix> matricesOut,
                                                                       int dataType,
                                                                       MTLCommandBuffer commandBuffer)
        As @ref createWeightGradientMatrices, but the matrices will be temporary with readCount = 1, which means that they become invalid after the first encode call that reads them. Note also that as the matrices are temporary, their storage mode will be private which means that you can only access the data using a kernel on the GPU.
        Parameters:
        matricesOut - An array where the newly created matrices will be stored, will be initialized to zero.
        dataType - Datatype for the entries - currently MPSDataTypeFloat32 and MPSDataTypeFloat16 are supported.
        commandBuffer - The command buffer that the temporary matrices will live on.

      • createWeightGradientMatricesDataType

        public void createWeightGradientMatricesDataType​(NSMutableArray<MPSMatrix> matricesOut,
                                                 int dataType)
        Initializes a set of matrices that can be used in training for weight and bias gradient outputs in
        Parameters:
        matricesOut - An array where the newly created matrices will be stored, will be initialized to zero.
        dataType - Datatype for the entries - currently MPSDataTypeFloat32 and MPSDataTypeFloat16 are supported.

      • createWeightMatrices

        public void createWeightMatrices​(NSMutableArray<MPSMatrix> matricesOut)
        Initializes a set of matrices that can be used in training for weight and bias matrices in the forward and backward passes. The layout, datatype and number of matrices is the same as for the outputs of
        Parameters:
        matricesOut - An array where the newly created matrices will be stored, will be initialized to zero.

      • debugDescription_static

        public static java.lang.String debugDescription_static()

      • description_static

        public static java.lang.String description_static()

      • encodeCopyWeightsToCommandBufferWeightsMatrixIdMatrixCopyFromWeightsToMatrixMatrixOffset

        public void encodeCopyWeightsToCommandBufferWeightsMatrixIdMatrixCopyFromWeightsToMatrixMatrixOffset​(MTLCommandBuffer commandBuffer,
                                                                                                     NSArray<? extends MPSMatrix> weights,
                                                                                                     long matrixId,
                                                                                                     MPSMatrix matrix,
                                                                                                     boolean copyFromWeightsToMatrix,
                                                                                                     MTLOrigin matrixOffset)
        Encode a copy kernel that copies one matrix from the trainable weight set to a matrix with standard layout, where the column index is the input feature channel index (in forward direction) and row index is the output feature channel index.
        Parameters:
        commandBuffer - A valid MTLCommandBuffer to receive the encoded filter
        weights - An array weights from @see initWithDevice or @see createWeightMatrices.
        matrixId - Which matrix to copy - has to be a valid Id based on inputs defined in the rnnDescriptor of @see initWithDevice.
        matrix - The destination or source matrix that is used in the copy.
        copyFromWeightsToMatrix - If YES then the copy direction is from the set of trainable 'weights' to 'matrix', otherwise the copy is done from 'matrix' to 'weights'.
        matrixOffset - A (valid) offset into matrix to be applied to the copy operation.

      • encodeForwardSequenceToCommandBufferSourceMatricesDestinationMatricesTrainingStatesWeights

        public void encodeForwardSequenceToCommandBufferSourceMatricesDestinationMatricesTrainingStatesWeights​(MTLCommandBuffer commandBuffer,
                                                                                                       NSArray<? extends MPSMatrix> sourceMatrices,
                                                                                                       NSArray<? extends MPSMatrix> destinationMatrices,
                                                                                                       NSMutableArray<MPSRNNMatrixTrainingState> trainingStates,
                                                                                                       NSArray<? extends MPSMatrix> weights)
        Encode an MPSRNNMatrixTrainingLayer forward pass kernel for a sequence of inputs into a command buffer.
        Parameters:
        commandBuffer - A valid MTLCommandBuffer to receive the encoded filter
        sourceMatrices - An array of valid MPSMatrix objects containing the sequence of source matrices.
        destinationMatrices - An array valid MPSMatrices to be overwritten by result matrix sequence. destinationMatrices may not alias sourceMatrices.
        trainingStates - An array containing the training states to be passed to the gradient computation encode function.
        weights - An array of valid MPSMatrix objects containing the weights, should be the array that was produced either by @see initWithDevice or @see createWeightMatrices.

      • encodeForwardSequenceToCommandBufferSourceMatricesSourceOffsetsDestinationMatricesDestinationOffsetsTrainingStatesRecurrentInputStateRecurrentOutputStatesWeights

        public void encodeForwardSequenceToCommandBufferSourceMatricesSourceOffsetsDestinationMatricesDestinationOffsetsTrainingStatesRecurrentInputStateRecurrentOutputStatesWeights​(MTLCommandBuffer commandBuffer,
                                                                                                                                                                              NSArray<? extends MPSMatrix> sourceMatrices,
                                                                                                                                                                              org.moe.natj.general.ptr.NUIntPtr sourceOffsets,
                                                                                                                                                                              NSArray<? extends MPSMatrix> destinationMatrices,
                                                                                                                                                                              org.moe.natj.general.ptr.NUIntPtr destinationOffsets,
                                                                                                                                                                              NSMutableArray<MPSRNNMatrixTrainingState> trainingStates,
                                                                                                                                                                              MPSRNNRecurrentMatrixState recurrentInputState,
                                                                                                                                                                              NSMutableArray<MPSRNNRecurrentMatrixState> recurrentOutputStates,
                                                                                                                                                                              NSArray<? extends MPSMatrix> weights)
        Encode an MPSRNNMatrixTrainingLayer forward pass kernel for a sequence of inputs into a command buffer.
        Parameters:
        commandBuffer - A valid MTLCommandBuffer to receive the encoded filter
        sourceMatrices - An array of valid MPSMatrix objects containing the sequence of source matrices.
        sourceOffsets - An array of byte-offsets into the sourceMatrices, if nil zeros are assumed and if not nil must contain offset for every matrix in sourceMatrices.
        destinationMatrices - An array valid MPSMatrices to be overwritten by result matrix sequence. destinationMatrices may not alias sourceMatrices.
        destinationOffsets - An array of byte-offsets into the destinationMatrices, if nil zeros are assumed and if not nil must contain offset for every matrix in destinationMatrices.
        trainingStates - An array containing the training states to be passed to the gradient computation encode function.
        recurrentInputState - An optional state containing the output matrices and memory cells (for LSTMs) of the layer obtained from the previous input matrices in a sequence of inputs. Has to be the output of a previous call to this function or nil (assumed zero).
        recurrentOutputStates - An array that will be appended with the recurrent output states. May not be nil. If recurrentOutputIsTemporary is YES and then all returned recurrent states will be temporary. @see MPSState:isTemporary.
        weights - An array of valid MPSMatrix objects containing the weights, should be the array that was produced either by @see initWithDevice or @see createWeightMatrices.

      • encodeGradientSequenceToCommandBufferForwardSourcesForwardSourceOffsetsSourceGradientsSourceGradientOffsetsDestinationGradientsDestinationOffsetsWeightGradientsTrainingStatesRecurrentInputStateRecurrentOutputStatesWeights

        public void encodeGradientSequenceToCommandBufferForwardSourcesForwardSourceOffsetsSourceGradientsSourceGradientOffsetsDestinationGradientsDestinationOffsetsWeightGradientsTrainingStatesRecurrentInputStateRecurrentOutputStatesWeights​(MTLCommandBuffer commandBuffer,
                                                                                                                                                                                                                                          NSArray<? extends MPSMatrix> forwardSources,
                                                                                                                                                                                                                                          org.moe.natj.general.ptr.NUIntPtr forwardSourceOffsets,
                                                                                                                                                                                                                                          NSArray<? extends MPSMatrix> sourceGradients,
                                                                                                                                                                                                                                          org.moe.natj.general.ptr.NUIntPtr sourceGradientOffsets,
                                                                                                                                                                                                                                          NSArray<? extends MPSMatrix> destinationGradients,
                                                                                                                                                                                                                                          org.moe.natj.general.ptr.NUIntPtr destinationOffsets,
                                                                                                                                                                                                                                          NSArray<? extends MPSMatrix> weightGradients,
                                                                                                                                                                                                                                          NSArray<? extends MPSRNNMatrixTrainingState> trainingStates,
                                                                                                                                                                                                                                          MPSRNNRecurrentMatrixState recurrentInputState,
                                                                                                                                                                                                                                          NSMutableArray<MPSRNNRecurrentMatrixState> recurrentOutputStates,
                                                                                                                                                                                                                                          NSArray<? extends MPSMatrix> weights)
        Encode an MPSRNNMatrixTrainingLayer gradient pass kernel for a sequence of input gradients into a command buffer. NOTE: The time sequence indexing follows the array indexing in the inputs: sourceGradients[0] has to contain the gradients corresponding to the first matrix in the forward pass corresponding to the current subsequence, which is typically sourceMatrices[0].
        Parameters:
        commandBuffer - A valid MTLCommandBuffer to receive the encoded filter
        forwardSources - An array of MPSMatrix objects containing the sequence of source matrices of the forward pass.
        forwardSourceOffsets - An array of byte-offsets into the forwardSources, if nil zeros are assumed and if not nil must contain offset for every matrix in forwardSources.
        sourceGradients - An array of valid MPSMatrix objects containing the sequence of source gradient matrices.
        sourceGradientOffsets - An array of byte-offsets into the sourceGradients, if nil zeros are assumed and if not nil must contain offset for every matrix in sourceGradients.
        destinationGradients - An array valid MPSMatrix objects that will receive the backpropagated gradients, may be nil if not needed (for example first layer in graph).
        destinationOffsets - An array of byte-offsets into the destinationGradients, if nil zeros are assumed and if not nil must contain offset for every matrix in destinationGradients.
        weightGradients - An array of valid MPSMatrix objects that will receive the gradient wrt. weights and biases of the layer - should be the array that was produced either by @see initWithDevice or @see createWeightMatrices. May be nil in which case the gradients for the weights are not computed.
        trainingStates - An array containing the training states from the forward pass - the array must contain the states corresponding to the input gradients is sourceGradients.
        recurrentInputState - An optional state containing the output matrices and memory cells (for LSTMs) of the layer obtained from the previous input gradients in a sequence of inputs. Has to be the output of a previous call to this function or nil (assumed zero).
        recurrentOutputStates - An array that will be appended with the recurrent output states. Can be nil. If recurrentOutputIsTemporary is YES and then all returned recurrent states will be temporary. @see MPSState:isTemporary.
        weights - An array of valid MPSMatrix objects containing the weights, should be the array that was produced either by @see initWithDevice or @see createWeightMatrices.

      • encodeGradientSequenceToCommandBufferForwardSourcesSourceGradientsDestinationGradientsWeightGradientsTrainingStatesWeights

        public void encodeGradientSequenceToCommandBufferForwardSourcesSourceGradientsDestinationGradientsWeightGradientsTrainingStatesWeights​(MTLCommandBuffer commandBuffer,
                                                                                                                                       NSArray<? extends MPSMatrix> forwardSources,
                                                                                                                                       NSArray<? extends MPSMatrix> sourceGradients,
                                                                                                                                       NSArray<? extends MPSMatrix> destinationGradients,
                                                                                                                                       NSArray<? extends MPSMatrix> weightGradients,
                                                                                                                                       NSArray<? extends MPSRNNMatrixTrainingState> trainingStates,
                                                                                                                                       NSArray<? extends MPSMatrix> weights)
        Encode an MPSRNNMatrixTrainingLayer gradient pass kernel for a sequence of input gradients into a command buffer. NOTE: The time sequence indexing follows the array indexing in the inputs: sourceGradients[0] has to contain the gradients corresponding to the first matrix in the forward pass corresponding to the current subsequence, which is typically sourceMatrices[0].
        Parameters:
        commandBuffer - A valid MTLCommandBuffer to receive the encoded filter
        forwardSources - An array of MPSMatrix objects containing the sequence of source matrices of the forward pass.
        sourceGradients - An array of MPSMatrix objects containing the sequence of source gradient matrices.
        destinationGradients - An array valid MPSMatrix objects that will receive the backpropagated gradients, may be nil if not needed (for example first layer in graph).
        weightGradients - An array valid MPSMatrix objects that will receive the gradient wrt. weights and biases of the layer - should be the array that was produced either by @see initWithDevice or @see createWeightMatrices. May be nil in which case the gradients for the weights are not computed. NOTE: The weight gradients are accumulated on top of existing values so
        trainingStates - An array containing the training states from the forward pass - the array must contain the states corresponding to the input gradients is sourceGradients.
        weights - An array of valid MPSMatrix objects containing the weights, should be the array that was produced either by @see initWithDevice or @see createWeightMatrices.

      • hash_static

        public static long hash_static()

      • initWithCoderDevice

        public MPSRNNMatrixTrainingLayer initWithCoderDevice​(NSCoder aDecoder,
                                                     java.lang.Object device)
        NSSecureCoding compatability See @ref MPSKernel#initWithCoder.
        Overrides:
        initWithCoderDevice in class MPSKernel
        Parameters:
        aDecoder - The NSCoder subclass with your serialized MPSRNNMatrixTrainingLayer
        device - The MTLDevice on which to make the MPSRNNMatrixTrainingLayer
        Returns:
        A new MPSRNNMatrixTrainingLayer object, or nil if failure.

      • initWithDevice

        public MPSRNNMatrixTrainingLayer initWithDevice​(java.lang.Object device)
        Description copied from class: MPSKernel
        Standard init with default properties per filter type
        Overrides:
        initWithDevice in class MPSKernel
        Parameters:
        device - The device that the filter will be used on. May not be NULL.
        Returns:
        a pointer to the newly initialized object. This will fail, returning nil if the device is not supported. Devices must be MTLFeatureSet_iOS_GPUFamily2_v1 or later.

      • initWithDeviceRnnDescriptorTrainableWeights

        public MPSRNNMatrixTrainingLayer initWithDeviceRnnDescriptorTrainableWeights​(MTLDevice device,
                                                                             MPSRNNDescriptor rnnDescriptor,
                                                                             NSMutableArray<MPSMatrix> trainableWeights)
        Initializes a linear (fully connected) RNN kernel for training
        Parameters:
        device - The MTLDevice on which this MPSRNNMatrixLayer filter will be used
        rnnDescriptor - The descriptor that defines the RNN layer
        trainableWeights - An array where to store the weights of the layer as MPSMatrices. NOTE: The exact layout and number of matrices may vary between platforms and therefore you should not save out these weights directly, but instead use the function encodeCopyWeightsToCommandBuffer to identify the weights and biases for serialization. Typically you should pass here an initialized but empty NSMutableArray and when this function returns the array will have been populated with the weight matrices needed in the encode-calls, by using initial values from the datasources in rnnDescriptor.
        Returns:
        A valid MPSRNNMatrixTrainingLayer object or nil, if failure.

      • inputFeatureChannels

        public long inputFeatureChannels()
        [@property] inputFeatureChannels The number of feature channels input vector/matrix.

      • instanceMethodSignatureForSelector

        public static NSMethodSignature instanceMethodSignatureForSelector​(org.moe.natj.objc.SEL aSelector)

      • instancesRespondToSelector

        public static boolean instancesRespondToSelector​(org.moe.natj.objc.SEL aSelector)

      • isSubclassOfClass

        public static boolean isSubclassOfClass​(org.moe.natj.objc.Class aClass)

      • keyPathsForValuesAffectingValueForKey

        public static NSSet<java.lang.String> keyPathsForValuesAffectingValueForKey​(java.lang.String key)

      • new_objc

        public static java.lang.Object new_objc()

      • outputFeatureChannels

        public long outputFeatureChannels()
        [@property] outputFeatureChannels The number of feature channels in the output vector/matrix.

      • recurrentOutputIsTemporary

        public boolean recurrentOutputIsTemporary()
        [@property] recurrentOutputIsTemporary How recurrent output states from @ref encodeForwardSequenceToCommandBuffer and encodeGradientSequenceToCommandBuffer are constructed. Defaults to NO. For reference @see MPSState.

      • resolveClassMethod

        public static boolean resolveClassMethod​(org.moe.natj.objc.SEL sel)

      • resolveInstanceMethod

        public static boolean resolveInstanceMethod​(org.moe.natj.objc.SEL sel)

      • setAccumulateWeightGradients

        public void setAccumulateWeightGradients​(boolean value)
        [@property] accumulateWeightGradients If yes then the computed weight gradients are accumulated on top of existing values in calls to the gradient computation functions: encodeGradientSequenceToCommandBuffer. Defaults to NO.

      • setRecurrentOutputIsTemporary

        public void setRecurrentOutputIsTemporary​(boolean value)
        [@property] recurrentOutputIsTemporary How recurrent output states from @ref encodeForwardSequenceToCommandBuffer and encodeGradientSequenceToCommandBuffer are constructed. Defaults to NO. For reference @see MPSState.

      • setStoreAllIntermediateStates

        public void setStoreAllIntermediateStates​(boolean value)
        [@property] storeAllIntermediateStates If YES then calls to functions @ref encodeForwardSequenceToCommandBuffer and [@ref] encodeGradientSequenceToCommandBuffer return every recurrent state in the array: recurrentOutputStates. Defaults to NO.

      • setTrainingStateIsTemporary

        public void setTrainingStateIsTemporary​(boolean value)
        [@property] trainingStateIsTemporary How training output states from @ref encodeForwardSequenceToCommandBuffer are constructed. Defaults to NO. For reference @see MPSState.

      • setVersion_static

        public static void setVersion_static​(long aVersion)

      • storeAllIntermediateStates

        public boolean storeAllIntermediateStates()
        [@property] storeAllIntermediateStates If YES then calls to functions @ref encodeForwardSequenceToCommandBuffer and [@ref] encodeGradientSequenceToCommandBuffer return every recurrent state in the array: recurrentOutputStates. Defaults to NO.

      • superclass_static

        public static org.moe.natj.objc.Class superclass_static()

      • supportsSecureCoding

        public static boolean supportsSecureCoding()

      • _supportsSecureCoding

        public boolean _supportsSecureCoding()
        Description copied from interface: NSSecureCoding
        This property must return YES on all classes that allow secure coding. Subclasses of classes that adopt NSSecureCoding and override initWithCoder: must also override this method and return YES. The Secure Coding Guide should be consulted when writing methods that decode data.
        Specified by:
        _supportsSecureCoding in interface NSSecureCoding
        Overrides:
        _supportsSecureCoding in class MPSKernel

      • trainingStateIsTemporary

        public boolean trainingStateIsTemporary()
        [@property] trainingStateIsTemporary How training output states from @ref encodeForwardSequenceToCommandBuffer are constructed. Defaults to NO. For reference @see MPSState.

      • version_static

        public static long version_static()