[API Compatibility] Add paddle.cuda apis

docs/api/paddle/cuda/Overview_cn.rst

@@ -18,3 +18,9 @@ PyTorch 兼容函数
     " :ref:`cudart <cn_api_paddle_cuda_cudart>` ", "以模块的形式返回 CUDA Runtime 对象"
     " :ref:`is_initialized <cn_api_paddle_cuda_is_initialized>` ", "判断 CUDA 是否已经初始化"
     " :ref:`mem_get_info <cn_api_paddle_cuda_mem_get_info>` ", "获取指定设备上的全局空闲显存和显存总量"
+    " :ref:`current_device <cn_api_paddle_cuda_current_device>` ", "返回当前设备的索引"
+    " :ref:`device_count <cn_api_paddle_cuda_device_count>` ", "返回可用的 CUDA 设备数量"
+    " :ref:`empty_cache <cn_api_paddle_cuda_empty_cache>` ", "释放当前设备上所有未占用的缓存内存"
+    " :ref:`memory_allocated <cn_api_paddle_cuda_memory_allocated>` ", "返回当前设备上分配的内存总量"
+    " :ref:`memory_reserved <cn_api_paddle_cuda_memory_reserved>` ", "返回当前设备上由缓存分配器管理的内存总量"
+    " :ref:`set_device <cn_api_paddle_cuda_set_device>` ", "设置当前设备"

docs/api/paddle/cuda/current_device_cn.rst

@@ -0,0 +1,17 @@
+.. _cn_api_paddle_cuda_current_device:
+
+current_device
+--------------
+
+.. py:function:: paddle.cuda.current_device()
+
+返回当前设备的索引。
+
+返回
+::::::::::::
+
+    int, 当前设备的索引。
+
+代码示例
+::::::::::::
+COPY-FROM: paddle.cuda.current_device

docs/api/paddle/cuda/device_count_cn.rst

@@ -0,0 +1,17 @@
+.. _cn_api_paddle_cuda_device_count:
+
+device_count
+------------
+
+.. py:function:: paddle.cuda.device_count()
+
+返回可用的计算卡设备数量。
+
+返回
+::::::::::::
+
+    int, 可用的计算卡设备数量。
+
+代码示例
+::::::::::::
+COPY-FROM: paddle.cuda.device_count

docs/api/paddle/cuda/empty_cache_cn.rst

@@ -0,0 +1,12 @@
+.. _cn_api_paddle_cuda_empty_cache:
+
+empty_cache
+-----------
+
+.. py:function:: paddle.cuda.empty_cache()
+
+该函数用于释放显存分配器中空闲的显存，这样其他的 GPU 应用程序就可以使用释放出来的显存，并在 nvidia-smi 中可见。大多数情况下您不需要使用该函数，当您删除 GPU 上的 Tensor 时，Paddle 框架并不会将显存释放，而是将显存保留起来，以便在下一次申明显存时可以更快的完成分配。
+
+代码示例
+::::::::::::
+COPY-FROM: paddle.cuda.empty_cache

docs/api/paddle/cuda/memory_allocated_cn.rst

@@ -0,0 +1,22 @@
+.. _cn_api_paddle_cuda_memory_allocated:
+
+memory_allocated
+---------------
+
+.. py:function:: paddle.cuda.memory_allocated(device=None)
+
+返回给定设备上当前分配给 Tensor 的显存大小。
+
+参数
+::::::::::::
+
+    - **device** (DeviceLike) - 指定要查询的设备，可以是 "int" 用来表示设备 id，可以是形如 "gpu:0" 之类的设备描述字符串，也可以是 `paddle.CUDAPlace(0)` 之类的设备实例。如果为 None（默认值）或未指定设备索引，则返回由 ``paddle.device.get_device()`` 给出的当前设备的统计信息。
+
+返回
+::::::::::::
+
+    int, 当前设备上分配的内存总量（字节）。
+
+代码示例
+::::::::::::
+COPY-FROM: paddle.cuda.memory_allocated

docs/api/paddle/cuda/memory_reserved_cn.rst

