inference-engine/include/ie_icnn_network.hpp

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