Skip to content

N
NiuTrans.Tensor
Commit 8e21537a by liyinqiao
Options

Support CMake tool to install NiuTensor. 

1. Offer CMakeLists.txt to compile the NiuTensor.
2. Update the manuals for CMake.
parent 6d137345
正在显示 包含 358 行增加 和 63 行删除
CMakeLists.txt 0 → 100644
# if your visual studio's version is before 2019
# use commond "cmake -A x64 .." to build this project
# or use cmake gui to build VS (remember to select x64)
# if there's some warnings, don't worry about that.
# cmake minimum version
cmake_minimum_required(VERSION 2.8)
# project's name
project(NiuTensor)
# the prefix of the generated executable file
set(NIUTRANS_EXE "NiuTensor")
# generated file path
set(EXECUTABLE_OUTPUT_PATH ../bin)
# 0 - Linux or macOS
# 1 - Windows
set(ON_WINDOWS 0)
# 0 - Not use
# 1 - Use, if set 1, please modify the CUDA_VERSION and CUDA_TOOLKIT_ROOT_DIR below
set(USE_CUDA 0)
if (USE_CUDA)
set(CUDA_VERSION 9.0)
set(CUDA_TOOLKIT_ROOT_DIR "/usr/local/cuda")
endif()
# use CMAKE_MACOSX_RPATH for macOS
set(CMAKE_MACOSX_RPATH 1)
# open floder manage
set_property(GLOBAL PROPERTY USE_FOLDERS On)
add_definitions(-std=c++11)
# find all the .cpp .h .cu .chu files in source folder
file(GLOB_RECURSE CPP_FILES source/*.cpp)
file(GLOB_RECURSE H_FILES source/*.h)
file(GLOB_RECURSE CU_FILES source/*.cu)
file(GLOB_RECURSE CUH_FILES source/*.cuh)
function(assign_source_group)
foreach(_source IN ITEMS ${ARGN})
if (IS_ABSOLUTE "${_source}")
file(RELATIVE_PATH _source_rel "${CMAKE_CURRENT_SOURCE_DIR}" "${_source}")
else()
set(_source_rel "${_source}")
endif()
get_filename_component(_source_path "${_source_rel}" PATH)
string(REPLACE "/" "\\" _source_path_msvc "${_source_path}")
source_group("${_source_path_msvc}" FILES "${_source}")
endforeach()
endfunction(assign_source_group)
function(my_add_executable)
foreach(_source IN ITEMS ${ARGN})
assign_source_group(${_source})
endforeach()
if(USE_CUDA)
cuda_add_executable(${ARGV})
else()
add_executable(${ARGV})
endif()
endfunction(my_add_executable)
if(USE_CUDA)
set(NIUTRANS_EXE "${NIUTRANS_EXE}.GPU")
add_definitions(-DUSE_CUDA)
if(ON_WINDOWS)
find_package(CUDA ${CUDA_VERSION} REQUIRED)
add_compile_options(-Wno-dev)
SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /wd4819")
set(CMAKE_CUDA_FLAGS ${CMAKE_CUDA_FLAGS} "-maxrregcount=0 -m64 --disable-warnings -use_fast_math -DUSE_CUDA")
set(CMAKE_CUDA_FLAGS ${CMAKE_CUDA_FLAGS} -arch=sm_30
-gencode=arch=compute_30,code=sm_30
-gencode=arch=compute_50,code=sm_50
-gencode=arch=compute_52,code=sm_52
-gencode=arch=compute_60,code=sm_60
-gencode=arch=compute_61,code=sm_61
-gencode=arch=compute_62,code=sm_62
-gencode=arch=compute_70,code=sm_70
-gencode=arch=compute_70,code=compute_70
)
set(CMAKE_POLICY_DEFAULT_CMP0028 NEW)
link_directories("${CUDA_TOOLKIT_ROOT_DIR}/lib/x64")
include_directories("${CUDA_TOOLKIT_ROOT_DIR}/include")
set(CUDA_LIB_PATH_ME "${CUDA_TOOLKIT_ROOT_DIR}/lib/x64/")
set(CUDA_LIBS_ME ${CUDA_LIBS_ME} "${CUDA_LIB_PATH_ME}cublas.lib")
set(CUDA_LIBS_ME ${CUDA_LIBS_ME} "${CUDA_LIB_PATH_ME}npps.lib")
set(CUDA_LIBS_ME ${CUDA_LIBS_ME} "${CUDA_LIB_PATH_ME}nppc.lib")
set(CUDA_LIBS_ME ${CUDA_LIBS_ME} "${CUDA_LIB_PATH_ME}cudadevrt.lib")
set(CUDA_LIBS_ME ${CUDA_LIBS_ME} "${CUDA_LIB_PATH_ME}curand.lib")
my_add_executable(${NIUTRANS_EXE} ${CPP_FILES} ${H_FILES} ${CU_FILES} ${CUH_FILES})
else()
find_package(CUDA ${CUDA_VERSION} REQUIRED)
set(CMAKE_CXX_FLAGS "-fPIC -msse4.2 -w -march=native -Wno-enum-compare -Wno-sign-compare -Wno-format -Wno-dev -O3 -DNDEBUG -rdynamic")
set(CUDA_NVCC_FLAGS "-Xcompiler -fPIC -maxrregcount=0 --disable-warnings -use_fast_math -DUSE_CUDA -Wno-deprecated-gpu-targets -std=c++11")
set(CUDA_NVCC_FLAGS ${CUDA_NVCC_FLAGS} -arch=sm_30
-gencode=arch=compute_30,code=sm_30
-gencode=arch=compute_50,code=sm_50
-gencode=arch=compute_52,code=sm_52
-gencode=arch=compute_60,code=sm_60
-gencode=arch=compute_61,code=sm_61
-gencode=arch=compute_62,code=sm_62
-gencode=arch=compute_70,code=sm_70
-gencode=arch=compute_70,code=compute_70
)
link_directories(${CUDA_TOOLKIT_ROOT_DIR}/lib64)
include_directories(${CUDA_TOOLKIT_ROOT_DIR}/include)
set(CUDA_LIB_PATH_ME "${CUDA_TOOLKIT_ROOT_DIR}/lib64/")
set(CUDA_LIBS_ME ${CUDA_LIBS_ME} "${CUDA_LIB_PATH_ME}libcublas_static.a")
set(CUDA_LIBS_ME ${CUDA_LIBS_ME} "${CUDA_LIB_PATH_ME}libculibos.a")
set(CUDA_LIBS_ME ${CUDA_LIBS_ME} "${CUDA_LIB_PATH_ME}libnpps_static.a")
set(CUDA_LIBS_ME ${CUDA_LIBS_ME} "${CUDA_LIB_PATH_ME}libnppc_static.a")
set(CUDA_LIBS_ME ${CUDA_LIBS_ME} "${CUDA_LIB_PATH_ME}libcudadevrt.a")
set(CUDA_LIBS_ME ${CUDA_LIBS_ME} "${CUDA_LIB_PATH_ME}libcurand_static.a")
set(CUDA_LIBS_ME ${CUDA_LIBS_ME} "/usr/lib64/libdl.so.2")
my_add_executable(${NIUTRANS_EXE} ${CPP_FILES} ${H_FILES} ${CU_FILES} ${CUH_FILES})
endif()
else()
set(NIUTRANS_EXE "${NIUTRANS_EXE}.CPU")
my_add_executable(${NIUTRANS_EXE} ${CPP_FILES} ${H_FILES})
endif()
set(CUDA_LIB ${CUDA_LIBS_ME})
if(ON_WINDOWS)
add_definitions(-DWIN32) # for windows specially
if(USE_CUDA)
message(STATUS "On Windows and use cuda")
target_link_libraries(${NIUTRANS_EXE} ${CUDA_LIB})
else()
message(STATUS "On Windows and not use cuda")
target_link_libraries(${NIUTRANS_EXE} ${CUDA_LIB})
endif()
else()
if(USE_CUDA)
message(STATUS "On Linux and use cuda")
target_link_libraries(${NIUTRANS_EXE} ${CUDA_LIB} -lpthread -lcudart -lnvidia-ml)
else()
message(STATUS "On Linux and not use cuda")
target_link_libraries(${NIUTRANS_EXE} ${CUDA_LIB} -lpthread)
endif()
endif()
message(STATUS "name of executable file:" ${NIUTRANS_EXE})
\ No newline at end of file
README.md
...@@ -12,38 +12,142 @@ NiuTensor是小牛开源项目所开发的一个轻量级工具包，提供了 ...@@ -12,38 +12,142 @@ NiuTensor是小牛开源项目所开发的一个轻量级工具包，提供了
## 开发文档 ## 开发文档
更多详细使用方法请见[NiuTensor开发文档](http://niutrans.com/openSource/niutensor/index.html)，包括： 更多详细使用方法请见[NiuTensor开发文档](http://opensource.niutrans.com/niutensor/index.html)，包括：
* 张量计算的调用接口及说明 * 张量计算的调用接口及说明
* 示例程序（如语言模型、机器翻译等） * 示例程序（如语言模型、机器翻译等）
## 安装方法 ## 安装方法
在开始创建您的项目并使用NiuTensor工具包时，需要注意的是： NiuTensor工具包的安装方法目前支持CMake（跨平台：支持Windows、Linux以及macOS）、Visual Studio项目（Windows平台）以及Makefile（Linux以及macOS平台）三种编译方式，这里推荐使用CMake对工具包进行安装。
* 所创建项目如在CPU上运行，我们的系统支持高性能的数学运算库，推荐安装[MKL](https://software.intel.com/en-us/mkl)或[OpenBLAS](http://www.openblas.net/)。 在开始创建您的项目并使用NiuTensor工具包时，需要**注意**的是：
* 所创建项目如在CPU上运行，我们的系统支持高性能的数学运算库，推荐安装[MKL](https://software.intel.com/en-us/mkl)或[OpenBLAS](http://www.openblas.net/)（目前CMake方式不支持MKL和OpenBLAS，如希望使用上述运算库，建议使用Visual Studio或Makefile的方式进行编译，后续CMake将提供对其的完整支持）。
* 所创建项目如需在GPU上运行，需安装 [CUDA](https://developer.nvidia.com/cuda-downloads)，CUDA版本需求为9.0及以上，CUDA工具为创建高性能GPU加速应用程序提供了开发环境。 * 所创建项目如需在GPU上运行，需安装 [CUDA](https://developer.nvidia.com/cuda-downloads)，CUDA版本需求为9.0及以上，CUDA工具为创建高性能GPU加速应用程序提供了开发环境。
小牛开源项目所开发的NiuTensor工具包采用源程序编译方法，在Windows和Linux环境下的安装方法如下所示。 ### 编译文件的修改
小牛开源项目所开发的NiuTensor工具包采用源程序编译方法，除在Windows平台手动配置Visual Studio项目外，CMake以及Makefile两种方式均需要针对不同平台对编译文件进行简单的修改，操作方式如下：
#### CMake
在Windows平台使用CMake生成Visual Studio的项目、在Linux或macOS平台使用CMake配置CLion项目以及使用CMake工具通过命令行的方式进行编译安装均需要对NiuTensor工具包根目录的CMakeLists.txt文件进行少量修改，具体步骤如下：
- 打开CMakeLists.txt文件对其进行编辑。
- 操作系统设置：若NiuTensor编译环境为Windows，则在`set(ON_WINDOWS 0)`中将`ON_WINDOWS`的值置为1；若编译环境为Linux或macOS，则将`ON_WINDOWS`的值置为0。
- 编译设备设置：若希望在CPU环境下编译使用NiuTensor工具包，则将`set(USE_CUDA 0)`中的`USE_CUDA`置为0即可；若希望在GPU环境下使用，则需将`USE_CUDA`置为1，同时在`set(CUDA_VERSION 9.0)`中设置CUDA版本号，在`set(CUDA_TOOLKIT_ROOT_DIR "/usr/local/cuda")`中设置CUDA工具安装的根目录。
#### Makefile
在Linux或macOS平台可以使用Makefile工具通过命令行的方式进行编译安装，这种方式需要对NiuTensor工具包根目录的Makefile文件进行少量修改，具体步骤如下：
- 打开Makefile文件对其进行编辑。
- 操作系统设置：若NiuTensor编译环境为Windows或Linux，则在`OnMac = 0`中将`OnMac`的值置为0；若编译环境为macOS，则将`OnMac`的值置为1。
- 编译设备设置：若希望在CPU环境下编译使用NiuTensor工具包，则将`USE_CUDA = 0`中的`USE_CUDA`置为0即可；若希望在GPU环境下使用，则需将`USE_CUDA`置为1，同时在`CUDA_ROOT = /usr/local/cuda-9.0`中设置CUDA工具安装的根目录。
- 编译内容设置：若希望生成NiuTensor工具包的动态链接库，则将`dll = 0`中的`dll`置为1即可；若无需编译动态链接库，则将其置为0。
### 工具包的安装
在Windows、Linux以及macOS环境下的NiuTensor工具包的安装方法如下。
#### Windows
对于WIndows平台下NiuTensor工具包的使用，这里推荐通过Visual Studio集成开发环境对项目进行管理，项目配置提供CMake自动生成以及手动配置两种方式，开发人员可任选其一。
##### CMake方式（Visual Studio）
对于WIndows平台的NiuTensor工具包安装，这里可以使用CMake工具自动生成Visual Studio项目（需要用户提前安装CMake工具以及Visual Studio集成开发环境），操作步骤如下：
- 参考前述”编译文件的修改“章节，根据系统自身情况对工具包根目录中的CMakeLists.txt文件进行修改。
- 在工具包根目录新建目录以保存生成的Visual Studio项目文件（如建立build目录）。
- 在项目根目录打开Windows平台的命令行工具（如PowerShell），执行`cd build`命令进入新建的build目录。
- 执行`cmake ..`命令对Visual Studio项目进行生成（如果 visual studio 版本低于 2019，则使用命令`cmake -A x64 ..`），执行成功将显示`Build files have been written to:...`。
- 打开build目录中的NiuTensor.sln文件即可通过Visual Studio打开NiuTensor项目。
- 打开后在解决方案管理器中选中NiuTensor.CPU或NiuTensor.GPU，右键将其设为启动项目即可开始使用。
##### 手动配置方式
同时我们也支持用户根据自身项目需求对Visual Studio项目进行手动配置，在手动配置Visual Studio项目的过程中，一些必须的环境配置方法请参考 [通过Visual Studio手动配置NiuTensor项目](https://github.com/NiuTrans/NiuTensor/blob/master/doc/Configuration.md)。
#### Linux和macOS
对于Linux和macOS平台下NiuTensor工具包的使用，这里提供三种使用方式进行项目管理，分别为基于CMake的CLion集成开发环境、CMake工具（命令行）以及Makefile（命令行）的方式，开发人员可任选其一。
### Windows ##### CMake方式（CLion）
若在Windows上使用NiuTensor工具包： 对于Linux或macOS平台的NiuTensor工具包安装，CLion集成开发环境可以通过对CMakeLists.txt文件进行解析自动获取项目信息（需要用户提前安装CMake工具以及CLion集成开发环境），操作步骤如下：
- 参考前述”编译文件的修改“章节，根据系统自身情况对工具包根目录中的CMakeLists.txt文件进行修改。
- 使用CLion打开NiuTensor项目所在目录即可正常使用（确保CMakeLists.txt在其根目录位置），CLion将根据CMakeLists.txt文件自动读取项目信息。
##### CMake方式（命令行）
若仅需通过命令行方式对项目进行管理，开发者同样可以使用CMake快速对NiuTensor项目进行编译安装（需要用户提前安装CMake工具），操作步骤如下：
- 参考前述”编译文件的修改“章节，根据系统自身情况对工具包根目录中的CMakeLists.txt文件进行修改。
- 在项目根目录打开Linux或macOS平台的命令行工具（如Terminal），在工具包内新建目录以保存生成的中间文件（如执行`mkdir build`建立build目录）。
- 执行`cd build`命令进入新建的build目录。
- 执行`cmake ..`命令对项目进行生成，执行成功将显示`Build files have been written to:...`并在该目录下生成Makefile文件。
- 执行`make`命令对NiuTensor项目进行编译，执行成功将显示`Built target NiuTensor.CPU`或`Built target NiuTensor.GPU`，安装完毕。
完成安装后将在bin目录下生成NiuTensor.CPU或NiuTensor.GPU。
##### Makefile方式（命令行）
除CMake方式外，NiuTensor开源工具包同样提供直接通过Makefile对项目进行编译安装的方式，操作步骤如下：
- 参考前述”编译文件的修改“章节，根据系统自身情况对工具包根目录中的Makefile文件进行修改。
- 在项目根目录打开Linux或macOS平台的命令行工具（如Terminal）。
- 执行`make`命令对NiuTensor项目进行编译，执行成功将显示`Building executable file: ./bin/NiuTensor.CPU`或`Building executable file: ./bin/NiuTensor.GPU`，安装完毕。
完成安装后将在bin目录下生成NiuTensor.CPU或NiuTensor.GPU，或在lib目录下生成相应的动态链接库。
环境配置完成后，以CPU为例，可以使用`NiuTensor.CPU -test`命令运行本项目的测试用例，如果最后输出
```shell
OK! Everything is good!
```
则说明本项目配置成功。
>注意：
>
>1. 若先生成CPU的可执行文件，之后如需生成GPU可执行文件，需要先执行make clean命令，删除生成CPU时产生的中间结果，反之亦然。
>2. 在执行make命令时，可以使用-j参数来指定编译过程中使用的线程数量，该操作将显著加快编译速度，如：`make -j8`。
### 将工具包嵌入到自己的项目中
若希望在自己的项目中使用NiuTensor工具包，这里建议将工具包编译为动态链接库进行使用，编译库的方式可以参考前文所述（目前版本仅支持通过Makefile的方式生成Linux下的动态链接库，CMake方式以及更多的平台将在后续进行支持），而对于库文件的使用规则如下：
* 首先需要将NiuTensor代码包含在所创建的项目中
* 在所创建项目中需要引用XTensor.h、core里的CHeader.h和function里的FHeader.h这三个头文件： * 在所创建项目中需要引用XTensor.h、core里的CHeader.h和function里的FHeader.h这三个头文件：
* 通过XTensor.h可以获取我们需要操作的XTensor类 * 通过XTensor.h可以获取我们需要操作的XTensor类。
* 通过core里的CHeader.h可以对Tensor进行一些张量运算 * 通过core里的CHeader.h可以对Tensor进行一些张量运算。
* 通过function里的FHeader.h可以调用一些激活函数 * 通过function里的FHeader.h可以调用一些激活函数。
* 在所创建项目中使用命名空间nts * 在所创建项目中使用命名空间nts。
编译过程以编译好的CPU的动态链接库为例，假设动态链接库所在的路径为当前目录的lib目录，则通过以下命令可以编译生成可执行文件：
```shell
g++ -o MyTest Main.cpp -L./lib -lNiuTensor.CPU -std=c++11
```
然后将lib目录加入到环境变量中，可以通过以下命令进行临时修改（退出shell后则失效）：
```shell
export LD_LIBRARY_PATH=./lib:$LD_LIBRARY_PATH
```
此外，一些必须的环境配置方法请参考 [NiuTensor环境配置](https://github.com/NiuTrans/NiuTensor/blob/master/doc/Configuration.md)。 或者将上述命令加入到~/.bashrc配置文件中进行永久修改（需要将相对路径./lib转换为绝对路径），并执行以下这条命令使修改立即生效：
### Linux ```shell
source ~/.bashrc
```
若在Linux上使用NiuTensor工具包，直接执行make即可在bin目录下生成NiuTensor.CPU或NiuTensor.GPU，分别对应于NiuTensor的CPU以及GPU的可执行文件，同时在lib目录下生成相应的动态链接库。以测试为例，输入以下命令即可在GPU上执行提供的测试用例： 之后就可以运行MyTest可执行文件。
>./bin/NiuTensor.GPU -test
注意：若先生成CPU的可执行文件，之后如需生成GPU可执行文件，需要先执行make clean命令，删除生成CPU时产生的中间结果 ```shell
./MyTest
```
## 开发团队 ## 开发团队
...@@ -52,4 +156,4 @@ NiuTensor张量计算库由东北大学自然语言处理实验室小牛开源 ...@@ -52,4 +156,4 @@ NiuTensor张量计算库由东北大学自然语言处理实验室小牛开源
## 更新版本 ## 更新版本
NiuTensor version 0.1.1 - 2019年11月3日 NiuTensor version 0.2.1 - 2020年3月28日
doc/Configuration.md
# NiuTensor # 通过Visual Studio手动配置NiuTensor项目
## Windows系统通过Visual Studio配置NiuTensor项目 ## 注意事项
### 注意事项
* 我们仅仅测试了VS2015和CUDA9.0之后的版本，对于之前的版本并不清楚是否存在问题。 * 我们仅仅测试了VS2015和CUDA9.0之后的版本，对于之前的版本并不清楚是否存在问题。
* VS2015版本可以直接使用，使用较新版本的VS（如VS2017）时，需要**安装组件“适用于桌面的 VC++ 2015.3 v14.00 (v140) 工具集”**。 * VS2015版本可以直接使用，使用较新版本的VS（如VS2017）时，需要**安装组件“适用于桌面的 VC++ 2015.3 v14.00 (v140) 工具集”**。
...@@ -15,14 +13,14 @@ ...@@ -15,14 +13,14 @@
> C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\v140\BuildCustomizations > C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\v140\BuildCustomizations
> C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE\VC\VCTargets\BuildCustomizations > C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\Common7\IDE\VC\VCTargets\BuildCustomizations
### 新建项目 ## 新建项目
* 新建一个VC++空项目。 * 新建一个VC++空项目。
* 将菜单栏中的**解决方案平台**设置为×64（默认是X86）。 * 将菜单栏中的**解决方案平台**设置为×64（默认是X86）。
* 在**菜单栏->项目->属性**中，将平台设置为X64。 * 在**菜单栏->项目->属性**中，将平台设置为X64。
* 将源代码(source文件夹)拷贝到项目的根目录，然后选择**菜单栏->项目->显示所有文件**，解决方案中即可以看到source文件夹，右键点击source，选择包含在项目中，即可将所有的*.h和*.cpp加入到本项目中。 * 将源代码(source文件夹)拷贝到项目的根目录，然后选择**菜单栏->项目->显示所有文件**，解决方案中即可以看到source文件夹，右键点击source，选择包含在项目中，即可将所有的*.h和*.cpp加入到本项目中。
### CUDA配置（无GPU设备可以跳过此步骤） ## CUDA配置（无GPU设备可以跳过此步骤）
在VS项目中使用CUDA，需要设置项目的相关属性。 在VS项目中使用CUDA，需要设置项目的相关属性。
以下配置选项在 **菜单栏->项目 -> 属性** 中可以找到。 以下配置选项在 **菜单栏->项目 -> 属性** 中可以找到。
...@@ -46,7 +44,7 @@ ...@@ -46,7 +44,7 @@
* 上述配置完成后，在**菜单栏->项目->生成自定义**中，勾选CUDA*（根据自己安装的CUDA版本自行选择）。 * 上述配置完成后，在**菜单栏->项目->生成自定义**中，勾选CUDA*（根据自己安装的CUDA版本自行选择）。
* 在所有的*.cu和*.cuh文件上右键，包含在项目中。 * 在所有的*.cu和*.cuh文件上右键，包含在项目中。
### 其他配置 ## 其他配置
注：以下选项也是 **菜单栏-项目 -> 属性** 中可以找到。 注：以下选项也是 **菜单栏-项目 -> 属性** 中可以找到。
......
doc/manual.md
...@@ -11,71 +11,117 @@ NiuTensor是小牛开源项目所开发的一个工具包，提供了完整的 ...@@ -11,71 +11,117 @@ NiuTensor是小牛开源项目所开发的一个工具包，提供了完整的
## 安装NiuTensor ## 安装NiuTensor
NiuTensor工具包的安装方法目前支持CMake（跨平台：支持Windows、Linux以及macOS）、Visual Studio项目（Windows平台）以及Makefile（Linux以及macOS平台）三种编译方式，这里推荐使用CMake对工具包进行安装。
在开始创建您的项目并使用NiuTensor工具包时，需要**注意**的是： 在开始创建您的项目并使用NiuTensor工具包时，需要**注意**的是：
* 所创建项目如在CPU上运行，我们的系统支持高性能的数学运算库，推荐安装[Intel® MKL](https://software.intel.com/en-us/mkl)或[OpenBLAS](http://www.openblas.net/)。 * 所创建项目如在CPU上运行，我们的系统支持高性能的数学运算库，推荐安装[MKL](https://software.intel.com/en-us/mkl)或[OpenBLAS](http://www.openblas.net/)（目前CMake方式不支持MKL和OpenBLAS，如希望使用上述运算库，建议使用Visual Studio或Makefile的方式进行编译，后续CMake将提供对其的完整支持）。
* 所创建项目如需在GPU上运行，需安装 [NVIDIA®CUDA®Toolkit](https://developer.nvidia.com/cuda-downloads)，CUDA版本需求为9.0及以上，CUDA工具为创建高性能GPU加速应用程序提供了开发环境。 * 所创建项目如需在GPU上运行，需安装 [CUDA](https://developer.nvidia.com/cuda-downloads)，CUDA版本需求为9.0及以上，CUDA工具为创建高性能GPU加速应用程序提供了开发环境。
小牛开源项目所开发的NiuTensor工具包采用源程序编译方法，在Windows和Linux环境下的安装方法如下所示。 ### 编译文件的修改
### Windows 小牛开源项目所开发的NiuTensor工具包采用源程序编译方法，除在Windows平台手动配置Visual Studio项目外，CMake以及Makefile两种方式均需要针对不同平台对编译文件进行简单的修改，操作方式如下：
若在Windows上使用NiuTensor工具包，需要安装Visual Studio集成开发工具，具体的环境配置方法请参考[NiuTensor环境配置](https://github.com/NiuTrans/NiuTensor/blob/master/doc/Configuration.md)。 #### CMake
环境配置完成后，可以使用 **-test** 命令行参数运行本项目的测试用例，如果最后输出 在Windows平台使用CMake生成Visual Studio的项目、在Linux或macOS平台使用CMake配置CLion项目以及使用CMake工具通过命令行的方式进行编译安装均需要对NiuTensor工具包根目录的CMakeLists.txt文件进行少量修改，具体步骤如下：
```shell - 打开CMakeLists.txt文件对其进行编辑。
OK! Everything is good! - 操作系统设置：若NiuTensor编译环境为Windows，则在`set(ON_WINDOWS 0)`中将`ON_WINDOWS`的值置为1；若编译环境为Linux或macOS，则将`ON_WINDOWS`的值置为0。
``` - 编译设备设置：若希望在CPU环境下编译使用NiuTensor工具包，则将`set(USE_CUDA 0)`中的`USE_CUDA`置为0即可；若希望在GPU环境下使用，则需将`USE_CUDA`置为1，同时在`set(CUDA_VERSION 9.0)`中设置CUDA版本号，在`set(CUDA_TOOLKIT_ROOT_DIR "/usr/local/cuda")`中设置CUDA工具安装的根目录。
则说明本项目配置成功。 #### Makefile
<!-- * 首先需要将NiuTensor代码包含在所创建的项目中 在Linux或macOS平台可以使用Makefile工具通过命令行的方式进行编译安装，这种方式需要对NiuTensor工具包根目录的Makefile文件进行少量修改，具体步骤如下：
* 在所创建项目中需要引用XTensor.h、core里的CHeader.h和function里的FHeader.h这三个头文件：
* 通过XTensor.h可以获取我们需要操作的XTensor类
* 通过core里的CHeader.h可以对Tensor进行一些张量运算
* 通过function里的FHeader.h可以调用一些激活函数
* 在所创建项目中使用命名空间nts -->
### Linux - 打开Makefile文件对其进行编辑。
- 操作系统设置：若NiuTensor编译环境为Windows或Linux，则在`OnMac = 0`中将`OnMac`的值置为0；若编译环境为macOS，则将`OnMac`的值置为1。
- 编译设备设置：若希望在CPU环境下编译使用NiuTensor工具包，则将`USE_CUDA = 0`中的`USE_CUDA`置为0即可；若希望在GPU环境下使用，则需将`USE_CUDA`置为1，同时在`CUDA_ROOT = /usr/local/cuda-9.0`中设置CUDA工具安装的根目录。
- 编译内容设置：若希望生成NiuTensor工具包的动态链接库，则将`dll = 0`中的`dll`置为1即可；若无需编译动态链接库，则将其置为0。
若在Linux上使用NiuTensor工具包，请使用[Makefile](https://github.com/NiuTrans/NiuTensor/blob/master/Makefile)文件。 ### 工具包的安装
Makefile默认执行CPU编译，如果想要执行GPU编译，需要将Makefile文件第19行修改为 **USE_CUDA = 1**，并在第21行中修改 **CUDA_ROOT** 项来指定CUDA所在的路径。
之后，在Makefile文件所在目录执行 **make** 命令，即可在当前目录的bin目录下中生成NiuTensor.CPU或NiuTensor.GPU，分别对应于NiuTensor工具包的CPU以及GPU的可执行文件。 在Windows、Linux以及macOS环境下的NiuTensor工具包的安装方法如下。
如果用户想要生成NiuTensor工具包的动态链接库，则将Makefile文件中第11行修改为 **dll = 1**，执行 **make** 命令后，即可在当前目录的lib目录下生成相应的动态链接库libNiuTensor.CPU.so或libNiuTensor.GPU.so。 #### Windows
> **注意**：若执行CPU环境下的编译后，想要重新在GPU环境下编译，则需要先执行make clean命令，删除CPU编译时产生的中间结果，反之亦然。 对于WIndows平台下NiuTensor工具包的使用，这里推荐通过Visual Studio集成开发环境对项目进行管理，项目配置提供CMake自动生成以及手动配置两种方式，开发人员可任选其一。
在执行make命令时，可以使用-j参数来进行并行编译，可以显著加快编译速度，如 ##### CMake方式（Visual Studio）
```shell 对于WIndows平台的NiuTensor工具包安装，这里可以使用CMake工具自动生成Visual Studio项目（需要用户提前安装CMake工具以及Visual Studio集成开发环境），操作步骤如下：
make -j8
```
输入以下命令即可执行提供的测试用例： - 参考前述”编译文件的修改“章节，根据系统自身情况对工具包根目录中的CMakeLists.txt文件进行修改。
- 在工具包根目录新建目录以保存生成的Visual Studio项目文件（如建立build目录）。
- 在项目根目录打开Windows平台的命令行工具（如PowerShell），执行`cd build`命令进入新建的build目录。
- 执行`cmake ..`命令对Visual Studio项目进行生成（如果 visual studio 版本低于 2019，则使用命令`cmake -A x64 ..`），执行成功将显示`Build files have been written to:...`。
- 打开build目录中的NiuTensor.sln文件即可通过Visual Studio打开NiuTensor项目。
- 打开后在解决方案管理器中选中NiuTensor.CPU或NiuTensor.GPU，右键将其设为启动项目即可开始使用。
```shell ##### 手动配置方式
./bin/NiuTensor.CPU -test
```
或 同时我们也支持用户根据自身项目需求对Visual Studio项目进行手动配置，在手动配置Visual Studio项目的过程中，一些必须的环境配置方法请参考 [通过Visual Studio手动配置NiuTensor项目](https://github.com/NiuTrans/NiuTensor/blob/master/doc/Configuration.md)。
```shell
./bin/NiuTensor.GPU -test #### Linux和macOS
```
对于Linux和macOS平台下NiuTensor工具包的使用，这里提供三种使用方式进行项目管理，分别为基于CMake的CLion集成开发环境、CMake工具（命令行）以及Makefile（命令行）的方式，开发人员可任选其一。
##### CMake方式（CLion）
对于Linux或macOS平台的NiuTensor工具包安装，CLion集成开发环境可以通过对CMakeLists.txt文件进行解析自动获取项目信息（需要用户提前安装CMake工具以及CLion集成开发环境），操作步骤如下：
- 参考前述”编译文件的修改“章节，根据系统自身情况对工具包根目录中的CMakeLists.txt文件进行修改。
- 使用CLion打开NiuTensor项目所在目录即可正常使用（确保CMakeLists.txt在其根目录位置），CLion将根据CMakeLists.txt文件自动读取项目信息。
##### CMake方式（命令行）
若仅需通过命令行方式对项目进行管理，开发者同样可以使用CMake快速对NiuTensor项目进行编译安装（需要用户提前安装CMake工具），操作步骤如下：
- 参考前述”编译文件的修改“章节，根据系统自身情况对工具包根目录中的CMakeLists.txt文件进行修改。
- 在项目根目录打开Linux或macOS平台的命令行工具（如Terminal），在工具包内新建目录以保存生成的中间文件（如执行`mkdir build`建立build目录）。
- 执行`cd build`命令进入新建的build目录。
- 执行`cmake ..`命令对项目进行生成，执行成功将显示`Build files have been written to:...`并在该目录下生成Makefile文件。
- 执行`make`命令对NiuTensor项目进行编译，执行成功将显示`Built target NiuTensor.CPU`或`Built target NiuTensor.GPU`，安装完毕。
完成安装后将在bin目录下生成NiuTensor.CPU或NiuTensor.GPU。
##### Makefile方式（命令行）
除CMake方式外，NiuTensor开源工具包同样提供直接通过Makefile对项目进行编译安装的方式，操作步骤如下：
- 参考前述”编译文件的修改“章节，根据系统自身情况对工具包根目录中的Makefile文件进行修改。
- 在项目根目录打开Linux或macOS平台的命令行工具（如Terminal）。
- 执行`make`命令对NiuTensor项目进行编译，执行成功将显示`Building executable file: ./bin/NiuTensor.CPU`或`Building executable file: ./bin/NiuTensor.GPU`，安装完毕。
完成安装后将在bin目录下生成NiuTensor.CPU或NiuTensor.GPU，或在lib目录下生成相应的动态链接库。
环境配置完成后，以CPU为例，可以使用`NiuTensor.CPU -test`命令运行本项目的测试用例，如果最后输出
如果最后输出
```shell ```shell
OK! Everything is good! OK! Everything is good!
``` ```
则说明编译成功。 则说明本项目配置成功。
>注意：
>
>1. 若先生成CPU的可执行文件，之后如需生成GPU可执行文件，需要先执行make clean命令，删除生成CPU时产生的中间结果，反之亦然。
>2. 在执行make命令时，可以使用-j参数来指定编译过程中使用的线程数量，该操作将显著加快编译速度，如：`make -j8`。
### 将工具包嵌入到自己的项目中
用户也可以选择通过NiuTensor的动态链接库进行编译，以编译好的GPU的动态链接库为例，假设动态链接库所在的路径为当前目录的lib目录，则通过以下命令可以编译生成可执行文件： 若希望在自己的项目中使用NiuTensor工具包，这里建议将工具包编译为动态链接库进行使用，编译库的方式可以参考前文所述（目前版本仅支持通过Makefile的方式生成Linux下的动态链接库，CMake方式以及更多的平台将在后续进行支持），而对于库文件的使用规则如下：
* 在所创建项目中需要引用XTensor.h、core里的CHeader.h和function里的FHeader.h这三个头文件：
* 通过XTensor.h可以获取我们需要操作的XTensor类。
* 通过core里的CHeader.h可以对Tensor进行一些张量运算。
* 通过function里的FHeader.h可以调用一些激活函数。
* 在所创建项目中使用命名空间nts。
编译过程以编译好的CPU的动态链接库为例，假设动态链接库所在的路径为当前目录的lib目录，则通过以下命令可以编译生成可执行文件：
```shell ```shell
g++ -o MyTest Main.cpp -L./lib -lNiuTensor.GPU -std=c++11 g++ -o MyTest Main.cpp -L./lib -lNiuTensor.CPU -std=c++11
``` ```
然后将lib目录加入到环境变量中，可以通过以下命令进行临时修改（退出shell后则失效）： 然后将lib目录加入到环境变量中，可以通过以下命令进行临时修改（退出shell后则失效）：
...@@ -1240,7 +1286,6 @@ NiuTensor/Tensor/test/TCopyValues.cpp ...@@ -1240,7 +1286,6 @@ NiuTensor/Tensor/test/TCopyValues.cpp
沿给定轴 dim ,将输入索引张量 index 指定位置的值进行聚合，一个$2 \times 3$的张量沿着第0维进行聚合的过程如下所示： 沿给定轴 dim ,将输入索引张量 index 指定位置的值进行聚合，一个$2 \times 3$的张量沿着第0维进行聚合的过程如下所示：
$$ $$
\begin{aligned} \begin{aligned}
inputTensor: & \left( inputTensor: & \left(
\begin{matrix}1.0 & 2.0 & 3.0\\4.0 & 5.0 & 6.0\end{matrix}\right)\\ + \begin{matrix}1.0 & 2.0 & 3.0\\4.0 & 5.0 & 6.0\end{matrix}\right)\\ +
......
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑！
请 注册 或者 后发表评论