tensor.h 14.9 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
/* Copyright (c) 2021 PaddlePaddle Authors. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. */

#pragma once

#include <functional>
#include <memory>
#include <utility>
20
#include <vector>
21

22 23 24 25
#ifdef PADDLE_WITH_CUDA
#include <cuda_runtime.h>
using gpuStream_t = cudaStream_t;
#endif
26

27 28 29 30 31
#ifdef PADDLE_WITH_HIP
#include <hip/hip_runtime.h>
using gpuStream_t = hipStream_t;
#endif

32
#include "paddle/phi/api/include/dll_decl.h"
33 34 35 36 37
#include "paddle/phi/common/data_type.h"
#include "paddle/phi/common/layout.h"
#include "paddle/phi/common/place.h"

namespace phi {
38
class DenseTensor;
39
}  // namespace phi
40

41
namespace phi {
42
class TensorBase;
43
class DDim;
44
}  // namespace phi
45 46

namespace paddle {
47

48 49 50 51 52 53 54 55 56 57
namespace experimental {

class AbstractAutogradMeta {
 public:
  // No AbstractAutogradMeta should be created
  virtual ~AbstractAutogradMeta() {}
};

/**
 * Tensor is the API description of the basic data structure in the
58
 * [ "Paddle Tensor Operation (phi)" Library ].
59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82
 *
 * It is not limited to a simple n-dimensional array.
 * It contains a smart pointer to `TensorImpl`. The data description contained
 * in Tensor is defined by TensorImpl. Tensor only defines the interface for
 * computation.
 *
 * This is a new Tensor design, which is independent of the original
 * framework::Tensor in fluid. The original Tensor will be gradually discarded
 * in the future.
 *
 * Note: Tensor can be NULL state, Tensor is meaningful only when the
 * TensorImpl to which it is pointed is not empty.
 *
 * Note: For the consistency of C++ API self, and the consistency between C++
 * API and Python API, all member methods of Tensor are named with lowercase
 * letters and underscores.
 *
 * Note: Tensor cannot be inherited. The heterogeneous Tensor implementation
 * can be achieved by inheriting the underlying TensorBase.
 *
 * Note: This Tensor API is suitable for training and custom operators,
 * another simple Tensor design may be required for inference.
 */

83
class PADDLE_API Tensor final {
84
 public:
85 86
  /* Part 1: Construction and destruction methods */

87 88 89 90 91 92 93 94
  /**
   * @brief Construct a new Tensor object
   */
  Tensor() = default;

  /**
   * @brief Construct a new Tensor object by copy
   */
95
  Tensor(const Tensor&) = default;
96 97 98 99

  /**
   * @brief Construct a new Tensor object by move
   */
100 101 102
  Tensor(Tensor&&) = default;

  /**
103 104 105 106
   * @brief Construct a new Tensor object by a TensorBase pointer
   *
   * @param tensor_impl
   */
107
  explicit Tensor(std::shared_ptr<phi::TensorBase> tensor_impl);
108 109 110

  /**
   * @brief Construct a new Tensor object on the target place.
111 112
   *
   * This is a deprecated method and may be removed in the future!!!
113 114
   *
   * @param place
115
   */
116
  explicit Tensor(const Place& place);
117 118 119 120

  /**
   * @brief Construct a new Tensor object on the target place
   * with specified shape.
121 122
   *
   * This is a deprecated method and may be removed in the future!!!
123 124 125 126
   *
   * @param place
   * @param shape
   */
127
  Tensor(const Place& place, const std::vector<int64_t>& shape);
128

129 130 131 132 133
  /**
   * @brief Construct a new Tensor object by a TensorBase pointer and name
   *
   * @param tensor_impl
   */
134
  Tensor(std::shared_ptr<phi::TensorBase> tensor_impl, const std::string& name);
135

J
Jiabin Yang 已提交
136
  /**
137
   * @brief Construct a new Tensor object with name
J
Jiabin Yang 已提交
138
   *
139 140 141
   * @note Internal method, used to adapt original execution mechanism and
   * debug analysis in the development of new dygraph. It may be removed in
   * the future.
142 143
   * */
  explicit Tensor(const std::string& name) : name_(name) {}
J
Jiabin Yang 已提交
144

145
  /* Part 2: Dimension, DataType and DataLayout methods */
146 147 148 149 150 151 152 153 154 155

