forked from m-a-d-n-e-s-s/madness
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathINSTALL
243 lines (194 loc) · 13 KB
/
INSTALL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
# Introduction
When configuring MADNESS with CMake, you must specify cache variables and the
path to the MADNESS source directory. To specify a cache variable prefix it with
the -D command line flag and set it equal to the desired value (see below for a
valid cache variables). For example, to specify the C/C++ compilers
$ cmake -D CMAKE_C_COMPILER=gcc -D CMAKE_CXX_COMPILER=g++ \
/path/to/madness/source
The resulting build directory will be the current working directory specified
where the CMake command it run. It is recommended that you configure and build
MADNESS outside the source tree. Boolean values for cache variables are
considered true if the constant is 1, ON, YES, TRUE, Y, or a non-zero number; or
false if the constant is 0, OFF, NO, FALSE, N, or IGNORE.
# Toolchain files
MADNESS provides toolchain files for select systems. It is recommended that you
use these files if provided as they contain the platform specific settings
neccessary to build on the given platform. The toolchain files are included wiht
the MADNESS source in the cmake/toolchains directory.
* CMAKE_TOOLCHAIN_FILE --- Specifies the path (including the file name) to the
toolchain file.
For example, to specify the toolchain file for Mira:
$ cmake -D CMAKE_TOOLCHAIN_FILE=/path/to/madness/source/cmake/toolchains/mira-gcc-essl.cmake \
/path/to/madness/source
Additional cache variables may be specified.
# Compiler variables
The following CMake cache variables are used to specify the compilers, compiler
flags, and linker flags.
* CMAKE_C_COMPILER --- C compiler [default=search]
* CMAKE_CXX_COMPILER --- C++ compiler [default=search]
* CMAKE_ASM_COMPILER --- Assembly compiler (set only if required)
[default=search]
* MPI_CXX_COMPILER --- MPI C++ compiler wrapper (required if ENABLE_MPI=ON)
[default=search]
* MPI_C_COMPILER --- MPI C compiler wrapper (required if ENABLE_MPI=ON)
[default=search]
You can specify compile flags with the following variables. These cache variables
are optional, and it is typically not necessary to specify these variables.
* CMAKE_C_FLAGS --- Compile flags passed to the C compiler
* CMAKE_CXX_FLAGS --- Compile flags passed to the C++ compiler
* CMAKE_EXE_LINKER_FLAGS --- Linker flags to be used to create executables.
* CMAKE_STATIC_LINKER_FLAGS --- Linker flags to be used to create static
libraries.
* CMAKE_SHARED_LINKER_FLAGS --- Linker flags to be used to create shared
libraries.
# Build options
The following CMake cache variables turn MADNESS features on and off.
* ENABLE_GENTENSOR --- Enable generic tensors; only useful if need
compressed 6-d tensors, e.g. in MP2 [default=OFF]
* ENABLE_TASK_PROFILER - Enable task profiler that collects per-task start and
stop times. [default=OFF]
* ENABLE_WORLD_PROFILE --- Enables world profiling [default=OFF]
* ENABLE_MEM_STATS --- Gather memory statistics (expensive) (default=OFF)
* ENABLE_TENSOR_BOUNDS_CHECKING --- Enable checking of bounds in tensors ...
slow but useful for debugging [default=OFF]
* ENABLE_TENSOR_INSTANCE_COUNT --- Enable counting of allocated tensors for
memory leak detection [default=OFF]
* ENABLE_SPINLOCKS --- Enables use of spinlocks instead of mutexes (faster
unless over subscribing processors) [default=ON]
* ENABLE_NEVER_SPIN --- Disables use of spinlocks (notably for use inside
virtual machines [default=OFF]
* ENABLE_BSEND_ACKS --- Use MPI Send instead of MPI Bsend for huge message
acknowledgements [default=ON]
* ENABLE_UNITTESTS --- Enables unit tests targets [default=ON]
* FORTRAN_INTEGER_SIZE --- Set the fortran integer size (4 or 8 bytes) used for
BLAS and LAPACK function calls [default=4]
* ASSERTION_TYPE --- Define MADNESS assertion behavior
(abort|assert|disable|throw) [default=throw]
* MPI_THREAD --- Thread level for MPI (multiple|serialized)" [default=multiple]
* BUILD_SHARED_LIBS --- Enable shared libraries. This option is only available
if the platform supports shared libraries; if that's true and MADNESS_ASSUMES_ASLR_DISABLED is ON (see below) the default is ON,
otherwise the default is OFF.
* MADNESS_BUILD_MADWORLD_ONLY --- whether to build the MADNESS runtime only; if `ON`, discovery of BLAS/LAPACK
and building of numerical components and applications will be disabled [default=`OFF`]
# MADNESS Runtime and the Address Space Layout Randomization (ASLR)
ASLR is a standard technique for increasing platform security implemented by the OS kernel and/or
the dynamic linker. By randomizing both where the shared libraries are loaded as well as (when enabled) the absolute
position of the executable in memory (such executables are known as position-independent executables). Until recently
MADNESS could not be used on platforms with ASLR if ran with more than 1 MPI rank;
if properly configured and built it can now be used on ASLR platforms. Use the following
variables to control the ASLR-related aspects of MADNESS runtime.
* MADNESS_ASSUMES_ASLR_DISABLED --- MADNESS runtime will assume that the Address Space Layout Randomization (ASLR) is off.
By default MADNESS_ASSUMES_ASLR_DISABLED is set to OFF (i.e. MADNESS will assume that ASLR is enabled);
this will cause all libraries by default to be static (BUILD_SHARED_LIBS=OFF)
and compiled as position-independent code (CMAKE_POSITION_INDEPENDENT_CODE=ON).
This will also enable a runtime check for ASLR.
* CMAKE_POSITION_INDEPENDENT_CODE --- This standard CMake variable controls whether targets are compiled by default
as position-independent code or not. If BUILD_SHARED_LIBS=OFF need to set this to ON if want to use the MADNESS
libraries to build shared libraries or position-independent executables.
To make things more concrete, consider the following 2 scenarios:
* Platform with ASLR disabled --- set MADNESS_ASSUMES_ASLR_DISABLED=ON to set defaults correctly and enable the ASLR check.
BUILD_SHARED_LIBS can be set to ON (to produce shared libraries, e.g. to save space) or to OFF to
produce static libraries. If the static libraries will be linked into shared libraries set
CMAKE_POSITION_INDEPENDENT_CODE=ON, otherwise CMAKE_POSITION_INDEPENDENT_CODE will be set to OFF for maximum efficiency
of function calls.
* Platform with ASLR enabled --- this is the default. Setting BUILD_SHARED_LIBS=ON in this scenario will produce
executables that can only be safely used with 1 MPI rank, thus BUILD_SHARED_LIBS will be defaulted to OFF (i.e.
MADNESS libraries will be build as static libraries). CMAKE_POSITION_INDEPENDENT_CODE is by default set to ON,
thus MADNESS libraries can be linked into position-independent executables safely. MADNESS libraries can also be
linked into a shared library, provided that *ALL* code using MADNESS is part of the *SAME* shared library.
E.g. to link MADNESS into a Python module compile MADNESS and all libraries using MADNESS as static libraries
(with CMAKE_POSITION_INDEPENDENT_CODE=ON) and link them all together into a single module
(same logic applies to shared libraries using MADNESS).
# External libraries
The following CMake cache variables enable the use of external libraries with
MADNESS. If the WITH_* variable is set to "ON" by default, failure to find the
external library is not an error. If you explicitly set a WITH_* variable to
"ON" when the default is set to "OFF," an error will occur if the library is
not found.
* CMAKE_PREFIX_PATH - A semicolon seperated list of paths that are used when
searching for external libraries and dependencies. You may use this CMake
cache variable to specify the prefix for any of the dependencies, or you
may specify path for individual components below.
* ENABLE_MPI --- Enable use of MPI, should specify MPI_CXX_COMPILER or MPI_C_COMPILER
explicitly or have them in PATH; if not found will use StubMPI and
be limited to 1 process [default=ON]
In the following section, each optional library privides four variables that
the user can use to enable cmake to find the correct dependencies:
* ENABLE_<LIB> --- Enable the library feathres (ON|OFF)
* <LIB>_ROOT_DIR --- Prefix path used to search for the external library.
* <LIB>_INCLUDE_DIR --- The external library include path. By default the
include path is ${<LIB>_ROOT_DIR}/include, if <LIB>_ROOT_DIR is
specified in the configure command.
* <LIB>_LIBRARY --- The external library path. By default the
include path is ${<LIB>_ROOT_DIR}/(lib64|lib), if <LIB>_ROOT_DIR is
specified in the configure command.
If the <LIB>_ROOT_DIR, <LIB>_INCLUDE_DIR, and <LIB>_LIBRARY will be used to
search for specific dependencies. If the external library is not found in these
given paths, or if the paths are not given, CMake will search the paths in
CMAKE_PREFIX_PATH as well as other system paths.
# Intel Threading Building Blocks (TBB):
* ENABLE_TBB --- Enables use of Intel TBB as the task scheduler [default=OFF]
* TBB_ROOT_DIR --- The install prefix for TBB
* TBB_INCLUDE_DIR --- The path to the TBB include directory
* TBB_LIBRARY --- The path to the TBB library directory. By default, the library
search path is ${TBB_ROOT_DIR}/(lib/intel64/gcc4.4|lib) on Linux and
${TBB_ROOT_DIR}/(lib/libc++|lib) on OS X, if TBB_ROOT_DIR is specified in
the configure command.
* MADNESS_EXPLOIT_TBB_PRIORITY --- If ON, MADNESS will try to use Intel TBB task priorities [default=OFF]
If TBB_ROOT_DIR is not given, it will be set to the value of the TBBROOT environment variable if it is set.
# Intel Math Kernel Library (MKL):
* ENABLE_MKL --- Search for Intel MKL for BLAS and LAPACK support [default=ON]
* MKL_ROOT_DIR --- The install prefix for MKL.
* MKL_LIBRARY --- The path to the MKL library directory.
If MKL_ROOT_DIR is not given, it will be set to the value of the MKLROOT environment variable if it is set.
# AMD Core Math Library (ACML):
* ENABLE_ACML --- Search for AMD math library for BLAS and LAPACK support
[default=ON]
* ACML_ROOT_DIR --- The install prefix for ACML.
* ACML_LIBRARY --- The path to the ACML library directory.
# Google Performance Tools (Gperftools):
* ENABLE_GPERFTOOLS --- Enable use of gperftools, including tcmalloc.
[default=ON]
* GPERFTOOLS_ROOT_DIR --- The install prefix for gperftools.
* GPERFTOOLS_INCLUDE_DIR --- The path to the gperftools include directory.
* GPERFTOOLS_LIBRARY --- The path to the gperftools library directory.
If GPERFTOOLS_ROOT_DIR is not given, it will be set to the value of the GPERFTOOLS_DIR environment variable if it is set.
# Libunwind:
* ENABLE_LIBUNWIND --- Force detection of gperftools [default=OFF, i.e. Libunwind will be searched for when needed]
* LIBUNWIND_ROOT_DIR --- The install prefix for Libunwind.
* LIBUNWIND_INCLUDE_DIR --- The path to the Libunwind include directory.
* LIBUNWIND_LIBRARY --- The path to the Libunwind library directory.
If LIBUNWIND_ROOT_DIR is not given, it will be set to the value of the LIBUNWIND_DIR environment variable if it is set.
# Library of Exchange-Correlation DFT functionals (LIBXC):
* ENABLE_LIBXC --- Enables use of the libxc library of density functionals.
[default=ON]
* LIBXC_ROOT_DIR --- The install prefix for LIBXC.
* LIBXC_INCLUDE_DIR --- The path to the LIBXC include directory.
* LIBXC_LIBRARY --- The path to the LIBXC library directory.
# Polarizable Conitinuum Solver (PCM):
* ENABLE_PCM --- Enables use of PCM
* PCM_ROOT_DIR --- The install prefix for PCM
* PCM_INCLUDE_DIR --- The path to the PCM include directory (should be added automatically when the correct PCM_ROOT_DIR is given)
* PCM_LIBRARY --- The path to the PCM library (should be added automatically when the correct PCM_ROOT_DIR is given)
set either PCM_ROOT_DIR or manually set PCM_INCLUDE_DIR and PCM_LIBRARY
See also
madness/CMakeLists.txt
madness/external/pcm.cmake
madness/modules/FindPCM.cmake
madness/src/apps/chem/CMakeLists.txt
# Performance Application Programming Interface (PAPI):
* ENABLE_PAPI --- Enables use of PAPI [default=OFF]
* PAPI_ROOT_DIR --- The install prefix for PAPI.
* PAPI_INCLUDE_DIR --- The path to the PAPI include directory.
* PAPI_LIBRARY --- The path to the PAPI library directory.
# Elemental parallel linear algebra library:
Elemental provides optional distributed-memory linear algebra for some MADNESS application codes.
MADNESS source includes (modified) Elemental v0.84, which has been validated to work with
the few MADNESS apps that can use Elemental. You can instruct MADNESS to download and compile
a more recent version of Elemental, if desired, but the apps will not use Elemental then.
Such bundling is currently necessary if your code uses the MADworld runtime AND Elemental because
madness::initialize will call El::initialize() .
* ENABLE_ELEMENTAL --- Enable Elemental [default=OFF].
* ELEMENTAL_TAG --- specifies the version of Elemental to be downloaded, compiled, and installed alongside
MADNESS (numerical codes of MADNESS will not use Elemental).
If not set, will use the included Elemental source.