-
Notifications
You must be signed in to change notification settings - Fork 13
Developer's tutorial
This document is a tutorial for who is going to join ClPy development.
For first developers, we recommend CUDA environment to develop.
Download and install CUDA from this url ( https://developer.nvidia.com/cuda-downloads ). OpenCL is embedded in CUDA. Since the downloading / installing method is written in the link destination, omit it.
Each pass is shown below.
- CUDA:/usr/local/cuda
- OpenCL:/usr/local/cuda/include/CL
If you want use ClPy on non-CUDA environment (e.g. AMD GPUs), install the OpenCL SDK.
Don't forget apt install opencl-headers for amdgpu-pro.
Because you are recommended specific version of Python by ClPy and CuPy, it is convenient to be able to use any version of Python. To use any version of Python, introduce pyenv.
And you should handle environments of CuPy and ClPy in the same machine. You can use pyenv-virtualenv plugins for such purpose.
There are two steps to introducing pyenv and pyenv-virtualenv.
The first step is to clone pyenv and pyenv-virtualenv from github.
$ git clone git://github.com/pyenv/pyenv.git ~/.pyenv
$ git clone https://github.com/pyenv/pyenv-virtualenv.git ~/.pyenv/plugins/pyenv-virtualenvThe second step is to edit bash_profile to pass the pyenv and pyenv-virtualenv path.You should set following environment variables.
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"You should execute the following command to apply the change of bash_profile.
source ~/.bash_profile
Then the pyenv command is available.
Since Python version recommended for ClPy is 3.6.5, use Python 3.6.5. You can use Python 3.6.5 by executing the following commands. (Note: Check and install Python dependencies if it's the first time on your machine)
$ pyenv install 3.6.5Now, you can create virtual environment by following command
$ pyenv virtualenv 3.6.5 Name'Name' is an appropriate name indicating usage.
$ pyenv versionsTo work in the created virtual environment Name, execute the following command.
$ pyenv shell NameWith the above operation, it is now possible to create multiple environments with any version of Python.
(Skip this section if you use non-CUDA environment)
Before try ClPy, we recommend to learn how to use with CuPy.
CuPy is a NumPy-compatible matrix library accelerated by CUDA. Therefore, Python is necessary to use CuPy.
Introducing CuPy and Chainer in virtual environment. Both CuPy and Chainer can install from pip. Install with the following commands.
- Since NumPy is required to use CuPy, install NumPy as well.
- CuPy is suited to the version of CUDA used on the machine, since CUDA 9.2 is used in titanv (the machine used to write this guide), install cupy-cuda92.
- As it is recommended to use 3.3.0 for Chainer version in ClPy, make sure to install 3.3.0 instead of the latest version of Chainer.
$ pyenv virtualenv cupy
$ pyenv local cupy
$ pip install numpy
$ pip install cupy
$ pip install chainer==3.3.0To run Chainer's MNIST example, get the MNIST program. For that, clone Chainer from github. Clone with the following command.
- As it is recommended to use 3.3.0 for Chainer version in ClPy, clone 3.3.0 instead of the latest version of Chainer.
$ git clone -b v3.3.0 https://github.com/chainer/chainer.git
$ cd chainer
$ pyenv local cupyNext, enter the Chainer repository and run MNIST example. MNIST exists in /path/to/chainer/examples/mnist. MNIST can be executed by moving to the above directory and then inputting the following command.
- -g: An option to decide which GPU to run. The default is -1.
python train_mnist.py -g 0
Note: Without the option -g 0, the kernels will run on CPUs. You might want to double check this option when you get an execution time different from usual.
Here's a warning from the program that " matplotlib is not installed on your environment, so nothing will be plotted at this time. Please install matplotlib to plot figures.", so installing matplotlib (done with the following command) and running the program again may cause another error. In that case, you can attach the --noplot option.
pip install matplotlib
With the --noplot option
python train_mnist.py -g 0 --noplot
ClPy requires OpenCL, LLVM/Clang and CLBlast. Therefore, install these three at the beginning.
Since OpenCL is embedded in CUDA, you only need to set following environment variables to bash_profile.
export C_INCLUDE_PATH=/usr/local/cuda/include:${C_INCLUDE_PATH}
export CPLUS_INCLUDE_PATH=/usr/local/cuda/include:${CPLUS_INCLUDE_PATH}
export LIBRARY_PATH=/usr/local/cuda/lib64:${LIBRARY_PATH}
Followings are for amdgpu-pro:
# No need for include path if you install cl.h by "apt install opencl-headers"
export LIBRARY_PATH=${LIBRARY_PATH}:/opt/amdgpu-pro/lib/x86_64-linux-gnu/
You can install one from source, or if you are a user of titanv server, use the already built binaries.
Either way, please set the envs in ~/.bash_profile referencing README's instrucion and following your install path.
As of 20 Sep 2019, titanv has a v7.1.0 build in /opt/clpy/llvm-7.1.0/.
CLBlast is not installed, so you need to install it. It is recommended to use CLBlast version 1.4.1 or later with ClPy. This time use version 1.4.1.
Obtain CLBlast from url (https://github.com/CNugteren/CLBlast/releases/tag/1.4.1). Download Source code (tar.gz).
Extract the obtained file and move it to the appropriate directory. Move to file (CLBlast - 1.4.1). In order to be able to use CLBlast, do the following command.
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make
You might need -DOPENCL_LIBRARIES=/opt/amdgpu-pro/lib/x86_64-linux-gnu/libOpenCL.so on cmake in amdgpu-pro environment.
Then the program appears in the build directory. Set following environment variables to bash_profile so that CLBlast can be used with ClPy.
export CLBLAST=/path/to/CLBlast-1.4.1
export C_INCLUDE_PATH=${CLBLAST}/include:${C_INCLUDE_PATH}
export CPLUS_INCLUDE_PATH=${CLBLAST}/include:${CPLUS_INCLUDE_PATH}
export LIBRARY_PATH=${CLBLAST}/build:${LIBRARY_PATH}
export LD_LIBRARY_PATH=${CLBLAST}/build:${LD_LIBRARY_PATH}
Execute the following command to apply the above bash_profile changes.
source ~/.bash_profile
Next, create a virtual environment for ClPy. You can create it just as you did when creating the virtual environment 'Name'. Subsequently, introduction of ClPy is started. First, clone ClPy from github. Use the following command.
git clone https://github.com/fixstars/clpy.git
After clone, move to the clpy directory. Since NumPy and Cython are necessary, install with pip.
pip install numpy
pip install cython
After that, you can install ClPy by executing the following command in the clpy directory.
python setup.py install
When ClPy installation is completed successfully, do a simple test. Since pytest is necessary for testing, install with pip.
pip install pytest
Since there are multiple test programs in the clpy directory, you can execute the test you wish to perform with the following command.
cd /path/to/clpy/tests/you/want
python -m pytest test_you_want.py
The execution result of each test is displayed in https://github.com/fixstars/clpy/wiki/cupy_test_example_results.
Chainer can install from pip. Install with the following command.
pip install chainer==3.3.0
Move to chainer directory. At this time, the virtual environment is for ClPy. Move to the directory where MNIST is located (/path/to/chainer/examples/mnist). After moving to the above directory, you can run MNIST with ClPy by entering the following command.
- -m clpy: Change CuPy to ClPy
python -m clpy train_mnist.py -g 0
With this, MNIST can be executed with ClPy. Likewise, various programs written with CuPy can be executed with ClPy
( https://github.com/fixstars/clpy/wiki/chainer_test_example_results#example ).