Line data Source code
1 : // SPDX-License-Identifier: Apache-2.0
2 : /**
3 : * Copyright (C) 2020 Parichay Kapoor <pk.kapoor@samsung.com>
4 : *
5 : * @file model.h
6 : * @date 14 October 2020
7 : * @see https://github.com/nnstreamer/nntrainer
8 : * @author Jijoong Moon <jijoong.moon@samsung.com>
9 : * @author Parichay Kapoor <pk.kapoor@samsung.com>
10 : * @bug No known bugs except for NYI items
11 : * @brief This is model interface for c++ API
12 : *
13 : * @note This is experimental API and not stable.
14 : */
15 :
16 : #ifndef __ML_TRAIN_MODEL_H__
17 : #define __ML_TRAIN_MODEL_H__
18 :
19 : #if __cplusplus >= MIN_CPP_VERSION
20 :
21 : #include <string>
22 : #include <type_traits>
23 : #include <vector>
24 :
25 : #include <common.h>
26 :
27 : #include <dataset.h>
28 : #include <layer.h>
29 : #include <optimizer.h>
30 : #include <tensor_dim.h>
31 :
32 : namespace nntrainer {
33 : class RunLayerContext;
34 : }
35 : /** Define more aliases for the model in the API */
36 : namespace ml {
37 : namespace train {
38 :
39 : /**
40 : * @brief Statistics from running or training a model
41 : */
42 : struct RunStats {
43 : float accuracy; /** accuracy of the model */
44 : float loss; /** loss of the model */
45 : int num_iterations; /** number of iterations done on this stat */
46 : int max_epoch;
47 : int epoch_idx;
48 : unsigned int
49 : num_correct_predictions; /** number of right sample on this run */
50 :
51 : /**
52 : * @brief Initializer of RunStats
53 : */
54 881 : RunStats() :
55 : accuracy(0),
56 : loss(0),
57 : num_iterations(0),
58 : max_epoch(0),
59 : epoch_idx(0),
60 881 : num_correct_predictions(0) {}
61 : };
62 :
63 : /**
64 : * @brief Enumeration of Network Type
65 : */
66 : enum class ModelType {
67 : KNN, /** k Nearest Neighbor */
68 : NEURAL_NET, /** Neural Network */
69 : UNKNOWN /** Unknown */
70 : };
71 :
72 : /**
73 : * @brief Enumeration to state type of reference of layers
74 : */
75 : enum class ReferenceLayersType {
76 : BACKBONE, /** backbone */
77 : RECURRENT, /** recurrent */
78 : };
79 :
80 : /**
81 : * @brief Model saving options
82 : *
83 : */
84 : enum class ModelFormat {
85 : MODEL_FORMAT_BIN =
86 : ML_TRAIN_MODEL_FORMAT_BIN, /**< raw bin file saves model weights required
87 : for inference and training without any configurations*/
88 : MODEL_FORMAT_INI = ML_TRAIN_MODEL_FORMAT_INI, /**< ini file */
89 : MODEL_FORMAT_INI_WITH_BIN =
90 : ML_TRAIN_MODEL_FORMAT_INI_WITH_BIN, /**< ini file with save_path defined
91 : where the binary will be saved */
92 : MODEL_FORMAT_FLATBUFFER =
93 : ML_TRAIN_MODEL_FORMAT_FLATBUFFER, /**< flatbuffer file */
94 : };
95 :
96 : /**
97 : * @class Model Class
98 : * @brief Model Class containing configuration, layers, optimizer and dataset
99 : */
100 881 : class Model {
101 : public:
102 : /**
103 : * @brief Destructor of Model Class
104 : */
105 1457 : virtual ~Model() = default;
106 :
107 : /**
108 : * @brief Create and load the Network with ini configuration file.
109 : * @param[in] config config file path
110 : * @retval #ML_ERROR_NONE Successful.
111 : * @retval #ML_ERROR_INVALID_PARAMETER invalid parameter.
112 : */
113 : virtual int loadFromConfig(const std::string &config) = 0;
114 :
115 : /**
116 : * @brief Minimal set of properties that must be supported by the model
117 : * @details The minimal properties:
118 : - loss_type
119 : - batch_size
120 : - epochs
121 : - save_path
122 : - continue_train
123 : */
124 : /**
125 : * @brief set Property of Network
126 : * @param[in] values values of property
127 : * @retval #ML_ERROR_NONE Successful.
128 : * @retval #ML_ERROR_INVALID_PARAMETER invalid parameter.
129 : * @details This function accepts vector of properties in the format -
130 : * { std::string property_name, void * property_val, ...}
131 : */
132 : virtual void setProperty(const std::vector<std::string> &values) = 0;
133 :
134 : /**
135 : * @brief Compile Network. This should be called before initialize
136 : * @retval #ML_ERROR_NONE Successful.
137 : * @retval #ML_ERROR_INVALID_PARAMETER invalid parameter.
138 : */
139 : virtual int compile() = 0;
140 :
141 : /**
142 : * @brief Initialize Network. This should be called after setting the
143 : * property and compiling.
144 : * @retval #ML_ERROR_NONE Successful.
145 : * @retval #ML_ERROR_INVALID_PARAMETER invalid parameter.
146 : */
147 : virtual int initialize() = 0;
148 :
149 : /**
150 : * @brief save model states and training parameters from a file
151 : * @param file_path file_path to save the model, if full path is not
152 : * given, it should be saved inside working directory
153 : * @param format format to save parameters
154 : */
155 : virtual void save(const std::string &file_path,
156 : ModelFormat format = ModelFormat::MODEL_FORMAT_BIN) = 0;
157 :
158 : /**
159 : * @brief load model with regard to the format
160 : * @param file_path file_path to save the model, if full path is not
161 : * given, it should be saved inside working directory
162 : * @param format format to save parameters
163 : */
164 : virtual void load(const std::string &file_path,
165 : ModelFormat format = ModelFormat::MODEL_FORMAT_BIN) = 0;
166 :
167 : /**
168 : * @brief Run Model training and validation
169 : * @param[in] values hyper parameters
170 : * @param[in] stop_cb callback function to decide stop training or not
171 : * ~~~~~
172 : * @a stop_user_data user_data to be used in stop_cb
173 : * @a bool true if stop the training
174 : * ~~~~~
175 : * @param[in] epoch_complete_cb Called the end of an epoch
176 : * ~~~~~
177 : * @a epoch_user_data user_data to be used in epoch_complete_cb
178 : * ~~~~~
179 : * @retval #ML_ERROR_NONE Successful.
180 : * @retval #ML_ERROR_INVALID_PARAMETER invalid parameter.
181 : * @details This function accepts vector of properties in the format -
182 : * { std::string property_name, void * property_val, ...}
183 : */
184 : virtual int train(const std::vector<std::string> &values = {},
185 : std::function<bool(void *)> stop_cb =
186 59264 : [](void *stop_user_data) { return false; },
187 : void *stop_user_data = nullptr,
188 : std::function<void(void *)> epoch_complete_cb =
189 1142 : [](void *epoch_user_data) { return false; },
190 : void *epoch_user_data = nullptr) = 0;
191 :
192 : /**
193 : * @brief Run Model train with callback function by user
194 : * @param[in] mode mode of the dataset
195 : * @param[in] dataset set the dataset
196 : * @retval #ML_ERROR_NONE Successful.
197 : * @retval #ML_ERROR_INVALID_PARAMETER invalid parameter.
198 : */
199 : virtual int setDataset(const ml::train::DatasetModeType &mode,
200 : std::shared_ptr<Dataset> dataset) = 0;
201 :
202 : /**
203 : * @brief add layer into neural network model
204 : * @retval #ML_ERROR_NONE Successful.
205 : * @retval #ML_ERROR_INVALID_PARAMETER invalid parameter.
206 : */
207 : virtual int addLayer(std::shared_ptr<Layer> layer) = 0;
208 :
209 : /**
210 : * @brief add referring to reference layers.
211 : * @note This method does add the provided layers itself but adds a deep copy
212 : * of the passed layers to the model. The layers passed to this function can
213 : * be reused later.
214 : * @note @a reference is a set of layers connected each other to form a part
215 : * or whole graph which can be loaded to a model and can be run.
216 : * More specifically, the graph with a non cyclic, directed graph with all
217 : * node has either incoming or outgoing connection defined when considering
218 : * non-input layer is directly connected to the previous layer. 'input
219 : * layer' is defined as a layer that has no incoming connection and
220 : * (identified as @a start_layers or input shape is specified explicitly).
221 : *
222 : * @param reference a group of layers being referred to.
223 : * @param type type of reference layers
224 : * @param scope scope of added layers, identifier will be added
225 : * @param input_layers input layers which will be used to connect input layers
226 : * @param start_layers start layers which will be used to specify start of the
227 : * layers inside @a reference
228 : * @param end_layers end layers which will be used to specify end of the
229 : * layers inside @a reference
230 : * @param type_properties type dependent properties
231 : */
232 : virtual void addWithReferenceLayers(
233 : const std::vector<std::shared_ptr<Layer>> &reference,
234 : const std::string &scope, const std::vector<std::string> &input_layers,
235 : const std::vector<std::string> &start_layers,
236 : const std::vector<std::string> &end_layers, ReferenceLayersType type,
237 : const std::vector<std::string> &type_properties = {}) = 0;
238 :
239 : /**
240 : * @brief Visit each layer inside model
241 : * @param fn function to be called for each layer
242 : * - call param
243 : * @param layer layer the call back is visiting
244 : * @param rc run layer context reference clubbed with layer
245 : * @param user_data user data passed along the function
246 : * @param user_data user data to pass along the callback
247 : */
248 : virtual void
249 : forEachLayer(std::function<void(Layer & /**< layer */,
250 : nntrainer::RunLayerContext & /**< rc */,
251 : void * /**< user_data */)>
252 : fn,
253 : void *user_data = nullptr) = 0;
254 :
255 : /**
256 : * @brief set optimizer for the neural network model
257 : * @retval #ML_ERROR_NONE Successful.
258 : * @retval #ML_ERROR_INVALID_PARAMETER invalid parameter.
259 : */
260 : virtual int setOptimizer(std::shared_ptr<Optimizer> optimizer) = 0;
261 :
262 : /**
263 : * @brief get layer by name from neural network model
264 : * @param[in] name name of the layer to get
265 : * @param[out] layer shared_ptr to hold the layer to get
266 : * @retval #ML_ERROR_NONE Successful.
267 : * @retval #ML_ERROR_INVALID_PARAMETER invalid parameter.
268 : */
269 : virtual int getLayer(const char *name, std::shared_ptr<Layer> *layer) = 0;
270 :
271 : /**
272 : * @brief get input dimension of a model
273 : * @retval std::vector<ml::train::TensorDim> input dimension
274 : */
275 : virtual std::vector<ml::train::TensorDim> getInputDimension() = 0;
276 :
277 : /**
278 : * @brief get output dimension of a model
279 : * @retval std::vector<ml::train::TensorDim> output dimension
280 : */
281 : virtual std::vector<ml::train::TensorDim> getOutputDimension() = 0;
282 :
283 : /**
284 : * @brief Run the inference of the model
285 : * @param[in] batch batch size of current input
286 : * @param[in] input inputs as a list of each input data
287 : * @param[in] label labels as a list of each label data
288 : * @retval list of output as float *
289 : * @note The output memory must not be freed by the caller
290 : */
291 : virtual std::vector<float *> inference(unsigned int batch,
292 : const std::vector<float *> &input,
293 : const std::vector<float *> &label) = 0;
294 :
295 : /**
296 : * @brief Summarize the model
297 : * @param out std::ostream to get the model summary
298 : * @param verbosity verbosity of the summary
299 : */
300 : virtual void summarize(std::ostream &out,
301 : ml_train_summary_type_e verbosity) = 0;
302 :
303 : /**
304 : * @brief Get current epoch_idx
305 : * @retval epoch_idx
306 : */
307 : virtual unsigned int getCurrentEpoch() = 0;
308 :
309 : /**
310 : * @brief Get Loss
311 : * @retval loss value
312 : */
313 : virtual float getLoss() = 0;
314 :
315 : /**
316 : * @brief returns compilation state of a network
317 : * @retval initialized value
318 : */
319 : virtual bool getCompiled() const = 0;
320 :
321 : /**
322 : * @brief returns initialization state of a network
323 : * @retval initialized value
324 : */
325 : virtual bool getInitialized() const = 0;
326 :
327 : /**
328 : * @brief returns loadedFromConfig state of a network
329 : * @retval loadedFromConfig value
330 : */
331 : virtual bool getLoadedFromConfig() const = 0;
332 :
333 : /**
334 : * @brief Get Loss from the previous epoch of training data
335 : * @retval loss value
336 : */
337 : virtual float getTrainingLoss() = 0;
338 :
339 : /**
340 : * @brief Get Loss from the previous epoch of validation data
341 : * @retval loss value
342 : */
343 : virtual float getValidationLoss() = 0;
344 :
345 : /**
346 : * @brief Get training statstics
347 : * @retval training statstics
348 : */
349 : virtual RunStats getTrainingStats() = 0;
350 :
351 : /**
352 : * @brief Get validation statstics
353 : * @retval validation statstics
354 : */
355 : virtual RunStats getValidStats() = 0;
356 :
357 : /**
358 : * @brief Get test statstics
359 : * @retval test statstics
360 : */
361 : virtual RunStats getTestStats() = 0;
362 :
363 : /**
364 : * @brief export the model according to given export method
365 : * @param method export method
366 : * @param file_path path to be serialized
367 : */
368 : virtual void exports(const ExportMethods &method,
369 : const std::string file_path) = 0;
370 : };
371 :
372 : /**
373 : * @brief Factory creator with constructor for optimizer
374 : */
375 : std::unique_ptr<Model>
376 : createModel(ModelType type = ml::train::ModelType::NEURAL_NET,
377 : const std::vector<std::string> &properties = {});
378 :
379 : /**
380 : * @brief creator by copying the configuration of other model
381 : */
382 : std::unique_ptr<Model> copyConfiguration(Model &from);
383 :
384 : } // namespace train
385 : } // namespace ml
386 :
387 : #else
388 : #error "CPP versions c++17 or over are only supported"
389 : #endif // __cpluscplus
390 : #endif // __ML_TRAIN_MODEL_H__
|