@@ -0,0 +1,22 @@
+.. _cn_api_paddle_cuda_memory_reserved:
+
+memory_reserved
+---------------
+
+.. py:function:: paddle.cuda.memory_reserved(device=None)
+
+返回当前设备上由缓存分配器管理的内存总量。
+
+参数
+::::::::::::
+
+    - **device** (DeviceLike) - 指定要查询的设备，可以是 "int" 用来表示设备 id，可以是形如 "gpu:0" 之类的设备描述字符串，也可以是 `paddle.CUDAPlace(0)` 之类的设备实例。如果为 None（默认值）或未指定设备索引，则返回由 ``paddle.device.get_device()`` 给出的当前设备的统计信息。
+
+返回
+::::::::::::
+
+    int, 当前设备上由缓存分配器管理的内存总量（字节）。
+
+代码示例
+::::::::::::
+COPY-FROM: paddle.cuda.memory_reserved

docs/api/paddle/cuda/set_device_cn.rst

@@ -0,0 +1,17 @@
+.. _cn_api_paddle_cuda_set_device:
+
+set_device
+----------
+
+.. py:function:: paddle.cuda.set_device(device)
+
+设置当前设备。
+
+参数
+::::::::::::
+
+    - **device** (DeviceLike) - 要设置的设备，可以是 "int" 用来表示设备 id，可以是形如 "gpu:0" 之类的设备描述字符串，也可以是 `paddle.CUDAPlace(0)` 之类的设备实例。
+
+代码示例
+::::::::::::
+COPY-FROM: paddle.cuda.set_device

docs/api/paddle/device/Overview_cn.rst

@@ -25,11 +25,20 @@ paddle.device 目录下包含 cuda 目录和 xpu 目录， cuda 目录中存放
     :header: "API 名称", "API 功能"
     :widths: 10, 30
 
+    " :ref:`device_count <cn_api_paddle_device_device_count>` ", "返回指定设备类型的可用设备数量"
+    " :ref:`empty_cache <cn_api_paddle_device_empty_cache>` ", "释放当前设备上所有未占用的缓存内存"
     " :ref:`get_all_custom_device_type <cn_api_paddle_device_get_all_custom_device_type>` ", "获得所有可用的自定义设备类型"
     " :ref:`get_all_device_type <cn_api_paddle_device_get_all_device_type>` ", "获得所有可用的设备类型"
     " :ref:`get_available_custom_device <cn_api_paddle_device_get_available_custom_device>` ", "获得所有可用的自定义设备"
     " :ref:`get_available_device <cn_api_paddle_device_get_available_device>` ", "获得所有可用的设备"
     " :ref:`get_cudnn_version <cn_api_paddle_device_get_cudnn_version>` ", "获得 cudnn 的版本"
+    " :ref:`get_device_properties <cn_api_paddle_device_get_device_properties>` ", "返回指定设备的属性"
+    " :ref:`max_memory_allocated <cn_api_paddle_device_max_memory_allocated>` ", "返回给定设备上分配给 Tensor 的内存峰值统计"
+    " :ref:`max_memory_reserved <cn_api_paddle_device_max_memory_reserved>` ", "返回给定设备上由内存分配器管理的内存峰值统计"
+    " :ref:`memory_allocated <cn_api_paddle_device_memory_allocated>` ", "返回给定设备上当前分配给 Tensor 的内存大小"
+    " :ref:`memory_reserved <cn_api_paddle_device_memory_reserved>` ", "返回给定设备上当前由内存分配器管理的内存大小"
+    " :ref:`reset_max_memory_allocated <cn_api_paddle_device_reset_max_memory_allocated>` ", "重置给定设备上分配给 Tensor 的内存峰值统计"
+    " :ref:`reset_max_memory_reserved <cn_api_paddle_device_reset_max_memory_reserved>` ", "重置给定设备上由内存分配器管理的内存峰值统计"
     " :ref:`set_device <cn_api_paddle_device_set_device>` ", "指定 OP 运行的全局设备"
     " :ref:`get_device <cn_api_paddle_device_get_device>` ", "获得 OP 运行的全局设备"
 

docs/api/paddle/device/device_count_cn.rst

@@ -0,0 +1,22 @@
+.. _cn_api_paddle_device_device_count:
+
+device_count
+------------
+
+.. py:function:: paddle.device.device_count(device=None)
+
+返回指定设备类型的可用设备数量。
+
+参数
+::::::::::::
+
+    - **device** (paddle.CUDAPlace|paddle.CustomPlace|paddle.XPUPlace|str|int，可选) - 设备、设备 ID 或形如 ``gpu:x``、``xpu:x`` 或自定义设备名称的设备字符串。如果为 None，则返回当前设备类型的可用设备数量。默认值为 None。
+
+返回
+::::::::::::
+
+    int，指定设备类型的可用设备数量。
+
+代码示例
+::::::::::::
+COPY-FROM: paddle.device.device_count

