-
Notifications
You must be signed in to change notification settings - Fork 79
/
INSTALL-NOTES
340 lines (245 loc) · 11.4 KB
/
INSTALL-NOTES
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
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
****************************************************************************
* Copyright 1997-2024 *
* Lawrence Livermore National Security, LLC. *
* All rights reserved. *
****************************************************************************
****************************************************************************
* *
* Structured Adaptive Mesh Refinement Applications Infrastructure *
* https://computing.llnl.gov/projects/samrai *
* *
****************************************************************************
* For installation help, see INSTALL-NOTES. *
* For release notes, see RELEASE-NOTES. *
* For copyright information, see COPYRIGHT and LICENSE. *
* For code and user documentation, see files in /docs directory *
* For help and information about updates and releases, please send *
* email to [email protected] *
* For reporting bugs and suggestions, please post an issue at the *
* SAMRAI github page https://github.com/LLNL/SAMRAI *
* For more information on SAMRAI see *
* https://computing.llnl.gov/projects/samrai *
****************************************************************************
****************************************************************************
Overview
--------
This document describes the SAMRAI installation process.
Documentation for the library can be found in the docs directory after
you untar the distribution. See the docs/main.html web page for pointers
to other documents.
Directory Structure
-------------------
We recommend the following directory structure:
SAMRAI-vX.Y.Z/
SAMRAI/
ARCH1-CXX1-OPTDEBUG1/
config/ lib/
ARCH2-CXX2-OPTDEBUG2/
config/ lib/
ARCH3-CXX3-OPTDEBUG3/
config/ lib/
where SAMRAI/ is the SAMRAI source distribution and the other
subdirectories contain library archives and configuration files
for a particular architecture, compiler, and set of optimization
flags. For example,
SAMRAI-v3.3.3/
SAMRAI/
solaris-g++-debug/
config/ lib/
solaris-KCC-opt/
config/ lib/
rs6000-g++-optdebug/
config/ lib/
The subdirectories config/, lib/, etc.,
are created automatically by the SAMRAI installation procedure
(configure).
(1) Unpacking the Distribution
------------------------------
The SAMRAI source code is generally distributed as a gzipped tar file.
SAMRAI version numbers are of the form X.Y.Z, where X is the major release
number, Y is the minor release number, and Z is the bug fix patch number.
To unpack the distribution as described above, do:
(a) gunzip SAMRAI-vX.Y.Z.tar.gz
(b) mkdir SAMRAI-vX.Y.Z (substitue appropriate version numbers)
(b) cd SAMRAI-vX.Y.Z
(e) tar xvf ../SAMRAI-vX.Y.Z.tar
You may need to use the GNU tar (often named gtar) due to name length
problems with some of the native tar implementations.
Note that this assumes that the SAMRAI tar file is in the same directory
as SAMRAI-v.X.Y.Z. If this is not the case, you will need to change the
path in the zcat to point to the SAMRAI tar file.
After these steps, the directories should look as follows:
SAMRAI-vX.Y.Z/
SAMRAI/
(2) CMake build system
----------------------------
The CMake build system uses the open source tool CMake supplemented with the
macro library BLT. An execution of CMAKE will determine the various
system-dependent features are needed during the compilation, and allows users
to turn on or off optional features and dependencies.
Users should make sure that BLT is included in the SAMRAI distribution that
they are trying to install. BLT is included as a submodule in SAMRAI's github
repository, and its presence in your distribution depends on how you
obtained SAMRAI. If you downloaded SAMRAI from the llnl.gov project page,
BLT should be included in the distributed tarball. If you obtained the
tarball from the "Releases" section of SAMRAI's github page, BLT will not
be there. These tarballs are automatically generated by github and do not
include submodules. If the blt subdirectory in the top level of your SAMRAI
distribution is empty, run
git submodule init
git submodule update
before proceeded with a CMake-based build.
(For more information about BLT, see its github page
https://github.com/LLNL/blt)
The object files for SAMRAI files are typically compiled into a separate
directory from the SAMRAI source. This approach facilitates building separate
SAMRAI installations in the same directory structure (e.g., for different
architectures that share a file system). This object directory can be placed
at the same level as the SAMRAI distribution:
SAMRAI-vX.Y.Z/
SAMRAI/
objs/
where the directory name ``objs'' is arbitrary. To configure SAMRAI for your
architecture, do the following:
(a) mkdir objs
(b) cd objs
(c) cmake ../SAMRAI [options]
where [options] are a set of optional flags to select different configuration
options.
See the section "CMake Options" below for more details on supported
configuration options.
(4) Making the Libraries
------------------------
The CMake configuration is set up by default to build all of the SAMRAI
libraries as well as the test code and executables. If you just want the
SAMRAI libraries so that you can link them into your application, you should
run cmake with the option ``-DENABLE_TESTS=OFF''. If you already ran cmake
without this option, that's OK, just run it again with this option added.
To build, make sure you are in directory ``objs'' and use GNU make
(standard Unix make will NOT work) to build the libraries.
(a) cd objs
(b) make
At any time if you want to start over you may remove all object and library
files via ``make clean''.
(4) Making the tools
------------------------
The optional tools may be built if you add this to the cmake line:
-DENABLE_TOOLS=ON
This includes the restart-redistribute utility to convert a SAMRAI
restart file to run on N processors to one compatible with running on
M processors.
(6) Installing the Libraries
----------------------------
After the libraries have been created, install the libraries and configuration
files using:
(a) make install
For this to work, you must have used the ``-DCMAKE_INSTALL_PREFIX=[directory]''
to specify where you want your installed files to be located.
``make install'' will move files into the specified directory.
(6) Cleaning Up
---------------
After installing the libraries, you may remove the source and
object directory ``objs'' in which SAMRAI was compiled. However,
it is recommended that you do not remove the SAMRAI source
directory, since it contains source files for the debugger.
CMake Options:
-------------------
There are many CMake options that can be put on the CMake line. Here we
list some of the most useful options.
Compilers:
-DCMAKE_CXX_COMPILER=[C++ compiler]
-DCMAKE_Fortran_COMPILER=[Fortran compiler]
-DCMAKE_CUDA_COMPILER=[CUDA compiler] (optional)
In order to compile with CUDA, you must also add -DENABLE_CUDA=On to the
CMake line.
Libraries:
Setting most optional third-party libraries follows a straightforward pattern.
-DHDF5_DIR=[HDF5 installation location]
-DHYPRE_DIR=[HYPRE installation location]
-DPETSC_DIR=[PESTC installation location]
-DSILO_DIR=[SILO installation location]
-DSUNDIALS_DIR=[Sundials installation location]
-DCONDUIT_DIR=[Conduit installation location]
HDF5 is the only one of these that is included by default. CMake usually will
be able to find an HDF5 installation without one being specified on the
command line, but this option allows you to point explicitly to an
installation.
Setting Umpire and RAJA requires slightly different usage, due to how these
libraries have been set up to have their installations interact with CMake.
Note the lower-case characters in the "umpire_DIR" symbol.
-Dumpire_DIR=[Umpire installation location]/share/umpire/cmake
-DRAJA_DIR=[RAJA installation location]/share/umpire/cmake
SAMRAI's current usage of RAJA depends on Umpire, so a configuration with
RAJA but without Umpire will exit with an error. A configuration with Umpire
but without RAJA is allowed.
All of these libraries can also be explicitly excluded using
-DENABLE_HDF5=OFF
-DENABLE_HYPRE=OFF
-DENABLE_PETSC=OFF
-DENABLE_SILO=OFF
-DENABLE_SUNDIALS=OFF
-DENABLE_CONDUIT=OFF
-DENABLE_UMPIRE=OFF
-DENABLE_RAJA=OFF
Build options:
This CMake option governs usage of optimization or debugging flags:
-DCMAKE_BUILD_TYPE=[Release|Debug|RelWithDebInfo]
Choose whether to build executables or just the libraries:
-DENABLE_TESTS=[ON|OFF] (Default ON)
-DENABLE_TOOLS=[ON|OFF] (Default OFF)
Installation options:
-DCMAKE_INSTALL_PREFIX=[installation directory]
Documentation:
To enable the build of documenation using doxygen, add:
-DENABLE_DOCS=ON
Versions of libraries/tools used by the development team
--------------------------------------------------------
The following are the versions of libraries and tools we have used in
the development of the library. This list should not be considered
as a requirement list (with the exception of PETSc), it is intended to
provide information on versions we believe should be working. Users
who encounter problems compiling and linking and want to see if they
are using a version significantly older or newer. The versions listed
are used in our regression test suite.
Tool Version(s)
-------------- --------------------------------------
gcc 8.1.0, 10.3.1
HDF5 1.8.5
MVAPICH2 2.3
PETSc 3.21.0
Sundials 7.0.0
hypre 2.31.0
VisIt 3.1.1
doxygen 1.6.1
graphviz 2.26
Umpire v2024.02.0
RAJA v2024.02.0
Visualization Tools:
--------------------
SAMRAI uses the VisIt visualization system. This replaces the
vizamrai utility used in the past. VisIt binaries, source, and
documentation are available at http://www.llnl.gov/visit. You must
compile with HDF in order to create VisIt output files. See the
SAMRAI/test/applications/Euler program for an example of how to use
the VisItDataWriter.
Location users can find VisIt in /usr/apps/visit on CASC systems and
/usr/gapps/ on LC systems.
Performance Analysis Tools:
---------------------------
SAMRAI can be build with the Caliper library to allow for code annotations
that can be used with performance analysis and profiling tools.
See https://github.com/LLNL/Caliper
Documentation
--------------------
SAMRAI uses the Doxygen system for building code documentation. The
Graphviz is also utilized for building the inheritance/relationship
diagrams within the documentation.
To enable a build of the documentation using doxygen, run cmake with the
option ``-DENABLE_DOCS=ON'' and then run ``make doxygen_docs''.
Please note that older version of Doxygen will hang when building the
documentation. The SAMRAI team is using the versions indicated above;
if you are using older versions it may not work.
Doxygen is available at: http://www.stack.nl/~dimitri/doxygen
Graphviz is available at: http://www.graphviz.org/
****************************************************************************
****************************************************************************