Skip to content

Commit 89ef8bb

Browse files
author
Mathieu Taillefumier
committed
Added basic documentation
1 parent 83f6c40 commit 89ef8bb

File tree

3 files changed

+125
-89
lines changed

3 files changed

+125
-89
lines changed

‎.ci/uenv-recipes/tmlqcd/daint-gh200/repo/packages/lemonio/package.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ class CMakeBuilder(cmake.CMakeBuilder):
2828
def cmake_args(self):
2929
spec = self.spec
3030
args = [
31-
self.define_from_variant("DBUILD_SHARED_LIBS" "shared"),
31+
self.define_from_variant("DBUILD_SHARED_LIBS", "shared"),
3232
]
3333
return args
3434

‎CMakeLists.txt‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -80,8 +80,8 @@ option(TM_USE_MPI "Enable MPI support" OFF)
8080
option(TM_USE_CUDA "Enable QUDA support" OFF)
8181
option(TM_USE_HIP "Enable HIP support" OFF)
8282
option(TM_USE_DDalphaAMG "Enable DDalphaAMG support" OFF)
83-
option(TM_USE_OMP "Enable openMP" ON)
84-
option(TM_FIXEDVOLUME "fix volume at compile time" OFF)
83+
option(TM_USE_OMP "Enable OpenMP" ON)
84+
option(TM_FIXEDVOLUME "Fix volume at compile time" OFF)
8585
set(TM_ENABLE_ALIGNMENT
8686
"auto"
8787
CACHE
@@ -95,7 +95,7 @@ set_property(CACHE TM_ENABLE_ALIGNMENT PROPERTY STRINGS "auto" "none" "16" "32"
9595
option(TM_USE_OPTIMIZATION "enable optimisation" ON)
9696
option(TM_USE_GAUGE_COPY "Enable use of a copy of the gauge field" ON)
9797
option(TM_USE_HALFSPINOR "Use a Dirac Op. with halfspinor exchange" ON)
98-
option(TM_USE_QPHIX "enable QPhiX" OFF)
98+
option(TM_USE_QPHIX "Enable QPhiX" OFF)
9999
option(TM_USE_SHMEM "Use shmem API" OFF)
100100
option(TM_USE_QUDA "Enable QUDA support" OFF)
101101
option(TM_ENABLE_WARNINGS "Enable all warnings" ON)
@@ -106,7 +106,7 @@ cmake_dependent_option(
106106
TM_PERSISTENT_MPI "Use persistent MPI calls for halfspinor [default=no]" OFF
107107
"TM_USE_MPI" OFF)
108108
cmake_dependent_option(
109-
TM_NONBLOCKING_MPI "Use non-blocking MPI calls for spinor and gaug" ON
109+
TM_NONBLOCKING_MPI "Use non-blocking MPI calls for spinor and gauge" ON
110110
"TM_USE_MPI" OFF)
111111

112112
# need to do it properly. Just a place holder
@@ -293,6 +293,9 @@ if(TM_USE_MPI)
293293
endif()
294294
endif()
295295

296+
if (TM_USE_HALFSPINOR AND NOT TM_USE_GAUGE_COPY)
297+
message(FATAL_ERROR "The TM_USE_GAUGE_COPY option should also be set to ON when TM_USE_HALFSPINOR is ON")
298+
endif()
296299
# keep the autotool config.h header.
297300
configure_file("${PROJECT_SOURCE_DIR}/cmake/tmlqcd_config_internal.h.in"
298301
"${PROJECT_BINARY_DIR}/tmlqcd_config_internal.h" @ONLY)

‎doc/install.tex‎

Lines changed: 117 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,136 @@
1-
The software ships with a GNU autoconf environment and a configure
2-
script, which will generate GNU Makefiles to build the programmes. It
3-
is supported and recommended to configure and build the executables in
4-
a separate build directory. This also allows to have several builds with
5-
different options from the same source code directory.
1+
The software ships with a CMake environment, which will configure and build the
2+
programmes. It is recommended to configure and build the executables in a
3+
separate build directory. This also allows to have several builds with different
4+
options from the same source code directory.
65

76
\subsection{Prerequisites}
87

9-
In order to compile the programmes the {\ttfamily
10-
LAPACK}~\cite{lapack:web} library (fortran version) needs to be
11-
installed. In addition it must be known which linker options are
12-
needed to link against {\ttfamily LAPACK}, e.g. {\ttfamily
13-
-Lpath-to-lapack -llapack -lblas}. Also a the latest
14-
version (tested is version 1.2.3) of {\ttfamily
15-
C-LIME}~\cite{lime:web} must be available, which is used as a
16-
packaging scheme to read and write gauge configurations and
17-
propagators to files.
8+
In order to compile the programmes the {\ttfamily LAPACK}~\cite{lapack:web}
9+
library (fortran version) needs to be installed. CMake will search for the
10+
library in all default directories. Also the latest version (tested is version
11+
1.2.3) of {\ttfamily C-LIME}~\cite{lime:web} must be available, which is used as
12+
a packaging scheme to read and write gauge configurations and propagators to
13+
files.
1814

1915
\subsection{Configuring the hmc package}
2016
\label{sec:config}
2117

22-
In order to get a simple configuration of the hmc package it is enough
23-
to just type
24-
\begin{verbatim}
25-
path-to-src-code/configure --with-lime=<path-to-lime> \
26-
--with-lapack=<linker-flags> CC=<mycc> \
27-
F77=<myf77> CFLAGS=<c-compiler flags>
28-
\end{verbatim}
29-
in the build directory. If
30-
{\ttfamily CC, F77} and {\ttfamily CFLGAS} are not specified,
31-
{\ttfamily configure} will guess them.
32-
33-
The code was successfully compiled and run at least on the following
34-
platforms: i686 and compatible, x64 and compatible, IBM Regatta
35-
systems, IBM Blue Gene/L, IBM Blue Gene/P, SGI Altix and SGI PC
36-
clusters, powerpc clusters.
37-
38-
The configure script accepts certain options to influence the building
39-
procedure. One can get an overview over all supported options with
40-
{\ttfamily configure --help}. There are {\ttfamily enable|disable}
41-
options switching on and off optional features and {\ttfamily
42-
with|without} switches usually related to optional packages. In the
43-
following we describe the most important of them (check {\ttfamily
44-
configure --help} for the defaults and more options):
45-
18+
The build system uses CMake to configure and build the hmc package. The
19+
following list gives all options (OFF by default unless specified):
4620
\begin{itemize}
47-
\item {\ttfamily --enable-mpi}:\\
48-
This option switches on the support for MPI. On certain platforms it
49-
automatically chooses the correct parallel compiler or searches for
50-
a command {\ttfamily mpicc} in the search path.
51-
52-
\item {\ttfamily --enable-gaugecopy}:\\
53-
See section \ref{sec:dirac} for details on this option. It will
21+
\item {\ttfamily CMAKE\_POSITION\_INDEPENDENT\_CODE}: Build a position independent
22+
code. ON by default.
23+
\item {\ttfamily BUILD\_SHARED\_LIBS}: Build the shared version of the hmc library.
24+
\item {\ttfamily TM\_USE\_FFTW}: Enable fftw support.
25+
\item {\ttfamily TM\_USE\_CUDA}: Enable CUDA support.
26+
\item {\ttfamily TM\_USE\_HIP}: Enable HIP support (AMD or NVidia GPUs)
27+
\item {\ttfamily TM\_USE\_DDalphaAMG}: Enable DDalphaAMG support.
28+
\item {\ttfamily TM\_USE\_LEMON}: Use the lemon io library.
29+
\item {\ttfamily TM\_USE\_OMP}: Enable OpenMP ({\bf ON} by default)
30+
\item {\ttfamily TM\_FIXEDVOLUME}: Fix volume at compile time.
31+
\item {\ttfamily TM\_ENABLE\_ALIGNMENT}: Automatically or expliclty align arrays to
32+
byte number. auto, none, 16, 32, 64.
33+
\item {\ttfamily TM\_USE\_GAUGE\_COPY}: Enable use of a copy of the gauge field (ON
34+
by default). See section \ref{sec:dirac} for details on this option. It will
5435
increase the memory requirement of the code.
36+
\item {\ttfamily TM\_USE\_HALFSPINOR}: Use a Dirac Op. with halfspinor exchange (ON
37+
by default). See sub-section \ref{sec:dirac} for details.
38+
\item {\ttfamily TM\_USE\_QUDA}: Enable QUDA support.
39+
\item {\ttfamily TM\_USE\_SHMEM}: Use shmem API.
40+
\item {\ttfamily TM\_ENABLE\_WARNINGS}: Enable all warnings (ON by default).
41+
\item {\ttfamily TM\_ENABLE\_TESTS}: Enable tests.
42+
\item {\ttfamily TM\_USE\_QPHIX}: Enable QPhiX.
43+
\begin{itemize}
44+
\item {\ttfamily TM\_QPHIX\_SOALEN}: QPhiX specific parameter (default is 4)
45+
\item \textcolor{red}{{\ttfamily QPHIX\_DIR}}: Directory where QPhiX is installed.
46+
The QPhiX current CMake build system does not export all information (
47+
include and lib directories) that are needed to compile hmc.
48+
\item \textcolor{red}{\ttfamily QMP\_DIR}: Directory where QMP is installed (
49+
QPhiX dependency).
50+
The QPhiX current CMake build system does not export all information about the
51+
include and lib directories nor its dependencies (QMP in that case).
52+
\end{itemize}
53+
\item {\ttfamily TM\_USE\_MPI}: Enable MPI support.
54+
\begin{itemize}
55+
\item {\ttfamily TM\_PERSISTENT\_MPI}: Use persistent MPI calls for halfspinor.
56+
\item {\ttfamily TM\_NONBLOCKING\_MPI}: Use non-blocking MPI calls for spinor and
57+
gauge.
58+
\item {\ttfamily TM\_MPI\_DIMENSION}: Use $n$ dimensional parallelisation ($XYZT$)
59+
[default=4]. The number of parallel directions can be specified. $1, 2, 3$ and $4$
60+
dimensional parallelisation is supported.
61+
\item {\ttfamily TM\_USE\_LEMON} Use the lemon io library
62+
\end{itemize}
63+
\end{itemize}
5564

56-
\item {\ttfamily --enable-halfspinor}:\\
57-
If this option is enabled the Dirac operator using half spinor
58-
fields is used. See sub-section \ref{sec:dirac} for details. If this
59-
feature is switched on, also the gauge copy feature is switched
60-
on automatically.
61-
62-
%\item {\ttfamily --enable-shmem}:\\
63-
% Use shared memory API instead of MPI for the communication of spinor
64-
% fields. This is currently only usable on the Munich Altix machine.
65-
66-
\item {\ttfamily --with-mpidimension=n}:\\
67-
This option has only effect if the preceding one is switched
68-
on. The number of parallel directions can be specified. 1,2,3 and 4
69-
dimensional parallelisation is supported.
70-
71-
\item {\ttfamily --with-lapack="<linker flags>"}:\\
72-
the code requires lapack to be linked. All linker flags necessary
73-
to do so must be specified here. Note, that {\ttfamily LIBS="..."}
74-
works similar.
65+
The following minimal list of commands will configure and build the hmc package with
66+
minimal dependencies
67+
\begin{verbatim}
68+
mkdir build
69+
cd build
70+
cmake -DCMAKE_INSTALL_PREFIX=/my_path -DCMAKE_PREFIX_PATH=/my_c_line_path ..
71+
make -j
72+
make install
73+
\end{verbatim}
7574

76-
\item {\ttfamily --with-limedir=<dir>}:\\
77-
Tells configure where to find the lime package, which is required for
78-
the build of the HMC. It is used for the ILDG file format.
79-
80-
\end{itemize}
75+
These instructions assume that the {\ttfamily c-lime} package is installed in {\ttfamily
76+
/my\_c\_line\_path}. By default {\ttfamily CMAKE\_PREFIX\_PATH} variable is a list
77+
of paths separated by a semi-colunm containing the path of all installed to
78+
dependencies.
8179

82-
The configure script will guess at the very beginning on which
83-
platform the build is done. In case this fails or a cross compilation
84-
must be performed please use the option {\ttfamily --host=HOST}. For
85-
instance in order to compile for the BG/P one needs to specify
86-
{\ttfamily --host=ppc-ibm-bprts --build=ppc64-ibm-linux}.
80+
Adding {\ttfamily -DTM\_USE\_MPI=ON} will enable MPI support with parallelization
81+
over spatial and temporal dimensions. The command line is then
82+
\begin{verbatim}
83+
cmake -DCMAKE_INSTALL_PREFIX=/my_path -DCMAKE_PREFIX_PATH=/my_c_line_path -DTM_USE_MPI=ON ..
84+
\end{verbatim}
85+
We can combine it with the lemon-io library (isntalled in {\ttfamily /my\_lemon\_path})
86+
\begin{verbatim}
87+
cmake -DCMAKE_INSTALL_PREFIX=/my_path \
88+
-DCMAKE_PREFIX_PATH="/my_c_line_path;/my_lemon_path" \
89+
-DTM_USE_MPI=ON \
90+
-DTM_USE_LEMON=ON ..
91+
\end{verbatim}
8792

88-
For certain architectures like the Blue Gene systems there are
89-
{\ttfamily README.arch} files in the top source directory with
90-
example configure calls.
93+
{\ttfamily QUDA} support (installed in {\ttfamily my\_quda\_path}) can be added with
94+
\begin{verbatim}
95+
cmake -DCMAKE_INSTALL_PREFIX=/my_path \
96+
-DCMAKE_PREFIX_PATH="/my_c_line_path;/my_lemon_path;\my_quda_path" \
97+
-DTM_USE_MPI=ON \
98+
-DTM_USE_LEMON=ON \
99+
-DTM_USE_QUDA \
100+
-DTM_USE_CUDA=ON \
101+
-DCMAKE_CUDA_ARCHITECTURES=90 ..
102+
\end{verbatim}
103+
Note that the command assumes that QUDA is compiled with CUDA support. AMD GPU
104+
are also supported after replacing {\ttfamily -DTM\_USE\_CUDA=ON} with
105+
{\ttfamily -DTM\_USE\_HIP=ON} and compiling {\ttfamily QUDA} with {\ttfamily
106+
HIP} support. The {\ttfamily ROCM} architecture is defined by the variable
107+
{\ttfamily CMAKE\_HIP\_ARCHITECTURES=gfxxxx}.
91108

92-
\subsection{Building and Installing}
109+
{\ttfamily QPhiX} and/or {\ttfamily DDalphaAMG} support can be added with
110+
\begin{verbatim}
111+
cmake -DCMAKE_INSTALL_PREFIX=/my_path \
112+
-DCMAKE_PREFIX_PATH="/my_c_line_path;/my_lemon_path;/my_quda_path;/my_path_ddalphaamg" \
113+
-DTM_USE_MPI=ON \
114+
-DTM_USE_LEMON=ON \
115+
-DTM_USE_QUDA=ON \
116+
-DTM_USE_CUDA=ON \
117+
-DCMAKE_CUDA_ARCHITECTURES=90 \
118+
-DTM_USE_QPHIX=ON \
119+
-DQPHIX_DIR=/my_qphix_dir \
120+
-DTM_USE_DDalphaAMG=ON \
121+
-DQMP_DIR=/my_qmp_dir \
122+
-DTM_USE_OMP=ON ..
123+
\end{verbatim}
124+
{\ttfamily QPhiX} cmake config support is incomplete and requires both the {\ttfamily QPhiX}
125+
and {\ttfamily QMP} installation directories to work properly.
93126

94-
After successfully configuring the package the code can be build by
95-
simply typing {\ttfamily make} in the build directory. This will
96-
compile the standard executables. Typing {\ttfamily make install} will
97-
copy these executables into the install directory. The default install
98-
directory is {\ttfamily \$HOME/bin}, which can be influenced e.g. with
99-
the {\ttfamily --prefix} option to {\ttfamily configure}.
127+
CMake has several relevant specific options that control the build. Compiler
128+
options are defined by the variable {\ttfamily CMAKE\_C\_FLAGS} and {\ttfamily
129+
CMAKE\_CXX\_FLAGS}. CUDA and HIP compilations options are controlled by their
130+
equivalent {\ttfamily CMAKE\_\{CUDA/HIP\}\_FLAGS}.
100131

132+
Adding for instance {\ttfamily -GNinja} to the {\ttfamily CMake} command line will use
133+
{\ttfamily ninja} instead of {\ttfamily make}.
101134

102135
%%% Local Variables:
103136
%%% mode: latex

0 commit comments

Comments
 (0)