  /**
   * @brief Return the number of elements of Tensor.
   *
   * @return int64_t
   */
  int64_t numel() const;

  /**
   * @brief Get the size of current tensor.
156
   *
157 158 159 160 161 162 163
   * The compatible method of `Tensor::numel()`.
   * This is a deprecated method and may be removed in the future!
   *
   * @return int64_t
   */
  int64_t size() const;

164
  /**
165 166
   * @brief Return the dimensions of Tensor.
   *
167
   * @return phi::DDim
168
   */
169
  const phi::DDim& dims() const;
170 171

  /**
172
   * @brief Return the shape (dimensions) of Tensor.
173
   *
174 175 176 177 178 179 180 181 182
   * The compatible method of `Tensor::dims()`.
   * This is a deprecated method and may be removed in the future!
   *
   * @return std::vector<int64_t>
   */
  std::vector<int64_t> shape() const;

  /**
   * @brief Reset the shape of the tensor.
183
   * @note: This method means Reset the shape of the tensor,
184
   * and must be called before calling mutable_data() or
185
   * copy_to(const Place& place), this is not a standard definition of
186
   * reshape behavior, so we will deprecated this feature in the future.
187 188 189 190 191 192 193 194 195
   *
   * @param shape
   */
  void reshape(const std::vector<int64_t>& shape);

  /**
   * @brief Return the data type of Tensor.
   *
   * @return DataType
196
   */
197
  DataType dtype() const;
198 199

  /**
200
   * @brief Return the data type of Tensor.
201
   *
202 203 204 205
   * The compatible method of `Tensor::dtype()`.
   * This is a deprecated method and may be removed in the future!
   *
   * @return DataType
206
   */
207
  DataType type() const;
208 209

  /**
210 211 212
   * @brief Return the layout of Tensor.
   *
   * @return DataLayout
213
   */
214
  DataLayout layout() const;
215

C
Chen Weihang 已提交
216 217 218 219 220 221 222 223
  /**
   * @brief Determine whether tensor is DenseTensor
   *
   * @return true
   * @return false
   */
  bool is_dense_tensor() const;

224 225 226 227 228 229 230 231
  /**
   * @brief Determine whether tensor is SelectedRows
   *
   * @return true
   * @return false
   */
  bool is_selected_rows() const;

232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247
  /**
   * @brief Determine whether tensor is SparseCooTensor
   *
   * @return true
   * @return false
   */
  bool is_sparse_coo_tensor() const;

  /**
   * @brief Determine whether tensor is SparseCsrTensor
   *
   * @return true
   * @return false
   */
  bool is_sparse_csr_tensor() const;

J
Jack Zhou 已提交
248 249 250 251 252 253 254 255
  /**
   * @brief Determine whether tensor is StringTensor
   *
   * @return true
   * @return false
   */
  bool is_string_tensor() const;

256
  /* Part 3: Device and Backend methods */
257

258
  /**
259 260
   * @brief Return the place (device) of Tensor.
   *
261
   * @return Place
262
   */
263
  const Place& place() const;
264 265

  /**
266 267 268 269
   * @brief Determine whether the tensor device is CPU
   *
   * @return true
   * @return false
270
   */
271 272 273
  bool is_cpu() const;

  /**
274
   * @brief Determine whether the tensor device is GPU
275 276 277 278
   *
   * @return true
   * @return false
   */
279 280 281 282 283 284 285 286 287
  bool is_gpu() const;

  /**
   * @brief Determine whether the tensor device is GPU_PINNED
   *
   * @return true
   * @return false
   */
  bool is_gpu_pinned() const;
288 289

  /* Part 4: Data Access methods */
290 291 292

  /**
   * @brief Get the memory pointer in CPU or GPU with specific data type.
293
   * It's usually used to get the output data pointer, same as the T* data().
294 295 296 297 298 299 300
   *
   * @tparam T
   * @return T*
   */
  template <typename T>
  T* mutable_data();

301
  /**
302
   * @brief Get the memory pointer in CPU or GPU with specific data type.
303
   *
304 305 306 307 308 309 310 311
   * It's usually used to get the output data pointer.
   * This is a deprecated method and may be removed in the future!
   *
   * @tparam T
   * @param place
   * @return T*
   */
  template <typename T>
312
  T* mutable_data(const Place& place);
313 314 315 316 317 318 319 320 321 322 323 324 325

