Skip to content
This repository was archived by the owner on Jun 13, 2024. It is now read-only.

Commit e9b6fc8

Browse files
gratienjgratienj
authored
Dev aliendoc (#110)
* update sphinx alien documentation with ref semantic and sycl usage * update SYCL documentation * update SYCL documentation * update SYCL documentation
1 parent 53827bd commit e9b6fc8

18 files changed

+814
-7
lines changed

‎README.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,3 +82,33 @@ git subtree split -P arccore -b arccore
8282
cd ../alien
8383
git subtree pull --prefix=framework/arccore --squash ../framework arccore
8484
```
85+
86+
## Documentation generation
87+
88+
You need a python version 3 with sphinx and breathe modules
89+
90+
You can easily create a conda environment as following
91+
92+
```shell script
93+
cd $ALIEN_ROOT/tools/python
94+
conda env create -f alien-env.yml
95+
conda activate alien-env
96+
```
97+
98+
Then the CMAKE OPTIONS has to be activated in the Alien configuration step
99+
100+
```shell script
101+
cmake -S `pwd`/alien \
102+
-B `pwd`/build-alien \
103+
-DALIEN_GENERATE_DOCUMENTATION=ON \
104+
....
105+
106+
make -C `pwd`/build-alien install
107+
make -C `pwd`/build-alien doc_alien
108+
```
109+
110+
The documentation is generated in :
111+
112+
```shell script
113+
firefox `pwd`/build-alien/alien_doc/index.html
114+
```

‎docs/CMakeLists.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ if (ALIEN_GENERATE_DOCUMENTATION)
1313

1414
sphinx_add_docs(
1515
alien_doc
16-
BREATHE_PROJECTS doxygen_api_docs_movesemantic doxygen_api_docs_core_data
16+
BREATHE_PROJECTS doxygen_api_docs_movesemantic doxygen_api_docs_refsemantic doxygen_api_docs_core_data
1717
BUILDER html
1818
SOURCE_DIRECTORY sphinx
1919
OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}/alien_doc"

‎docs/sphinx/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ Welcome to Alien's documentation!
1010
tutorial
1111

1212
developer/index
13+
14+
sycl/index
1315

1416
Indices and tables
1517
==================

‎docs/sphinx/sycl/SYCL.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.. _sycl_SYCL:
2+
3+
=====================
4+
SYCL backend in ALIEN
5+
=====================
6+
7+
Introduction
8+
============
9+
10+
Alien provide a SYCL backend to handle NVidia, AMD and Intel GP-GPUs
11+
12+
It is based on the hipSYCL implementation of the SYCL 2020 API.
13+
14+
It depends on :
15+
16+
- LLVM and Clang
17+
- CUDA 10 to handle NVidia GP-GPUs
18+
- ROCM to handle AMD GP-GPUs
19+
- OneAPI and DPC++ for Intel GP-GPUs
20+
21+
It provides a Block EllPack Matrix implementation and a Linear Algebra with all
22+
the Blas 1 and 2 operations required to implement the CG and BiCGStab krylov algorithms.

‎docs/sphinx/sycl/build.rst

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
.. _sycl_build:
2+
3+
=====================================
4+
Building and using Alien SYCL backend
5+
=====================================
6+
7+
Building Alien SYCL backend
8+
===========================
9+
10+
Alien's build system is based on CMake.
11+
12+
13+
Configuring
14+
-----------
15+
16+
17+
.. code-block:: bash
18+
19+
export GCCCORE='path_to_gccroot_compiler'
20+
cmake -S `pwd`/alien \
21+
-B `pwd`/build-alien \
22+
-DCMAKE_BUILD_TYPE=Release \
23+
-DALIEN_WANT_AVX2=ON \
24+
-DALIEN_USE_LIBXML2=ON \
25+
-DALIEN_UNIT_TESTS=ON \
26+
-DALIEN_USE_HDF5=ON -DHIPSYCL_TARGETS=cuda:sm_50 \
27+
-DALIEN_USE_SYCL=ON \
28+
-DGCCCORE_ROOT:PATH=${GCCXORE_ROOT} \
29+
../alien
30+
cmake --build <build_dir>
31+
cmake --install <build_dir>
32+
33+
34+
Concepts
35+
--------
36+

‎docs/sphinx/sycl/example.rst

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
.. _sycl_example:
2+
3+
=======================================
4+
Exemple : how to use Alien SYCL backend
5+
=======================================
6+
7+
8+
Introduction
9+
------------
10+
11+
This tutorial illustrates how to build vectors and matrices, to apply linear algebra operations
12+
and to solve linear systems with solver supporting the Alien SYCL BackEnd.
13+
14+
15+
Using SYCL Linear Algebra
16+
-------------------------
17+
18+
.. code-block:: bash
19+
20+
/*
21+
* LINEAR SYSTEM CONSTRUCTION
22+
*/
23+
24+
auto A = Alien::Matrix(mdist);
25+
auto B = Alien::Vector(vdist);
26+
auto X = Alien::Vector(vdist);
27+
auto Y = Alien::Vector(vdist);
28+
auto R = Alien::Vector(vdist);
29+
30+
/*
31+
* Create a SYCL LinearAlgebra object
32+
*/
33+
Alien::SYCLLinearAlgebra sycl_alg;
34+
35+
/*
36+
* Apply Blas operation to compute R = B - A*X
37+
*/
38+
sycl_alg.mult(A,X,Y) ;
39+
sycl_alg.copy(B,R)
40+
sycl_alg.axpy(-1,Y,R)
41+
auto residual = sycl_alg.dot(R,R) ;
42+
43+
Linear Systems resolution
44+
-------------------------
45+
46+
.. code-block:: bash
47+
48+
/*
49+
* LINEAR SYSTEM CONSTRUCTION
50+
*/
51+
auto trace_mng = Alien::Universe.traceMng() ;
52+
53+
auto A = Alien::Matrix(mdist);
54+
auto B = Alien::Vector(vdist);
55+
auto X = Alien::Vector(vdist);
56+
57+
/*
58+
* Create a SYCLInternalLinearAlgebra instance
59+
* and get true SYCL Matrix and vectors implementations
60+
*/
61+
typedef Alien::SYCLInternalLinearAlgebra AlgebraType ;
62+
typedef typename AlgebraType::BackEndType BackEndType ;
63+
typedef Alien::Iteration<AlgebraType> StopCriteriaType ;
64+
65+
AlgebraType sycl_alg;
66+
67+
auto const& true_A = A.impl()->get<BackEndType>() ;
68+
auto const& true_b = b.impl()->get<BackEndType>() ;
69+
auto& true_x = x.impl()->get<BackEndType>(true) ;
70+
71+
/*
72+
* Create a CG solver and stop criteria
73+
*/
74+
StopCriteriaType stop_criteria{alg,true_b,tol,max_iteration,output_level>0?trace_mng:nullptr} ;
75+
76+
typedef Alien::CG<AlgebraType> SolverType ;
77+
78+
SolverType solver{alg,trace_mng} ;
79+
solver.setOutputLevel(output_level) ;
80+
81+
/*
82+
*Create a Chebyshev polynomial preconditioner
83+
*/
84+
trace_mng->info()<<"CHEBYSHEV PRECONDITIONER";
85+
double polynom_factor = 0.5 ;
86+
int polynom_order = 3 ;
87+
int polynom_factor_max_iter = 10 ;
88+
89+
typedef Alien::ChebyshevPreconditioner<AlgebraType> PrecondType ;
90+
PrecondType precond{alg,true_A,polynom_factor,polynom_order,polynom_factor_max_iter,trace_mng} ;
91+
precond.init() ;
92+
93+
/*
94+
* Solve the Linear System A*x=B
95+
*/
96+
solver.solve(precond,stop_criteria,true_A,true_b,true_x) ;
97+
98+
/*
99+
* Analyze the solution
100+
*/
101+
if(stop_criteria.getStatus())
102+
{
103+
trace_mng->info()<<"Solver has converged";
104+
trace_mng->info()<<"Nb iterations : "<<stop_criteria();
105+
trace_mng->info()<<"Criteria value : "<<stop_criteria.getValue();
106+
}
107+
else
108+
{
109+
trace_mng->info()<<"Solver convergence failed";
110+
}

‎docs/sphinx/sycl/index.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. _sycl:
2+
3+
Alien SYCL documentation
4+
========================
5+
6+
.. toctree::
7+
:maxdepth: 2
8+
SYCL
9+
install
10+
build
11+
example

‎docs/sphinx/sycl/install.rst

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
.. _sycl_install:
2+
3+
===================
4+
How to install SYCL
5+
===================
6+
7+
Installing SYCL
8+
===============
9+
10+
Alien's build system is based on CMake.
11+
12+
Getting the sources
13+
-------------------
14+
15+
16+
.. code-block:: bash
17+
18+
git clone --recurse-submodules -b stable https://github.com/illuhad/hipSYCL
19+
20+
Configuring
21+
-----------
22+
23+
.. code-block:: bash
24+
25+
export INSTALL_PREFIX=`pwd`/usr/local/gcc102
26+
export HIPSYCL_INSTALL_PREFIX=${INSTALL_PATH}/sycl2020
27+
export HIPSYCL_LLVM_INSTALL_PREFIX=${INSTALL_PATH}
28+
export HIPSYCL_WITH_ROCM=OFF
29+
export CC=${GCCCORE_ROOT}/bin/gcc
30+
export CXX=${GCCCORE_ROOT}/bin/g++
31+
export HIPSYCL_BASE_CC=gcc
32+
export HIPSYCL_BASE_CXX=g++
33+
export hipSYCL_DIR=${INSTALL_PATH}/sycl2020/lib/cmake/hipSYCL
34+
export HIPSYCL_LLVM_BUILD_DIR=$PWD/llvm
35+
export HIPSYCL_BUILD_DIR=$PWD/sycl2020/hipSYCL
36+
mkdir build-hipSYCL
37+
cmake -S `pwd`/hipSYCL \
38+
-B `pwd`/build-hipSYCL \
39+
-DCMAKE_C_COMPILER=$HIPSYCL_LLVM_INSTALL_PREFIX/llvm/bin/clang \
40+
-DCMAKE_CXX_COMPILER=$HIPSYCL_LLVM_INSTALL_PREFIX/llvm/bin/clang++ \
41+
-DCMAKE_CXX_FLAGS:STRING='--gcc-toolchain=/work/gratienj/local/expl/eb/centos_7/easybuild/software/Core/GCCcore/10.2.0' \
42+
-DWITH_CPU_BACKEND=ON \
43+
-DWITH_CUDA_BACKEND=$HIPSYCL_WITH_CUDA \
44+
-DWITH_ROCM_BACKEND=$HIPSYCL_WITH_ROCM \
45+
-DLLVM_DIR=$HIPSYCL_LLVM_INSTALL_PREFIX/llvm/lib/cmake/llvm \
46+
-DROCM_PATH=$HIPSYCL_INSTALL_PREFIX/rocm \
47+
-DCUDA_TOOLKIT_ROOT_DIR=$HIPSYCL_LLVM_INSTALL_PREFIX/cuda \
48+
-DCLANG_EXECUTABLE_PATH=$HIPSYCL_LLVM_INSTALL_PREFIX/llvm/bin/clang++ \
49+
-DCLANG_INCLUDE_PATH=$LLVM_INCLUDE_PATH \
50+
-DCMAKE_INSTALL_PREFIX=$HIPSYCL_INSTALL_PREFIX \
51+
-DROCM_LINK_LINE='-rpath $HIPSYCL_ROCM_LIB_PATH -rpath $HIPSYCL_ROCM_PATH/hsa/lib -L$HIPSYCL_ROCM_LIB_PATH -lhip_hcc -lamd_comgr -lamd_hostcall -lhsa-runtime64 -latmi_runtime -rpath $HIPSYCL_ROCM_PATH/hcc/lib -L$HIPSYCL_ROCM_PATH/hcc/lib -lmcwamp -lhc_am' \
52+
53+
54+
Installing
55+
----------
56+
57+
.. code-block:: bash
58+
59+
module load GCC/10.2.0
60+
module load CUDA/10.1
61+
module load Boost/1.74.0
62+
module load CMake
63+
#module load LLVM/11.0.0
64+
#module load Clang/11.0.1
65+
66+
export CUDA_TOOLKIT_ROOT_DIR= ...
67+
export CUDA_SDK_ROOT_DIR= ...
68+
export INSTALL_PATH=`pwd`/Install
69+
70+
export HIPSYCL_PKG_LLVM_VERSION_MAJOR=10
71+
export INSTALL_PREFIX=`pwd`/usr/local/gcc102
72+
export HIPSYCL_INSTALL_PREFIX=${INSTALL_PATH}/sycl2020
73+
export HIPSYCL_LLVM_INSTALL_PREFIX=${INSTALL_PATH}
74+
export HIPSYCL_WITH_ROCM=OFF
75+
export CC=${GCCCORE_ROOT}/bin/gcc
76+
export CXX=${GCCCORE_ROOT}/bin/g++
77+
export HIPSYCL_BASE_CC=gcc
78+
export HIPSYCL_BASE_CXX=g++
79+
export hipSYCL_DIR=${INSTALL_PATH}/sycl2020/lib/cmake/hipSYCL
80+
export HIPSYCL_LLVM_BUILD_DIR=$PWD/llvm
81+
export HIPSYCL_BUILD_DIR=$PWD/sycl2020/hipSYCL
82+
export LD_LIBRARY_PATH=$HIPSYCL_LLVM_INSTALL_PREFIX/llvm/lib:$LD_LIBRARY_PATH
83+
84+
sh ${ALIEN_ROOT}/tools/sycl/install-llvm.sh
85+
86+
sh ${ALIEN_ROOT}/tools/syclinstall-hipsycl.sh

0 commit comments

Comments
 (0)