include/armnn/INetwork.hpp

   1 //
   2 // Copyright © 2017 Arm Ltd. All rights reserved.
   3 // See LICENSE file in the project root for full license information.
   4 //
   5 #pragma once
   6
   7 #include "armnn/NetworkFwd.hpp"
   8 #include "armnn/DescriptorsFwd.hpp"
   9 #include "armnn/TensorFwd.hpp"
  10
  11 #include "armnn/Types.hpp"
  12
  13 #include <memory>
  14
  15 namespace armnn
  16 {
  17
  18 /// @brief An input connection slot for a layer.
  19 /// The input slot can be connected to an output slot of the preceding layer in the graph.
  20 /// Only one connection to the input slot is allowed.
  21 class IInputSlot
  22 {
  23 public:
  24     virtual const IOutputSlot* GetConnection() const = 0;
  25     virtual IOutputSlot* GetConnection() = 0;
  26
  27 protected:
  28     ~IInputSlot() {} /// Not user deletable
  29 };
  30
  31 /// @brief An output connection slot for a layer.
  32 /// The output slot may be connected to 1 or more input slots of subsequent layers in the graph.
  33 class IOutputSlot
  34 {
  35 public:
  36     virtual unsigned int GetNumConnections() const = 0;
  37     virtual const IInputSlot* GetConnection(unsigned int index) const = 0;
  38     virtual IInputSlot* GetConnection(unsigned int index) = 0;
  39
  40     virtual void SetTensorInfo(const TensorInfo& tensorInfo) = 0;
  41     virtual const TensorInfo& GetTensorInfo() const = 0;
  42     virtual bool IsTensorInfoSet() const = 0;
  43
  44     virtual int Connect(IInputSlot& destination) = 0;
  45     virtual void Disconnect(IInputSlot& slot) = 0;
  46
  47 protected:
  48     ~IOutputSlot() {} /// Not user deletable
  49 };
  50
  51 /// @brief Interface for a layer that is connectable to other layers via InputSlots and OutputSlots.
  52 class IConnectableLayer
  53 {
  54 public:
  55     virtual const char* GetName() const = 0;
  56
  57     virtual unsigned int GetNumInputSlots() const = 0;
  58     virtual unsigned int GetNumOutputSlots() const = 0;
  59
  60     virtual const IInputSlot& GetInputSlot(unsigned int index) const = 0;
  61     virtual IInputSlot& GetInputSlot(unsigned int index) = 0;
  62
  63     virtual const IOutputSlot& GetOutputSlot(unsigned int index) const = 0;
  64     virtual IOutputSlot& GetOutputSlot(unsigned int index) = 0;
  65
  66 protected:
  67     ~IConnectableLayer() {} // Objects are not deletable via the handle
  68 };
  69
  70 using INetworkPtr = std::unique_ptr<INetwork, void(*)(INetwork* network)>;
  71
  72 /// Main network class which provides the interface for building up a neural network.
  73 /// This object is subsequently required by the IRuntime::Load() method.
  74 class INetwork
  75 {
  76 public:
  77     static INetwork* CreateRaw();
  78     static INetworkPtr Create();
  79     static void Destroy(INetwork* network);
  80
  81     virtual Status PrintGraph() = 0;
  82
  83     /// Add an input layer to the network.
  84     /// @param id User generated id to uniquely identify a particular input. The same id needs to be specified
  85     /// when passing the inputs to the IRuntime::EnqueueWorkload() function.
  86     /// @param name Optional name for the layer
  87     /// @return Interface for configuring the layer.
  88     virtual IConnectableLayer* AddInputLayer(LayerBindingId id, const char* name = nullptr) = 0;
  89
  90     /// Add a 2D convolution layer to the network.
  91     /// @param convolution2dDescriptor Description of the 2D convolution layer
  92     /// @param weights Tensor for the weights data.
  93     /// @param biases (Optional) Tensor for the bias data. Must match the output tensor shape.
  94     /// @param name Optional name for the layer
  95     /// @return Interface for configuring the layer.
  96     virtual IConnectableLayer* AddConvolution2dLayer(const Convolution2dDescriptor& convolution2dDescriptor,
  97         const ConstTensor& weights,
  98         const char* name = nullptr) = 0;
  99
 100     virtual IConnectableLayer* AddConvolution2dLayer(const Convolution2dDescriptor& convolution2dDescriptor,
 101         const ConstTensor& weights,
 102         const ConstTensor& biases,
 103         const char* name = nullptr) = 0;
 104
 105     /// Add a 2D depthwise convolution layer to the network.
 106     /// @param convolution2dDescriptor Description of the 2D depthwise convolution layer
 107     /// @param weights Tensor for the weights data. Expected format: [1, outputChannels, height, width]
 108     /// @param biases (Optional) Tensor for the bias data. Must match the output tensor shape.
 109     /// @param name Optional name for the layer
 110     /// @return Interface for configuring the layer.
 111     virtual IConnectableLayer* AddDepthwiseConvolution2dLayer(
 112         const DepthwiseConvolution2dDescriptor& convolution2dDescriptor,
 113         const ConstTensor& weights,
 114         const char* name = nullptr) = 0;
 115
 116     virtual IConnectableLayer* AddDepthwiseConvolution2dLayer(
 117         const DepthwiseConvolution2dDescriptor& convolution2dDescriptor,
 118         const ConstTensor& weights,
 119         const ConstTensor& biases,
 120         const char* name = nullptr) = 0;
 121
 122     /// Add a fully connected layer to the network.
 123     /// @param fullyConnectedDescriptor Description of the fully connected layer
 124     /// @param weights Tensor for the weights data.
 125     /// @param biases (Optional) Tensor for the bias data.
 126     /// @param name Optional name for the layer
 127     /// @return Interface for configuring the layer.
 128     virtual IConnectableLayer* AddFullyConnectedLayer(const FullyConnectedDescriptor& fullyConnectedDescriptor,
 129         const ConstTensor& weights,
 130         const char* name = nullptr) = 0;
 131
 132     virtual IConnectableLayer* AddFullyConnectedLayer(const FullyConnectedDescriptor& fullyConnectedDescriptor,
 133         const ConstTensor& weights,
 134         const ConstTensor& biases,
 135         const char* name = nullptr) = 0;
 136
 137     /// Add a permute layer to the network.
 138     /// @param permuteDescriptor PermuteDescriptor to configure the permute
 139     /// @param name Optional name for the layer
 140     /// @return Interface for configuring the layer.
 141     virtual IConnectableLayer* AddPermuteLayer(const PermuteDescriptor& permuteDescriptor,
 142                                                const char* name = nullptr) = 0;
 143
 144     /// Add a pooling layer to the network.
 145     /// @param pooling2dDescriptor Pooling2dDescriptor to configure the pooling
 146     /// @param name Optional name for the layer
 147     /// @return Interface for configuring the layer.
 148     virtual IConnectableLayer* AddPooling2dLayer(const Pooling2dDescriptor& pooling2dDescriptor,
 149         const char* name = nullptr) = 0;
 150
 151     /// Add an activation layer to the network.
 152     /// @param activationDescriptor ActivationDescriptor to configure the activation
 153     /// @param name Optional name for the layer
 154     /// @return Interface for configuring the layer.
 155     virtual IConnectableLayer* AddActivationLayer(const ActivationDescriptor& activationDescriptor,
 156         const char* name = nullptr) = 0;
 157
 158     /// Add a normalization layer to the network.
 159     /// @param normalizationDescriptor NormalizationDescriptor to configure the normalization
 160     /// @param name Optional name for the layer
 161     /// @return Interface for configuring the layer.
 162     virtual IConnectableLayer* AddNormalizationLayer(const NormalizationDescriptor& normalizationDescriptor,
 163         const char* name = nullptr) = 0;
 164
 165     /// Add a softmax layer to the network.
 166     /// @param softmaxDescriptor SoftmaxDescriptor to configure the softmax
 167     /// @param name Optional name for the layer
 168     /// @return Interface for configuring the layer.
 169     virtual IConnectableLayer* AddSoftmaxLayer(const SoftmaxDescriptor& softmaxDescriptor,
 170         const char* name = nullptr) = 0;
 171
 172     /// Add a splitter layer to the network.
 173     /// @param splitterDescriptor WindowsDescriptor to configure the splitting process. Number of Views must be equal to
 174     ///                           the number of outputs, and their order must match - e.g. first view corresponds to
 175     ///                           the first output, second view to the second output, etc....
 176     /// @param name Optional name for the layer
 177     /// @return Interface for configuring the layer.
 178     virtual IConnectableLayer* AddSplitterLayer(const ViewsDescriptor& splitterDescriptor
 179         , const char* name = nullptr) = 0;
 180
 181     /// Add a merger layer to the network.
 182     /// @param mergerDescriptor WindowsDescriptor to configure the merging process. Number of Views must be equal to
 183     ///                           the number of inputs, and their order must match - e.g. first view corresponds to
 184     ///                           the first input, second view to the second input, etc....
 185     /// @param name Optional name for the layer
 186     /// @return Interface for configuring the layer.
 187     virtual IConnectableLayer* AddMergerLayer(const OriginsDescriptor& mergerDescriptor,
 188         const char* name = nullptr) = 0;
 189
 190     /// Add an addition layer to the network.
 191     /// @param name Optional name for the layer
 192     /// @return Interface for configuring the layer.
 193     virtual IConnectableLayer* AddAdditionLayer(const char* name = nullptr) = 0;
 194
 195     /// Add a multiplication layer to the network.
 196     /// @param name Optional name for the layer
 197     /// @return Interface for configuring the layer.
 198     virtual IConnectableLayer* AddMultiplicationLayer(const char* name = nullptr) = 0;
 199
 200     /// Add a batch normalization layer to the network.
 201     /// @param mean Pre-calculated mean for each channel
 202     /// @param variance Pre-calculated variance for each channel
 203     /// @param beta Per-channel additive factor
 204     /// @param gamma Per-channel multiplicative factor
 205     /// @return Interface for configuring the layer.
 206     /// @param name Optional name for the layer
 207     virtual IConnectableLayer* AddBatchNormalizationLayer(const BatchNormalizationDescriptor& desc,
 208         const ConstTensor& mean,
 209         const ConstTensor& variance,
 210         const ConstTensor& beta,
 211         const ConstTensor& gamma,
 212         const char* name = nullptr) = 0;
 213
 214     /// Add a resize bilinear layer to the network.
 215     /// @param resizeDesc Parameters for the resize operation
 216     /// @param name Optional name for the layer
 217     /// @return Interface for configuring the layer
 218     virtual IConnectableLayer* AddResizeBilinearLayer(const ResizeBilinearDescriptor& resizeDesc,
 219                                                       const char* name = nullptr) = 0;
 220
 221     /// Add an L2 normalization layer to the network.
 222     /// Normalization is performed along dimension 1, but requires a 4d input.
 223     /// @param name Optional name for the layer
 224     /// @return Interface for configuring the layer
 225     virtual IConnectableLayer* AddL2NormalizationLayer(const char* name = nullptr) = 0;
 226
 227     /// Adds a layer with no inputs and a single output, which always corresponds to
 228     /// the passed in constant tensor.
 229     /// @param input Tensor to be provided as the only output of the layer. The layer will maintain its own copy of the
 230     ///        tensor data, meaning the memory referenced by @a input can be freed or reused after this function is
 231     ///        called.
 232     /// @param name Optional name for the layer
 233     /// @return Interface for configuring the layer
 234     virtual IConnectableLayer* AddConstantLayer(const ConstTensor& input,
 235         const char* name = nullptr) = 0;
 236
 237     /// Add a reshape layer to the network.
 238     /// @param reshapeDescriptor Parameters for the reshape operation
 239     /// @param name Optional name for the layer
 240     /// @return Interface for configuring the layer.
 241     virtual IConnectableLayer* AddReshapeLayer(const ReshapeDescriptor& reshapeDescriptor,
 242                                                const char* name = nullptr) = 0;
 243
 244     /// Add a floor layer to the network.
 245     /// @param name Optional name for the layer
 246     /// @return Interface for configuring the layer.
 247     virtual IConnectableLayer* AddFloorLayer(const char* name = nullptr) = 0;
 248
 249     /// Add an output layer to the network.
 250     /// @param id User generated id to uniquely identify a particular output. The same id needs to be specified
 251     /// when passing the outputs to the IRuntime::EnqueueWorkload() function.
 252     /// @param name Optional name for the layer
 253     /// @return Interface for configuring the layer.
 254     virtual IConnectableLayer* AddOutputLayer(LayerBindingId id, const char* name = nullptr) = 0;
 255
 256 protected:
 257     ~INetwork() {}
 258 };
 259
 260 using IOptimizedNetworkPtr = std::unique_ptr<IOptimizedNetwork, void(*)(IOptimizedNetwork* network)>;
 261
 262 class IOptimizedNetwork
 263 {
 264 public:
 265     static void Destroy(IOptimizedNetwork* network);
 266
 267     virtual Status PrintGraph() = 0;
 268
 269 protected:
 270     ~IOptimizedNetwork() {}
 271 };
 272
 273
 274 /// Create an optimized version of the network
 275 /// @param network INetwork description of the network to be optimized.
 276 /// @param deviceSpec The choice of the default computation backend.
 277 /// @return An IOptimizedNetworkPtr interface to the optimized network, throws an exception derived from
 278 /// armnn::Exception if process fails.
 279 IOptimizedNetworkPtr Optimize(const INetwork& network, const DeviceSpec& deviceSpec);
 280
 281 } //namespace armnn