  /**
   * @brief Get the const memory pointer directly.
   * It's usually used to get the output data pointer.
   *
   * @tparam T
   * @return T*
   */
  template <typename T>
  const T* data() const;

  /**
   * @brief Get the memory pointer directly.
326
   * It's usually used to get the mutable output data pointer.
327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345
   *
   * @tparam T
   * @return T*
   */
  template <typename T>
  T* data();

  /**
   * @brief Return a sub-tensor of the given tensor.
   * It is usually used to extract a sub-tensor (which supports
   * modifying the data of the original tensor) to perform further
   * operations.
   *
   * @param begin_idx The index of the start row (inclusive) to slice.
   *                  The index number begins from 0.
   * @param end_idx The index of the end row (exclusive) to slice.
   *                 The index number begins from begin_idx + 1.
   * @return Tensor
   */
346
  Tensor slice(int64_t begin_idx, int64_t end_idx) const;
347 348 349 350

  /**
   * @brief Return the implemention of current Tensor.
   *
351
   * @return std::shared_ptr<phi::TensorBase>
352
   */
353
  const std::shared_ptr<phi::TensorBase>& impl() const;
354 355 356 357 358 359

  /**
   * @brief Set the implemention of current Tensor.
   *
   * @param impl
   */
360
  void set_impl(const std::shared_ptr<phi::TensorBase>& impl);
361

362 363 364 365 366 367 368
  /**
   * @brief Set the implemention of current Tensor.
   *
   * @param impl
   */
  void set_impl(std::shared_ptr<phi::TensorBase>&& impl);

369 370 371 372 373 374 375 376 377 378
#if defined(PADDLE_WITH_CUDA) || defined(PADDLE_WITH_HIP)
  /**
   * @brief Get the stream where the tensor is currently located
   * This is a deprecated method and may be removed in the future!
   *
   * @return gpuStream_t
   */
  gpuStream_t stream() const;
#endif

379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396
  /**
   * @brief Return the name of Tensor.
   * @note Used to adapt original execution mechanism and debug analysis
   * in the development of new dygraph. It may be removed in the future.
   *
   * @return const std::string&
   */
  const std::string& name() const { return name_; }

  /**
   * @brief Set name of Tensor.
   * @note Used to adapt original execution mechanism and debug analysis
   * in the development of new dygraph. It may be removed in the future.
   *
   * @param const std::string& name
   */
  void set_name(const std::string& name) { name_ = name; }

397
  /* Part 5: Data Transform methods */
398 399
  /* Alert!!!!: All copy method can only deep copy impl, autograd info only be
   * copied */
400
  /* out of phi */
401 402
  /**
   * @brief Copy the current Tensor data to the specified device
403
   * and return the new Tensor. It's usually used to set the input tensor data.
404 405 406 407
   * @note The Tensor's `copy_to` method is deprecated since version 2.3, and
   * will be removed in version 2.4, please use `copy_to` method without
   * template argument instead.
   * reason: copying a Tensor to another device does not need to specify the
408
   * data type template argument
409 410 411 412
   *
   * @tparam T
   * @param target_place, the target place of which the tensor will copy to.
   * @return Tensor
413
   */
414
  template <typename T>
415
  Tensor copy_to(const Place& target_place) const;
416 417

  /**
418 419
   * @brief Transfer the current Tensor to the specified device and return.
   *
420
   * @param place, The target place of which the tensor will copy to.
421
   * @param blocking, Should we copy this in sync way.
422 423
   * @return Tensor
   */
424
  Tensor copy_to(const Place& place, bool blocking) const;
425 426

  /**
427 428 429 430 431 432
   * @brief Transfer the source Tensor to current Tensor.
   *
   * @param src, the source Tensor to be copied.
   * @param blocking, Should we copy this in sync way.
   * @return void
   */
433 434
  void copy_(const Tensor& src, const Place& target_place, bool blocking);

435
  /**
436 437 438 439
   * @brief Cast datatype from one to another
   *
   * @param target_type
   * @return Tensor
440
   */
441
  Tensor cast(DataType target_type) const;
442

443
  /* Part 6: Status utils methods */
444

445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468
  /**
   * @brief Determine whether it is a meaningful Tensor
   *
   * @return true
   * @return false
   */
  bool defined() const;

  /**
   * @brief Determine whether Tensor is initialized.
   *
   * @return true
   * @return false
   */
  bool initialized() const;

