C++ API Reference for Intel® Data Analytics Acceleration Library 2020 Update 1

tensor.h
1 /* file: tensor.h */
2 /*******************************************************************************
3 * Copyright 2014-2020 Intel Corporation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *******************************************************************************/
17 
18 /*
19 //++
20 // Declaration and implementation of the base class for numeric n-cubes.
21 //--
22 */
23 
24 
25 #ifndef __TENSOR_H__
26 #define __TENSOR_H__
27 
28 #include "services/error_handling.h"
29 #include "services/daal_memory.h"
30 #include "services/collection.h"
31 #include "data_management/data/data_archive.h"
32 #include "data_management/data/numeric_types.h"
33 
34 namespace daal
35 {
36 namespace data_management
37 {
38 
39 namespace interface1
40 {
52 template<typename DataType> class SubtensorDescriptor;
53 
54 class Tensor;
55 typedef services::SharedPtr<Tensor> TensorPtr;
56 
63 class TensorIface
64 {
65 public:
70  enum MemoryStatus
71  {
72  notAllocated = 0,
73  userAllocated = 1,
74  internallyAllocated = 2
75  };
76 
81  enum AllocationFlag
82  {
83  doNotAllocate = 0,
84  notAllocate = 0,
85  doAllocate = 1
86  };
87 
88  /*
89  * \DAAL_DEPRECATED
90  */
91  virtual ~TensorIface()
92  {}
99  virtual services::Status setDimensions(size_t ndim, const size_t* dimSizes) = 0;
100 
106  virtual services::Status setDimensions(const services::Collection<size_t>& dimensions) = 0;
107 
112  DAAL_DEPRECATED_VIRTUAL virtual services::Status allocateDataMemory(daal::MemType type = daal::dram) = 0;
113 
118  DAAL_DEPRECATED_VIRTUAL virtual services::Status freeDataMemory() = 0;
119 
120  virtual services::Status resize(const services::Collection<size_t>& dimensions) = 0;
121 
127  virtual services::Status check(const char *description) const = 0;
128 
134  DAAL_DEPRECATED_VIRTUAL virtual TensorPtr getSampleTensor(size_t firstDimIndex) = 0;
135 };
136 
143 class DAAL_EXPORT TensorLayoutIface
144 {
145 public:
146  /*
147  * \DAAL_DEPRECATED
148  */
149  virtual ~TensorLayoutIface() {}
150 
156  virtual services::Status shuffleDimensions(const services::Collection<size_t>& dimsOrder) = 0;
157 };
158 
165 class DAAL_EXPORT TensorLayout : public SerializationIface, public TensorLayoutIface
166 {
167 public:
168  /*
169  * \DAAL_DEPRECATED
170  */
171  virtual ~TensorLayout() {}
177  const services::Collection<size_t>& getDimensions() const
178  {
179  return _dims;
180  }
181 
182 protected:
183  TensorLayout(const services::Collection<size_t>& dims) : _dims(dims), _nDims(dims.size()) {}
184 
185  size_t _nDims;
186  services::Collection<size_t> _dims;
187 
188  template<typename Archive, bool onDeserialize>
189  services::Status serialImpl( Archive *arch )
190  {
191  arch->set(_dims);
192  _nDims = _dims.size();
193 
194  return services::Status();
195  }
196 };
197 
198 typedef services::SharedPtr<TensorLayout> TensorLayoutPtr;
199 
205 class DAAL_EXPORT TensorOffsetLayout : public TensorLayout
206 {
207 public:
208  /*
209  * \DAAL_DEPRECATED
210  */
211  TensorOffsetLayout(const TensorOffsetLayout& inLayout) : TensorLayout(inLayout.getDimensions()),
212  _offsets(inLayout.getOffsets()), _indices(inLayout.getIndices()), _isDefaultLayout(inLayout._isDefaultLayout),
213  _isRawLayout(inLayout._isRawLayout)
214  {}
215 
221  TensorOffsetLayout(const services::Collection<size_t>& dims) : TensorLayout(dims), _offsets(dims.size()), _indices(dims.size()),
222  _isDefaultLayout(true), _isRawLayout(true)
223  {
224  if(_nDims==0) return;
225 
226  size_t lastIndex = _nDims-1;
227 
228  _offsets[lastIndex]=1;
229  _indices[0] = 0;
230  for(size_t i=1; i<_nDims; i++)
231  {
232  _offsets[lastIndex-i] = _offsets[lastIndex-i+1]*_dims[lastIndex-i+1];
233  _indices[i] = i;
234  }
235 
236  _isDefaultLayout = true;
237  _isRawLayout = true;
238  }
239 
247  DAAL_DEPRECATED TensorOffsetLayout(const services::Collection<size_t>& dims, const services::Collection<size_t>& offsets,
248  const services::Collection<size_t>& indices) : TensorLayout(dims)
249  {
250  if(_nDims==0) return;
251  if(dims.size()==offsets.size()) return;
252 
253  _offsets = offsets;
254  _indices = indices;
255 
256  checkLayout();
257  }
258 
259  /*
260  * \DAAL_DEPRECATED
261  */
262  virtual ~TensorOffsetLayout() {}
263 
269  const services::Collection<size_t>& getOffsets() const
270  {
271  return _offsets;
272  }
273 
279  const services::Collection<size_t>& getIndices() const
280  {
281  return _indices;
282  }
283 
291  bool isLayout(const TensorOffsetLayout & layout) const
292  {
293  if( !(_nDims == layout.getDimensions().size()) ) return false;
294 
295  const services::Collection<size_t> & dims = layout.getDimensions();
296  const services::Collection<size_t> & offsets = layout.getOffsets();
297 
298  int dimsMatch = 0;
299  int offsetsMatch = 0;
300  for(size_t i = 0; i < _nDims; i++)
301  {
302  dimsMatch += _dims[i] == dims[i];
303  offsetsMatch += _offsets[i] == offsets[i];
304  }
305  return (dimsMatch == _nDims) && (offsetsMatch == _nDims);
306  }
307 
308  bool isDefaultLayout() const
309  {
310  return _isDefaultLayout;
311  }
312 
313  bool isRawLayout() const
314  {
315  return _isRawLayout;
316  }
317 
318  virtual services::Status shuffleDimensions(const services::Collection<size_t>& dimsOrder) DAAL_C11_OVERRIDE;
319 
320  services::Status sortOffsets();
321 
322  virtual int getSerializationTag() const DAAL_C11_OVERRIDE
323  {
324  return SERIALIZATION_TENSOR_OFFSET_LAYOUT_ID;
325  }
326 
327  DECLARE_SERIALIZABLE_IMPL();
328 
329 protected:
330  services::Collection<size_t> _offsets;
331  services::Collection<size_t> _indices;
332 
333  bool _isDefaultLayout;
334  bool _isRawLayout;
335 
336  template<typename Archive, bool onDeserialize>
337  services::Status serialImpl( Archive *arch )
338  {
339  TensorLayout::serialImpl<Archive,onDeserialize>(arch);
340 
341  arch->set(_offsets);
342  arch->set(_indices);
343  arch->set(_isDefaultLayout);
344  arch->set(_isRawLayout);
345 
346  return services::Status();
347  }
348 
349 private:
350  services::Status checkLayout();
351 };
352 
359 class DenseTensorIface
360 {
361 public:
362  /*
363  * \DAAL_DEPRECATED
364  */
365  virtual ~DenseTensorIface()
366  {}
378  virtual services::Status getSubtensorEx(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
379  ReadWriteMode rwflag, SubtensorDescriptor<double>& subtensor, const TensorOffsetLayout& layout ) = 0;
391  virtual services::Status getSubtensorEx(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
392  ReadWriteMode rwflag, SubtensorDescriptor<float>& subtensor, const TensorOffsetLayout& layout ) = 0;
404  virtual services::Status getSubtensorEx(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
405  ReadWriteMode rwflag, SubtensorDescriptor<int>& subtensor, const TensorOffsetLayout& layout ) = 0;
406 
412  virtual services::Status releaseSubtensor(SubtensorDescriptor<double>& subtensor) = 0;
418  virtual services::Status releaseSubtensor(SubtensorDescriptor<float>& subtensor) = 0;
424  virtual services::Status releaseSubtensor(SubtensorDescriptor<int>& subtensor) = 0;
425 
436  virtual services::Status getSubtensor(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
437  ReadWriteMode rwflag, SubtensorDescriptor<double>& subtensor )
438  {
439  return getSubtensorEx(fixedDims, fixedDimNums, rangeDimIdx, rangeDimNum, rwflag, subtensor, createDefaultSubtensorLayout() );
440  }
441 
452  virtual services::Status getSubtensor(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
453  ReadWriteMode rwflag, SubtensorDescriptor<float>& subtensor )
454  {
455  return getSubtensorEx(fixedDims, fixedDimNums, rangeDimIdx, rangeDimNum, rwflag, subtensor, createDefaultSubtensorLayout() );
456  }
457 
468  virtual services::Status getSubtensor(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
469  ReadWriteMode rwflag, SubtensorDescriptor<int>& subtensor )
470  {
471  return getSubtensorEx(fixedDims, fixedDimNums, rangeDimIdx, rangeDimNum, rwflag, subtensor, createDefaultSubtensorLayout() );
472  }
473 
474  virtual TensorOffsetLayout createDefaultSubtensorLayout() const = 0;
475  virtual TensorOffsetLayout createRawSubtensorLayout() const = 0;
476 };
477 
484 class DAAL_EXPORT Tensor : public SerializationIface, public TensorIface, public DenseTensorIface
485 {
486 public:
487  DAAL_CAST_OPERATOR(Tensor)
488 
489 
494  Tensor(TensorLayout *layoutPtr) : _layoutPtr(layoutPtr), _memStatus(notAllocated) {}
495 
500  DAAL_DEPRECATED Tensor() : _layoutPtr(0), _memStatus(notAllocated) {}
501 
506  virtual ~Tensor() {}
507 
511  MemoryStatus getDataMemoryStatus() const { return _memStatus; }
512 
518  size_t getNumberOfDimensions() const
519  {
520  return _layoutPtr->getDimensions().size();
521  }
522 
530  size_t getDimensionSize(size_t dimIdx) const
531  {
532  if(getNumberOfDimensions() > dimIdx) return (_layoutPtr->getDimensions())[dimIdx];
533  return 0;
534  }
535 
541  const services::Collection<size_t>& getDimensions() const
542  {
543  return _layoutPtr->getDimensions();
544  }
545 
551  DAAL_DEPRECATED services::SharedPtr<services::KernelErrorCollection> getErrors()
552  {
553  return _status.getCollection()->getErrors();
554  }
555 
560  size_t getSize() const;
561 
568  size_t getSize(size_t startingIdx, size_t rangeSize) const;
569 
575  virtual services::Status check(const char *description) const DAAL_C11_OVERRIDE
576  {
577  if(_memStatus == notAllocated)
578  {
579  return services::Status(services::ErrorNullTensor);
580  }
581  /* Check that the tensor is not empty */
582  size_t nDims = getNumberOfDimensions();
583  if (nDims == 0)
584  {
585  return services::Status(services::ErrorIncorrectNumberOfDimensionsInTensor);
586  }
587 
588  if (getSize() == 0)
589  {
590  return services::Status(services::ErrorIncorrectSizeOfDimensionInTensor);
591  }
592 
593  return services::Status();
594  }
595 
596  const TensorLayout* getLayoutPtr() const
597  {
598  return _layoutPtr;
599  }
600 
601  DAAL_DEPRECATED_VIRTUAL services::Status allocateDataMemory(daal::MemType type = daal::dram) DAAL_C11_OVERRIDE
602  {
603  return allocateDataMemoryImpl(type);
604  }
605 
606  DAAL_DEPRECATED_VIRTUAL services::Status freeDataMemory() DAAL_C11_OVERRIDE
607  {
608  return freeDataMemoryImpl();
609  }
610 
611  virtual services::Status resize(const services::Collection<size_t>& dimensions) DAAL_C11_OVERRIDE
612  {
613  freeDataMemoryImpl();
614  services::Status s = setDimensions(dimensions);
615  if(!s)
616  return s;
617  s = allocateDataMemoryImpl();
618  return s;
619  }
620 
621 protected:
622  MemoryStatus _memStatus;
623  services::Status _status;
624 
625  Tensor(TensorLayout *layoutPtr, services::Status &st) : _layoutPtr(layoutPtr), _memStatus(notAllocated) {}
626 
627  template<typename Archive, bool onDeserialize>
628  services::Status serialImpl( Archive *arch )
629  {
630  if( onDeserialize )
631  {
632  _memStatus = notAllocated;
633  }
634 
635  return services::Status();
636  }
637 
638  virtual services::Status allocateDataMemoryImpl(daal::MemType type = daal::dram) = 0;
639 
640  virtual services::Status freeDataMemoryImpl() = 0;
641 
642 private:
643  TensorLayout *_layoutPtr;
644 };
646 }
647 
648 using interface1::Tensor;
649 using interface1::TensorIface;
650 using interface1::TensorPtr;
651 using interface1::TensorOffsetLayout;
652 using interface1::TensorLayout;
653 using interface1::TensorLayoutPtr;
654 
662 DAAL_EXPORT services::Status checkTensor(const Tensor *tensor, const char *description, const services::Collection<size_t> *dims = NULL);
663 }
664 } // namespace daal
665 
666 #include "data_management/data/subtensor.h"
667 
668 #endif
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::data_management::interface1::TensorLayout::getDimensions
const services::Collection< size_t > & getDimensions() const
Definition: tensor.h:177
daal::data_management::interface1::TensorOffsetLayout::getSerializationTag
virtual int getSerializationTag() const DAAL_C11_OVERRIDE
Definition: tensor.h:322
daal::data_management::interface1::TensorIface::setDimensions
virtual services::Status setDimensions(size_t ndim, const size_t *dimSizes)=0
daal::data_management::interface1::Tensor::getDataMemoryStatus
MemoryStatus getDataMemoryStatus() const
Definition: tensor.h:511
daal::data_management::interface1::Tensor::getDimensions
const services::Collection< size_t > & getDimensions() const
Definition: tensor.h:541
daal::data_management::interface1::TensorIface::allocateDataMemory
virtual DAAL_DEPRECATED_VIRTUAL services::Status allocateDataMemory(daal::MemType type=daal::dram)=0
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:468
daal::data_management::interface1::Tensor::Tensor
DAAL_DEPRECATED Tensor()
Definition: tensor.h:500
daal::data_management::interface1::TensorIface::internallyAllocated
Definition: tensor.h:74
daal::data_management::interface1::TensorIface::doAllocate
Definition: tensor.h:85
daal::data_management::interface1::TensorLayoutIface
Abstract interface class for a data management component responsible for representation of data layou...
Definition: tensor.h:143
daal::data_management::interface1::TensorIface::check
virtual services::Status check(const char *description) const =0
daal::services::ErrorNullTensor
Definition: error_indexes.h:110
daal::data_management::interface1::TensorIface::doNotAllocate
Definition: tensor.h:83
daal::data_management::interface1::TensorIface
Abstract interface class for a data management component responsible for representation of data in th...
Definition: tensor.h:63
daal::data_management::interface1::TensorOffsetLayout::getIndices
const services::Collection< size_t > & getIndices() const
Definition: tensor.h:279
daal::data_management::interface1::TensorIface::AllocationFlag
AllocationFlag
Enumeration to specify whether the Numeric Table must allocate memory.
Definition: tensor.h:81
daal::data_management::interface1::Tensor::allocateDataMemory
DAAL_DEPRECATED_VIRTUAL services::Status allocateDataMemory(daal::MemType type=daal::dram) DAAL_C11_OVERRIDE
Definition: tensor.h:601
daal::MemType
MemType
Definition: daal_defines.h:147
daal::data_management::interface1::Tensor::getDimensionSize
size_t getDimensionSize(size_t dimIdx) const
Definition: tensor.h:530
daal::data_management::interface1::TensorIface::MemoryStatus
MemoryStatus
Enumeration to specify the status of memory related to the Numeric Table.
Definition: tensor.h:70
daal::data_management::interface1::Tensor::getNumberOfDimensions
size_t getNumberOfDimensions() const
Definition: tensor.h:518
daal::data_management::interface1::DenseTensorIface
Abstract interface class for a data management component responsible for accessing data in the numeri...
Definition: tensor.h:359
daal::data_management::interface1::TensorOffsetLayout::isLayout
bool isLayout(const TensorOffsetLayout &layout) const
Definition: tensor.h:291
daal::data_management::interface1::SerializationIface
Abstract interface class that defines the interface for serialization and deserialization.
Definition: data_serialize.h:52
daal::data_management::interface1::DenseTensorIface::releaseSubtensor
virtual services::Status releaseSubtensor(SubtensorDescriptor< double > &subtensor)=0
daal::data_management::interface1::Tensor::getErrors
DAAL_DEPRECATED services::SharedPtr< services::KernelErrorCollection > getErrors()
Definition: tensor.h:551
daal::services::ErrorIncorrectSizeOfDimensionInTensor
Definition: error_indexes.h:112
daal::data_management::interface1::TensorOffsetLayout
Class for a data management component responsible for representation of data layout in the HomogenTen...
Definition: tensor.h:205
daal::data_management::interface1::TensorOffsetLayout::TensorOffsetLayout
TensorOffsetLayout(const services::Collection< size_t > &dims)
Definition: tensor.h:221
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:436
daal::dram
Definition: daal_defines.h:149
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:452
daal::data_management::interface1::SubtensorDescriptor
Class with descriptor of the subtensor retrieved from Tensor getSubTensor function.
Definition: subtensor.h:49
daal::data_management::interface1::TensorIface::notAllocated
Definition: tensor.h:72
daal::data_management::interface1::TensorLayout
Class for a data management component responsible for representation of data layout in the tensor...
Definition: tensor.h:165
daal::data_management::interface1::TensorIface::freeDataMemory
virtual DAAL_DEPRECATED_VIRTUAL services::Status freeDataMemory()=0
daal::data_management::interface1::TensorOffsetLayout::getOffsets
const services::Collection< size_t > & getOffsets() const
Definition: tensor.h:269
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::TensorOffsetLayout
DAAL_DEPRECATED TensorOffsetLayout(const services::Collection< size_t > &dims, const services::Collection< size_t > &offsets, const services::Collection< size_t > &indices)
Definition: tensor.h:247
daal::data_management::interface1::Tensor::check
virtual services::Status check(const char *description) const DAAL_C11_OVERRIDE
Definition: tensor.h:575
daal::data_management::interface1::Tensor
Class for a data management component responsible for representation of data in the n-dimensions nume...
Definition: tensor.h:484
daal::services::ErrorIncorrectNumberOfDimensionsInTensor
Definition: error_indexes.h:111
daal::data_management::interface1::Tensor::freeDataMemory
DAAL_DEPRECATED_VIRTUAL services::Status freeDataMemory() DAAL_C11_OVERRIDE
Definition: tensor.h:606
daal::data_management::interface1::TensorIface::notAllocate
Definition: tensor.h:84
daal::data_management::interface1::TensorIface::userAllocated
Definition: tensor.h:73
daal::data_management::interface1::TensorIface::getSampleTensor
virtual DAAL_DEPRECATED_VIRTUAL TensorPtr getSampleTensor(size_t firstDimIndex)=0

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