docs/api/paddle/device/empty_cache_cn.rst

@@ -0,0 +1,18 @@
+.. _cn_api_paddle_device_empty_cache:
+
+empty_cache
+-----------
+
+.. py:function:: paddle.device.empty_cache()
+
+释放当前设备上所有未占用的缓存内存。
+
+代码示例
+::::::::::::
+.. code-block:: python
+
+    import paddle
+
+    x = paddle.randn([1000, 1000])
+    del x
+    paddle.device.empty_cache()

docs/api/paddle/device/get_device_properties_cn.rst

@@ -0,0 +1,22 @@
+.. _cn_api_paddle_device_get_device_properties:
+
+get_device_properties
+---------------------
+
+.. py:function:: paddle.device.get_device_properties(device=None)
+
+返回指定设备的属性。
+
+参数
+::::::::::::
+
+    - **device** (paddle.CUDAPlace|paddle.CustomPlace|paddle.XPUPlace|str|int，可选) - 设备、设备 ID 或形如 ``gpu:x``、``xpu:x`` 或自定义设备名称的设备字符串。如果为 None，则返回当前设备的属性。默认值为 None。
+
+返回
+::::::::::::
+
+    String，指定设备的属性，包括设备名称、主要计算能力、次要计算能力、全局可用内存和设备上的多处理器数量。
+
+代码示例
+::::::::::::
+COPY-FROM: paddle.device.get_device_properties

docs/api/paddle/device/max_memory_allocated_cn.rst

@@ -0,0 +1,28 @@
+.. _cn_api_paddle_device_max_memory_allocated:
+
+max_memory_allocated
+--------------------
+
+.. py:function:: paddle.device.max_memory_allocated(device=None)
+
+返回给定设备上分配给 Tensor 的内存峰值统计。
+
+参数
+::::::::::::
+
+    - **device** (paddle.CUDAPlace|paddle.CustomPlace|paddle.XPUPlace|str|int，可选) - 设备、设备 ID 或形如 ``gpu:x``、``xpu:x`` 或自定义设备名称的设备字符串。如果为 None，则返回当前设备的统计信息。默认值为 None。
+
+返回
+::::::::::::
+
+    int，给定设备上分配给 Tensor 的内存峰值统计，以字节为单位。
+
+代码示例
+::::::::::::
+.. code-block:: python
+
+    >>> import paddle
+    >>> paddle.device.max_memory_allocated('npu:0')
+    >>> paddle.device.max_memory_allocated('npu')
+    >>> paddle.device.max_memory_allocated(0)
+    >>> paddle.device.max_memory_allocated(Paddle.CustomPlace('npu',0))

docs/api/paddle/device/max_memory_reserved_cn.rst

@@ -0,0 +1,28 @@
+.. _cn_api_paddle_device_max_memory_reserved:
+
+max_memory_reserved
+-------------------
+
+.. py:function:: paddle.device.max_memory_reserved(device=None)
+
+返回给定设备上由内存分配器管理的内存峰值统计。
+
+参数
+::::::::::::
+
+    - **device** (paddle.CUDAPlace|paddle.CustomPlace|paddle.XPUPlace|str|int，可选) - 设备、设备 ID 或形如 ``gpu:x``、``xpu:x`` 或自定义设备名称的设备字符串。如果为 None，则返回当前设备的统计信息。默认值为 None。
+
+返回
+::::::::::::
+
+    int，给定设备上由内存分配器管理的内存峰值统计，以字节为单位。
+
+代码示例
+::::::::::::
+.. code-block:: python
+
+    >>> import paddle
+    >>> paddle.device.max_memory_reserved('npu:0')
+    >>> paddle.device.max_memory_reserved('npu')
+    >>> paddle.device.max_memory_reserved(0)
+    >>> paddle.device.max_memory_reserved(Paddle.CustomPlace('npu',0))

docs/api/paddle/device/memory_allocated_cn.rst