  /**
   * @brief Determine whether Tensor is initialized.
   * This is a deprecated method and may be removed in the future!
   *
   * @return true
   * @return false
   */
  bool is_initialized() const;
469 470

  /**
471
   * @brief Reset the Tensor implementation
472
   */
473 474 475
  void reset();

  /* Part 7: Operator overloading */
476 477

  /**
478 479 480 481
   * @brief Assignment operator
   *
   * @param x
   * @return Tensor&
482
   */
483
  Tensor& operator=(const Tensor& x) &;
484 485

  /**
486 487 488 489
   * @brief Move assignment operator
   *
   * @param x
   * @return Tensor&
490
   */
491
  Tensor& operator=(Tensor&& x) &;
492

493
  /* Part 8: Autograd methods */
494

495
  /**
496
   * @brief Get the autograd meta object pointer
497 498 499 500
   *
   * @return AbstractAutogradMeta*
   */
  AbstractAutogradMeta* get_autograd_meta() const;
501 502 503 504 505 506

  /**
   * @brief Get the shared pointer of autograd meta object
   *
   * @return std::shared_ptr<AbstractAutogradMeta>&
   */
507
  const std::shared_ptr<AbstractAutogradMeta>& mutable_autograd_meta() const;
508

509 510 511 512 513 514
  /**
   * @brief Set the autograd meta object
   *
   * @param autograd_meta
   */
  void set_autograd_meta(std::shared_ptr<AbstractAutogradMeta> autograd_meta);
515

516 517 518 519 520 521 522 523 524 525 526 527 528 529
  /* Part 9: Inplace methods */

  /**
   * @brief Increase inplace version
   */
  void bump_inplace_version();

  /**
   * @brief Get current inplace version
   *
   * @return uint32_t
   */
  uint32_t current_inplace_version();

530 531 532 533 534
  /**
   * @brief Reset inplace version
   */
  void reset_inplace_version(bool set_to_zero = false);

535
  /* Part 10: Auto generated Tensor methods */
536

537
  /* Part 11: Methods of converting underlying TensorType to each other
538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560
   */
  /**
   * @brief Convert DenseTensor or SparseCsrTensor to SparseCooTensor
   *
   * @param sparse_dim, The number of sparse dimensions
   * @return Tensor
   */
  Tensor to_sparse_coo(const int64_t sparse_dim) const;

  /**
   * @brief Convert DenseTensor or SparseCooTensor to SparseCsrTensor
   *
   * @return Tensor
   */
  Tensor to_sparse_csr() const;

  /**
   * @brief Convert SparseCooTensor or SparseCsrTensor to DenseTensor
   *
   * @return Tensor
   */
  Tensor to_dense() const;

561 562 563 564 565 566 567 568
 private:
  /**
   * [ Why use abstract TensorImpl interface here? ]
   *
   * We hope that the data structure at the API level of the framework can be
   * unified to Tensor, but Tensor itself is heterogeneous.
   *
   * Tensor can generally be represented by void* and size_t, place.
569
   * This is suitable for most scenarios including CPU, GPU, HIP, CPU, etc.,
570 571 572 573 574 575 576 577 578 579
   * but there are a few cases where this definition cannot be described,
   * such as the Tensor representation in third-party lib such as Metal,
   * OpenCL, etc., as well as some special Tensor implementations, including
   * Tensor containing only one Scalar value, or Tensor representing String,
   * etc.
   *
   * Therefore, we hope to use a unified interface to shield the underlying
   * heterogeneous Tensor implementation, so that the API level can be unified
   * to one `Tensor`.
   */
H
hong 已提交
580
  std::shared_ptr<phi::TensorBase> impl_{nullptr};
581 582 583 584 585 586 587 588 589 590 591 592 593 594 595

  /**
   * [ Why need abstract AbstractAutogradMeta here? ]
   *
   * Dynamic graphs need to hold backward information
   *
   * [ Why AutogradMeta not in TensorImpl? ]
   *
   * 1. AutogradMeta is only used in dynamic graph, It is execution-related
   *    information, not Tensor data description-related information.
   * 2. Kernel calculation does not require AutogradMeta.
   */
  std::shared_ptr<AbstractAutogradMeta> autograd_meta_{nullptr};

  /**
596
   * Tensor name: used to adapt original execution mechanism and debug analysis
597
   * in the development of new dygraph. It may be removed in the future.
598
   */
599
  std::string name_{""};
600 601 602 603
};

}  // namespace experimental
}  // namespace paddle