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

tensor.h
1 /* file: tensor.h */
2 /*******************************************************************************
3 * Copyright 2014-2017 Intel Corporation
4 * All Rights Reserved.
5 *
6 * If this software was obtained under the Intel Simplified Software License,
7 * the following terms apply:
8 *
9 * The source code, information and material ("Material") contained herein is
10 * owned by Intel Corporation or its suppliers or licensors, and title to such
11 * Material remains with Intel Corporation or its suppliers or licensors. The
12 * Material contains proprietary information of Intel or its suppliers and
13 * licensors. The Material is protected by worldwide copyright laws and treaty
14 * provisions. No part of the Material may be used, copied, reproduced,
15 * modified, published, uploaded, posted, transmitted, distributed or disclosed
16 * in any way without Intel's prior express written permission. No license under
17 * any patent, copyright or other intellectual property rights in the Material
18 * is granted to or conferred upon you, either expressly, by implication,
19 * inducement, estoppel or otherwise. Any license under such intellectual
20 * property rights must be express and approved by Intel in writing.
21 *
22 * Unless otherwise agreed by Intel in writing, you may not remove or alter this
23 * notice or any other notice embedded in Materials by Intel or Intel's
24 * suppliers or licensors in any way.
25 *
26 *
27 * If this software was obtained under the Apache License, Version 2.0 (the
28 * "License"), the following terms apply:
29 *
30 * You may not use this file except in compliance with the License. You may
31 * obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
32 *
33 *
34 * Unless required by applicable law or agreed to in writing, software
35 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
36 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
37 *
38 * See the License for the specific language governing permissions and
39 * limitations under the License.
40 *******************************************************************************/
41 
42 /*
43 //++
44 // Declaration and implementation of the base class for numeric n-cubes.
45 //--
46 */
47 
48 
49 #ifndef __TENSOR_H__
50 #define __TENSOR_H__
51 
52 #include "services/error_handling.h"
53 #include "services/daal_memory.h"
54 #include "services/collection.h"
55 #include "data_management/data/data_archive.h"
56 #include "data_management/data/numeric_types.h"
57 
58 namespace daal
59 {
60 namespace data_management
61 {
62 
63 namespace interface1
64 {
75 template<typename DataType> class SubtensorDescriptor;
76 
77 class Tensor;
78 typedef services::SharedPtr<Tensor> TensorPtr;
79 
85 class TensorIface
86 {
87 public:
92  enum MemoryStatus
93  {
94  notAllocated = 0,
95  userAllocated = 1,
96  internallyAllocated = 2
97  };
98 
103  enum AllocationFlag
104  {
105  doNotAllocate = 0,
106  notAllocate = 0,
107  doAllocate = 1
108  };
109 
110  virtual ~TensorIface()
111  {}
118  virtual services::Status setDimensions(size_t ndim, const size_t* dimSizes) = 0;
119 
125  virtual services::Status setDimensions(const services::Collection<size_t>& dimensions) = 0;
126 
131  DAAL_DEPRECATED_VIRTUAL virtual services::Status allocateDataMemory(daal::MemType type = daal::dram) = 0;
132 
137  DAAL_DEPRECATED_VIRTUAL virtual services::Status freeDataMemory() = 0;
138 
139  virtual services::Status resize(const services::Collection<size_t>& dimensions) = 0;
140 
146  virtual services::Status check(const char *description) const = 0;
147 
153  DAAL_DEPRECATED_VIRTUAL virtual TensorPtr getSampleTensor(size_t firstDimIndex) = 0;
154 };
155 
161 class DAAL_EXPORT TensorLayoutIface
162 {
163 public:
164  virtual ~TensorLayoutIface() {}
165 
171  virtual services::Status shuffleDimensions(const services::Collection<size_t>& dimsOrder) = 0;
172 };
173 
179 class DAAL_EXPORT TensorLayout : public SerializationIface, public TensorLayoutIface
180 {
181 public:
182  virtual ~TensorLayout() {}
188  const services::Collection<size_t>& getDimensions() const
189  {
190  return _dims;
191  }
192 
193 protected:
194  TensorLayout(const services::Collection<size_t>& dims) : _dims(dims), _nDims(dims.size()) {}
195 
196  size_t _nDims;
197  services::Collection<size_t> _dims;
198 
199  template<typename Archive, bool onDeserialize>
200  services::Status serialImpl( Archive *arch )
201  {
202  arch->set(_dims);
203  _nDims = _dims.size();
204 
205  return services::Status();
206  }
207 };
208 
209 typedef services::SharedPtr<TensorLayout> TensorLayoutPtr;
210 
215 class DAAL_EXPORT TensorOffsetLayout : public TensorLayout
216 {
217 public:
218  TensorOffsetLayout(const TensorOffsetLayout& inLayout) : TensorLayout(inLayout.getDimensions()),
219  _offsets(inLayout.getOffsets()), _indices(inLayout.getIndices()), _isDefaultLayout(inLayout._isDefaultLayout),
220  _isRawLayout(inLayout._isRawLayout)
221  {}
222 
227  TensorOffsetLayout(const services::Collection<size_t>& dims) : TensorLayout(dims), _offsets(dims.size()), _indices(dims.size()),
228  _isDefaultLayout(true), _isRawLayout(true)
229  {
230  if(_nDims==0) return;
231 
232  size_t lastIndex = _nDims-1;
233 
234  _offsets[lastIndex]=1;
235  _indices[0] = 0;
236  for(size_t i=1; i<_nDims; i++)
237  {
238  _offsets[lastIndex-i] = _offsets[lastIndex-i+1]*_dims[lastIndex-i+1];
239  _indices[i] = i;
240  }
241 
242  _isDefaultLayout = true;
243  _isRawLayout = true;
244  }
245 
252  TensorOffsetLayout(const services::Collection<size_t>& dims, const services::Collection<size_t>& offsets,
253  const services::Collection<size_t>& indices) : TensorLayout(dims)
254  {
255  if(_nDims==0) return;
256  if(dims.size()==offsets.size()) return;
257 
258  _offsets = offsets;
259  _indices = indices;
260 
261  checkLayout();
262  }
263 
264  virtual ~TensorOffsetLayout() {}
265 
271  const services::Collection<size_t>& getOffsets() const
272  {
273  return _offsets;
274  }
275 
281  const services::Collection<size_t>& getIndices() const
282  {
283  return _indices;
284  }
285 
293  bool isLayout(const TensorOffsetLayout & layout) const
294  {
295  if( !(_nDims == layout.getDimensions().size()) ) return false;
296 
297  const services::Collection<size_t> & dims = layout.getDimensions();
298  const services::Collection<size_t> & offsets = layout.getOffsets();
299 
300  int dimsMatch = 0;
301  int offsetsMatch = 0;
302  for(size_t i = 0; i < _nDims; i++)
303  {
304  dimsMatch += _dims[i] == dims[i];
305  offsetsMatch += _offsets[i] == offsets[i];
306  }
307  return (dimsMatch == _nDims) && (offsetsMatch == _nDims);
308  }
309 
310  bool isDefaultLayout() const
311  {
312  return _isDefaultLayout;
313  }
314 
315  bool isRawLayout() const
316  {
317  return _isRawLayout;
318  }
319 
320  virtual services::Status shuffleDimensions(const services::Collection<size_t>& dimsOrder) DAAL_C11_OVERRIDE;
321 
322  services::Status sortOffsets();
323 
324  virtual int getSerializationTag() const DAAL_C11_OVERRIDE
325  {
326  return SERIALIZATION_TENSOR_OFFSET_LAYOUT_ID;
327  }
328 
329  DECLARE_SERIALIZABLE_IMPL();
330 
331 protected:
332  services::Collection<size_t> _offsets;
333  services::Collection<size_t> _indices;
334 
335  bool _isDefaultLayout;
336  bool _isRawLayout;
337 
338  template<typename Archive, bool onDeserialize>
339  services::Status serialImpl( Archive *arch )
340  {
341  TensorLayout::serialImpl<Archive,onDeserialize>(arch);
342 
343  arch->set(_offsets);
344  arch->set(_indices);
345  arch->set(_isDefaultLayout);
346  arch->set(_isRawLayout);
347 
348  return services::Status();
349  }
350 
351 private:
352  services::Status checkLayout();
353 };
354 
360 class DenseTensorIface
361 {
362 public:
363  virtual ~DenseTensorIface()
364  {}
376  virtual services::Status getSubtensorEx(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
377  ReadWriteMode rwflag, SubtensorDescriptor<double>& subtensor, const TensorOffsetLayout& layout ) = 0;
389  virtual services::Status getSubtensorEx(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
390  ReadWriteMode rwflag, SubtensorDescriptor<float>& subtensor, const TensorOffsetLayout& layout ) = 0;
402  virtual services::Status getSubtensorEx(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
403  ReadWriteMode rwflag, SubtensorDescriptor<int>& subtensor, const TensorOffsetLayout& layout ) = 0;
404 
410  virtual services::Status releaseSubtensor(SubtensorDescriptor<double>& subtensor) = 0;
416  virtual services::Status releaseSubtensor(SubtensorDescriptor<float>& subtensor) = 0;
422  virtual services::Status releaseSubtensor(SubtensorDescriptor<int>& subtensor) = 0;
423 
434  virtual services::Status getSubtensor(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
435  ReadWriteMode rwflag, SubtensorDescriptor<double>& subtensor )
436  {
437  return getSubtensorEx(fixedDims, fixedDimNums, rangeDimIdx, rangeDimNum, rwflag, subtensor, createDefaultSubtensorLayout() );
438  }
439 
450  virtual services::Status getSubtensor(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
451  ReadWriteMode rwflag, SubtensorDescriptor<float>& subtensor )
452  {
453  return getSubtensorEx(fixedDims, fixedDimNums, rangeDimIdx, rangeDimNum, rwflag, subtensor, createDefaultSubtensorLayout() );
454  }
455 
466  virtual services::Status getSubtensor(size_t fixedDims, const size_t* fixedDimNums, size_t rangeDimIdx, size_t rangeDimNum,
467  ReadWriteMode rwflag, SubtensorDescriptor<int>& subtensor )
468  {
469  return getSubtensorEx(fixedDims, fixedDimNums, rangeDimIdx, rangeDimNum, rwflag, subtensor, createDefaultSubtensorLayout() );
470  }
471 
472  virtual TensorOffsetLayout createDefaultSubtensorLayout() const = 0;
473  virtual TensorOffsetLayout createRawSubtensorLayout() const = 0;
474 };
475 
481 class DAAL_EXPORT Tensor : public SerializationIface, public TensorIface, public DenseTensorIface
482 {
483 public:
484  DAAL_CAST_OPERATOR(Tensor)
485 
486 
491  Tensor(TensorLayout *layoutPtr) : _layoutPtr(layoutPtr), _memStatus(notAllocated) {}
492 
496  Tensor() : _layoutPtr(0), _memStatus(notAllocated) {}
497 
499  virtual ~Tensor() {}
500 
504  MemoryStatus getDataMemoryStatus() const { return _memStatus; }
505 
511  size_t getNumberOfDimensions() const
512  {
513  return _layoutPtr->getDimensions().size();
514  }
515 
523  size_t getDimensionSize(size_t dimIdx) const
524  {
525  if(getNumberOfDimensions() > dimIdx) return (_layoutPtr->getDimensions())[dimIdx];
526  return 0;
527  }
528 
534  const services::Collection<size_t>& getDimensions() const
535  {
536  return _layoutPtr->getDimensions();
537  }
538 
544  DAAL_DEPRECATED services::SharedPtr<services::KernelErrorCollection> getErrors()
545  {
546  return _status.getCollection()->getErrors();
547  }
548 
553  size_t getSize() const;
554 
561  size_t getSize(size_t startingIdx, size_t rangeSize) const;
562 
568  virtual services::Status check(const char *description) const DAAL_C11_OVERRIDE
569  {
570  if(_memStatus == notAllocated)
571  {
572  return services::Status(services::ErrorNullTensor);
573  }
574  /* Check that the tensor is not empty */
575  size_t nDims = getNumberOfDimensions();
576  if (nDims == 0)
577  {
578  return services::Status(services::ErrorIncorrectNumberOfDimensionsInTensor);
579  }
580 
581  if (getSize() == 0)
582  {
583  return services::Status(services::ErrorIncorrectSizeOfDimensionInTensor);
584  }
585 
586  return services::Status();
587  }
588 
589  const TensorLayout* getLayoutPtr() const
590  {
591  return _layoutPtr;
592  }
593 
594  DAAL_DEPRECATED_VIRTUAL services::Status allocateDataMemory(daal::MemType type = daal::dram) DAAL_C11_OVERRIDE
595  {
596  return allocateDataMemoryImpl(type);
597  }
598 
599  DAAL_DEPRECATED_VIRTUAL services::Status freeDataMemory() DAAL_C11_OVERRIDE
600  {
601  return freeDataMemoryImpl();
602  }
603 
604  virtual services::Status resize(const services::Collection<size_t>& dimensions) DAAL_C11_OVERRIDE
605  {
606  freeDataMemoryImpl();
607  services::Status s = setDimensions(dimensions);
608  if(!s)
609  return s;
610  s = allocateDataMemoryImpl();
611  return s;
612  }
613 
614 protected:
615  MemoryStatus _memStatus;
616  services::Status _status;
617 
618  Tensor(TensorLayout *layoutPtr, services::Status &st) : _layoutPtr(layoutPtr), _memStatus(notAllocated) {}
619 
620  template<typename Archive, bool onDeserialize>
621  services::Status serialImpl( Archive *arch )
622  {
623  if( onDeserialize )
624  {
625  _memStatus = notAllocated;
626  }
627 
628  return services::Status();
629  }
630 
631  virtual services::Status allocateDataMemoryImpl(daal::MemType type = daal::dram) = 0;
632 
633  virtual services::Status freeDataMemoryImpl() = 0;
634 
635 private:
636  TensorLayout *_layoutPtr;
637 };
639 }
640 
641 using interface1::Tensor;
642 using interface1::TensorIface;
643 using interface1::TensorPtr;
644 using interface1::TensorOffsetLayout;
645 using interface1::TensorLayout;
646 using interface1::TensorLayoutPtr;
647 
655 DAAL_EXPORT services::Status checkTensor(const Tensor *tensor, const char *description, const services::Collection<size_t> *dims = NULL);
656 }
657 } // namespace daal
658 
659 #include "data_management/data/subtensor.h"
660 
661 #endif
daal::data_management::interface1::Tensor::getDimensions
const services::Collection< size_t > & getDimensions() const
Definition: tensor.h:534
daal::data_management::interface1::TensorIface::freeDataMemory
virtual DAAL_DEPRECATED_VIRTUAL services::Status freeDataMemory()=0
daal::services::ErrorIncorrectNumberOfDimensionsInTensor
Definition: error_indexes.h:135
daal::data_management::interface1::TensorLayoutIface
Abstract interface class for a data management component responsible for representation of data layou...
Definition: tensor.h:161
daal
Definition: algorithm_base_common.h:57
daal::data_management::interface1::Tensor::freeDataMemory
DAAL_DEPRECATED_VIRTUAL services::Status freeDataMemory() DAAL_C11_OVERRIDE
Definition: tensor.h:599
daal::data_management::interface1::Tensor
Class for a data management component responsible for representation of data in the n-dimensions nume...
Definition: tensor.h:481
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:434
daal::data_management::interface1::Tensor::getErrors
DAAL_DEPRECATED services::SharedPtr< services::KernelErrorCollection > getErrors()
Definition: tensor.h:544
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:134
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:252
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:511
daal::data_management::interface1::TensorIface::check
virtual services::Status check(const char *description) const =0
daal::dram
Definition: daal_defines.h:158
daal::data_management::interface1::TensorIface::notAllocated
Definition: tensor.h:94
daal::data_management::interface1::TensorIface::notAllocate
Definition: tensor.h:106
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:466
daal::data_management::interface1::TensorIface::doAllocate
Definition: tensor.h:107
daal::data_management::interface1::Tensor::getDimensionSize
size_t getDimensionSize(size_t dimIdx) const
Definition: tensor.h:523
daal::data_management::interface1::TensorIface::MemoryStatus
MemoryStatus
Enumeration to specify the status of memory related to the Numeric Table.
Definition: tensor.h:92
daal::data_management::interface1::DenseTensorIface
Abstract interface class for a data management component responsible for accessing data in the numeri...
Definition: tensor.h:360
daal::data_management::interface1::TensorOffsetLayout::TensorOffsetLayout
TensorOffsetLayout(const services::Collection< size_t > &dims)
Definition: tensor.h:227
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:450
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:504
daal::data_management::interface1::TensorLayout
Class for a data management component responsible for representation of data layout in the tensor...
Definition: tensor.h:179
daal::data_management::interface1::TensorIface::AllocationFlag
AllocationFlag
Enumeration to specify whether the Numeric Table must allocate memory.
Definition: tensor.h:103
daal::data_management::interface1::TensorIface
Abstract interface class for a data management component responsible for representation of data in th...
Definition: tensor.h:85
daal::data_management::interface1::TensorIface::internallyAllocated
Definition: tensor.h:96
daal::data_management::interface1::Tensor::Tensor
Tensor()
Definition: tensor.h:496
daal::data_management::interface1::TensorOffsetLayout
Class for a data management component responsible for representation of data layout in the HomogenTen...
Definition: tensor.h:215
daal::data_management::interface1::TensorIface::userAllocated
Definition: tensor.h:95
daal::data_management::interface1::Tensor::check
virtual services::Status check(const char *description) const DAAL_C11_OVERRIDE
Definition: tensor.h:568
daal::data_management::interface1::TensorOffsetLayout::getIndices
const services::Collection< size_t > & getIndices() const
Definition: tensor.h:281
daal::data_management::interface1::TensorIface::doNotAllocate
Definition: tensor.h:105
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:594
daal::data_management::interface1::TensorOffsetLayout::getSerializationTag
virtual int getSerializationTag() const DAAL_C11_OVERRIDE
Definition: tensor.h:324
daal::data_management::interface1::TensorOffsetLayout::isLayout
bool isLayout(const TensorOffsetLayout &layout) const
Definition: tensor.h:293
daal::data_management::interface1::SubtensorDescriptor
Class with descriptor of the subtensor retrieved from Tensor getSubTensor function.
Definition: subtensor.h:73
daal::data_management::interface1::SerializationIface
Abstract interface class that defines the interface for serialization and deserialization.
Definition: data_serialize.h:76
daal::algorithms::implicit_als::training::init::offsets
Definition: implicit_als_training_init_types.h:117
daal::data_management::interface1::TensorLayout::getDimensions
const services::Collection< size_t > & getDimensions() const
Definition: tensor.h:188
daal::MemType
MemType
Definition: daal_defines.h:156
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:271
daal::services::ErrorIncorrectSizeOfDimensionInTensor
Definition: error_indexes.h:136

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