C++ API Reference for Intel® Data Analytics Acceleration Library 2019 Update 5

tensor.h
1 /* file: tensor.h */
2 /*******************************************************************************
3 * Copyright 2014-2019 Intel Corporation.
4 *
5 * This software and the related documents are Intel copyrighted materials, and
6 * your use of them is governed by the express license under which they were
7 * provided to you (License). Unless the License provides otherwise, you may not
8 * use, modify, copy, publish, distribute, disclose or transmit this software or
9 * the related documents without Intel's prior written permission.
10 *
11 * This software and the related documents are provided as is, with no express
12 * or implied warranties, other than those that are expressly stated in the
13 * License.
14 *******************************************************************************/
15 
16 /*
17 //++
18 // Declaration and implementation of the base class for numeric n-cubes.
19 //--
20 */
21 
22 
23 #ifndef __TENSOR_H__
24 #define __TENSOR_H__
25 
26 #include "services/error_handling.h"
27 #include "services/daal_memory.h"
28 #include "services/collection.h"
29 #include "data_management/data/data_archive.h"
30 #include "data_management/data/numeric_types.h"
31 
32 namespace daal
33 {
34 namespace data_management
35 {
36 
37 namespace interface1
38 {
49 template<typename DataType> class SubtensorDescriptor;
50 
51 class Tensor;
52 typedef services::SharedPtr<Tensor> TensorPtr;
53 
59 class TensorIface
60 {
61 public:
66  enum MemoryStatus
67  {
68  notAllocated = 0,
69  userAllocated = 1,
70  internallyAllocated = 2
71  };
72 
77  enum AllocationFlag
78  {
79  doNotAllocate = 0,
80  notAllocate = 0,
81  doAllocate = 1
82  };
83 
84  virtual ~TensorIface()
85  {}
92  virtual services::Status setDimensions(size_t ndim, const size_t* dimSizes) = 0;
93 
99  virtual services::Status setDimensions(const services::Collection<size_t>& dimensions) = 0;
100 
105  DAAL_DEPRECATED_VIRTUAL virtual services::Status allocateDataMemory(daal::MemType type = daal::dram) = 0;
106 
111  DAAL_DEPRECATED_VIRTUAL virtual services::Status freeDataMemory() = 0;
112 
113  virtual services::Status resize(const services::Collection<size_t>& dimensions) = 0;
114 
120  virtual services::Status check(const char *description) const = 0;
121 
127  DAAL_DEPRECATED_VIRTUAL virtual TensorPtr getSampleTensor(size_t firstDimIndex) = 0;
128 };
129 
135 class DAAL_EXPORT TensorLayoutIface
136 {
137 public:
138  virtual ~TensorLayoutIface() {}
139 
145  virtual services::Status shuffleDimensions(const services::Collection<size_t>& dimsOrder) = 0;
146 };
147 
153 class DAAL_EXPORT TensorLayout : public SerializationIface, public TensorLayoutIface
154 {
155 public:
156  virtual ~TensorLayout() {}
162  const services::Collection<size_t>& getDimensions() const
163  {
164  return _dims;
165  }
166 
167 protected:
168  TensorLayout(const services::Collection<size_t>& dims) : _dims(dims), _nDims(dims.size()) {}
169 
170  size_t _nDims;
171  services::Collection<size_t> _dims;
172 
173  template<typename Archive, bool onDeserialize>
174  services::Status serialImpl( Archive *arch )
175  {
176  arch->set(_dims);
177  _nDims = _dims.size();
178 
179  return services::Status();
180  }
181 };
182 
183 typedef services::SharedPtr<TensorLayout> TensorLayoutPtr;
184 
189 class DAAL_EXPORT TensorOffsetLayout : public TensorLayout
190 {
191 public:
192  TensorOffsetLayout(const TensorOffsetLayout& inLayout) : TensorLayout(inLayout.getDimensions()),
193  _offsets(inLayout.getOffsets()), _indices(inLayout.getIndices()), _isDefaultLayout(inLayout._isDefaultLayout),
194  _isRawLayout(inLayout._isRawLayout)
195  {}
196 
201  TensorOffsetLayout(const services::Collection<size_t>& dims) : TensorLayout(dims), _offsets(dims.size()), _indices(dims.size()),
202  _isDefaultLayout(true), _isRawLayout(true)
203  {
204  if(_nDims==0) return;
205 
206  size_t lastIndex = _nDims-1;
207 
208  _offsets[lastIndex]=1;
209  _indices[0] = 0;
210  for(size_t i=1; i<_nDims; i++)
211  {
212  _offsets[lastIndex-i] = _offsets[lastIndex-i+1]*_dims[lastIndex-i+1];
213  _indices[i] = i;
214  }
215 
216  _isDefaultLayout = true;
217  _isRawLayout = true;
218  }
219 
226  TensorOffsetLayout(const services::Collection<size_t>& dims, const services::Collection<size_t>& offsets,
227  const services::Collection<size_t>& indices) : TensorLayout(dims)
228  {
229  if(_nDims==0) return;
230  if(dims.size()==offsets.size()) return;
231 
232  _offsets = offsets;
233  _indices = indices;
234 
235  checkLayout();
236  }
237 
238  virtual ~TensorOffsetLayout() {}
239 
245  const services::Collection<size_t>& getOffsets() const
246  {
247  return _offsets;
248  }
249 
255  const services::Collection<size_t>& getIndices() const
256  {
257  return _indices;
258  }
259 
267  bool isLayout(const TensorOffsetLayout & layout) const
268  {
269  if( !(_nDims == layout.getDimensions().size()) ) return false;
270 
271  const services::Collection<size_t> & dims = layout.getDimensions();
272  const services::Collection<size_t> & offsets = layout.getOffsets();
273 
274  int dimsMatch = 0;
275  int offsetsMatch = 0;
276  for(size_t i = 0; i < _nDims; i++)
277  {
278  dimsMatch += _dims[i] == dims[i];
279  offsetsMatch += _offsets[i] == offsets[i];
280  }
281  return (dimsMatch == _nDims) && (offsetsMatch == _nDims);
282  }
283 
284  bool isDefaultLayout() const
285  {
286  return _isDefaultLayout;
287  }
288 
289  bool isRawLayout() const
290  {
291  return _isRawLayout;
292  }
293 
294  virtual services::Status shuffleDimensions(const services::Collection<size_t>& dimsOrder) DAAL_C11_OVERRIDE;
295 
296  services::Status sortOffsets();
297 
298  virtual int getSerializationTag() const DAAL_C11_OVERRIDE
299  {
300  return SERIALIZATION_TENSOR_OFFSET_LAYOUT_ID;
301  }
302 
303  DECLARE_SERIALIZABLE_IMPL();
304 
305 protected:
306  services::Collection<size_t> _offsets;
307  services::Collection<size_t> _indices;
308 
309  bool _isDefaultLayout;
310  bool _isRawLayout;
311 
312  template<typename Archive, bool onDeserialize>
313  services::Status serialImpl( Archive *arch )
314  {
315  TensorLayout::serialImpl<Archive,onDeserialize>(arch);
316 
317  arch->set(_offsets);
318  arch->set(_indices);
319  arch->set(_isDefaultLayout);
320  arch->set(_isRawLayout);
321 
322  return services::Status();
323  }
324 
325 private:
326  services::Status checkLayout();
327 };
328 
334 class DenseTensorIface
335 {
336 public:
337  virtual ~DenseTensorIface()
338  {}
350  virtual services::Status getSubtensorEx(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
351  ReadWriteMode rwflag, SubtensorDescriptor<double>& subtensor, const TensorOffsetLayout& layout ) = 0;
363  virtual services::Status getSubtensorEx(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
364  ReadWriteMode rwflag, SubtensorDescriptor<float>& subtensor, const TensorOffsetLayout& layout ) = 0;
376  virtual services::Status getSubtensorEx(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
377  ReadWriteMode rwflag, SubtensorDescriptor<int>& subtensor, const TensorOffsetLayout& layout ) = 0;
378 
384  virtual services::Status releaseSubtensor(SubtensorDescriptor<double>& subtensor) = 0;
390  virtual services::Status releaseSubtensor(SubtensorDescriptor<float>& subtensor) = 0;
396  virtual services::Status releaseSubtensor(SubtensorDescriptor<int>& subtensor) = 0;
397 
408  virtual services::Status getSubtensor(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
409  ReadWriteMode rwflag, SubtensorDescriptor<double>& subtensor )
410  {
411  return getSubtensorEx(fixedDims, fixedDimNums, rangeDimIdx, rangeDimNum, rwflag, subtensor, createDefaultSubtensorLayout() );
412  }
413 
424  virtual services::Status getSubtensor(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
425  ReadWriteMode rwflag, SubtensorDescriptor<float>& subtensor )
426  {
427  return getSubtensorEx(fixedDims, fixedDimNums, rangeDimIdx, rangeDimNum, rwflag, subtensor, createDefaultSubtensorLayout() );
428  }
429 
440  virtual services::Status getSubtensor(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
441  ReadWriteMode rwflag, SubtensorDescriptor<int>& subtensor )
442  {
443  return getSubtensorEx(fixedDims, fixedDimNums, rangeDimIdx, rangeDimNum, rwflag, subtensor, createDefaultSubtensorLayout() );
444  }
445 
446  virtual TensorOffsetLayout createDefaultSubtensorLayout() const = 0;
447  virtual TensorOffsetLayout createRawSubtensorLayout() const = 0;
448 };
449 
455 class DAAL_EXPORT Tensor : public SerializationIface, public TensorIface, public DenseTensorIface
456 {
457 public:
458  DAAL_CAST_OPERATOR(Tensor)
459 
460 
465  Tensor(TensorLayout *layoutPtr) : _layoutPtr(layoutPtr), _memStatus(notAllocated) {}
466 
470  Tensor() : _layoutPtr(0), _memStatus(notAllocated) {}
471 
473  virtual ~Tensor() {}
474 
478  MemoryStatus getDataMemoryStatus() const { return _memStatus; }
479 
485  size_t getNumberOfDimensions() const
486  {
487  return _layoutPtr->getDimensions().size();
488  }
489 
497  size_t getDimensionSize(size_t dimIdx) const
498  {
499  if(getNumberOfDimensions() > dimIdx) return (_layoutPtr->getDimensions())[dimIdx];
500  return 0;
501  }
502 
508  const services::Collection<size_t>& getDimensions() const
509  {
510  return _layoutPtr->getDimensions();
511  }
512 
518  DAAL_DEPRECATED services::SharedPtr<services::KernelErrorCollection> getErrors()
519  {
520  return _status.getCollection()->getErrors();
521  }
522 
527  size_t getSize() const;
528 
535  size_t getSize(size_t startingIdx, size_t rangeSize) const;
536 
542  virtual services::Status check(const char *description) const DAAL_C11_OVERRIDE
543  {
544  if(_memStatus == notAllocated)
545  {
546  return services::Status(services::ErrorNullTensor);
547  }
548  /* Check that the tensor is not empty */
549  size_t nDims = getNumberOfDimensions();
550  if (nDims == 0)
551  {
552  return services::Status(services::ErrorIncorrectNumberOfDimensionsInTensor);
553  }
554 
555  if (getSize() == 0)
556  {
557  return services::Status(services::ErrorIncorrectSizeOfDimensionInTensor);
558  }
559 
560  return services::Status();
561  }
562 
563  const TensorLayout* getLayoutPtr() const
564  {
565  return _layoutPtr;
566  }
567 
568  DAAL_DEPRECATED_VIRTUAL services::Status allocateDataMemory(daal::MemType type = daal::dram) DAAL_C11_OVERRIDE
569  {
570  return allocateDataMemoryImpl(type);
571  }
572 
573  DAAL_DEPRECATED_VIRTUAL services::Status freeDataMemory() DAAL_C11_OVERRIDE
574  {
575  return freeDataMemoryImpl();
576  }
577 
578  virtual services::Status resize(const services::Collection<size_t>& dimensions) DAAL_C11_OVERRIDE
579  {
580  freeDataMemoryImpl();
581  services::Status s = setDimensions(dimensions);
582  if(!s)
583  return s;
584  s = allocateDataMemoryImpl();
585  return s;
586  }
587 
588 protected:
589  MemoryStatus _memStatus;
590  services::Status _status;
591 
592  Tensor(TensorLayout *layoutPtr, services::Status &st) : _layoutPtr(layoutPtr), _memStatus(notAllocated) {}
593 
594  template<typename Archive, bool onDeserialize>
595  services::Status serialImpl( Archive *arch )
596  {
597  if( onDeserialize )
598  {
599  _memStatus = notAllocated;
600  }
601 
602  return services::Status();
603  }
604 
605  virtual services::Status allocateDataMemoryImpl(daal::MemType type = daal::dram) = 0;
606 
607  virtual services::Status freeDataMemoryImpl() = 0;
608 
609 private:
610  TensorLayout *_layoutPtr;
611 };
613 }
614 
615 using interface1::Tensor;
616 using interface1::TensorIface;
617 using interface1::TensorPtr;
618 using interface1::TensorOffsetLayout;
619 using interface1::TensorLayout;
620 using interface1::TensorLayoutPtr;
621 
629 DAAL_EXPORT services::Status checkTensor(const Tensor *tensor, const char *description, const services::Collection<size_t> *dims = NULL);
630 }
631 } // namespace daal
632 
633 #include "data_management/data/subtensor.h"
634 
635 #endif
daal::data_management::interface1::Tensor::getDimensions
const services::Collection< size_t > & getDimensions() const
Definition: tensor.h:508
daal::data_management::interface1::TensorIface::freeDataMemory
virtual DAAL_DEPRECATED_VIRTUAL services::Status freeDataMemory()=0
daal::services::ErrorIncorrectNumberOfDimensionsInTensor
Definition: error_indexes.h:109
daal::data_management::interface1::TensorLayoutIface
Abstract interface class for a data management component responsible for representation of data layou...
Definition: tensor.h:135
daal
Definition: algorithm_base_common.h:31
daal::data_management::interface1::Tensor::freeDataMemory
DAAL_DEPRECATED_VIRTUAL services::Status freeDataMemory() DAAL_C11_OVERRIDE
Definition: tensor.h:573
daal::data_management::interface1::Tensor
Class for a data management component responsible for representation of data in the n-dimensions nume...
Definition: tensor.h:455
daal::data_management::interface1::DenseTensorIface::getSubtensor
virtual services::Status getSubtensor(size_t fixedDims, const size_t *fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum, ReadWriteMode rwflag, SubtensorDescriptor< double > &subtensor)
Definition: tensor.h:408
daal::data_management::interface1::Tensor::getErrors
DAAL_DEPRECATED services::SharedPtr< services::KernelErrorCollection > getErrors()
Definition: tensor.h:518
daal::data_management::interface1::DenseTensorIface::getSubtensorEx
virtual services::Status getSubtensorEx(size_t fixedDims, const size_t *fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum, ReadWriteMode rwflag, SubtensorDescriptor< double > &subtensor, const TensorOffsetLayout &layout)=0
daal::services::ErrorNullTensor
Definition: error_indexes.h:108
daal::data_management::interface1::TensorOffsetLayout::TensorOffsetLayout
TensorOffsetLayout(const services::Collection< size_t > &dims, const services::Collection< size_t > &offsets, const services::Collection< size_t > &indices)
Definition: tensor.h:226
daal::data_management::interface1::TensorIface::setDimensions
virtual services::Status setDimensions(size_t ndim, const size_t *dimSizes)=0
daal::data_management::interface1::Tensor::getNumberOfDimensions
size_t getNumberOfDimensions() const
Definition: tensor.h:485
daal::data_management::interface1::TensorIface::check
virtual services::Status check(const char *description) const =0
daal::dram
Definition: daal_defines.h:147
daal::data_management::interface1::TensorIface::notAllocated
Definition: tensor.h:68
daal::data_management::interface1::TensorIface::notAllocate
Definition: tensor.h:80
daal::data_management::interface1::DenseTensorIface::getSubtensor
virtual services::Status getSubtensor(size_t fixedDims, const size_t *fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum, ReadWriteMode rwflag, SubtensorDescriptor< int > &subtensor)
Definition: tensor.h:440
daal::data_management::interface1::TensorIface::doAllocate
Definition: tensor.h:81
daal::data_management::interface1::Tensor::getDimensionSize
size_t getDimensionSize(size_t dimIdx) const
Definition: tensor.h:497
daal::data_management::interface1::TensorIface::MemoryStatus
MemoryStatus
Enumeration to specify the status of memory related to the Numeric Table.
Definition: tensor.h:66
daal::data_management::interface1::DenseTensorIface
Abstract interface class for a data management component responsible for accessing data in the numeri...
Definition: tensor.h:334
daal::data_management::interface1::TensorOffsetLayout::TensorOffsetLayout
TensorOffsetLayout(const services::Collection< size_t > &dims)
Definition: tensor.h:201
daal::data_management::interface1::DenseTensorIface::getSubtensor
virtual services::Status getSubtensor(size_t fixedDims, const size_t *fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum, ReadWriteMode rwflag, SubtensorDescriptor< float > &subtensor)
Definition: tensor.h:424
daal::data_management::interface1::TensorIface::allocateDataMemory
virtual DAAL_DEPRECATED_VIRTUAL services::Status allocateDataMemory(daal::MemType type=daal::dram)=0
daal::data_management::interface1::DenseTensorIface::releaseSubtensor
virtual services::Status releaseSubtensor(SubtensorDescriptor< double > &subtensor)=0
daal::data_management::interface1::Tensor::getDataMemoryStatus
MemoryStatus getDataMemoryStatus() const
Definition: tensor.h:478
daal::data_management::interface1::TensorLayout
Class for a data management component responsible for representation of data layout in the tensor...
Definition: tensor.h:153
daal::data_management::interface1::TensorIface::AllocationFlag
AllocationFlag
Enumeration to specify whether the Numeric Table must allocate memory.
Definition: tensor.h:77
daal::data_management::interface1::TensorIface
Abstract interface class for a data management component responsible for representation of data in th...
Definition: tensor.h:59
daal::data_management::interface1::TensorIface::internallyAllocated
Definition: tensor.h:70
daal::data_management::interface1::Tensor::Tensor
Tensor()
Definition: tensor.h:470
daal::data_management::interface1::TensorOffsetLayout
Class for a data management component responsible for representation of data layout in the HomogenTen...
Definition: tensor.h:189
daal::data_management::interface1::TensorIface::userAllocated
Definition: tensor.h:69
daal::data_management::interface1::Tensor::check
virtual services::Status check(const char *description) const DAAL_C11_OVERRIDE
Definition: tensor.h:542
daal::data_management::interface1::TensorOffsetLayout::getIndices
const services::Collection< size_t > & getIndices() const
Definition: tensor.h:255
daal::data_management::interface1::TensorIface::doNotAllocate
Definition: tensor.h:79
daal::data_management::interface1::TensorIface::getSampleTensor
virtual DAAL_DEPRECATED_VIRTUAL TensorPtr getSampleTensor(size_t firstDimIndex)=0
daal::data_management::interface1::Tensor::allocateDataMemory
DAAL_DEPRECATED_VIRTUAL services::Status allocateDataMemory(daal::MemType type=daal::dram) DAAL_C11_OVERRIDE
Definition: tensor.h:568
daal::data_management::interface1::TensorOffsetLayout::getSerializationTag
virtual int getSerializationTag() const DAAL_C11_OVERRIDE
Definition: tensor.h:298
daal::data_management::interface1::TensorOffsetLayout::isLayout
bool isLayout(const TensorOffsetLayout &layout) const
Definition: tensor.h:267
daal::data_management::interface1::SubtensorDescriptor
Class with descriptor of the subtensor retrieved from Tensor getSubTensor function.
Definition: subtensor.h:47
daal::data_management::interface1::SerializationIface
Abstract interface class that defines the interface for serialization and deserialization.
Definition: data_serialize.h:50
daal::algorithms::implicit_als::training::init::offsets
Definition: implicit_als_training_init_types.h:91
daal::data_management::interface1::TensorLayout::getDimensions
const services::Collection< size_t > & getDimensions() const
Definition: tensor.h:162
daal::MemType
MemType
Definition: daal_defines.h:145
daal::data_management::checkTensor
DAAL_EXPORT services::Status checkTensor(const Tensor *tensor, const char *description, const services::Collection< size_t > *dims=NULL)
daal::data_management::interface1::TensorOffsetLayout::getOffsets
const services::Collection< size_t > & getOffsets() const
Definition: tensor.h:245
daal::services::ErrorIncorrectSizeOfDimensionInTensor
Definition: error_indexes.h:110

For more complete information about compiler optimizations, see our Optimization Notice.