<!--
{
  "availability" : [
    "iOS: 11.0.0 -",
    "iPadOS: 11.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 10.13.0 -",
    "tvOS: 11.0.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "MetalPerformanceShaders",
  "identifier" : "/documentation/MetalPerformanceShaders/MPSNNGraph",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Metal Performance Shaders"
    ],
    "preciseIdentifier" : "c:objc(cs)MPSNNGraph"
  },
  "title" : "MPSNNGraph"
}
-->

# MPSNNGraph

An optimized representation of a graph of neural network image and filter nodes.

```
class MPSNNGraph
```

## Overview

Once you have prepared a graph of [`MPSNNImageNode`](/documentation/MetalPerformanceShaders/MPSNNImageNode), [`MPSNNFilterNode`](/documentation/MetalPerformanceShaders/MPSNNFilterNode), and, if needed, [`MPSNNStateNode`](/documentation/MetalPerformanceShaders/MPSNNStateNode) objects, you may initialize a [`MPSNNGraph`](/documentation/MetalPerformanceShaders/MPSNNGraph) using the image node that you wish to appear as the result. The graph object will introspect the graph representation and determine which nodes are needed for inputs, and which nodes are produced as output state (if any). Nodes which are not needed to calculate the result image node are ignored. Some nodes may be internally concatenated with other nodes for better performance.

> Note:
> The ``doc://com.apple.metalperformanceshaders/documentation/MetalPerformanceShaders/MPSNNImageNode`` that you choose as the result node may be interior to a graph. This feature is provided as a means to examine intermediate computations in the full graph for debugging purposes.

During [`MPSNNGraph`](/documentation/MetalPerformanceShaders/MPSNNGraph) construction, the graph attached to the result node will be parsed and reduced to an optimized representation. This representation may be saved using the <doc://com.apple.documentation/documentation/Foundation/NSSecureCoding> protocol for later recall.

When decoding a [`MPSNNGraph`](/documentation/MetalPerformanceShaders/MPSNNGraph) using a <doc://com.apple.documentation/documentation/Foundation/NSCoder>, it will be created against the system default <doc://com.apple.documentation/documentation/Metal/MTLDevice>. If you would like to set the device, your <doc://com.apple.documentation/documentation/Foundation/NSCoder> should conform to the [`MPSDeviceProvider`](/documentation/MetalPerformanceShaders/MPSDeviceProvider) protocol.

### Debugging Tips

In typical usage, some refinement, especially of padding policies, may be required to get the expected answer from Metal Performance Shaders. If the result image is the wrong size, padding is typically the problem. When the answers are incorrect, the [`offset`](/documentation/MetalPerformanceShaders/MPSCNNKernel/offset) or other property may be incorrectly configured at some stage. As the graph is generated starting from an output image node, you may create other graphs starting at any image node within the graph. This will give you a view into the result produced from each intermediate layer with a minimum of fuss. In addition, the usual <doc://com.apple.documentation/documentation/ObjectiveC/NSObject-swift.class/debugDescription()> method is available to inspect objects to make sure they conform to expectation.

Note that certain operations such as neuron filters that follow convolution filters and image concatenation may be optimized away by the [`MPSNNGraph`](/documentation/MetalPerformanceShaders/MPSNNGraph) when it is constructed. The convolution can do neuron operations as part of its operation. Concatenation is best done by writing the result of earlier filter passes in the right place using [`destinationFeatureChannelOffset`](/documentation/MetalPerformanceShaders/MPSCNNKernel/destinationFeatureChannelOffset) rather than by adding an extra copy. Other optimizations may be added as framework capabilities improve.

## Topics

### Initializers

[`-  initWithCoder:device:`](/documentation/MetalPerformanceShaders/MPSNNGraph/init(coder:device:))

[`-  initWithDevice:resultImage:`](/documentation/MetalPerformanceShaders/MPSNNGraph/init(device:resultImage:))

[`-  initWithDevice:resultImage:resultImageIsNeeded:`](/documentation/MetalPerformanceShaders/MPSNNGraph/init(device:resultImage:resultImageIsNeeded:))

[`-  initWithDevice:resultImages:resultsAreNeeded:`](/documentation/MetalPerformanceShaders/MPSNNGraph/init(device:resultImages:resultsAreNeeded:))

### Instance Properties

[`destinationImageAllocator`](/documentation/MetalPerformanceShaders/MPSNNGraph/destinationImageAllocator)

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

[`intermediateImageHandles`](/documentation/MetalPerformanceShaders/MPSNNGraph/intermediateImageHandles)

[`outputStateIsTemporary`](/documentation/MetalPerformanceShaders/MPSNNGraph/outputStateIsTemporary)

[`resultHandle`](/documentation/MetalPerformanceShaders/MPSNNGraph/resultHandle)

[`resultStateHandles`](/documentation/MetalPerformanceShaders/MPSNNGraph/resultStateHandles)

[`sourceImageHandles`](/documentation/MetalPerformanceShaders/MPSNNGraph/sourceImageHandles)

[`sourceStateHandles`](/documentation/MetalPerformanceShaders/MPSNNGraph/sourceStateHandles)

[`format`](/documentation/MetalPerformanceShaders/MPSNNGraph/format)

[`resultImageIsNeeded`](/documentation/MetalPerformanceShaders/MPSNNGraph/resultImageIsNeeded)

### Instance Methods

[`-  encodeToCommandBuffer:sourceImages:`](/documentation/MetalPerformanceShaders/MPSNNGraph/encode(to:sourceImages:))

[`-  encodeToCommandBuffer:sourceImages:sourceStates:intermediateImages:destinationStates:`](/documentation/MetalPerformanceShaders/MPSNNGraph/encode(to:sourceImages:sourceStates:intermediateImages:destinationStates:))

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

An opaque data container for large storage in MPS CNN filters.

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

A class representing the state of a gradient binary kernel when it was encoded.

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

A class representing the state of a gradient kernel when it was encoded.

[`-  executeAsyncWithSourceImages:completionHandler:`](/documentation/MetalPerformanceShaders/MPSNNGraph/executeAsync(withSourceImages:completionHandler:))

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

A notification when an asynchronous graph execution has finished.

[`-  encodeBatchToCommandBuffer:sourceImages:sourceStates:`](/documentation/MetalPerformanceShaders/MPSNNGraph/encodeBatch(to:sourceImages:sourceStates:))

[`-  encodeBatchToCommandBuffer:sourceImages:sourceStates:intermediateImages:destinationStates:`](/documentation/MetalPerformanceShaders/MPSNNGraph/encodeBatch(to:sourceImages:sourceStates:intermediateImages:destinationStates:))

[`-  readCountForSourceImageAtIndex:`](/documentation/MetalPerformanceShaders/MPSNNGraph/readCountForSourceImage(at:))

[`-  readCountForSourceStateAtIndex:`](/documentation/MetalPerformanceShaders/MPSNNGraph/readCountForSourceState(at:))

[`-  reloadFromDataSources`](/documentation/MetalPerformanceShaders/MPSNNGraph/reloadFromDataSources())

## Relationships

### Conforms To

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`NSCoding`](/documentation/Foundation/NSCoding)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`NSCopying`](/documentation/Foundation/NSCopying)

[`CVarArg`](/documentation/Swift/CVarArg)

[`Hashable`](/documentation/Swift/Hashable)

[`Equatable`](/documentation/Swift/Equatable)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`NSSecureCoding`](/documentation/Foundation/NSSecureCoding)

### Inherits From

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

---

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)