MPSNeuralNetworkTypes.h(3) MetalPerformanceShaders.framework MPSNeuralNetworkTypes.h(3)
NAME
MPSNeuralNetworkTypes.h
SYNOPSIS
#import <MPSCore/MPSCoreTypes.h>
Classes
protocol <MPSNNPadding >
class MPSNNDefaultPadding
protocol <MPSImageSizeEncodingState >
Typedefs
typedef enum MPSCNNConvolutionFlags MPSCNNConvolutionFlags
typedef enum MPSCNNBinaryConvolutionFlags MPSCNNBinaryConvolutionFlags
typedef enum MPSCNNBinaryConvolutionType MPSCNNBinaryConvolutionType
typedef enum MPSNNTrainingStyle MPSNNTrainingStyle
typedef enum MPSCNNBatchNormalizationFlags MPSCNNBatchNormalizationFlags
typedef enum MPSNNPaddingMethod MPSNNPaddingMethod
Enumerations
enum MPSCNNConvolutionFlags { MPSCNNConvolutionFlagsNone }
enum MPSCNNBinaryConvolutionFlags { MPSCNNBinaryConvolutionFlagsNone, MPSCNNBinaryConvolutionFlagsUseBetaScaling }
enum MPSCNNBinaryConvolutionType { MPSCNNBinaryConvolutionTypeBinaryWeights, MPSCNNBinaryConvolutionTypeXNOR,
MPSCNNBinaryConvolutionTypeAND }
enum MPSNNConvolutionAccumulatorPrecisionOption { MPSNNConvolutionAccumulatorPrecisionOptionHalf,
MPSNNConvolutionAccumulatorPrecisionOptionFloat }
enum MPSNNTrainingStyle { MPSNNTrainingStyleUpdateDeviceNone, MPSNNTrainingStyleUpdateDeviceCPU, MPSNNTrainingStyleUpdateDeviceGPU }
enum MPSCNNBatchNormalizationFlags { MPSCNNBatchNormalizationFlagsDefault, MPSCNNBatchNormalizationFlagsCalculateStatisticsAutomatic,
MPSCNNBatchNormalizationFlagsCalculateStatisticsAlways, MPSCNNBatchNormalizationFlagsCalculateStatisticsNever,
MPSCNNBatchNormalizationFlagsCalculateStatisticsMask }
enum MPSNNPaddingMethod { MPSNNPaddingMethodAlignCentered, MPSNNPaddingMethodAlignTopLeft, MPSNNPaddingMethodAlignBottomRight,
MPSNNPaddingMethodAlign_reserved, MPSNNPaddingMethodAlignMask = MPSNNPaddingMethodAlign_reserved,
MPSNNPaddingMethodAddRemainderToTopLeft, MPSNNPaddingMethodAddRemainderToTopRight, MPSNNPaddingMethodAddRemainderToBottomLeft,
MPSNNPaddingMethodAddRemainderToBottomRight, MPSNNPaddingMethodAddRemainderToMask = MPSNNPaddingMethodAddRemainderToBottomRight,
MPSNNPaddingMethodSizeValidOnly, MPSNNPaddingMethodSizeSame, MPSNNPaddingMethodSizeFull, MPSNNPaddingMethodSize_reserved,
MPSNNPaddingMethodCustom, MPSNNPaddingMethodSizeMask, MPSNNPaddingMethodExcludeEdges }
Typedef Documentation
typedef enum MPSCNNBatchNormalizationFlags
MPSCNNBatchNormalizationFlags"
typedef enum MPSCNNBinaryConvolutionFlags
MPSCNNBinaryConvolutionFlags"
typedef enum MPSCNNBinaryConvolutionType
MPSCNNBinaryConvolutionType"
typedef enum MPSCNNConvolutionFlags
MPSCNNConvolutionFlags"
typedef enum MPSNNPaddingMethod
MPSNNPaddingMethod"
typedef enum MPSNNTrainingStyle
MPSNNTrainingStyle"
Enumeration Type Documentation
enum MPSCNNBatchNormalizationFlags
Enumerator
MPSCNNBatchNormalizationFlagsDefault
Default Settings
MPSCNNBatchNormalizationFlagsCalculateStatisticsAutomatic
Statistics are calculated if another node consumes the gradient node (training). The data source is used otherwise.
MPSCNNBatchNormalizationFlagsCalculateStatisticsAlways
Statistics are calculated always
MPSCNNBatchNormalizationFlagsCalculateStatisticsNever
Statistics are never calculated. Predefined values from the data source are used instead
MPSCNNBatchNormalizationFlagsCalculateStatisticsMask
Bits used for MPSCNNBatchNormalizationFlagsCalculateStatistics
enum MPSCNNBinaryConvolutionFlags
Options used to control CNN Binary convolution kernels.
Enumerator
MPSCNNBinaryConvolutionFlagsNone
Use default in binary convolution options
MPSCNNBinaryConvolutionFlagsUseBetaScaling
Scale the binary convolution operation using the beta-image option as detailed in MPSCNNBinaryConvolution
enum MPSCNNBinaryConvolutionType
Defines what operations are used to perform binary convolution
Enumerator
MPSCNNBinaryConvolutionTypeBinaryWeights
Otherwise a normal convolution operation, except that the weights are binary values
MPSCNNBinaryConvolutionTypeXNOR
Use input image binarization and the XNOR-operation to perform the actual convolution - See MPSCNNBinaryConvolution for details
MPSCNNBinaryConvolutionTypeAND
Use input image binarization and the AND-operation to perform the actual convolution - See MPSCNNBinaryConvolution for details
enum MPSCNNConvolutionFlags
Options used to control how kernel weights are stored and used in the CNN kernels. For future expandability.
Enumerator
MPSCNNConvolutionFlagsNone
Use default options
enum MPSNNConvolutionAccumulatorPrecisionOption
Options set on MPSCNNConvolution objects to control precision of accumulator used. Convolution operation involves sequence of multiply-
accumulate operation i.e. accumulator = imageData * weight + accumulator Default MPSDataType for both imageData and weight is
MPSDataTypeFloat16 i.e. half precision float. Multiply-accumulate result (imageData * weight + accumulator) needs to be rounded to
precision of accumulator. MPS allows either half float or full float accumulator type using appropriate flags. The choice of accmulator
precision should be based on how much precision loss application can sustain without significanly affecting accuracy of network. Default
accumulator precision is half (MPSNNConvolutionAccumulatorPrecisionOptionHalf). If accumulation of computational rounding error in the
result is excessive, user can specify MPSNNConvolutionAccumulatorPrecisionOptionFloat for full float accumulator. Note that on some
devices, which doesnt provide IEEE compliant half arithmetic (A10 and older), half precision accumulator can cause excessive loss of
precision causing severe loss in accuracy. MPS automatically ignores this option on those hardware and uses full float accumulator. On
hardware that do support IEEE compliant half arithmetic and half accumulator do meet applications accuracy requirements, it can provide
significant performance benefits.
Enumerator
MPSNNConvolutionAccumulatorPrecisionOptionHalf
Set accumulator type to half precision float.
MPSNNConvolutionAccumulatorPrecisionOptionFloat
Set accumulator type to single precision float.
enum MPSNNPaddingMethod
How to pad MPSNNGraph image nodes The MPSNNGraph must make automatic decisions about how big to make the result of each filter node. This
is typically determined by a combination of input image size, size of the filter window (e.g. convolution weights), filter stride, and a
description of how much extra space beyond the edges of the image to allow the filter read. By knowing the properties of the filter, we can
then infer the size of the result image. Most of this information is known to the MPSNNGraph as part of its normal operation. However, the
amount of padding to add and where to add it is a matter of choice left to you, the developer. Different neural network frameworks such as
TensorFlow and Caffe make different choices here. Depending on where your network was trained, you will need to adjust the policies used by
MPS during inference. In the event that the padding method is not simply described by this enumeration, you may provide you own custom
policy definition by overriding the -destinationImageDescriptorForSourceImages: sourceStates:forKernel:suggestedDescriptor: method in a
custom MPSNNPadding child class.
Common values that influence the size of the result image by adjusting the amount of padding added to the source images:
o MPSNNPaddingMethodSizeValidOnly Result values are only produced for the area that is guaranteed to have all of its input values defined
(i.e. not off the edge). This produces the smallest result image.
o MPSNNPaddingMethodSizeSame The result image is the same size as the input image. If the stride is not 1, then the result is scaled
accordingly.
- MPSNNPaddingMethodSizeFull Result values are produced for any position for which at least one input value is defined (i.e. not off the
edge)
o MPSNNPaddingMethodCustom The sizing and centering policy is given by the [MPSNNPadding destinationImageDescriptorForSourceImages:
sourceStates:forKernel:suggestedDescriptor:]
Except possibly when MPSNNPaddingMethodCustom is used, the area within the source image that is read will be centered on the source image.
Even so, at times the area can not be perfectly centered because the source image has odd size and the region read has even size, or vice
versa. In such cases, you may use the following values to select where to put the extra padding:
- MPSNNPaddingMethodAddRemainderToTopLeft Leftover padding is added to the top or left
side of image as appropriate.
- MPSNNPaddingMethodAddRemainderToBottomRight Leftover padding is added to the bottom or right
side of image as appropriate.
Here again, different external frameworks may use different policies.
In some cases, Caffe intoduces the notion of a region beyond the padding which is invalid. This can happen when the padding is set to a
width narrower than what is needed for a destination size. In such cases, MPSNNPaddingMethodExcludeEdges is used to adjust normalization
factors for filter weights (particularly in pooling) such that invalid regions beyond the padding are not counted towards the filter area.
Currently, only pooling supports this feature. Other filters ignore it.
The MPSNNPaddingMethodSize and a MPSNNPaddingMethodAddRemainder policy always appear together in the MPSNNPaddingMethod. There is no
provision for a MPSNNPaddingMethodSize without a remainder policy or vice versa. It is in practice used as a bit field.
Most MPSNN filters are considered forward filters. Some (e.g. convolution transpose) are considered reverse filters. For the reverse
filters, the image stride is measured in destination values rather than source values and has the effect of enlarging the image rather than
reducing it. When a reverse filter is used to 'undo' the effects of a forward filter, the MPSNNPaddingMethodSize should be the opposite of
the forward MPSNNPaddingMethod. For example, if the forward filter used MPSNNPaddingMethodSizeValidOnly |
MPSNNPaddingMethodAddRemainderToTopLeft, the reverse filter should use MPSNNPaddingMethodSizeFull |
MPSNNPaddingMethodAddRemainderToTopLeft. Some consideration of the geometry of inputs and outputs will reveal why this is so. It is usually
not important to adjust the centering method because the size of the reverse result generally doesn't suffer from centering asymmetries.
That is: the size would usually be given by:
static int DestSizeReverse( int sourceSize, int stride, int filterWindowSize, Style style ) {
return (sourceSize-1) * stride + 1 + style * (filterWindowSize-1); // style = {-1,0,1} for valid-only, same, full
}
so the result size is exactly the one needed for the source size and there are no centering problems. In some cases where the reverse pass
is intended to completely reverse a forward pass, the MPSState object produced by the forward pass should be used to determine the size of
the reverse pass result image.
Tensorflow does not appear to provide a full padding method, but instead appears to use its valid-only padding mode for reverse filters to
in effect achieve what is called MPSNNPaddingMethodSizeFull here.
MPSGetPaddingPolicy() is provided as a convenience to make shorter work of MPSNNPaddingMethods and policies.
Walkthrough of operation of padding policy:
Most MPSCNNKernels have two types of -encode calls. There is one for which you must pass in a preallocated MPSImage to receive the results.
This is for manual configuration. It assumes you know what you are doing, and asks you to correctly set a diversity of properties to
correctly position image inputs and size results. It does not use the padding policy. You must size the result correctly, set the clipRect,
offset and other properties as needed yourself. Layered on top of that is usually another flavor of -encode call that returns a destination
image instead from the left hand side of the function. It is designed to automatically configure itself based on the
MPSCNNKernel.paddingPolicy. When this more automated -encode... method is called, it invokes a method in the MPSKernel that looks at the
MPSNNPaddingMethod bitfield of the policy. Based on the information therein and the size of the input images and other filter properties,
it determines the size of the output, sets the offset property, and returns an appropriate MPSImageDescriptor for the destination image. If
you set the MPSNNPaddingMethodCustom bit in the MPSNNPaddingMethod, then the MPSNNPadding
-destinationImageDescriptorForSourceImages:sourceStates:forKernel:suggestedDescriptor: method is called. The MPSImageDescriptor prepared
earlier is passed in as the last parameter. You can use this descriptor or modify as needed. In addition, you can adjust any properties of
the MPSKernel with which it will be used. If, for example, the descriptor is not the right MPSFeatureChannelFormat, you can change it, or
make your own MPSImageDescriptor based on the one handed to you. This is your opportunity to customize the configuration of the MPSKernel.
In some cases (e.g. paddingForTensorflowAveragePooling (MPSNNDefaultPadding) you might change other properties such as the filter edging
mode, or adjust the offset that was already set for you. When the kernel is fully configured, return the MPSImageDescriptor. The
MPSImageDescriptor is then passed to the MPSCNNKernel.destinationImageAllocator to allocate the image. You might provide such an allocator
if you want to use your own custom MTLHeap rather than the MPS internal heap. The allocator can be set either directly in the MPSCNNKernel
or through the MPSNNImageNode.allocator property. It is intended that most of the time, default values for padding method and destination
image allocator should be good enough. Only minimal additional configuration should be required, apart from occasional adjustments to set
the MPSNNPaddingMethod when something other than default padding for the object is needed. If you find yourself encumbered by frequent
adjustments of this kind, you might find it to your advantage to subclass MPSNNFilterNodes or MPSCNNKernels to adjust the default padding
policy and allocator at initialization time.
tensorFlowSame = MPSNNPaddingMethodAddRemainderToBottomRight | MPSNNPaddingMethodAlignCentered | MPSNNPaddingMethodSizeSame.fi
Enumerator
MPSNNPaddingMethodAlignCentered
MPSNNPaddingMethodAlignTopLeft
MPSNNPaddingMethodAlignBottomRight
MPSNNPaddingMethodAlign_reserved
MPSNNPaddingMethodAlignMask
MPSNNPaddingMethodAddRemainderToTopLeft
MPSNNPaddingMethodAddRemainderToTopRight
MPSNNPaddingMethodAddRemainderToBottomLeft
MPSNNPaddingMethodAddRemainderToBottomRight
MPSNNPaddingMethodAddRemainderToMask
MPSNNPaddingMethodSizeValidOnly
MPSNNPaddingMethodSizeSame
MPSNNPaddingMethodSizeFull
MPSNNPaddingMethodSize_reserved
MPSNNPaddingMethodCustom
MPSNNPaddingMethodSizeMask
MPSNNPaddingMethodExcludeEdges
The caffe framework constrains the average pooling area to the limits of the padding area in cases where a pixel would read beyond the padding area. Set this bit for Caffe emulation with average pooling.
enum MPSNNTrainingStyle
Options that control how the MPSNNGraph nodes are trained Nodes tha are trainable conform to the MPSNNTrainableNode protocol. This adds a
MPSNNTrainingStyle property to the node that may be used to influence when and where the neural network training paramers such as
convolution weights are updated.
Enumerator
MPSNNTrainingStyleUpdateDeviceNone
Do not train this node, for example in transfer learning
MPSNNTrainingStyleUpdateDeviceCPU
The weight update pass will be called in a command buffer completion callback, with a nil command buffer
MPSNNTrainingStyleUpdateDeviceGPU
The weight update pass will be called immediately after the gradient pass is encoded, with a nonnull command buffer
Author
Generated automatically by Doxygen for MetalPerformanceShaders.framework from the source code.
Version MetalPerformanceShaders-100 Thu Feb 8 2018 MPSNeuralNetworkTypes.h(3)