Lightgbm Release 3.2.1.99
Total Page:16
File Type:pdf, Size:1020Kb
LightGBM Release 3.2.1.99 Microsoft Corporation Sep 26, 2021 CONTENTS: 1 Installation Guide 3 2 Quick Start 21 3 Python-package Introduction 23 4 Features 29 5 Experiments 37 6 Parameters 43 7 Parameters Tuning 65 8 C API 71 9 Python API 99 10 Distributed Learning Guide 175 11 LightGBM GPU Tutorial 185 12 Advanced Topics 189 13 LightGBM FAQ 191 14 Development Guide 199 15 GPU Tuning Guide and Performance Comparison 201 16 GPU SDK Correspondence and Device Targeting Table 205 17 GPU Windows Compilation 209 18 Recommendations When Using gcc 229 19 Documentation 231 20 Indices and Tables 233 Index 235 i ii LightGBM, Release 3.2.1.99 LightGBM is a gradient boosting framework that uses tree based learning algorithms. It is designed to be distributed and efficient with the following advantages: • Faster training speed and higher efficiency. • Lower memory usage. • Better accuracy. • Support of parallel, distributed, and GPU learning. • Capable of handling large-scale data. For more details, please refer to Features. CONTENTS: 1 LightGBM, Release 3.2.1.99 2 CONTENTS: CHAPTER ONE INSTALLATION GUIDE This is a guide for building the LightGBM Command Line Interface (CLI). If you want to build the Python-package or R-package please refer to Python-package and R-package folders respectively. All instructions below are aimed at compiling the 64-bit version of LightGBM. It is worth compiling the 32-bit version only in very rare special cases involving environmental limitations. The 32-bit version is slow and untested, so use it at your own risk and don’t forget to adjust some of the commands below when installing. If you need to build a static library instead of a shared one, you can add -DBUILD_STATIC_LIB=ON to CMake flags. Users who want to perform benchmarking can make LightGBM output time costs for different internal routines by adding -DUSE_TIMETAG=ON to CMake flags. It is possible to build LightGBM in debug mode. In this mode all compiler optimizations are disabled and LightGBM performs more checks internally. To enable debug mode you can add -DUSE_DEBUG=ON to CMake flags or choose Debug_* configuration (e.g. Debug_DLL, Debug_mpi) in Visual Studio depending on how you are building LightGBM. In addition to the debug mode, LightGBM can be built with compiler sanitizers. To enable them add -DUSE_SANITIZER=ON -DENABLED_SANITIZERS="address;leak;undefined" to CMake flags. These values re- fer to the following supported sanitizers: • address - AddressSanitizer (ASan); • leak - LeakSanitizer (LSan); • undefined - UndefinedBehaviorSanitizer (UBSan); • thread - ThreadSanitizer (TSan). Please note, that ThreadSanitizer cannot be used together with other sanitizers. For more info and additional sanitizers’ parameters please refer to the following docs. It is very useful to build C++ unit tests with sanitizers. You can also download the artifacts of the latest successful build on master branch (nightly builds) here:. Contents • Windows • Linux • macOS • Docker • Build Threadless Version (not Recommended) • Build MPI Version • Build GPU Version 3 LightGBM, Release 3.2.1.99 • Build CUDA Version (Experimental) • Build HDFS Version • Build Java Wrapper • Build C++ Unit Tests 1.1 Windows On Windows LightGBM can be built using • Visual Studio; • CMake and VS Build Tools; • CMake and MinGW. 1.1.1 Visual Studio (or VS Build Tools) With GUI 1. Install Visual Studio (2015 or newer). 2. Download zip archive and unzip it. 3. Go to LightGBM-master/windows folder. 4. Open LightGBM.sln file with Visual Studio, choose Release configuration and click BUILD -> Build Solution (Ctrl+Shift+B). If you have errors about Platform Toolset, go to PROJECT -> Properties -> Configuration Properties -> General and select the toolset installed on your machine. The .exe file will be in LightGBM-master/windows/x64/Release folder. From Command Line 1. Install Git for Windows, CMake (3.8 or higher) and VS Build Tools( VS Build Tools is not needed if Visual Studio (2015 or newer) is already installed). 2. Run the following commands: git clone--recursive https://github.com/microsoft/LightGBM cd LightGBM mkdir build cd build cmake-A x64.. cmake--build.--target ALL_BUILD--config Release The .exe and .dll files will be in LightGBM/Release folder. 4 Chapter 1. Installation Guide LightGBM, Release 3.2.1.99 1.1.2 MinGW-w64 1. Install Git for Windows, CMake and MinGW-w64. 2. Run the following commands: git clone--recursive https://github.com/microsoft/LightGBM cd LightGBM mkdir build cd build cmake-G"MinGW Makefiles".. mingw32-make.exe-j4 The .exe and .dll files will be in LightGBM/ folder. Note: You may need to run the cmake -G "MinGW Makefiles" .. one more time if you encounter the sh.exe was found in your PATH error. It is recommended that you use Visual Studio since it has better multithreading efficiency in Windows for many-core systems (see Question 4 and Question 8). Also, you may want to read gcc Tips. 1.2 Linux On Linux LightGBM can be built using CMake and gcc or Clang. 1. Install CMake. 2. Run the following commands: git clone--recursive https://github.com/microsoft/LightGBM cd LightGBM mkdir build cd build cmake.. make-j4 Note: glibc >= 2.14 is required. Note: In some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for lib[g|i]omp for doing this). Also, you may want to read gcc Tips. 1.3 macOS On macOS LightGBM can be installed using Homebrew, or can be built using CMake and Apple Clang or gcc. 1.2. Linux 5 LightGBM, Release 3.2.1.99 1.3.1 Apple Clang Only Apple Clang version 8.1 or higher is supported. Install Using Homebrew brew install lightgbm Build from GitHub 1. Install CMake (3.16 or higher): brew install cmake 2. Install OpenMP: brew install libomp 3. Run the following commands: git clone--recursive https://github.com/microsoft/LightGBM cd LightGBM mkdir build cd build cmake.. make-j4 1.3.2 gcc 1. Install CMake (3.2 or higher): brew install cmake 2. Install gcc: brew install gcc 3. Run the following commands: git clone--recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=g++-7CC=gcc-7 # replace "7" with version of gcc installed on your ,!machine mkdir build cd build cmake.. make-j4 Also, you may want to read gcc Tips. 6 Chapter 1. Installation Guide LightGBM, Release 3.2.1.99 1.4 Docker Refer to Docker folder. 1.5 Build Threadless Version (not Recommended) The default build version of LightGBM is based on OpenMP. You can build LightGBM without OpenMP support but it is strongly not recommended. 1.5.1 Windows On Windows a version of LightGBM without OpenMP support can be built using • Visual Studio; • CMake and VS Build Tools; • CMake and MinGW. Visual Studio (or VS Build Tools) With GUI 1. Install Visual Studio (2015 or newer). 2. Download zip archive and unzip it. 3. Go to LightGBM-master/windows folder. 4. Open LightGBM.sln file with Visual Studio. 5. Go to PROJECT -> Properties -> Configuration Properties -> C/C++ -> Language and change the OpenMP Support property to No (/openmp-). 6. Get back to the project’s main screen, then choose Release configuration and click BUILD -> Build Solution (Ctrl+Shift+B). If you have errors about Platform Toolset, go to PROJECT -> Properties -> Configuration Properties -> General and select the toolset installed on your machine. The .exe file will be in LightGBM-master/windows/x64/Release folder. From Command Line 1. Install Git for Windows, CMake (3.8 or higher) and VS Build Tools( VS Build Tools is not needed if Visual Studio (2015 or newer) is already installed). 2. Run the following commands: git clone--recursive https://github.com/microsoft/LightGBM cd LightGBM mkdir build cd build (continues on next page) 1.4. Docker 7 LightGBM, Release 3.2.1.99 (continued from previous page) cmake-A x64-DUSE_OPENMP=OFF.. cmake--build.--target ALL_BUILD--config Release The .exe and .dll files will be in LightGBM/Release folder. MinGW-w64 1. Install Git for Windows, CMake and MinGW-w64. 2. Run the following commands: git clone--recursive https://github.com/microsoft/LightGBM cd LightGBM mkdir build cd build cmake-G"MinGW Makefiles"-DUSE_OPENMP=OFF.. mingw32-make.exe-j4 The .exe and .dll files will be in LightGBM/ folder. Note: You may need to run the cmake -G "MinGW Makefiles" -DUSE_OPENMP=OFF .. one more time if you encounter the sh.exe was found in your PATH error. 1.5.2 Linux On Linux a version of LightGBM without OpenMP support can be built using CMake and gcc or Clang. 1. Install CMake. 2. Run the following commands: git clone--recursive https://github.com/microsoft/LightGBM cd LightGBM mkdir build cd build cmake-DUSE_OPENMP=OFF.. make-j4 Note: glibc >= 2.14 is required. 1.5.3 macOS On macOS a version of LightGBM without OpenMP support can be built using CMake and Apple Clang or gcc. 8 Chapter 1. Installation Guide LightGBM, Release 3.2.1.99 Apple Clang Only Apple Clang version 8.1 or higher is supported. 1. Install CMake (3.16 or higher): brew install cmake 2. Run the following commands: git clone--recursive https://github.com/microsoft/LightGBM cd LightGBM mkdir build cd build cmake-DUSE_OPENMP=OFF.. make-j4 gcc 1. Install CMake (3.2 or higher): brew install cmake 2. Install gcc: brew install gcc 3. Run the following commands: git clone--recursive https://github.com/microsoft/LightGBM cd LightGBM export CXX=g++-7CC=gcc-7 # replace "7" with version of gcc installed on your ,!machine mkdir build cd build cmake-DUSE_OPENMP=OFF.. make-j4 1.6 Build MPI Version The default build version of LightGBM is based on socket.