<!--
{
  "documentType" : "article",
  "framework" : "MetalPerformanceShaders",
  "identifier" : "/documentation/MetalPerformanceShaders/convolutional-neural-network-kernels",
  "metadataVersion" : "0.1.0",
  "role" : "collectionGroup",
  "title" : "Convolutional Neural Network Kernels"
}
-->

# Convolutional Neural Network Kernels

Build neural networks with layers.

## Discussion

- Think carefully about the edge mode requested for pooling layers. The default value is [`MPSImageEdgeMode.zero`](/documentation/MetalPerformanceShaders/MPSImageEdgeMode/zero), but there are times when a [`MPSImageEdgeMode.clamp`](/documentation/MetalPerformanceShaders/MPSImageEdgeMode/clamp) value may be better.
- To avoid reading off the edge of an image for filters that have a filter area (convolution, pooling), set `MPSCNNKernel.offset = (MPSOffset){ .x = kernelWidth/2, .y = kernelHeight/2, .z = 0}` and reduce the size of the output image by `{kernelWidth-1, kernelHeight-1, 0}`. The filter area stretches up and to the left of the kernel offset by `{kernelWidth/2, kernelHeight/2}`.
- Always remember the following distinction:
- The [`MPSCNNConvolution`](/documentation/MetalPerformanceShaders/MPSCNNConvolution) class takes weights in the order `weight[outputChannels][kernelHeight][kernelWidth][inputChannels/groups]`.
- The [`MPSCNNFullyConnected`](/documentation/MetalPerformanceShaders/MPSCNNFullyConnected) class takes weights in the order `weight[outputChannels][sourceWidth][sourceHeight][inputChannels]`.
- Initialize [`MPSCNNKernel`](/documentation/MetalPerformanceShaders/MPSCNNKernel) objects once and reuse them.
- You can use [`MPSCNNNeuron`](/documentation/MetalPerformanceShaders/MPSCNNNeuron) objects and similar to perform pre-processing of images, such as scaling and resizing.
- Specify a neuron filter with an [`MPSCNNConvolutionDescriptor`](/documentation/MetalPerformanceShaders/MPSCNNConvolutionDescriptor) object to combine the convolution and neuron operations.
- Use [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) objects for intermediate images that live for a short period of time (one <doc://com.apple.documentation/documentation/Metal/MTLCommandBuffer> object).

[`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) objects can reduce the amount of memory used by the CNN by several folds, and similarly reduce the amount of CPU time spent allocating storage and latency between the time a command buffer is committed and when it is actually executed on the GPU.

You cannot read or write to a [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) object using the CPU. Generally, [`MPSTemporaryImage`](/documentation/MetalPerformanceShaders/MPSTemporaryImage) objects should be created as needed and thrown away promptly. Persistent objects should not retain them.

Please be sure to understand the purpose of the [`readCount`](/documentation/MetalPerformanceShaders/MPSTemporaryImage/readCount) property.

- Because the Metal Performance Shaders framework encodes its work in place in your command buffer, you always have the option to insert your own code in between [`MPSCNNKernel`](/documentation/MetalPerformanceShaders/MPSCNNKernel) encodings as a Metal function for tasks not covered by the framework. You do not need to use the Metal Performance Shaders framework for everything.

## Topics

### Arithmetic Layers

[`MPSCNNAdd`](/documentation/MetalPerformanceShaders/MPSCNNAdd)

An addition operator.

[`MPSCNNAddGradient`](/documentation/MetalPerformanceShaders/MPSCNNAddGradient)

A gradient addition operator.

[`MPSCNNSubtract`](/documentation/MetalPerformanceShaders/MPSCNNSubtract)

A subtraction operator.

[`MPSCNNSubtractGradient`](/documentation/MetalPerformanceShaders/MPSCNNSubtractGradient)

A gradient subtraction operator.

[`MPSCNNMultiply`](/documentation/MetalPerformanceShaders/MPSCNNMultiply)

A multiply operator.

[`MPSCNNMultiplyGradient`](/documentation/MetalPerformanceShaders/MPSCNNMultiplyGradient)

A gradient multiply operator.

[`MPSCNNDivide`](/documentation/MetalPerformanceShaders/MPSCNNDivide)

A division operator.

[`MPSCNNArithmetic`](/documentation/MetalPerformanceShaders/MPSCNNArithmetic)

The base class for arithmetic operators.

[`MPSCNNArithmeticGradient`](/documentation/MetalPerformanceShaders/MPSCNNArithmeticGradient)

The base class for gradient arithmetic operators.

[`MPSCNNArithmeticGradientState`](/documentation/MetalPerformanceShaders/MPSCNNArithmeticGradientState)

An object that stores the clamp mask used by gradient arithmetic operators.

### Convolution Layers

[`MPSCNNBinaryConvolution`](/documentation/MetalPerformanceShaders/MPSCNNBinaryConvolution)

A convolution kernel with binary weights and an input image using binary approximations.

[`MPSCNNConvolution`](/documentation/MetalPerformanceShaders/MPSCNNConvolution)

A convolution kernel that convolves the input image with a set of filters, with each producing one feature map in the output image.

[`MPSCNNDepthWiseConvolutionDescriptor`](/documentation/MetalPerformanceShaders/MPSCNNDepthWiseConvolutionDescriptor)

A description of a convolution object that does depthwise convolution.

[`MPSCNNSubPixelConvolutionDescriptor`](/documentation/MetalPerformanceShaders/MPSCNNSubPixelConvolutionDescriptor)

A description of a convolution object that does subpixel upsampling and reshaping.

[`MPSCNNConvolutionTranspose`](/documentation/MetalPerformanceShaders/MPSCNNConvolutionTranspose)

A transposed convolution kernel.

[`MPSCNNConvolutionGradient`](/documentation/MetalPerformanceShaders/MPSCNNConvolutionGradient)

A gradient convolution kernel.

[`MPSCNNConvolutionGradientState`](/documentation/MetalPerformanceShaders/MPSCNNConvolutionGradientState)

An object that exposes a gradient convolution kernel’s gradient with respect to weights and biases.

[`MPSImageSizeEncodingState`](/documentation/MetalPerformanceShaders/MPSImageSizeEncodingState)

A protocol for objects that contain information about an image size elsewhere in the graph.

[`MPSCNNConvolutionWeightsAndBiasesState`](/documentation/MetalPerformanceShaders/MPSCNNConvolutionWeightsAndBiasesState)

A class that stores weights and biases.

### Pooling Layers

[`MPSCNNPoolingAverage`](/documentation/MetalPerformanceShaders/MPSCNNPoolingAverage)

An average pooling filter.

[`MPSCNNPoolingAverageGradient`](/documentation/MetalPerformanceShaders/MPSCNNPoolingAverageGradient)

A gradient average pooling filter.

[`MPSCNNPoolingL2Norm`](/documentation/MetalPerformanceShaders/MPSCNNPoolingL2Norm)

An L2-norm pooling filter.

[`MPSCNNPoolingMax`](/documentation/MetalPerformanceShaders/MPSCNNPoolingMax)

A max pooling filter.

[`MPSCNNDilatedPoolingMax`](/documentation/MetalPerformanceShaders/MPSCNNDilatedPoolingMax)

A dilated max pooling filter.

[`MPSCNNPooling`](/documentation/MetalPerformanceShaders/MPSCNNPooling)

A pooling kernel.

[`MPSCNNPoolingGradient`](/documentation/MetalPerformanceShaders/MPSCNNPoolingGradient)

A gradient pooling kernel.

[`MPSCNNDilatedPoolingMaxGradient`](/documentation/MetalPerformanceShaders/MPSCNNDilatedPoolingMaxGradient)

A gradient dilated max pooling filter.

[`MPSCNNPoolingL2NormGradient`](/documentation/MetalPerformanceShaders/MPSCNNPoolingL2NormGradient)

A gradient L2-norm pooling filter.

[`MPSCNNPoolingMaxGradient`](/documentation/MetalPerformanceShaders/MPSCNNPoolingMaxGradient)

A gradient max pooling filter.

### Fully Connected Layers

[`MPSCNNBinaryFullyConnected`](/documentation/MetalPerformanceShaders/MPSCNNBinaryFullyConnected)

A fully connected convolution layer with binary weights and optionally binarized input image.

[`MPSCNNFullyConnected`](/documentation/MetalPerformanceShaders/MPSCNNFullyConnected)

A fully connected convolution layer, also known as an inner product layer.

[`MPSCNNFullyConnectedGradient`](/documentation/MetalPerformanceShaders/MPSCNNFullyConnectedGradient)

A gradient fully connected convolution layer.

### Neuron Layers

[`MPSCNNNeuronAbsolute`](/documentation/MetalPerformanceShaders/MPSCNNNeuronAbsolute)

An absolute neuron filter.

[`MPSCNNNeuronELU`](/documentation/MetalPerformanceShaders/MPSCNNNeuronELU)

A parametric ELU neuron filter.

[`MPSCNNNeuronHardSigmoid`](/documentation/MetalPerformanceShaders/MPSCNNNeuronHardSigmoid)

A hard sigmoid neuron filter.

[`MPSCNNNeuronLinear`](/documentation/MetalPerformanceShaders/MPSCNNNeuronLinear)

A linear neuron filter.

[`MPSCNNNeuronPReLU`](/documentation/MetalPerformanceShaders/MPSCNNNeuronPReLU)

A parametric ReLU (Rectified Linear Unit) neuron filter.

[`MPSCNNNeuronReLUN`](/documentation/MetalPerformanceShaders/MPSCNNNeuronReLUN)

A ReLUN neuron filter.

[`MPSCNNNeuronReLU`](/documentation/MetalPerformanceShaders/MPSCNNNeuronReLU)

A ReLU (Rectified Linear Unit) neuron filter.

[`MPSCNNNeuronSigmoid`](/documentation/MetalPerformanceShaders/MPSCNNNeuronSigmoid)

A sigmoid neuron filter.

[`MPSCNNNeuronSoftPlus`](/documentation/MetalPerformanceShaders/MPSCNNNeuronSoftPlus)

A parametric softplus neuron filter.

[`MPSCNNNeuronSoftSign`](/documentation/MetalPerformanceShaders/MPSCNNNeuronSoftSign)

A softsign neuron filter.

[`MPSCNNNeuronTanH`](/documentation/MetalPerformanceShaders/MPSCNNNeuronTanH)

A hyperbolic tangent neuron filter.

[`MPSCNNNeuron`](/documentation/MetalPerformanceShaders/MPSCNNNeuron)

A filter that applies a neuron activation function.

[`MPSCNNNeuronExponential`](/documentation/MetalPerformanceShaders/MPSCNNNeuronExponential)

An exponential neuron filter.

[`MPSCNNNeuronGradient`](/documentation/MetalPerformanceShaders/MPSCNNNeuronGradient)

A gradient neuron filter.

[`MPSCNNNeuronLogarithm`](/documentation/MetalPerformanceShaders/MPSCNNNeuronLogarithm)

A logarithm neuron filter.

[`MPSCNNNeuronPower`](/documentation/MetalPerformanceShaders/MPSCNNNeuronPower)

A power neuron filter.

[`MPSNNNeuronDescriptor`](/documentation/MetalPerformanceShaders/MPSNNNeuronDescriptor)

An object that specifies properties used by a neuron kernel.

### Softmax Layers

[`MPSCNNSoftMax`](/documentation/MetalPerformanceShaders/MPSCNNSoftMax)

A neural transfer function that is useful for classification tasks.

[`MPSCNNLogSoftMax`](/documentation/MetalPerformanceShaders/MPSCNNLogSoftMax)

A neural transfer function that  is useful for constructing a loss function to be minimized when training neural networks.

[`MPSCNNLogSoftMaxGradient`](/documentation/MetalPerformanceShaders/MPSCNNLogSoftMaxGradient)

A gradient logarithmic softmax filter.

[`MPSCNNSoftMaxGradient`](/documentation/MetalPerformanceShaders/MPSCNNSoftMaxGradient)

A gradient softmax filter.

### Normalization Layers

[`MPSCNNCrossChannelNormalization`](/documentation/MetalPerformanceShaders/MPSCNNCrossChannelNormalization)

A normalization kernel applied across feature channels.

[`MPSCNNCrossChannelNormalizationGradient`](/documentation/MetalPerformanceShaders/MPSCNNCrossChannelNormalizationGradient)

A gradient normalization kernel applied across feature channels.

[`MPSCNNLocalContrastNormalization`](/documentation/MetalPerformanceShaders/MPSCNNLocalContrastNormalization)

A local-contrast normalization kernel.

[`MPSCNNLocalContrastNormalizationGradient`](/documentation/MetalPerformanceShaders/MPSCNNLocalContrastNormalizationGradient)

A gradient local-contrast normalization kernel.

[`MPSCNNSpatialNormalization`](/documentation/MetalPerformanceShaders/MPSCNNSpatialNormalization)

A spatial normalization kernel.

[`MPSCNNSpatialNormalizationGradient`](/documentation/MetalPerformanceShaders/MPSCNNSpatialNormalizationGradient)

A gradient spatial normalization kernel.

[`MPSCNNBatchNormalization`](/documentation/MetalPerformanceShaders/MPSCNNBatchNormalization)

A batch normalization kernel.

[`MPSCNNBatchNormalizationGradient`](/documentation/MetalPerformanceShaders/MPSCNNBatchNormalizationGradient)

A gradient batch normalization kernel.

[`MPSCNNBatchNormalizationState`](/documentation/MetalPerformanceShaders/MPSCNNBatchNormalizationState)

An object that stores data required to execute batch normalization.

[`MPSCNNNormalizationMeanAndVarianceState`](/documentation/MetalPerformanceShaders/MPSCNNNormalizationMeanAndVarianceState)

An object that stores mean and variance terms used to execute batch normalization.

[`MPSCNNBatchNormalizationStatistics`](/documentation/MetalPerformanceShaders/MPSCNNBatchNormalizationStatistics)

An object that stores statistics required to execute batch normalization.

[`MPSCNNBatchNormalizationStatisticsGradient`](/documentation/MetalPerformanceShaders/MPSCNNBatchNormalizationStatisticsGradient)

An object that stores the gradient of the loss function with respect to the batch statistics and batch normalization weights.

[`MPSCNNInstanceNormalization`](/documentation/MetalPerformanceShaders/MPSCNNInstanceNormalization)

An instance normalization kernel.

[`MPSCNNInstanceNormalizationGradient`](/documentation/MetalPerformanceShaders/MPSCNNInstanceNormalizationGradient)

A gradient instance normalization kernel.

[`MPSCNNInstanceNormalizationGradientState`](/documentation/MetalPerformanceShaders/MPSCNNInstanceNormalizationGradientState)

An object that stores information required to execute a gradient pass for instance normalization.

[`MPSCNNNormalizationGammaAndBetaState`](/documentation/MetalPerformanceShaders/MPSCNNNormalizationGammaAndBetaState)

An object that stores gamma and beta terms used to apply a scale and bias in instance- or batch-normalization operations.

### Upsampling Layers

[`MPSCNNUpsampling`](/documentation/MetalPerformanceShaders/MPSCNNUpsampling)

A filter that resamples an existing MPS image.

[`MPSCNNUpsamplingBilinear`](/documentation/MetalPerformanceShaders/MPSCNNUpsamplingBilinear)

A bilinear spatial upsampling filter.

[`MPSCNNUpsamplingNearest`](/documentation/MetalPerformanceShaders/MPSCNNUpsamplingNearest)

A nearest spatial upsampling filter.

[`MPSCNNUpsamplingBilinearGradient`](/documentation/MetalPerformanceShaders/MPSCNNUpsamplingBilinearGradient)

A gradient bilinear spatial upsampling filter.

[`MPSCNNUpsamplingGradient`](/documentation/MetalPerformanceShaders/MPSCNNUpsamplingGradient)

A gradient filter that upsamples an existing Metal Performance Shaders image.

[`MPSCNNUpsamplingNearestGradient`](/documentation/MetalPerformanceShaders/MPSCNNUpsamplingNearestGradient)

A gradient upsampling filter that samples the pixel nearest to the source when upsampling to the destination pixel.

### Dropout Layers

[`MPSCNNDropout`](/documentation/MetalPerformanceShaders/MPSCNNDropout)

A dropout filter.

[`MPSCNNDropoutGradient`](/documentation/MetalPerformanceShaders/MPSCNNDropoutGradient)

A gradient dropout filter.

[`MPSCNNDropoutGradientState`](/documentation/MetalPerformanceShaders/MPSCNNDropoutGradientState)

A class that stores the mask used by dropout and gradient dropout filters.

### Loss Layers

[`MPSCNNLoss`](/documentation/MetalPerformanceShaders/MPSCNNLoss)

A kernel that computes the loss and loss gradient between specified predictions and labels.

[`MPSCNNLossDataDescriptor`](/documentation/MetalPerformanceShaders/MPSCNNLossDataDescriptor)

An object that specifies properties used by a loss data descriptor.

[`MPSCNNLossDescriptor`](/documentation/MetalPerformanceShaders/MPSCNNLossDescriptor)

An object that specifies properties used by a loss kernel.

[`MPSCNNLossLabels`](/documentation/MetalPerformanceShaders/MPSCNNLossLabels)

A class that stores the per-element weight buffer used by loss and gradient loss kernels.

[`MPSCNNYOLOLoss`](/documentation/MetalPerformanceShaders/MPSCNNYOLOLoss)

A kernel that computes the YOLO loss and loss gradient between specified predictions and labels.

[`MPSCNNYOLOLossDescriptor`](/documentation/MetalPerformanceShaders/MPSCNNYOLOLossDescriptor)

An object that specifies properties used by a YOLO loss kernel.

### Reduction Layers

[`MPSNNReduceRowMax`](/documentation/MetalPerformanceShaders/MPSNNReduceRowMax)

A reduction filter that returns the maximum value for each row in an image.

[`MPSNNReduceRowMin`](/documentation/MetalPerformanceShaders/MPSNNReduceRowMin)

A reduction filter that returns the minimum value for each row in an image.

[`MPSNNReduceRowSum`](/documentation/MetalPerformanceShaders/MPSNNReduceRowSum)

A reduction filter that returns the sum of all values for each row in an image.

[`MPSNNReduceRowMean`](/documentation/MetalPerformanceShaders/MPSNNReduceRowMean)

A reduction filter that returns the mean value for each row in an image.

[`MPSNNReduceColumnMax`](/documentation/MetalPerformanceShaders/MPSNNReduceColumnMax)

A reduction filter that returns the maximum value for each column in an image.

[`MPSNNReduceColumnMin`](/documentation/MetalPerformanceShaders/MPSNNReduceColumnMin)

A reduction filter that returns the minimum value for each column in an image.

[`MPSNNReduceColumnSum`](/documentation/MetalPerformanceShaders/MPSNNReduceColumnSum)

A reduction filter that returns the sum of all values for each column in an image.

[`MPSNNReduceColumnMean`](/documentation/MetalPerformanceShaders/MPSNNReduceColumnMean)

A reduction filter that returns the mean value for each column in an image.

[`MPSNNReduceFeatureChannelsMax`](/documentation/MetalPerformanceShaders/MPSNNReduceFeatureChannelsMax)

A reduction filter that returns the maximum value for each feature channel in an image.

[`MPSNNReduceFeatureChannelsMin`](/documentation/MetalPerformanceShaders/MPSNNReduceFeatureChannelsMin)

A reduction filter that returns the minimum value for each feature channel in an image.

[`MPSNNReduceFeatureChannelsSum`](/documentation/MetalPerformanceShaders/MPSNNReduceFeatureChannelsSum)

A reduction filter that returns the sum of all values for each feature channel in an image.

[`MPSNNReduceFeatureChannelsMean`](/documentation/MetalPerformanceShaders/MPSNNReduceFeatureChannelsMean)

A reduction filter that returns the mean value for each feature channel in an image.

[`MPSNNReduceFeatureChannelsArgumentMax`](/documentation/MetalPerformanceShaders/MPSNNReduceFeatureChannelsArgumentMax)

A reduction filter that returns the index of the location of the maximum value for each feature channel in an image.

[`MPSNNReduceFeatureChannelsArgumentMin`](/documentation/MetalPerformanceShaders/MPSNNReduceFeatureChannelsArgumentMin)

A reduction filter that returns the index of the location of the minimum value for each feature channel in an image.

[`MPSNNReduceFeatureChannelsAndWeightsSum`](/documentation/MetalPerformanceShaders/MPSNNReduceFeatureChannelsAndWeightsSum)

A reduction filter that returns the weighted sum of all values for each feature channel in an image.

[`MPSNNReduceFeatureChannelsAndWeightsMean`](/documentation/MetalPerformanceShaders/MPSNNReduceFeatureChannelsAndWeightsMean)

A reduction filter that returns the weighted sum for each feature channel in an image.

[`MPSNNReduceUnary`](/documentation/MetalPerformanceShaders/MPSNNReduceUnary)

The base class for unary reduction filters.

[`MPSNNReduceBinary`](/documentation/MetalPerformanceShaders/MPSNNReduceBinary)

The base class for binary reduction filters.

### Reshape Layer

[`MPSNNReshape`](/documentation/MetalPerformanceShaders/MPSNNReshape)

The base class for reshape operations.

### Slice Layer

[`MPSNNSlice`](/documentation/MetalPerformanceShaders/MPSNNSlice)

A kernel that extracts a slice from an image.

### Optimization Layers

[`MPSNNOptimizerAdam`](/documentation/MetalPerformanceShaders/MPSNNOptimizerAdam)

An optimization layer that performs an Adam pdate.

[`MPSNNOptimizerRMSProp`](/documentation/MetalPerformanceShaders/MPSNNOptimizerRMSProp)

An optimization layer that performs a root mean square propagation update.

[`MPSNNOptimizerStochasticGradientDescent`](/documentation/MetalPerformanceShaders/MPSNNOptimizerStochasticGradientDescent)

An optimization layer that performs a gradient descent with an optional momentum update.

[`MPSNNOptimizer`](/documentation/MetalPerformanceShaders/MPSNNOptimizer)

The base class for optimization layers.

[`MPSNNOptimizerDescriptor`](/documentation/MetalPerformanceShaders/MPSNNOptimizerDescriptor)

An object that specifies properties used by an optimizer kernel.

### Layer Base Classes

[`MPSCNNKernel`](/documentation/MetalPerformanceShaders/MPSCNNKernel)

Base class for neural network layers.

[`MPSCNNBinaryKernel`](/documentation/MetalPerformanceShaders/MPSCNNBinaryKernel)

A convolution neural network kernel.

[`MPSCNNGradientKernel`](/documentation/MetalPerformanceShaders/MPSCNNGradientKernel)

The base class for gradient layers.

### Predefined Padding Policies

[`MPSNNDefaultPadding`](/documentation/MetalPerformanceShaders/MPSNNDefaultPadding)

A class that provides predefined padding policies for common tasks.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)