@@ -0,0 +1,31 @@
+.. _cn_api_paddle_device_memory_allocated:
+
+memory_allocated
+---------------
+
+.. py:function:: paddle.device.memory_allocated(device=None)
+
+返回给定设备上当前分配给 Tensor 的内存大小。
+
+.. note::
+    Paddle 中分配给 Tensor 的内存块大小会进行 256 字节对齐，因此可能大于 Tensor 实际需要的内存大小。例如，一个 shape 为[1]的 float32 类型 Tensor 会占用 256 字节的内存，即使存储一个 float32 类型数据实际只需要 4 字节。
+
+参数
+::::::::::::
+
+    - **device** (paddle.CUDAPlace|paddle.CustomPlace|paddle.XPUPlace|str|int，可选) - 设备、设备 ID 或形如 ``gpu:x``、``xpu:x`` 或自定义设备名称的设备字符串。如果为 None，则返回当前设备的统计信息。默认值为 None。
+
+返回
+::::::::::::
+
+    int，给定设备上当前分配给 Tensor 的内存大小，以字节为单位。
+
+代码示例
+::::::::::::
+.. code-block:: python
+
+    >>> import paddle
+    >>> paddle.device.memory_allocated('npu:0')
+    >>> paddle.device.memory_allocated('npu')
+    >>> paddle.device.memory_allocated(0)
+    >>> paddle.device.memory_allocated(Paddle.CustomPlace('npu',0))

docs/api/paddle/device/memory_reserved_cn.rst

@@ -0,0 +1,28 @@
+.. _cn_api_paddle_device_memory_reserved:
+
+memory_reserved
+---------------
+
+.. py:function:: paddle.device.memory_reserved(device=None)
+
+返回给定设备上当前由内存分配器管理的内存大小。
+
+参数
+::::::::::::
+
+    - **device** (paddle.CUDAPlace|paddle.CustomPlace|paddle.XPUPlace|str|int，可选) - 设备、设备 ID 或形如 ``gpu:x``、``xpu:x`` 或自定义设备名称的设备字符串。如果为 None，则返回当前设备的统计信息。默认值为 None。
+
+返回
+::::::::::::
+
+    int，给定设备上当前由内存分配器管理的内存大小，以字节为单位。
+
+代码示例
+::::::::::::
+.. code-block:: python
+
+    >>> import paddle
+    >>> paddle.device.memory_reserved('npu:0')
+    >>> paddle.device.memory_reserved('npu')
+    >>> paddle.device.memory_reserved(0)
+    >>> paddle.device.memory_reserved(Paddle.CustomPlace('npu',0))

docs/api/paddle/device/reset_max_memory_allocated_cn.rst

@@ -0,0 +1,28 @@
+.. _cn_api_paddle_device_reset_max_memory_allocated:
+
+reset_max_memory_allocated
+-------------------------
+
+.. py:function:: paddle.device.reset_max_memory_allocated(device=None)
+
+重置给定设备上分配给 Tensor 的内存峰值统计。
+
+参数
+::::::::::::
+
+    - **device** (paddle.CUDAPlace|paddle.CustomPlace|paddle.XPUPlace|str|int，可选) - 设备、设备 ID 或形如 ``gpu:x``、``xpu:x`` 或自定义设备名称的设备字符串。如果为 None，则重置当前设备的统计信息。默认值为 None。
+
+返回
+::::::::::::
+
+    None
+
+代码示例
+::::::::::::
+.. code-block:: python
+
+    >>> import paddle
+    >>> paddle.device.reset_max_memory_allocated('npu:0')
+    >>> paddle.device.reset_max_memory_allocated('npu')
+    >>> paddle.device.reset_max_memory_allocated(0)
+    >>> paddle.device.reset_max_memory_allocated(Paddle.CustomPlace('npu',0))

docs/api/paddle/device/reset_max_memory_reserved_cn.rst

@@ -0,0 +1,28 @@
+.. _cn_api_paddle_device_reset_max_memory_reserved:
+
+reset_max_memory_reserved
+-------------------------
+
+.. py:function:: paddle.device.reset_max_memory_reserved(device=None)
+
+重置给定设备上由内存分配器管理的内存峰值统计。
+
+参数
+::::::::::::
+
+    - **device** (paddle.CUDAPlace|paddle.CustomPlace|paddle.XPUPlace|str|int，可选) - 设备、设备 ID 或形如 ``gpu:x``、``xpu:x`` 或自定义设备名称的设备字符串。如果为 None，则重置当前设备的统计信息。默认值为 None。
+
+返回
+::::::::::::
+
+    None
+
+代码示例
+::::::::::::
+.. code-block:: python
+
+    >>> import paddle
+    >>> paddle.device.reset_max_memory_reserved('npu:0')
+    >>> paddle.device.reset_max_memory_reserved('npu')
+    >>> paddle.device.reset_max_memory_reserved(0)
+    >>> paddle.device.reset_max_memory_reserved(Paddle.CustomPlace('npu',0))