From 20f68916edde611594ce7492f319c8f7df109bfa Mon Sep 17 00:00:00 2001 From: Youwei Song Date: Wed, 9 Oct 2019 19:20:50 +0800 Subject: [PATCH] refine CUDA CPU places en doc (#20243) * fix CUDA CPU places, test=document_fix, test=develop * fix CUDAPlace param doc, test=document_fix, test=develop * fix CUDAPlace param doc, test=document_fix, test=develop --- paddle/fluid/API.spec | 12 ++++----- paddle/fluid/pybind/pybind.cc | 32 ++++++++++++++++++------ python/paddle/fluid/framework.py | 42 +++++++++++++++++++------------- 3 files changed, 56 insertions(+), 30 deletions(-) diff --git a/paddle/fluid/API.spec b/paddle/fluid/API.spec index 84d346125e5..3fd45161e01 100755 --- a/paddle/fluid/API.spec +++ b/paddle/fluid/API.spec @@ -11,9 +11,9 @@ paddle.fluid.default_startup_program (ArgSpec(args=[], varargs=None, keywords=No paddle.fluid.default_main_program (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', '853718df675e59aea7104f3d61bbf11d')) paddle.fluid.program_guard (ArgSpec(args=['main_program', 'startup_program'], varargs=None, keywords=None, defaults=(None,)), ('document', '78fb5c7f70ef76bcf4a1862c3f6b8191')) paddle.fluid.name_scope (ArgSpec(args=['prefix'], varargs=None, keywords=None, defaults=(None,)), ('document', '917d313881ff990de5fb18d98a9c7b42')) -paddle.fluid.cuda_places (ArgSpec(args=['device_ids'], varargs=None, keywords=None, defaults=(None,)), ('document', '1f2bb6ece651e44117652d2d7bedecf5')) -paddle.fluid.cpu_places (ArgSpec(args=['device_count'], varargs=None, keywords=None, defaults=(None,)), ('document', '956bab564ebc69ffd17195c08cc8ffa0')) -paddle.fluid.cuda_pinned_places (ArgSpec(args=['device_count'], varargs=None, keywords=None, defaults=(None,)), ('document', 'c2562241744aabe3fff1b59af22dd281')) +paddle.fluid.cuda_places (ArgSpec(args=['device_ids'], varargs=None, keywords=None, defaults=(None,)), ('document', 'ab9bd2079536114aa7c1488a489ee87f')) +paddle.fluid.cpu_places (ArgSpec(args=['device_count'], varargs=None, keywords=None, defaults=(None,)), ('document', 'a7352a3dd39308fde4fbbf6421a4193d')) +paddle.fluid.cuda_pinned_places (ArgSpec(args=['device_count'], varargs=None, keywords=None, defaults=(None,)), ('document', '567ac29567716fd8e7432b533337d529')) paddle.fluid.in_dygraph_mode (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', 'df1f4d1ed7e1eefe04f6361efda6b75a')) paddle.fluid.is_compiled_with_cuda (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', '60c7f107a5050aeb58bb74eb175672b5')) paddle.fluid.Variable ('paddle.fluid.framework.Variable', ('document', '65ff735c2b96673d7131f5ff6b0db40c')) @@ -1058,11 +1058,11 @@ paddle.fluid.LoDTensor.shape shape(self: paddle.fluid.core_avx.Tensor) -> List[i paddle.fluid.LoDTensorArray ('paddle.fluid.core_avx.LoDTensorArray', ('document', 'e9895b67ba54438b9c0f7053e18966f5')) paddle.fluid.LoDTensorArray.__init__ __init__(self: paddle.fluid.core_avx.LoDTensorArray) -> None paddle.fluid.LoDTensorArray.append append(self: paddle.fluid.core_avx.LoDTensorArray, tensor: paddle.fluid.core_avx.LoDTensor) -> None -paddle.fluid.CPUPlace ('paddle.fluid.core_avx.CPUPlace', ('document', '6014005ef2649045b77d502aeb6cd7f9')) +paddle.fluid.CPUPlace ('paddle.fluid.core_avx.CPUPlace', ('document', 'd269ec68ce9b102ab10610e89ffa06e1')) paddle.fluid.CPUPlace.__init__ __init__(self: paddle.fluid.core_avx.CPUPlace) -> None -paddle.fluid.CUDAPlace ('paddle.fluid.core_avx.CUDAPlace', ('document', '6a6cd8ed607beb951692c4b066d08c94')) +paddle.fluid.CUDAPlace ('paddle.fluid.core_avx.CUDAPlace', ('document', 'f862cb3e5596a3920102f1b1238c223b')) paddle.fluid.CUDAPlace.__init__ __init__(self: paddle.fluid.core_avx.CUDAPlace, arg0: int) -> None -paddle.fluid.CUDAPinnedPlace ('paddle.fluid.core_avx.CUDAPinnedPlace', ('document', 'afd58ea5d390b5ea06ca70291a266d45')) +paddle.fluid.CUDAPinnedPlace ('paddle.fluid.core_avx.CUDAPinnedPlace', ('document', '1320ef739c81c95385330dab3fe6e80b')) paddle.fluid.CUDAPinnedPlace.__init__ __init__(self: paddle.fluid.core_avx.CUDAPinnedPlace) -> None paddle.fluid.ParamAttr ('paddle.fluid.param_attr.ParamAttr', ('document', 'a4d4d13ce9eeb86bbaa7ab935c207577')) paddle.fluid.ParamAttr.__init__ (ArgSpec(args=['self', 'name', 'initializer', 'learning_rate', 'regularizer', 'trainable', 'gradient_clip', 'do_model_average'], varargs=None, keywords=None, defaults=(None, None, 1.0, None, True, None, True)), ('document', '6adf97f83acf6453d4a6a4b1070f3754')) diff --git a/paddle/fluid/pybind/pybind.cc b/paddle/fluid/pybind/pybind.cc index ad375aebd0f..88999dcdda7 100644 --- a/paddle/fluid/pybind/pybind.cc +++ b/paddle/fluid/pybind/pybind.cc @@ -832,9 +832,23 @@ All parameter, weight, gradient are variables in Paddle. py::class_(m, "Communicator").def(py::init<>()); #endif py::class_(m, "CUDAPlace", R"DOC( - CUDAPlace is a descriptor of a device. It represents a GPU, and each CUDAPlace - has a dev_id to indicate the number of cards represented by the current CUDAPlace. + **Note**: + For multi-card tasks, please use `FLAGS_selected_gpus` environment variable to set the visible GPU device. + The next version will fix the problem with `CUDA_VISIBLE_DEVICES` environment variable. + + CUDAPlace is a descriptor of a device. + It represents a GPU device allocated or to be allocated with Tensor or LoDTensor. + Each CUDAPlace has a dev_id to indicate the graphics card ID represented by the current CUDAPlace, + staring from 0. The memory of CUDAPlace with different dev_id is not accessible. + Numbering here refers to the logical ID of the visible graphics card, not the actual ID of the graphics card. + You can set visible GPU devices by setting the `CUDA_VISIBLE_DEVICES` environment variable. + When the program starts, visible GPU devices will be numbered from 0. + If `CUDA_VISIBLE_DEVICES` is not set, all devices are visible by default, + and the logical ID is the same as the actual ID. + + Parameters: + id (int): GPU device ID. Examples: .. code-block:: python @@ -892,14 +906,14 @@ All parameter, weight, gradient are variables in Paddle. .def("__str__", string::to_string); py::class_(m, "CPUPlace", R"DOC( - CPUPlace is a descriptor of a device. It represents a CPU, and the memory - CPUPlace can be accessed by CPU. + CPUPlace is a descriptor of a device. + It represents a CPU device allocated or to be allocated with Tensor or LoDTensor. Examples: .. code-block:: python import paddle.fluid as fluid - cpu_place = fluid.CPUPlace() + cpu_place = fluid.CPUPlace()to be allocated )DOC") .def(py::init<>()) @@ -912,8 +926,12 @@ All parameter, weight, gradient are variables in Paddle. .def("__str__", string::to_string); py::class_(m, "CUDAPinnedPlace", R"DOC( - CUDAPinnedPlace is a descriptor of a device. The memory of CUDAPinnedPlace - can be accessed by GPU and CPU. + CUDAPinnedPlace is a descriptor of a device. + It refers to the page locked memory allocated by the CUDA function `cudaHostAlloc()` in the host memory. + The host operating system will not paging and exchanging the memory. + It can be accessed through direct memory access technology to speed up the copy of data between the host and GPU. + For more information on CUDA data transfer and `pinned memory`, + please refer to `official document `_ . Examples: .. code-block:: python diff --git a/python/paddle/fluid/framework.py b/python/paddle/fluid/framework.py index d83d782e855..f0a98d6c451 100644 --- a/python/paddle/fluid/framework.py +++ b/python/paddle/fluid/framework.py @@ -152,25 +152,29 @@ def is_compiled_with_cuda(): def cuda_places(device_ids=None): """ - Create a list of :code:`fluid.CUDAPlace` objects. + **Note**: + For multi-card tasks, please use `FLAGS_selected_gpus` environment variable to set the visible GPU device. + The next version will fix the problem with `CUDA_VISIBLE_DEVICES` environment variable. + + This function creates a list of :code:`fluid.CUDAPlace` objects. If :code:`device_ids` is None, environment variable of - :code:`FLAGS_selected_gpus` would be checked first. If + :code:`FLAGS_selected_gpus` would be checked first. For example, if :code:`FLAGS_selected_gpus=0,1,2`, the returned list would be [fluid.CUDAPlace(0), fluid.CUDAPlace(1), fluid.CUDAPlace(2)]. If :code:`FLAGS_selected_gpus` is not set, all visible - gpu places would be returned. + gpu places would be returned according to the :code:`CUDA_VISIBLE_DEVICES` environment variable. If :code:`device_ids` is not None, it should be the device - ids of gpus. For example, if :code:`device_ids=[0,1,2]`, + ids of GPUs. For example, if :code:`device_ids=[0,1,2]`, the returned list would be [fluid.CUDAPlace(0), fluid.CUDAPlace(1), fluid.CUDAPlace(2)]. - Args: - device_ids (None|list(int)|tuple(int)): gpu device id list. + Parameters: + device_ids (list or tuple of int, optional): list of GPU device ids. Returns: - out (list(fluid.CUDAPlace)): gpu place list. + list of fluid.CUDAPlace: Created GPU place list. Examples: .. code-block:: python @@ -190,18 +194,20 @@ def cuda_places(device_ids=None): def cpu_places(device_count=None): """ - Create a list of :code:`fluid.CPUPlace` objects. + This function creates a list of :code:`fluid.CPUPlace` objects, and returns the created list. If :code:`device_count` is None, the device count would be determined by environment variable :code:`CPU_NUM`. If :code:`CPU_NUM` is not set, the default value is 1, i.e. CPU_NUM=1. + :code:`CPU_NUM` indicates the number of devices used in the current task. + The running of the program can be accelerated if :code:`CPU_NUM` is the same as the number of physical cores. - Args: - device_count (None|int): device number. + Parameters: + device_count (int, optional): device number. Default: None. Returns: - out (list(fluid.CPUPlace)): cpu place list. + list of fluid.CPUPlace: Created list of CPU places. Examples: .. code-block:: python @@ -217,18 +223,20 @@ def cpu_places(device_count=None): def cuda_pinned_places(device_count=None): """ - Create a list of :code:`fluid.CUDAPinnedPlace` objects. + This function creates a list of :code:`fluid.CUDAPinnedPlace` objects. If :code:`device_count` is None, the device count would be determined by environment variable :code:`CPU_NUM`. - If :code:`CPU_NUM` is not set, the device count would - be determined by :code:`multiprocessing.cpu_count()`. + If :code:`CPU_NUM` is not set, the default value is 1, + i.e. CPU_NUM=1. + :code:`CPU_NUM` indicates the number of devices used in the current task. + The running of the program can be accelerated if :code:`CPU_NUM` is the same as the number of physical cores. - Args: - device_count (None|int): device number. + Parameters: + device_count (int, optional): device number. Default: None. Returns: - out (list(fluid.CUDAPinnedPlace)): cuda pinned place list. + list of fluid.CUDAPinnedPlace: Created list of CUDA pinned places. Examples: .. code-block:: python -- GitLab