| MPSNNGraph(3) | MetalPerformanceShaders.framework | MPSNNGraph(3) |
MPSNNGraph
#import <MPSNNGraph.h>
Inherits MPSKernel, <NSCopying>, and <NSSecureCoding>.
(nullable instancetype) -
initWithDevice:resultImage:resultImageIsNeeded:
(nullable instancetype) - initWithDevice:resultImage:
(nullable instancetype) - initWithCoder:device:
(nonnull instancetype) - initWithDevice:
(void) - reloadFromDataSources
(MPSImage *__nullable) -
encodeToCommandBuffer:sourceImages:sourceStates:intermediateImages:destinationStates:
(MPSImageBatch *__nullable) -
encodeBatchToCommandBuffer:sourceImages:sourceStates:intermediateImages:destinationStates:
(MPSImage *__nullable) - encodeToCommandBuffer:sourceImages:
(MPSImageBatch *__nullable) -
encodeBatchToCommandBuffer:sourceImages:sourceStates:
(MPSImage *__nonnull) -
executeAsyncWithSourceImages:completionHandler:
(nullable instancetype) +
graphWithDevice:resultImage:resultImageIsNeeded:
(nullable instancetype) + graphWithDevice:resultImage:
NSArray< id< MPSHandle > > *
sourceImageHandles
NSArray< id< MPSHandle > > * sourceStateHandles
NSArray< id< MPSHandle > > *
intermediateImageHandles
NSArray< id< MPSHandle > > * resultStateHandles
id< MPSHandle > resultHandle
BOOL outputStateIsTemporary
id< MPSImageAllocator > destinationImageAllocator
MPSImageFeatureChannelFormat format
BOOL resultImageIsNeeded
Optimized representation of a graph of MPSNNImageNodes and MPSNNFilterNodes Once you have prepared a graph of MPSNNImageNodes and MPSNNFilterNodes (and if needed MPSNNStateNodes), you may initialize a MPSNNGraph using the MPSNNImageNode that you wish to appear as the result. The MPSNNGraph 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 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 construction, the graph attached to the result node will be parsed and reduced to an optimized representation. This representation may be saved using the NSSecureCoding protocol for later recall.
When decoding a MPSNNGraph using a NSCoder, it will be created against the system default MTLDevice. If you would like to set the MTLDevice, your NSCoder should conform to the <MPSDeviceProvider> protocol.
You may find it helpful to set MPSKernelOptionsVerbose on the graph when debugging. To turn this on during MPSKernel initialization (including MPSNNGraph initialization) set the MPS_LOG_INFO environment variable. There is a lot of information about what optimizations are done to your graph, including some information on why certain optimizations were not made.
Convenience method to encode a batch of images
Encode the graph to a MTLCommandBuffer This interface is like the other except that it operates on a batch of images all at once. In addition, you may specify whether the result is needed.
Parameters:
Returns:
Encode the graph to a MTLCommandBuffer
IMPORTANT: Please use [MTLCommandBuffer addCompletedHandler:] to determine when this work is done. Use CPU time that would have been spent waiting for the GPU to encode the next command buffer and commit it too. That way, the work for the next command buffer is ready to go the moment the GPU is done. This will keep the GPU busy and running at top speed.
Those who ignore this advice and use [MTLCommandBuffer waitUntilCompleted] instead will likely cause their code to slow down by a factor of two or more. The CPU clock spins down while it waits for the GPU. When the GPU completes, the CPU runs slowly for a while until it spins up. The GPU has to wait for the CPU to encode more work (at low clock), giving it plenty of time to spin its own clock down. In typical CNN graph usage, neither may ever reach maximum clock frequency, causing slow down far beyond what otherwise would be expected from simple failure to schedule CPU and GPU work concurrently. Regrattably, it is probable that every performance benchmark you see on the net will be based on [MTLCommandBuffer waitUntilCompleted].
Parameters:
Returns:
Encode the graph to a MTLCommandBuffer
Parameters:
Returns:
Convenience method to execute a graph without having to manage many Metal details This function will synchronously encode the graph on a private command buffer, commit it to a MPS internal command queue and return. The GPU will start working. When the GPU is done, the completion handler will be called. You should use the intervening time to encode other work for execution on the GPU, so that the GPU stays busy and doesn't clock down.
The work will be performed on the MTLDevice that hosts the source images.
This is a convenience API. There are a few situations it does not handle optimally. These may be better handled using [encodeToCommandBuffer:sourceImages:]. Specifically:
o If the graph needs to be run multiple times for different images,
it would be better to encode the graph multiple times on the same
command buffer using [encodeToCommandBuffer:sourceImages:] This
will allow the multiple graphs to share memory for intermediate
storage, dramatically reducing memory usage. o If preprocessing or post-processing of the MPSImage is required,
such as resizing or normalization outside of a convolution, it would
be better to encode those things on the same command buffer.
Memory may be saved here too for intermediate storage. (MPSTemporaryImage
lifetime does not span multiple command buffers.)
Parameters:
Returns:
NSSecureCoding compatability While the standard NSSecureCoding/NSCoding method -initWithCoder: should work, since the file can't know which device your data is allocated on, we have to guess and may guess incorrectly. To avoid that problem, use initWithCoder:device instead.
Parameters:
Returns:
Reimplemented from MPSKernel.
Use initWithDevice:resultImage: instead
Initialize a MPSNNGraph object on a device starting with resultImage working backward The MPSNNGraph constructor will start with the indicated result image, and look to see what MPSNNFilterNode produced it, then look to its dependencies and so forth to reveal the subsection of the graph necessary to compute the image.
Parameters:
Returns:
Reinitialize all graph nodes from data sources A number of the nodes that make up a graph have a data source associated with them, for example a MPSCNNConvolutionDataSource or a MPSCNNBatchNormalizationDataSource. Generally, the data is read from these once at graph initialization time and then not looked at again, except during the weight / parameter update phase of the corresponding gradient nodes and then only if CPU updates are requested. Otherwise, update occurs on the GPU, and the data in the data source is thereafter ignored.
It can happen, though, that your application has determined the graph should load a new set of weights from the data source. When this method is called, the graph will find all nodes that support reloading and direct them to reinitialize themselves based on their data source.
This process occurs immediately. Your application will need to make sure any GPU work being done by the graph is complete to ensure data coherency. Most nodes do not have a data source and will not be modified. Nodes that are not used by the graph will not be updated.
Method to allocate the result image from -encodeToCommandBuffer... This property overrides the allocator for the final result image in the graph. Default: defaultAllocator (MPSImage)
The default storage format used for graph intermediate images This doesn't affect how data is stored in buffers in states. Nor does it affect the storage format for weights such as convolution weights stored by individual filters. Default: MPSImageFeatureChannelFormatFloat16
Get a list of identifiers for intermediate images objects produced by the graph
Should MPSState objects produced by -encodeToCommandBuffer... be temporary objects. See MPSState description. Default: NO
Get a handle for the graph result image
Set at -init time. If NO, nil will be returned from -encode calls and some computation may be omitted.
Get a list of identifiers for result state objects produced by the graph Not guaranteed to be in the same order as sourceStateHandles
Get a list of identifiers for source images needed to calculate the result image
Get a list of identifiers for source state objects needed to calculate the result image Not guaranteed to be in the same order as resultStateHandles
Generated automatically by Doxygen for MetalPerformanceShaders.framework from the source code.
| Mon Jul 9 2018 | Version MetalPerformanceShaders-119.3 |