From 25d0aa85bcdf57e58bfa085d1a9a34196007f54a Mon Sep 17 00:00:00 2001 From: StrikerRUS Date: Fri, 2 Oct 2020 19:27:31 +0300 Subject: [PATCH 1/4] document CUDA version support --- docs/Installation-Guide.rst | 29 +++++++++++++++++++++++++++++ docs/Parameters.rst | 4 +++- include/LightGBM/config.h | 3 ++- python-package/README.rst | 13 +++++++++++++ python-package/setup.py | 2 +- 5 files changed, 48 insertions(+), 3 deletions(-) diff --git a/docs/Installation-Guide.rst b/docs/Installation-Guide.rst index a0bbf366918c..1d5c7deed0d3 100644 --- a/docs/Installation-Guide.rst +++ b/docs/Installation-Guide.rst @@ -558,6 +558,35 @@ Docker Refer to `GPU Docker folder `__. +Build CUDA Version (Experimental) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The `original GPU version <#build-gpu-version>`__ of LightGBM is based on OpenCL. This version is a separate implementation and requires NVIDIA graphics card with compute capability 6.0 and higher. + +This version is very experimental and we suggest using it only when it is impossible to use OpenCL version, for instance, on IBM POWER microprocessors. + +**Note**: only Linux is supported, other operating systems are not supported yet. + +Linux +^^^^^ + +On Linux a CUDA version of LightGBM can be built using **CUDA**, **CMake** and **gcc** or **Clang**. + +The following dependencies should be installed before compilation: + +- **CUDA** libraries. + +- **CMake** 3.16 or later. + +To build LightGBM CUDA version, run the following commands: + +.. code:: + + git clone --recursive https://github.com/microsoft/LightGBM ; cd LightGBM + mkdir build ; cd build + cmake -DUSE_CUDA=1 .. + make -j4 + Build HDFS Version ~~~~~~~~~~~~~~~~~~ diff --git a/docs/Parameters.rst b/docs/Parameters.rst index 9cfb9413f21e..ef5e68920094 100644 --- a/docs/Parameters.rst +++ b/docs/Parameters.rst @@ -1124,7 +1124,9 @@ GPU Parameters - ``gpu_use_dp`` :raw-html:`🔗︎`, default = ``false``, type = bool - - set this to ``true`` to use double precision math on GPU (by default single precision is used in OpenCL implementation and double precision is used in CUDA implementation) + - set this to ``true`` to use double precision math on GPU (by default single precision is used) + + - **Note**: can be used only in OpenCL implementation, in CUDA implementation only double precision is supported yet - ``num_gpu`` :raw-html:`🔗︎`, default = ``1``, type = int, constraints: ``num_gpu > 0`` diff --git a/include/LightGBM/config.h b/include/LightGBM/config.h index b1e30ff40654..a36ed4553c2e 100644 --- a/include/LightGBM/config.h +++ b/include/LightGBM/config.h @@ -967,7 +967,8 @@ struct Config { // desc = **Note**: refer to `GPU Targets <./GPU-Targets.rst#query-opencl-devices-in-your-system>`__ for more details int gpu_device_id = -1; - // desc = set this to ``true`` to use double precision math on GPU (by default single precision is used in OpenCL implementation and double precision is used in CUDA implementation) + // desc = set this to ``true`` to use double precision math on GPU (by default single precision is used) + // desc = **Note**: can be used only in OpenCL implementation, in CUDA implementation only double precision is supported yet bool gpu_use_dp = false; // check = >0 diff --git a/python-package/README.rst b/python-package/README.rst index 5152e0424de8..e7101a124dbb 100644 --- a/python-package/README.rst +++ b/python-package/README.rst @@ -110,6 +110,17 @@ All available options: For more details see `FindBoost `__ and `FindOpenCL `__. +Build CUDA Version +~~~~~~~~~~~~~~~~~~ + +.. code:: sh + + pip install lightgbm --install-option=--cuda + +All remarks from `Build from Sources section <#build-from-sources>`__ are actual in this case and `CMake`_ (version 3.16 or higher) is strongly required. + +**CUDA** library is needed: details for installation can be found in `Installation Guide `__. + Build HDFS Version ~~~~~~~~~~~~~~~~~~ @@ -166,6 +177,8 @@ Run ``python setup.py install --mingw``, if you want to use **MinGW-w64** on **W Run ``python setup.py install --gpu`` to enable GPU support. All remarks from `Build GPU Version section <#build-gpu-version>`__ are actual in this case. To pass additional options to **CMake** use the following syntax: ``python setup.py install --gpu --opencl-include-dir=/usr/local/cuda/include/``, see `Build GPU Version section <#build-gpu-version>`__ for the complete list of them. +Run ``python setup.py install --cuda`` to enable CUDA support. All remarks from `Build CUDA Version section <#build-cuda-version>`__ are actual in this case. + Run ``python setup.py install --hdfs`` to enable HDFS support. All remarks from `Build HDFS Version section <#build-hdfs-version>`__ are actual in this case. Run ``python setup.py install --bit32``, if you want to use 32-bit version. All remarks from `Build 32-bit Version with 32-bit Python section <#build-32-bit-version-with-32-bit-python>`__ are actual in this case. diff --git a/python-package/setup.py b/python-package/setup.py index 4e3242fe2191..7202c5568fef 100644 --- a/python-package/setup.py +++ b/python-package/setup.py @@ -143,7 +143,7 @@ def compile_cpp(use_mingw=False, use_gpu=False, use_cuda=False, use_mpi=False, else: status = 1 lib_path = os.path.join(CURRENT_DIR, "compile", "windows", "x64", "DLL", "lib_lightgbm.dll") - if not any((use_gpu, use_mpi, use_hdfs, nomp, bit32, integrated_opencl)): + if not any((use_gpu, use_cuda, use_mpi, use_hdfs, nomp, bit32, integrated_opencl)): logger.info("Starting to compile with MSBuild from existing solution file.") platform_toolsets = ("v142", "v141", "v140") for pt in platform_toolsets: From 4a175a9625fe2542abb600bcd6647927157b4dbe Mon Sep 17 00:00:00 2001 From: StrikerRUS Date: Fri, 2 Oct 2020 20:59:14 +0300 Subject: [PATCH 2/4] address review comments --- docs/Installation-Guide.rst | 8 +++++--- docs/Parameters.rst | 2 +- include/LightGBM/config.h | 2 +- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/Installation-Guide.rst b/docs/Installation-Guide.rst index 1d5c7deed0d3..cfcf4907cedf 100644 --- a/docs/Installation-Guide.rst +++ b/docs/Installation-Guide.rst @@ -561,9 +561,9 @@ Refer to `GPU Docker folder `__ of LightGBM is based on OpenCL. This version is a separate implementation and requires NVIDIA graphics card with compute capability 6.0 and higher. +The `original GPU build <#build-gpu-version>`__ of LightGBM is based on OpenCL. -This version is very experimental and we suggest using it only when it is impossible to use OpenCL version, for instance, on IBM POWER microprocessors. +The CUDA-based build is a separate implementation and requires an NVIDIA graphics card with compute capability 6.0 and higher. It should be considered experimental, and we suggest using it only when it is impossible to use OpenCL version (for example, on IBM POWER microprocessors). **Note**: only Linux is supported, other operating systems are not supported yet. @@ -574,7 +574,7 @@ On Linux a CUDA version of LightGBM can be built using **CUDA**, **CMake** and * The following dependencies should be installed before compilation: -- **CUDA** libraries. +- **CUDA** libraries. Please refer to `this detailed guide`_. - **CMake** 3.16 or later. @@ -784,3 +784,5 @@ Also, you may want to read `gcc Tips <./gcc-Tips.rst>`__. .. _Boost Binaries: https://bintray.com/boostorg/release/boost-binaries/_latestVersion#files .. _SWIG: http://www.swig.org/download.html + +.. _this detailed guide: https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html diff --git a/docs/Parameters.rst b/docs/Parameters.rst index ef5e68920094..02fc9977a9d4 100644 --- a/docs/Parameters.rst +++ b/docs/Parameters.rst @@ -1126,7 +1126,7 @@ GPU Parameters - set this to ``true`` to use double precision math on GPU (by default single precision is used) - - **Note**: can be used only in OpenCL implementation, in CUDA implementation only double precision is supported yet + - **Note**: can be used only in OpenCL implementation, in CUDA implementation only double precision is currently supported - ``num_gpu`` :raw-html:`🔗︎`, default = ``1``, type = int, constraints: ``num_gpu > 0`` diff --git a/include/LightGBM/config.h b/include/LightGBM/config.h index a36ed4553c2e..d78a57cc6289 100644 --- a/include/LightGBM/config.h +++ b/include/LightGBM/config.h @@ -968,7 +968,7 @@ struct Config { int gpu_device_id = -1; // desc = set this to ``true`` to use double precision math on GPU (by default single precision is used) - // desc = **Note**: can be used only in OpenCL implementation, in CUDA implementation only double precision is supported yet + // desc = **Note**: can be used only in OpenCL implementation, in CUDA implementation only double precision is currently supported bool gpu_use_dp = false; // check = >0 From c812a5220047f373b9ca41137e9599d7e2a96be8 Mon Sep 17 00:00:00 2001 From: StrikerRUS Date: Thu, 28 Jan 2021 16:08:11 +0300 Subject: [PATCH 3/4] collapse CUDA section in the guide --- docs/_static/js/script.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_static/js/script.js b/docs/_static/js/script.js index 7863eedbc52e..fea43d369993 100644 --- a/docs/_static/js/script.js +++ b/docs/_static/js/script.js @@ -6,7 +6,7 @@ $(function() { if(window.location.pathname.toLocaleLowerCase().indexOf('installation-guide') != -1) { $('').appendTo('body'); var collapsable = ['#build-threadless-version-not-recommended', '#build-mpi-version', '#build-gpu-version', - '#build-hdfs-version', '#build-java-wrapper']; + '#build-cuda-version-experimental', '#build-hdfs-version', '#build-java-wrapper']; $.each(collapsable, function(i, val) { var header = val + ' > :header:first'; var content = val + ' :not(:header:first)'; From cac49eb65fc2a9e1e8743b1e0a36037379eb1f70 Mon Sep 17 00:00:00 2001 From: StrikerRUS Date: Thu, 28 Jan 2021 16:09:35 +0300 Subject: [PATCH 4/4] remove Clang support from CUDA docs as we have never tested it --- docs/Installation-Guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Installation-Guide.rst b/docs/Installation-Guide.rst index 8ae60f6efd8d..e528cec5024a 100644 --- a/docs/Installation-Guide.rst +++ b/docs/Installation-Guide.rst @@ -570,7 +570,7 @@ The CUDA-based build is a separate implementation and requires an NVIDIA graphic Linux ^^^^^ -On Linux a CUDA version of LightGBM can be built using **CUDA**, **CMake** and **gcc** or **Clang**. +On Linux a CUDA version of LightGBM can be built using **CUDA**, **CMake** and **gcc**. The following dependencies should be installed before compilation: