Update docs

This commit is contained in:
Salvatore Filippone
2024-07-11 13:12:17 +02:00
parent e9147c089e
commit 1911fec97b
73 changed files with 21156 additions and 2798 deletions
+152 -1
View File
@@ -31,9 +31,19 @@ routine in the library is built according to the following principles:
In this way, data items are put on the {GPU} memory ``on demand'' and
remain there as long as ``normal'' computations are carried out.
As an example, the following call to a matrix-vector product
\ifpdf
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{fortran}
call psb_spmm(alpha,a,x,beta,y,desc_a,info)
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
call psb_spmm(alpha,a,x,beta,y,desc_a,info)
\end{verbatim}
\end{minipage}
\end{center}
\fi
will transparently and automatically be performed on the {GPU} whenever
all three data inputs \fortinline|a|, \fortinline|x| and
\fortinline|y| are {GPU}-enabled. If a program makes many such calls
@@ -81,9 +91,19 @@ and \fortinline|beta|, and the return code \fortinline|info|.
environment}
\addcontentsline{toc}{subsection}{psb\_cuda\_init}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
call psb_cuda_init(ctxt [, device])
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
call psb_cuda_init(ctxt [, device])
\end{verbatim}
\end{minipage}
\end{center}
\fi
This subroutine initializes the PSBLAS-CUDA environment.
\begin{description}
@@ -109,9 +129,19 @@ available on the current node.
environment}
\addcontentsline{toc}{subsection}{psb\_cuda\_exit}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
call psb_cuda_exit(ctxt)
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
call psb_cuda_exit(ctxt)
\end{verbatim}
\end{minipage}
\end{center}
\fi
This subroutine exits from the PSBLAS CUDA context.
\begin{description}
@@ -131,9 +161,19 @@ Specified as: an integer variable.
\subsection*{psb\_cuda\_DeviceSync --- Synchronize CUDA device}
\addcontentsline{toc}{subsection}{psb\_cuda\_DeviceSync}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
call psb_cuda_DeviceSync()
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
call psb_cuda_DeviceSync()
\end{verbatim}
\end{minipage}
\end{center}
\fi
This subroutine ensures that all previosly invoked kernels, i.e. all
invocation of CUDA-side code, have completed.
@@ -142,45 +182,96 @@ invocation of CUDA-side code, have completed.
\subsection*{psb\_cuda\_getDeviceCount }
\addcontentsline{toc}{subsection}{psb\_cuda\_getDeviceCount}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
ngpus = psb_cuda_getDeviceCount()
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
ngpus = psb_cuda_getDeviceCount()
\end{verbatim}
\end{minipage}
\end{center}
\fi
Get number of devices available on current computing node.
\subsection*{psb\_cuda\_getDevice }
\addcontentsline{toc}{subsection}{psb\_cuda\_getDevice}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
ngpus = psb_cuda_getDevice()
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
ngpus = psb_cuda_getDevice()
\end{verbatim}
\end{minipage}
\end{center}
\fi
Get device in use by current process.
\subsection*{psb\_cuda\_setDevice }
\addcontentsline{toc}{subsection}{psb\_cuda\_setDevice}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
info = psb_cuda_setDevice(dev)
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
info = psb_cuda_setDevice(dev)
\end{verbatim}
\end{minipage}
\end{center}
\fi
Set device to be used by current process.
\subsection*{psb\_cuda\_DeviceHasUVA }
\addcontentsline{toc}{subsection}{psb\_cuda\_DeviceHasUVA}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
hasUva = psb_cuda_DeviceHasUVA()
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
hasUva = psb_cuda_DeviceHasUVA()
\end{verbatim}
\end{minipage}
\end{center}
\fi
Returns true if device currently in use supports UVA (Unified Virtual Addressing).
Returns true if device currently in use supports UVA
(Unified Virtual Addressing).
\subsection*{psb\_cuda\_WarpSize }
\addcontentsline{toc}{subsection}{psb\_cuda\_WarpSize}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
nw = psb_cuda_WarpSize()
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
nw = psb_cuda_WarpSize()
\end{verbatim}
\end{minipage}
\end{center}
\fi
Returns the warp size.
@@ -188,18 +279,38 @@ Returns the warp size.
\subsection*{psb\_cuda\_MultiProcessors }
\addcontentsline{toc}{subsection}{psb\_cuda\_MultiProcessors}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
nmp = psb_cuda_MultiProcessors()
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
nmp = psb_cuda_MultiProcessors()
\end{verbatim}
\end{minipage}
\end{center}
\fi
Returns the number of multiprocessors in the CUDA device.
\subsection*{psb\_cuda\_MaxThreadsPerMP }
\addcontentsline{toc}{subsection}{psb\_cuda\_MaxThreadsPerMP}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
nt = psb_cuda_MaxThreadsPerMP()
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
nt = psb_cuda_MaxThreadsPerMP()
\end{verbatim}
\end{minipage}
\end{center}
\fi
Returns the maximum number of threads per multiprocessor.
@@ -207,9 +318,19 @@ Returns the maximum number of threads per multiprocessor.
\subsection*{psb\_cuda\_MaxRegistersPerBlock }
\addcontentsline{toc}{subsection}{psb\_cuda\_MaxRegisterPerBlock}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
nr = psb_cuda_MaxRegistersPerBlock()
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
nr = psb_cuda_MaxRegistersPerBlock()
\end{verbatim}
\end{minipage}
\end{center}
\fi
Returns the maximum number of register per thread block.
@@ -217,27 +338,57 @@ Returns the maximum number of register per thread block.
\subsection*{psb\_cuda\_MemoryClockRate }
\addcontentsline{toc}{subsection}{psb\_cuda\_MemoryClockRate}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
cl = psb_cuda_MemoryClockRate()
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
cl = psb_cuda_MemoryClockRate()
\end{verbatim}
\end{minipage}
\end{center}
\fi
Returns the memory clock rate in KHz, as an integer.
\subsection*{psb\_cuda\_MemoryBusWidth }
\addcontentsline{toc}{subsection}{psb\_cuda\_MemoryBusWidth}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
nb = psb_cuda_MemoryBusWidth()
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
nb = psb_cuda_MemoryBusWidth()
\end{verbatim}
\end{minipage}
\end{center}
\fi
Returns the memory bus width in bits.
\subsection*{psb\_cuda\_MemoryPeakBandwidth }
\addcontentsline{toc}{subsection}{psb\_cuda\_MemoryPeakBandwidth}
\ifpdf
\begin{minted}[breaklines=true]{fortran}
bw = psb_cuda_MemoryPeakBandwidth()
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
bw = psb_cuda_MemoryPeakBandwidth()
\end{verbatim}
\end{minipage}
\end{center}
\fi
Returns the peak memory bandwidth in MB/s (real double precision).
+192 -6
View File
@@ -32,6 +32,7 @@ following steps:
Suppose you want to use the CUDA-enabled ELLPACK data structure; you
would use a piece of code like this (and don't forget, you need
CUDA-side vectors along with the matrices):
\ifpdf
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{fortran}
program my_cuda_test
use psb_base_mod
@@ -80,6 +81,61 @@ program my_cuda_test
stop
end program my_cuda_test
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
program my_cuda_test
use psb_base_mod
use psb_util_mod
use psb_ext_mod
use psb_cuda_mod
type(psb_dspmat_type) :: a, agpu
type(psb_d_vect_type) :: x, xg, bg
real(psb_dpk_), allocatable :: xtmp(:)
type(psb_d_vect_cuda) :: vmold
type(psb_d_elg_sparse_mat) :: aelg
type(psb_ctxt_type) :: ctxt
integer :: iam, np
call psb_init(ctxt)
call psb_info(ctxt,iam,np)
call psb_cuda_init(ctxt, iam)
! My own home-grown matrix generator
call gen_matrix(ctxt,idim,desc_a,a,x,info)
if (info /= 0) goto 9999
call a%cscnv(agpu,info,mold=aelg)
if (info /= 0) goto 9999
xtmp = x%get_vect()
call xg%bld(xtmp,mold=vmold)
call bg%bld(size(xtmp),mold=vmold)
! Do sparse MV
call psb_spmm(done,agpu,xg,dzero,bg,desc_a,info)
9999 continue
if (info == 0) then
write(*,*) '42'
else
write(*,*) 'Something went wrong ',info
end if
call psb_cuda_exit()
call psb_exit(ctxt)
stop
end program my_cuda_test
\end{verbatim}
\end{minipage}
\end{center}
\fi
A full example of this strategy can be seen in the
\texttt{test/ext/kernel} and \texttt{test/\-cuda/\-kernel} subdirectories,
where we provide sample programs
@@ -132,7 +188,11 @@ OFFSET & Offset for diagonals \\
\begin{figure}[ht]
\centering
% \includegraphics[width=5.2cm]{figures/mat.eps}
\includegraphics[width=5.2cm]{figures/mat.pdf}
\ifcase\pdfoutput
\includegraphics[width=5.2cm]{mat.png}
\or
\includegraphics[width=5.2cm]{figures/mat.pdf}
\fi
\caption{Example of sparse matrix}
\label{fig:dense}
\end{figure}
@@ -155,7 +215,11 @@ indices, e.g. the last valid one found in the same row.
\begin{figure}[ht]
\centering
% \includegraphics[width=8.2cm]{figures/ell.eps}
\includegraphics[width=8.2cm]{figures/ell.pdf}
\ifcase\pdfoutput
\includegraphics[width=8.2cm]{ell.png}
\or
\includegraphics[width=8.2cm]{figures/ell.pdf}
\fi
\caption{ELLPACK compression of matrix in Figure~\ref{fig:dense}}
\label{fig:ell}
\end{figure}
@@ -199,6 +263,7 @@ computing days; in modern CPUs it is not quite as popular, but it
is the basis for many GPU formats.
The relevant data type is \verb|psb_T_ell_sparse_mat|:
\ifpdf
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{fortran}
type, extends(psb_d_base_sparse_mat) :: psb_d_ell_sparse_mat
!
@@ -212,6 +277,25 @@ The relevant data type is \verb|psb_T_ell_sparse_mat|:
....
end type psb_d_ell_sparse_mat
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
type, extends(psb_d_base_sparse_mat) :: psb_d_ell_sparse_mat
!
! ITPACK/ELL format, extended.
!
integer(psb_ipk_), allocatable :: irn(:), ja(:,:), idiag(:)
real(psb_dpk_), allocatable :: val(:,:)
contains
....
end type psb_d_ell_sparse_mat
\end{verbatim}
\end{minipage}
\end{center}
\fi
\subsubsection*{Hacked ELLPACK}
@@ -251,13 +335,18 @@ submatrix inside the stacked \textit{cM}/\textit{rP} buffers, plus an
additional element pointing past the end of the last block, where the
next one would begin.
We thus have the property that
the elements of the $k$-th \textit{hack} are stored between \verb|hackOffsets[k]| and
the elements of the $k$-th \textit{hack} are stored between
\verb|hackOffsets[k]| and
\verb|hackOffsets[k+1]|, similarly to what happens in the CSR format.
\begin{figure}[ht]
\centering
% \includegraphics[width=8.2cm]{../figures/hll.eps}
\includegraphics[width=.72\textwidth]{../figures/hll.pdf}
\ifcase\pdfoutput
\includegraphics[width=.72\textwidth]{hll.png}
\or
\includegraphics[width=.72\textwidth]{../figures/hll.pdf}
\fi
\caption{Hacked ELLPACK compression of matrix in Figure~\ref{fig:dense}}
\label{fig:hll}
\end{figure}
@@ -267,6 +356,7 @@ therefore the additional memory is limited to the hack in which the
row appears.
The relevant data type is \verb|psb_T_hll_sparse_mat|:
\ifpdf
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{fortran}
type, extends(psb_d_base_sparse_mat) :: psb_d_hll_sparse_mat
!
@@ -280,6 +370,25 @@ The relevant data type is \verb|psb_T_hll_sparse_mat|:
....
end type
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
type, extends(psb_d_base_sparse_mat) :: psb_d_hll_sparse_mat
!
! HLL format. (Hacked ELL)
!
integer(psb_ipk_) :: hksz
integer(psb_ipk_), allocatable :: irn(:), ja(:), idiag(:), hkoffs(:)
real(psb_dpk_), allocatable :: val(:)
contains
....
end type
\end{verbatim}
\end{minipage}
\end{center}
\fi
\subsubsection*{Diagonal storage}
@@ -300,13 +409,18 @@ addressing is required.
\begin{figure}[ht]
\centering
% \includegraphics[width=8.2cm]{figures/dia.eps}
\includegraphics[width=.72\textwidth]{figures/dia.pdf}
\ifcase\pdfoutput
\includegraphics[width=.72\textwidth]{dia.png}
\or
\includegraphics[width=.72\textwidth]{figures/dia.pdf}
\fi
\caption{DIA compression of matrix in Figure~\ref{fig:dense}}
\label{fig:dia}
\end{figure}
\begin{algorithm}
\ifpdf
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{fortran}
do j=1,ndiag
if (offset(j) > 0) then
@@ -319,11 +433,30 @@ addressing is required.
end do
end do
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
do j=1,ndiag
if (offset(j) > 0) then
ir1 = 1; ir2 = m - offset(j);
else
ir1 = 1 - offset(j); ir2 = m;
end if
do i=ir1,ir2
y(i) = y(i) + alpha*as(i,j)*x(i+offset(j))
end do
end do
\end{verbatim}
\end{minipage}
\end{center}
\fi
\caption{\label{alg:dia} Matrix-Vector product in DIA format}
\end{algorithm}
The relevant data type is \verb|psb_T_dia_sparse_mat|:
\ifpdf
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{fortran}
type, extends(psb_d_base_sparse_mat) :: psb_d_dia_sparse_mat
!
@@ -336,6 +469,24 @@ The relevant data type is \verb|psb_T_dia_sparse_mat|:
end type
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
type, extends(psb_d_base_sparse_mat) :: psb_d_dia_sparse_mat
!
! DIA format, extended.
!
integer(psb_ipk_), allocatable :: offset(:)
integer(psb_ipk_) :: nzeros
real(psb_dpk_), allocatable :: data(:,:)
end type
\end{verbatim}
\end{minipage}
\end{center}
\fi
@@ -378,12 +529,17 @@ the number of diagonals of the $k$-th \textit{hack} is given by
\begin{figure}[ht]
\centering
% \includegraphics[width=8.2cm]{../figures/hdia.eps}
\includegraphics[width=.72\textwidth]{../figures/hdia.pdf}
\ifcase\pdfoutput
\includegraphics[width=.72\textwidth]{hdia.png}
\or
\includegraphics[width=.72\textwidth]{../figures/hdia.pdf}
\fi
\caption{Hacked DIA compression of matrix in Figure~\ref{fig:dense}}
\label{fig:hdia}
\end{figure}
The relevant data type is \verb|psb_T_hdia_sparse_mat|:
\ifpdf
\begin{minted}[breaklines=true,bgcolor=bg,fontsize=\small]{fortran}
type pm
real(psb_dpk_), allocatable :: data(:,:)
@@ -408,5 +564,35 @@ The relevant data type is \verb|psb_T_hdia_sparse_mat|:
....
end type
\end{minted}
\else
\begin{center}
\begin{minipage}[tl]{0.9\textwidth}
\begin{verbatim}
type pm
real(psb_dpk_), allocatable :: data(:,:)
end type pm
type po
integer(psb_ipk_), allocatable :: off(:)
end type po
type, extends(psb_d_base_sparse_mat) :: psb_d_hdia_sparse_mat
!
! HDIA format, extended.
!
type(pm), allocatable :: hdia(:)
type(po), allocatable :: offset(:)
integer(psb_ipk_) :: nblocks, nzeros
integer(psb_ipk_) :: hack = 64
integer(psb_long_int_k_) :: dim=0
contains
....
end type
\end{verbatim}
\end{minipage}
\end{center}
\fi
Binary file not shown.

After

Width:  |  Height:  |  Size: 50 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 52 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 58 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 61 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 90 KiB

-2
View File
@@ -18,8 +18,6 @@
\newtheorem{corollary}{Corollary}
\usepackage{listings}
\usepackage{algorithm2e}
\usepackage{minted}
\usemintedstyle{friendly}
\usepackage{microtype}
\ifpdf
\newmintinline[fortinline]{fortran}{}