tensor.h 15.0 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 33 34 35 36 37 38
#include "paddle/phi/api/ext/dll_decl.h"
#include "paddle/phi/api/ext/place.h"
#include "paddle/phi/common/data_type.h"
#include "paddle/phi/common/layout.h"
#include "paddle/phi/common/place.h"

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

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

namespace paddle {
48

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

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

/**
 * Tensor is the API description of the basic data structure in the
59
 * [ "Paddle Tensor Operation (phi)" Library ].
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
 *
 * 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.
 */

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

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

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

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

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

  /**
   * @brief Construct a new Tensor object on the target place.
   * This is a deprecated method and may be removed in the future!
   *
   * @param place
115
   */
116 117 118 119 120 121 122 123 124 125 126
  explicit Tensor(const PlaceType& place);

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

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

135
  /**
136
   * @brief Construct a new Tensor object with name
137
   *
138 139 140 141
   * @note Used to adapt original execution mechanism and debug analysis
   * in the development of new dygraph. It may be removed in the future.
   * */
  explicit Tensor(const std::string& name) : name_(name) {}
142

143
  /* Part 2: Dimension, DataType and DataLayout methods */
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160

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

  /**
   * @brief Get the size of current tensor.
   * 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;

161
  /**
162 163
   * @brief Return the dimensions of Tensor.
   *
164
   * @return phi::DDim
165
   */
166
  phi::DDim dims() const;
167 168

  /**
169 170 171 172 173 174 175 176 177 178
   * @brief Return the shape (dimensions) of Tensor.
   * 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.
179
   * @note: This method means Reset the shape of the tensor,
180 181 182
   * and must be called before calling mutable_data() or
   * copy_to(const PlaceType& place), this is not a standard definition of
   * reshape behavior, so we will deprecated this feature in the future.
183 184 185 186 187 188 189 190 191
   *
   * @param shape
   */
  void reshape(const std::vector<int64_t>& shape);

  /**
   * @brief Return the data type of Tensor.
   *
   * @return DataType
192
   */
193
  DataType dtype() const;
194 195

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

  /**
205 206 207
   * @brief Return the layout of Tensor.
   *
   * @return DataLayout
208
   */
209
  DataLayout layout() const;
210

211 212 213 214 215 216 217 218
  /**
   * @brief Determine whether tensor is DenseTensor
   *
   * @return true
   * @return false
   */
  bool is_dense_tensor() const;

219 220 221 222 223 224 225 226
  /**
   * @brief Determine whether tensor is SelectedRows
   *
   * @return true
   * @return false
   */
  bool is_selected_rows() const;

227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242
  /**
   * @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;

243
  /* Part 3: Device and Backend methods */
244

245
  /**
246 247 248 249
   * @brief Return the place (device) of Tensor.
   * This is a deprecated method and may be removed in the future!
   *
   * @return PlaceType
250
   */
251
  PlaceType place() const;
252 253

  /**
254 255 256 257 258
   * @brief Return the place (device) of Tensor.
   * Because the `place` method already exists, so we need to use a new name,
   * here we temporarily use `inner_place`.
   *
   * @return paddle::platform::Place
259
   */
260
  phi::Place inner_place() const;
261 262

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

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

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

  /* Part 4: Data Access methods */
287 288 289 290 291 292 293 294 295 296 297

  /**
   * @brief Get the memory pointer in CPU or GPU with specific data type.
   * It's usually used to get the output data pointer.
   *
   * @tparam T
   * @return T*
   */
  template <typename T>
  T* mutable_data();

298
  /**
299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342
   * @brief Get the memory pointer in CPU or GPU with specific data type.
   * 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>
  T* mutable_data(const PlaceType& place);

  /**
   * @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.
   * It's usually used to get the output data pointer.
   * This is a deprecated method and may be removed in the future!
   *
   * @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
   */
343
  Tensor slice(int64_t begin_idx, int64_t end_idx) const;
344 345 346 347

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

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

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

366 367 368 369 370 371 372 373 374 375
#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

376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393
  /**
   * @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; }

394
  /* Part 5: Data Transform methods */
395 396
  /* Alert!!!!: All copy method can only deep copy impl, autograd info only be
   * copied */
397
  /* out of phi */
398 399
  /**
   * @brief Copy the current Tensor data to the specified device
400
   * and return the new Tensor. It's usually used to set the input tensor data.
401 402 403 404
   * @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
405
   * data type template argument
406 407 408 409
   *
   * @tparam T
   * @param target_place, the target place of which the tensor will copy to.
   * @return Tensor
410
   */
411 412
  template <typename T>
  Tensor copy_to(const PlaceType& target_place) const;
413 414

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

  /**
424 425 426 427 428 429
   * @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
   */
J
Jiabin Yang 已提交
430
  void copy_(const Tensor& src, const phi::Place& target_place, bool blocking);
431
  /**
432 433 434 435
   * @brief Cast datatype from one to another
   *
   * @param target_type
   * @return Tensor
436
   */
437
  Tensor cast(DataType target_type) const;
438

439
  /* Part 6: Status utils methods */
440

441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464
  /**
   * @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;
465 466

  /**
467
   * @brief Reset the Tensor implementation
468
   */
469 470 471
  void reset();

  /* Part 7: Operator overloading */
472 473

  /**
474 475 476 477
   * @brief Assignment operator
   *
   * @param x
   * @return Tensor&
478
   */
479
  Tensor& operator=(const Tensor& x) &;
480 481

  /**
482 483 484 485
   * @brief Move assignment operator
   *
   * @param x
   * @return Tensor&
486
   */
487
  Tensor& operator=(Tensor&& x) &;
488

489
  /* Part 8: Autograd methods */
490

491 492 493 494 495 496
  /**
   * @brief Get the autograd meta object
   *
   * @return AbstractAutogradMeta*
   */
  AbstractAutogradMeta* get_autograd_meta() const;
497

498 499 500 501 502 503
  /**
   * @brief Set the autograd meta object
   *
   * @param autograd_meta
   */
  void set_autograd_meta(std::shared_ptr<AbstractAutogradMeta> autograd_meta);
504

505 506 507 508 509 510 511 512 513 514 515 516 517 518 519
  /* 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();

  /* Part 10: Auto generated Tensor methods */
520

521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544
  /* Part 11: Methods of converting SparseTensor and DenseTensor to each other
   */
  /**
   * @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;

545 546 547 548 549 550 551 552
 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.
553
   * This is suitable for most scenarios including CPU, GPU, HIP, CPU, etc.,
554 555 556 557 558 559 560 561 562 563
   * 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`.
   */
564
  std::shared_ptr<phi::TensorBase> impl_;
565 566 567 568 569 570 571 572 573 574 575 576 577 578 579

  /**
   * [ 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};

  /**
580
   * Tensor name: used to adapt original execution mechanism and debug analysis
581
   * in the development of new dygraph. It may be removed in the future.
582
   */
583
  std::string name_{""};
584 585 586 587 588 589

  /**
   * Place type: Return the expected memory location if the Tensor is
   * uninitialized.
   */
  PlaceType place_{PlaceType::kUNK};
590 591 592 593
};

}  // namespace experimental
}  // namespace paddle