[docs] document CUDA version support (#3428)

* document CUDA version support

* address review comments

* collapse CUDA section in the guide

* remove Clang support from CUDA docs as we have never tested it

docs/Installation-Guide.rst

@@ -558,6 +558,35 @@ Docker
 
 Refer to `GPU Docker folder <https://github.com/microsoft/LightGBM/tree/master/docker/gpu>`__.
 
+Build CUDA Version (Experimental)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The `original GPU build <#build-gpu-version>`__ of LightGBM is based on OpenCL.
+
+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.
+
+Linux
+^^^^^
+
+On Linux a CUDA version of LightGBM can be built using **CUDA**, **CMake** and **gcc**.
+
+The following dependencies should be installed before compilation:
+
+-  **CUDA** libraries. Please refer to `this detailed guide`_.
+
+-  **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
 ~~~~~~~~~~~~~~~~~~
 
@@ -755,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

docs/Parameters.rst

@@ -1176,7 +1176,9 @@ GPU Parameters
 
 -  ``gpu_use_dp`` :raw-html:`<a id="gpu_use_dp" title="Permalink to this parameter" href="#gpu_use_dp">&#x1F517;&#xFE0E;</a>`, 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 currently supported
 
 -  ``num_gpu`` :raw-html:`<a id="num_gpu" title="Permalink to this parameter" href="#num_gpu">&#x1F517;&#xFE0E;</a>`, default = ``1``, type = int, constraints: ``num_gpu > 0``
 

docs/_static/js/script.js

@@ -6,7 +6,7 @@ $(function() {
     if(window.location.pathname.toLocaleLowerCase().indexOf('installation-guide') != -1) {
         $('<style>.closed, .opened {cursor: pointer;} .closed:before, .opened:before {font-family: FontAwesome; display: inline-block; padding-right: 6px;} .closed:before {content: "\\f078";} .opened:before {content: "\\f077";}</style>').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)';

include/LightGBM/config.h

@@ -997,7 +997,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 currently supported
   bool gpu_use_dp = false;
 
   // check = >0

python-package/README.rst

@@ -110,6 +110,17 @@ All available options:
 
 For more details see `FindBoost <https://cmake.org/cmake/help/latest/module/FindBoost.html>`__ and `FindOpenCL <https://cmake.org/cmake/help/latest/module/FindOpenCL.html>`__.
 
+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 <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-cuda-version-experimental>`__.
+
 Build HDFS Version
 ~~~~~~~~~~~~~~~~~~
 
@@ -177,6 +188,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.

python-package/setup.py

@@ -163,7 +163,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: