inference-engine/include/ie_icnn_network.hpp

   1 // Copyright (C) 2018-2020 Intel Corporation
   2 // SPDX-License-Identifier: Apache-2.0
   3 //
   4
   5 /**
   6  * @brief This is a header file for the ICNNNetwork class
   7  *
   8  * @file ie_icnn_network.hpp
   9  */
  10 #pragma once
  11
  12 #include <map>
  13 #include <memory>
  14 #include <string>
  15
  16 #include "details/ie_irelease.hpp"
  17 #include "ie_blob.h"
  18 #include "ie_common.h"
  19 #include "ie_data.h"
  20 #include "ie_icnn_network_stats.hpp"
  21 #include "ie_iextension.h"
  22 #include "ie_input_info.hpp"
  23 #include "ie_layers.h"
  24 #include "ie_preprocess.hpp"
  25
  26 namespace ngraph {
  27
  28 class Function;
  29
  30 }  // namespace ngraph
  31
  32 namespace InferenceEngine {
  33
  34 /**
  35  * @brief A collection that contains string as key, and Data smart pointer as value
  36  */
  37 using OutputsDataMap = std::map<std::string, DataPtr>;
  38
  39 /**
  40  * @brief This is the main interface to describe the NN topology
  41  */
  42 class INFERENCE_ENGINE_API_CLASS(ICNNNetwork): public details::IRelease {
  43 public:
  44     using Ptr = std::shared_ptr<ICNNNetwork>;
  45
  46     /**
  47      * @brief Returns constant nGraph function
  48      * @return constant nGraph function
  49      */
  50     virtual const std::shared_ptr<const ngraph::Function> getFunction() const noexcept = 0;
  51
  52     /**
  53      * @brief Returns the main network operating precision.
  54      *
  55      * This may be MIXED if not homogeneous.
  56      *
  57      * @return A precision type
  58      */
  59     virtual Precision getPrecision() const noexcept = 0;
  60
  61     /**
  62      * @brief Gets the network output Data node information. The received info is stored in the given Data node.
  63      *
  64      * For single and multiple outputs networks.
  65      *
  66      * @param out Reference to the OutputsDataMap object
  67      */
  68     virtual void getOutputsInfo(OutputsDataMap& out) const noexcept = 0;
  69
  70     /**
  71      * @brief Gets the network input Data node information. The received info is stored in the given InputsDataMap
  72      * object.
  73      *
  74      * For single and multiple inputs networks.
  75      * This method must be called to find out input names for using them later during filling of a map
  76      * of blobs passed later to InferenceEngine::IInferencePlugin::Infer()
  77      *
  78      * @param inputs Reference to InputsDataMap object.
  79      */
  80     virtual void getInputsInfo(InputsDataMap& inputs) const noexcept = 0;
  81
  82     /**
  83      * @brief Returns information on certain input pointed by inputName
  84      *
  85      * @param inputName Name of input layer to get info on
  86      * @return A smart pointer to the input information
  87      */
  88     virtual InputInfo::Ptr getInput(const std::string& inputName) const noexcept = 0;
  89
  90     /**
  91      * @brief Gets the network name. The name is stored in the given pName string.
  92      *
  93      * @param pName - will receive actual network name, specified in IR file,
  94      *     pName should point to valid memory address before invoking this function
  95      * @param len - size in bytes of pName buffer, actual name is trimmed by this size
  96      */
  97     virtual void getName(char* pName, size_t len) const noexcept = 0;
  98
  99     /**
 100      * @brief Returns the network name.
 101      *
 102      * @return Network name
 103      */
 104     virtual const std::string& getName() const noexcept = 0;
 105
 106     /**
 107      * @brief Returns the number of layers in the network as an integer value
 108      *
 109      * @return The number of layers as an integer value
 110      */
 111     virtual size_t layerCount() const noexcept = 0;
 112
 113     /**
 114      * @brief Returns a smart pointer reference to a Data node given its name.
 115      *
 116      * If the Data node is missing, returns reference to a default initialized new empty data pointer with given name.
 117      *
 118      * @param dname Name of the Data node
 119      * @return Data node smart pointer
 120      */
 121     virtual DataPtr& getData(const char* dname) noexcept = 0;
 122
 123     /**
 124      * @brief Insert a layer into the network. A user is responsible to connect it to other data elements.
 125      *
 126      * @param layer Const reference to a layer smart pointer
 127      */
 128     virtual void addLayer(const CNNLayerPtr& layer) noexcept = 0;
 129
 130     /**
 131      * @brief Adds output to the layer
 132      *
 133      * @param layerName Name of the layer
 134      * @param outputIndex Index of the output
 135      * @param resp Response message
 136      * @return Status code of the operation
 137      */
 138     virtual StatusCode addOutput(const std::string& layerName, size_t outputIndex = 0,
 139                                  ResponseDesc* resp = nullptr) noexcept = 0;
 140
 141     /**
 142      * @brief Gets network layer with the given name
 143      *
 144      * @param layerName Given name of the layer
 145      * @param out Pointer to the found CNNLayer object with the given name
 146      * @param resp Pointer to the response message that holds a description of an error if any occurred
 147      * @return Status code of the operation. InferenceEngine::OK if succeeded
 148      */
 149     virtual StatusCode getLayerByName(const char* layerName, CNNLayerPtr& out, ResponseDesc* resp) const noexcept = 0;
 150
 151     /**
 152      * @brief Changes the inference batch size.
 153      *
 154      * @note There are several limitations and it's not recommended to use it. Set batch to the input shape and call
 155      * ICNNNetwork::reshape.
 156      *
 157      * @param size Size of batch to set
 158      * @return Status code of the operation
 159      * @note: Current implementation of the function sets batch size to the first dimension of all layers in the
 160      * networks. Before calling it make sure that all your layers have batch in the first dimension, otherwise the
 161      * method works incorrectly. This limitation is resolved via shape inference feature by using
 162      * InferenceEngine::ICNNNetwork::reshape method. To read more refer to the Shape Inference section in documentation
 163      *
 164      * @note: Current implementation of the function sets batch size to the first dimension of all layers in the
 165      * networks. Before calling it make sure that all your layers have batch in the first dimension, otherwise the
 166      * method works incorrectly. This limitation is resolved via shape inference feature by using
 167      * InferenceEngine::ICNNNetwork::reshape method. To read more refer to the Shape Inference section in documentation
 168      */
 169     virtual StatusCode setBatchSize(size_t size, ResponseDesc* responseDesc) noexcept = 0;
 170
 171     /**
 172      * @brief Gets the inference batch size
 173      *
 174      * @return The size of batch as a size_t value
 175      */
 176     virtual size_t getBatchSize() const noexcept = 0;
 177
 178     /**
 179      * @brief Map of pairs: name of corresponding data and its dimension.
 180      */
 181     using InputShapes = std::map<std::string, SizeVector>;
 182
 183     /**
 184      * @brief Run shape inference with new input shapes for the network
 185      *
 186      * @param inputShapes - map of pairs: name of corresponding data and its dimension.
 187      * @param resp Pointer to the response message that holds a description of an error if any occurred
 188      * @return Status code of the operation
 189      */
 190     virtual StatusCode reshape(const InputShapes& /*inputShapes*/, ResponseDesc* /*resp*/) noexcept {
 191         return NOT_IMPLEMENTED;
 192     };
 193
 194     /**
 195      * @brief Registers extension within the plugin
 196      *
 197      * @param extension Pointer to already loaded reader extension with shape propagation implementations
 198      * @param resp Pointer to the response message that holds a description of an error if any occurred
 199      * @return Status code of the operation. InferenceEngine::OK if succeeded
 200      */
 201     virtual StatusCode AddExtension(const IShapeInferExtensionPtr& /*extension*/, ResponseDesc* /*resp*/) noexcept {
 202         return NOT_IMPLEMENTED;
 203     };
 204
 205     virtual StatusCode getStats(ICNNNetworkStats** /*stats*/, ResponseDesc* /*resp*/) const noexcept {
 206         return NOT_IMPLEMENTED;
 207     };
 208
 209     /**
 210      * @brief Serialize network to IR and weights files.
 211      *
 212      * @param xmlPath Path to output IR file.
 213      * @param binPath Path to output weights file.
 214      * @return Status code of the operation
 215      */
 216     virtual StatusCode serialize(const std::string& xmlPath, const std::string& binPath, ResponseDesc* resp) const
 217         noexcept = 0;
 218
 219     virtual ~ICNNNetwork();
 220 };
 221 }  // namespace InferenceEngine