/
readme.html
752 lines (645 loc) · 44.6 KB
/
readme.html
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
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>The deal.II Readme</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<link href="screen.css" rel="StyleSheet" />
<meta name="copyright" content="Copyright (C) 1998 - 2018 by the deal.II Authors" />
<meta name="keywords" content="deal.II" />
</head>
<body>
<h1>Installation instructions and further information on <acronym>deal.II</acronym> </h1>
<div class="toc">
<ol>
<li> <a href="#prerequisites">System requirements</a>
<ol>
<li> <a href="#supported">Supported platforms</a></li>
<li> <a href="#additional-software">Additional software requirements</a></li>
</ol>
</li>
<li> <a href="#installation">Installation</a>
<ol>
<li> <a href="#unpacking">Unpacking</a></li>
<li> <a href="#configuration">Configuring and building the library</a></li>
<li> <a href="#documentation">Configuring and building the documentation</a></li>
<li> <a href="#configuration-options">Configuration options</a>
<ol>
<li> <a href="#optional-compilation">Selecting optional compilation features</a></li>
<li> <a href="#optional">Selecting optional library features</a></li>
<li> <a href="#optional-software">Optional interfaces to
other software packages</a></li>
<li> <a href="#conf-details">More information on configuring
and building the library</a></li>
</ol>
</li>
</ol>
</li>
<li> <a href="#license">License</a></li>
</ol>
</div>
<a name="prerequisites" />
<h2>System requirements</h2>
<a name="supported" />
<h3>Supported platforms</h3>
<p>
<acronym>deal.II</acronym> is mostly developed on Linux using the
<a href="http://gcc.gnu.org">GCC</a> compiler. However, it is not platform specific and we strive to keep the source code compliant with the <a href="https://www.iso.org/standard/50372.html">C++ 2011
Standard</a> (see also <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3337.pdf">here</a> for a copy of the C++11 standard).
</p>
<p>
<acronym>deal.II</acronym> supports at least the following platforms:
</p>
<ul>
<li>GNU/Linux: GCC version 4.8 or later; Clang version 3.3 or later; ICC versions 15 or later</li>
<li>Mac OS X: GCC version 4.8 or later; Clang version 3.3 or later. Please see the <a href="https://github.com/dealii/dealii/wiki/MacOSX" target="_top">deal.II Wiki</a> for installation instructions.</li>
<li>Windows: experimental support for Visual Studio 2017. Please have a look at the
<a href="https://github.com/dealii/dealii/wiki/Frequently-Asked-Questions#can-i-use-dealii-on-a-windows-platform">
FAQ</a> and at the <a href="https://github.com/dealii/dealii/wiki/Windows" target="_top">deal.II Wiki</a> for more information and alternative solutions.</li>
</li>
</ul>
<p>
Most other combinations of POSIX-style operating systems and C++ Standard compliant compilers should also work. <i>If they don't,
please report it as a bug.</i>
</p>
<a name="additional-software"></a>
<h3>Additional software requirements</h3>
<p>
In order to compile and use <acronym>deal.II</acronym> you need to have the following programs installed:
</p>
<ul>
<li>
<a href="http://www.cmake.org/" target="_top">CMake</a> version 2.8.12 or later
</li>
<li>
<a href="http://www.gnu.org/software/make/" target="_top">GNU make</a>, version 3.78 or later (or any other generator supported by CMake)
</li>
<li>
For generating the documentation:
<a href="http://www.perl.org/" target="_top">Perl 5.x</a>,
<a href="http://www.doxygen.org/" target="_top">doxygen</a> and <code>dot</code>, which is part of the
<a href="http://www.graphviz.org" target="_top">GraphViz</a> package
</li>
<li>
For debugging programs, we have found that the
<a href="http://www.gnu.org/software/gdb/" target="_top">GNU
debugger GDB</a> is an invaluable tool. GDB is a text-based tool not always easy to use; <a href="http://www.kdbg.org/" target="_top">kdbg</a>, is one of many graphical user interfaces for it. Most integrated development environments
like <a href="http://www.kdevelop.org/" target="_top">kdevelop</a> or <a href="http://eclipse.org/" target="_top">Eclipse</a> have built in debuggers as well. <acronym>deal.II</acronym> has some support for pretty printing its own classes
through GDB; see <a href="users/gdb.html">the GDB configuration guide</a> for setup information.
</li>
<li>
<p>
The library generates output in formats readable by
<a href="http://www.gnuplot.info/" target="_top">GNUPLOT</a>,
<a href="http://www.generalmeshviewer.com/" target="_top">GMV
(general mesh viewer)</a>,
<a href="http://www.tecplot.com/" target="_top">Tecplot</a> (ASCII and binary),
<a href="http://www.vtk.org/" target="_top">Visualization Toolkit (Vtk)</a>,
<a href="http://www.avs.com" target="_top">AVS Explorer</a>,
<a href="http://www.opendx.org" target="_top">Open DX</a>,
<a href="http://www.povray.org" target="_top">Povray</a>, and directly to Encapsulated Postscript.
</p>
<p>
<code>gnuplot</code> and a postscript viewer (for <code>eps</code>) should be available almost everywhere. In the last few years, most new visualization programs have moved to support
<code>vtk</code>/<code>vtu</code> format. There are a number of excellent programs that can read <code>vtk</code> and
<code>vtu</code>, such as
<a href="http://www.llnl.gov/visit/" target="_top">Visit</a>,
<a href="http://www.paraview.org/" target="_top">ParaView</a>, as well as others. Povray is freely available for almost all platforms. AVS is a commercial program available for most Unix flavors. Tecplot is a commercial program available
for Windows and most Unix platforms.
</p>
<p>
In case you didn't find your favorite graphics format above, adding a new writer to <acronym>deal.II</acronym> is not too difficult, as only a simple intermediate format needs to be converted into output (without references to cells, nodes,
types of finite elements, and the like).
</p>
</li>
</ul>
<a name="installation"></a>
<h2>Installation</h2>
<a name="unpacking"></a>
<h3>Unpacking</h3>
<p>
The whole library usually comes as a <code>tar.gz</code> file, which is a file archive compressed with gzip. After downloading it, unpack it using either
</p>
<pre>
gunzip deal.II-X.Y.Z.tar.gz
tar xf deal.II-X.Y.Z.tar
</pre>
<p>or, if you have GNU tar with</p>
<pre>
tar -xvf deal.II-X.Y.Z.tar.gz
</pre>
<p><b>Note:</b> You will want to hang on to the source files of <acronym>deal.II</acronym> after installation as it makes developing much simpler. Consequently, you should do the steps above in a permanent directory, not on <code>/tmp</code> as one often
does when installing software.
</p>
<a name="configuration"></a>
<h3>Configuring and building the library</h3>
<p>
<acronym>deal.II</acronym> uses the
<a href="http://www.cmake.org/" target="_top">CMake</a> integrated configuration and build system. Unpacking will create a subdirectory <tt>deal.II/</tt> in the current directory. Then do the following steps:</p>
<pre>
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/path/to/install/dir ../deal.II
make install
make test
</pre>
<p>
These steps compile, link, install the deal.II library, and run a few consistency checks. The whole process should take between a few minutes and an hour, depending on your machine.
</p>
<p>
<b>Note:</b></p>
<ul>
<li> <code>/path/to/install/dir</code> is the directory which deal.II should be installed into. This can be a directory in your home directory (e.g., <code>~/bin/deal.II</code>) or a directory such as <code>/usr/local</code> if you have root privileges.
Another option is to use something like <code>`pwd`/../installed/</code> (note the backticks). Make sure the installation directory is not the same as the location where you unpacked <tt>deal.II/</tt>.
</li>
<li> If your machine has multiple processors, use <code>make
-jN install</code> in the second to last step instead, where <code>N</code> is the number of simultaneous build processes you want <code>make</code> to use at any given time. Allowing <code>make</code> to use more simultaneous build processes (assuming you have that many processor
cores) will greatly lower the build time. <code>make test</code> automatically runs in parallel and no <code>-jN</code> flag should be supplied to it.
</li>
<li> If you do not intend to modify the <acronym>deal.II</acronym> sources and recompile things, then you can remove the <code>build/</code> directory after the last step.
</li>
<li> In principle, after installing <acronym>deal.II</acronym>, you can remove the source directory as well (i.e., the directory into which <code>tar</code> unpacked the file you downloaded) since projects using deal.II should only need files that
have been installed. However, you will find it convenient to keep the source files around anyway, for one reason: When debugging you often end up with assertions for which you'd like to see the place in the library's source files that triggered
it.
</li>
<li> The <acronym>deal.II</acronym> <code>CMake</code> system can accept a significant number of configuration parameters. See the discussion <a href="#configuration-options">below</a>.
</li>
<li> If you are changing part of the <acronym>deal.II</acronym> code itself, you can re-compile the library using only the last two commands above in the previously created build directory. It is also possible to change the configuration used in this
directory by calling <code>cmake</code> a second time, possibly with different arguments. However, this sometimes leads to surprising results and you may not get exactly what you were hoping for. For more information, see <a href="users/cmake.html">here</a>.
</li>
</ul>
<p>
The commands above build and install the <acronym>deal.II</acronym> libraries in two variants:
</p>
<ul>
<li>
<p><i>Debug mode</i>: This version of the library is compiled with compiler flags so that the library contains information that can be used by debuggers.
</p>
<p>
In addition, this library contains a great number of safety checks on most arguments of all functions you could possibly call. These assertions have proven to be an invaluable means to finding programming bugs since they will almost always abort your
program if something goes wrong. In our experience, more than ninety per cent of all errors are invalid parameters (such as vectors having the wrong size, etc.) and they are usually found almost instantaneously, displaying the file name
and line number of where the problem occurred.
</p>
<p>
With GCC Debug mode, by default, uses the <code>-Og</code> flag. It promises most of the debugging experience of <code>-O0</code> but at a better performance. This is a reasonable choice for unit tests and enables numerous asserts within
the library. Sometimes, however, one needs Debug mode to use
<code>-O0</code>, where all compiler optimizations are avoided and code and variables are exactly as indicated in the C++ program (e.g. with <code>-Og</code> GCC 6.2.0 optimizes out local variables). This can be achieved by configuring
<acronym>deal.II</acronym> with
<code>-DDEAL_II_HAVE_FLAG_Og=false</code>.
</p>
</li>
<li> <i>Optimized mode</i>: You will want to link with this version of the library once you know that your program is working as expected. It does not contain the safety checks any more and is compiled with aggressive compiler optimizations. The resulting
executables are smaller and will run between 2 and 10 times faster than the debug executables.
</li>
</ul>
<p>
At this point, you have generated everything necessary to write programs based on <acronym>deal.II</acronym>. If you are new to
<acronym>deal.II</acronym>, you may want to continue with the
<a href="doxygen/deal.II/Tutorial.html" target="_top">tutorial</a>.
</p>
<a name="documentation"></a>
<h3>Configuring and building the documentation</h3>
<p>
All the documentation about the version that you downloaded and that can be found at the <a href="http://www.dealii.org/" target="_top">
http://www.dealii.org/</a> domain can also be generated locally. To do so, invoke <code>cmake</code> in the build instructions above as follows:
</p>
<pre>
cmake -DDEAL_II_COMPONENT_DOCUMENTATION=ON -DCMAKE_INSTALL_PREFIX=/path/install/dir ../deal.II
</pre>
<p>
For this to succeed, you will need <a href="http://www.perl.org/" target="_top">Perl 5.x</a>,
<a href="http://www.doxygen.org/" target="_top">doxygen</a> and <code>dot</code> (which is part of the <a href="http://www.graphviz.org" target="_top">GraphViz</a> package) to be installed.
</p>
<p>
The documentation contains links to pictures (e.g., for the tutorial programs) that are by default stored online at the dealii.org domain. If you want to use the documentation completely offline, you can run the <code>contrib/utilities/makeofflinedoc.sh</code> script in an installed documentation directory to download all images.
</p>
<p> Finally, the default for locally installed documentation is to render formulas as images. You can force formulas to be displayed via the MathJax system by adding <code>-DDEAL_II_DOXYGEN_USE_MATHJAX=ON</code> to the CMake call above. These formulas
are then rendered natively by the browser. With <code>-DDEAL_II_DOXYGEN_USE_ONLINE_MATHJAX=OFF</code> CMake will try to find a local installation of MathJax scripts, otherwise the online version of the scripts will be used in the documentation.
</p>
<p>
Upon calling <code>make</code> and <code>make install</code>, this will install both this readme, other installation instructions, as well as the
<a href="doxygen/deal.II/index.html" target="_top">manual that documents
all functions and classes</a> as well as the <a href="doxygen/deal.II/Tutorial.html" target="_top"> tutorial
of well-documented example programs</a> (the "steps").
</p>
<p>
<b>Note:</b> Generating this documentation can take a <i>really long
time</i> — running doxygen through our hundreds of thousands of lines of code can take 15-20 minutes even on a fast machine during which you will not get any output from <code>make</code>.
</p>
<a name="configuration-options"></a>
<h3>Configuration options</h3>
<p>
<acronym>deal.II</acronym> has a large number of optional interfaces to other libraries. <b>By default, <code>cmake</code> will automatically
enable support for all external libraries it can find in default
paths.</b> However, this behavior can be changed using command line switches to the initial call to <code>cmake</code>. A detailed description can be found here: <a href="users/cmake.html">Detailed build system description</a>.
</p>
<p>
In the following, let us summarize the most common configuration options.
</p>
<a name="optional-compilation" />
<h4>Selecting optional compilation features</h4>
<ul>
<p>
<li> <i>Unity build</i>: deal.II may be compiled with a unity build; that is, one may configure the build process so that the library is compiled as a few large files instead of many small ones. The unity build feature may be enabled by passing
the <code>-DDEAL_II_UNITY_BUILD=ON</code> argument to <code>cmake</code>. This feature is disabled by default.
</p>
</ul>
<a name="optional" />
<h4>Selecting optional library features</h4>
<ul>
<li>
<p>
<i>Threading</i>: By default, deal.II supports parallelism between multiple cores on the same machine using threads and a task-based model built on the
<a href="http://threadingbuildingblocks.org/" target="_top">Threading Building Blocks</a>. You can switch threading off by passing the <code>-DDEAL_II_WITH_THREADS=OFF</code> argument to <code>cmake</code>.
</p>
</li>
<li>
<p>
<i>MPI</i>: To enable parallel computations beyond a single node using the <a href="http://mpi-forum.org/" target="_top">Message
Passing Interface (MPI)</a>, pass the
<code>-DDEAL_II_WITH_MPI=ON</code> argument to <code>cmake</code>. If <code>cmake</code> found MPI but you specifically do not want to use it, then pass <code>-DDEAL_II_WITH_MPI=OFF</code>.
The minimal supported version is MPI-2.0.
</p>
</li>
<li>
<p>
<i>64bit indices</i>: By default, deal.II use unsigned int (32bit) indices for degrees of freedom, using the <code>types::global_dof_index</code> type. This limits the number of unknowns to approximately four billions. If larger problem
must be solved, pass the
<code>-DDEAL_II_WITH_64BIT_INDICES=ON</code> argument to
<code>cmake</code>. You will not be able to solve problems of this size on a single machine, but only when using clusters of computers and linear algebra packages PETSc or Trilinos. To use this option with PETSc, PETSc must be compiled
with the option <code>--with-64-bit-indices</code>.
</p>
</li>
</ul>
<a name="optional-software" />
<h4>Optional interfaces to other software packages</h4>
<p>
When configuring interfacing to external libraries, the
<code>cmake</code> script by default tries to find all of these libraries in a number of standard locations on your file system. For <i>optional</i> interfaces, it gives up if the library is not found and <acronym>deal.II</acronym> will be built
without support for them. However, there is one interface that we <i>need</i> to have: <a href="http://www.boost.org/" target="_top">BOOST 1.59</a> or newer. If it is not found externally <code>cmake</code> will resort to the bundled boost version
that is part of the <acronym>deal.II</acronym> tar file.
</p>
<p>
The following paragraphs describe how the interfaces to the various packages, <acronym>deal.II</acronym> interacts with, can be configured.
</p>
<p><b>Notes:</b></p>
<ul>
<li>
<b>The majority of libraries mentioned below should be readily
packaged by most Linux distributions. Usually you need to
install a <i>development</i> version of a library package,
e.g. ending in <code>-dev</code> or <code>-devel</code>.
After that <code>cmake</code> will automatically find the
library and use it.</b>
</li>
<li>
Configuring the interface to a self compiled package, say <code>foo</code> can usually be done by specifying
<code>-DFOO_DIR=/path/to/foo</code>. Alternatively, you can set <code>FOO_DIR</code> as an environment variable in your
<code>.bashrc</code> or <code>.cshrc</code> file so that you do not have to enter this argument again the next time you invoke <code>cmake</code> in a fresh build directory. Any value passed on the command line wins over a value that may be
found in an environment variable.
</li>
<li>
To explicitly enable or disable support for a library <code>foo</code> use the argument
<code>-DDEAL_II_WITH_FOO=ON</code> resp.
<code>-DDEAL_II_WITH_FOO=OFF</code> for <code>cmake</code>.
</li>
</ul>
<dl>
<dt><a name="ADOL-C"/>
<a href="https://projects.coin-or.org/ADOL-C" target="_top">ADOL-C</a></dt>
<dd>
<p>
<a href="https://projects.coin-or.org/ADOL-C" target="_top">ADOL-C</a> is a package that facilitates the evaluation of first and higher derivatives of vector functions. In particular, it can be used for automatic differentiation. For using
<a href="https://projects.coin-or.org/ADOL-C/" target="_top">ADOL-C</a> with deal.II, version 2.6.4 or newer is required. To use a self compiled version, pass
<code>-DADOLC_DIR=/path/to/adolc</code> to the deal.II CMake call.
</p>
</dd>
<dt><a name="ARPACK"/>
<a href="http://www.caam.rice.edu/software/ARPACK/" target="_top">ARPACK</a></dt>
<dd>
<p>
<a href="http://www.caam.rice.edu/software/ARPACK/" target="_top">ARPACK</a> is a library for computing large scale eigenvalue problems.
<a href="http://www.caam.rice.edu/software/ARPACK/" target="_top">ARPACK</a> should be readily packaged by most Linux distributions. To use a self compiled version, pass
<code>-DARPACK_DIR=/path/to/arpack</code> to the deal.II CMake call. For a detailed description on how to compile ARPACK and linking with deal.II, see
<a href="external-libs/arpack.html" target="body">this page</a>.
</p>
</dd>
<dt><a name="Assimp"/>
<a href="http://www.assimp.org/" target="_top">Assimp</a></dt>
<dd>
<p>
<a href="http://www.assimp.org/" target="_top"></a> is a portable Open Source library to import various well-known 3D model formats in a uniform manner. A subset of these formats can be read from within deal.II to generate two-dimensional
meshes, possibly embedded in a three-dimensional space.
<a href="http://www.assimp.org/" target="_top">Assimp</a> should be readily packaged by most Linux distributions. To use a self compiled version, pass
<code>-DASSIMP_DIR=/path/to/assimp</code> to the deal.II CMake call.
</p>
</dd>
<dt>
<a name="blas"></a>
<a href="http://www.netlib.org/blas/" target="_top">BLAS</a>,
<a href="http://www.netlib.org/lapack/" target="_top">LAPACK</a>
</dt>
<dd>
<p>
<a href="http://www.netlib.org/blas/" target="_top">BLAS</a> (the <i>Basic Linear Algebra Subroutines</i>) and
<a href="http://www.netlib.org/lapack/" target="_top">LAPACK</a> (
<i>Linear Algebra Package</i>) are two packages that support low-level linear algebra operations on vectors and dense matrices. Both libraries should be packaged by almost all Linux distributions and found automatically whenever available.
(You might have to install development versions of the libraries for <acronym>deal.II</acronym> being able to use them). For details on how to set up <acronym>deal.II</acronym> with a non standard BLAS/LAPACK implementation, see the
<a href="users/cmake.html#advanced">advanced
setup</a> section in the CMake ReadME.
</p>
</dd>
<dt><a name="CUDA"></a><a href="https://developer.nvidia.com/cuda-zone">CUDA</a></dt>
<dd>
<p>
<a href="https://developer.nvidia.com/cuda-zone">CUDA</a> is a parallel computing platform and API model created by Nvidia. It allows software developers and software engineers to use CUDA-enabled GPU for general purpose processing. Details
about compatibility and configuration can be found <a href=external-libs/cuda.html target="body">here</a>.
</p>
<dt><a name="Ginkgo"/>
<a href="https://ginkgo-project.github.io/" target="_top">Ginkgo</a></dt>
<dd>
<p>
<a href="https://ginkgo-project.github.io/" target="_top">Ginkgo</a>
is a numerical linear algebra library with highly optimized kernels
for many core architectures with a focus on fine level parallelism.
It allows for easy switching of the executing paradigm (CUDA, OpenMP, etc.)
while providing a multitude of linear solvers and preconditioners
and extension to other linear operators with minimal changes required in the code.
To enable Ginkgo, pass <code>-DGINKGO_DIR=/path/to/ginkgo</code> to CMake when
configuring deal.II. For more detailed instructions, one can refer to
<a href="external-libs/ginkgo.html" target="body">this page</a>.
</p>
</dd>
<dt><a name="Gmsh"/>
<a href="http://gmsh.info/" target="_top">Gmsh</a></dt>
<dd>
<p>
<a href="http://gmsh.info/" target="_top">Gmsh</a>
is a 3D mesh generator. The executable can be used
to create meshes from within deal.II by specifying
the relevant input data. Gmsh should be readily
packaged by most Linux distributions. To use a
self compiled version,
pass <code>-DGMSH_DIR=/path/to/gmsh</code> to the
deal.II CMake call. Note that netgen, tetgen and
blas support has to be enabled in Gmsh.
</p>
</dd>
<dt><a name="GSL"></a><a href="http://www.gnu.org/software/gsl/">GSL</a></dt>
<dd>
<p>
The <a href="http://www.gnu.org/software/gsl/">GNU Scientific Library</a> provides a wide range of mathematical routines such as random number generators, special functions and least-squares fitting.
<a href="http://www.gnu.org/software/gsl/">GSL</a> should be readily packaged by most Linux distributions. To use a self compiled version, pass
<code>-DGSL_DIR=/path/to/gsl</code> to the deal.II CMake call.
</p>
</dd>
<dt><a name="HDF5"></a><a href="http://www.hdfgroup.org/HDF5/">HDF5</a></dt>
<dd>
<p>
The <a href="http://www.hdfgroup.org/HDF5/">HDF5 library</a> provides graphical output capabilities in <code>HDF5/XDMF</code> format.
<a href="http://www.hdfgroup.org/HDF5/">HDF5</a> should be readily packaged by most Linux distributions. To use a self compiled version, pass
<code>-DHDF5_DIR=/path/to/hdf5</code> to the deal.II CMake call.
</p>
</dd>
<dt><a name="metis"></a><a href="http://glaros.dtc.umn.edu/gkhome/metis/metis/overview"
target="_top">METIS</a></dt>
<dd>
<p>
<a href="http://glaros.dtc.umn.edu/gkhome/metis/metis/overview" target="_top">METIS</a> is a library that provides various methods to partition graphs. <acronym>deal.II</acronym> uses it in programs like the step-17 tutorial to partition
a mesh for parallel computing. To use a self compiled version, pass
<code>-DMETIS_DIR=/path/to/metis</code> to the deal.II CMake call.
<acronym>deal.II</acronym> supports METIS 5 and later.
</p>
<p>
<b>Note:</b> A more modern way to support parallel computations is shown in the step-40 tutorial program and is based on the <code>p4est</code> library instead of METIS. See below on installing <code>p4est</code>.
</p>
</dd>
<dt>
<a name="muparser"></a>
<a href="http://muparser.beltoforion.de/">muparser</a>
</dt>
<dd>
<p>
<a href="http://muparser.beltoforion.de/">muparser</a> is a library that allows to enter functions in text form and have them interpreted at run time. This is particularly useful in input parameter files. <code>cmake</code> will usually
find the version of this library that comes bundled with <acronym>deal.II</acronym>, but you can specify <code>-DMUPARSER_DIR=/path/to/muparser</code> if desired.
</p>
</dd>
<dt><a name="nanoflann"/>
<a href="https://github.com/jlblancoc/nanoflann" target="_top">nanoflann</a></dt>
<dd>
<p>
<a href="https://github.com/jlblancoc/nanoflann" target="_top">nanoflann</a> is a C++11 header-only library for building KD-Trees of datasets with different topologies. In particular, it can be used for operations such as finding the
vertex or cell closest to a given evaluation point that occur frequently in many applications using unstructured meshes. scale eigenvalue problems.
<a href="https://github.com/jlblancoc/nanoflann" target="_top">nanoflann</a> should be readily packaged by most Linux distributions. To use a self compiled version, pass
<code>-DNANOFLANN_DIR=/path/to/nanoflann</code> to the deal.II CMake call.
</p>
</dd>
<dt><a name="netcdf"></a><a href="http://www.unidata.ucar.edu/software/netcdf/" target="_top">NetCDF</a></dt>
<dd>
<p>
<a href="http://www.unidata.ucar.edu/software/netcdf/" target="_top">NetCDF</a> is a library that provides services for reading and writing mesh data (and many other things). <acronym>deal.II</acronym> can use it to read meshes via one
of the functions of the <code>GridIn</code> class.
<a href="http://www.unidata.ucar.edu/software/netcdf/" target="_top">NetCDF</a> should be readily packaged by most Linux distributions. To use a self compiled version, pass
<code>-DNETCDF_DIR=/path/to/netcdf</code> to <code>cmake</code>.
<em>The deal.II NetCDF bindings are only compatible with an obsolete version of NetCDF and will be removed in a future release of the library unless newer bindings are contributed.</em>
</p>
</dd>
<dt>
<a name="opencascade"></a>
<a href="http://www.opencascade.org/">OpenCASCADE</a>
</dt>
<dd>
Open CASCADE Technology is a software development kit for applications dealing with 3D CAD data, freely available in open source. Our internal interface works with the legacy version of OpenCASCADE, which you can download and install from the official
website, as well as with the OpenCASCADE Community Edition (OCE, available at
<a href="https://github.com/tpaviot/oce">https://github.com/tpaviot/oce</a>), which offers a cmake interface for its compilation. Alternatively, you can install one of the many external applications that ship with OpenCASCADE internally
(for example
<a href="http://www.salome-platform.org/">SALOME</a>, or
<a href="http://www.freecadweb.org/">FreeCAD</a>). Further installation instructions can be found <a href="external-libs/opencascade.html" target="body">here</a>.
</dd>
<dt><a name="p4est"></a><a href="http://www.p4est.org/" target="_top">p4est</a></dt>
<dd>
<p>
<a href="http://www.p4est.org/" target="_top">p4est</a> is a library that <acronym>deal.II</acronym> uses to distribute very large meshes across multiple processors (think meshes with a billion cells on 10,000 processors). Using and
installing p4est is discussed <a href="external-libs/p4est.html" target="body">here</a>. To use a self compiled version, pass the argument
<code>-DP4EST_DIR=/path/to/p4est</code> to the
<code>cmake</code> command.
</p>
</dd>
<dt><a name="petsc"></a><a href="http://www.mcs.anl.gov/petsc/"
target="_top">PETSc</a></dt>
<dd>
<p>
<a href="http://www.mcs.anl.gov/petsc/" target="_top">PETSc</a> is a library that supports parallel linear algebra and many other things.
<a href="http://www.mcs.anl.gov/petsc/" target="_top">PETSc</a> is already packaged by some Linux distributions and should be found automatically if present. To use a
self compiled version of PETSc, add <code>-DPETSC_DIR=/path/to/petsc
-DPETSC_ARCH=architecture</code> to the argument list for
<code>cmake</code>. The values for these arguments must be the same as those specified when building PETSc.
</p>
<p>
To disable the PETSc interfaces in cases where <code>cmake</code> automatically finds it, use <code>-DDEAL_II_WITH_PETSC=OFF</code>. More information on configuring and building PETSc can be found <a href="external-libs/petsc.html"
target="body">here</a>.
</p>
</dd>
<dt>
<a name="scalapack"></a>
<a href="http://www.netlib.org/scalapack/">ScaLAPACK</a>
</dt>
<dd>
<p>
<a href="http://www.netlib.org/scalapack/">scalapack</a> is a library of high-performance linear algebra routines for parallel distributed memory machines. ScaLAPACK solves dense and banded linear systems, least squares problems, eigenvalue
problems, and singular value problems. In order to enable this feature, add
<code>-DSCALAPACK_DIR=/path/to/scalapack</code> to the argument list for
<code>cmake</code>. If ScaLAPACK does not have embedded BLACS, you might need to pass <code>-DBLACS_DIR=/path/to/blacs</code> as well.
</p>
</dd>
<dt><a name="slepc"></a><a href="http://www.grycap.upv.es/slepc/" target="_top">SLEPc</a></dt>
<dd>
<p>
<a href="http://www.grycap.upv.es/slepc/" target="_top">SLEPc</a> is a library for eigenvalue computations that builds on PETSc. Its configuration works just like that for PETSc, except that the variable to set is <code>SLEPC_DIR</code>.
For the interface with SLEPc to work, <acronym>deal.II</acronym>'s PETSc interface must also be configured correctly (see above).
</p>
<p>
To disable the SLEPc interfaces in cases where <code>cmake</code> automatically finds it, use <code>-DDEAL_II_WITH_PETSC=OFF</code>. More information on configuring and building SLEPc can be found <a href="external-libs/slepc.html"
target="body">here</a>.
</p>
</dd>
<dt><a name="Sundials"/>
<a href="https://computation.llnl.gov/projects/sundials" target="_top">SUNDIALS</a></dt>
<dd>
<p>
<a href="https://computation.llnl.gov/projects/sundials" target="_top">SUNDIALS</a> is a collection of solvers for nonlinear and differential/algebraic equations.
<a href="https://computation.llnl.gov/projects/sundials" target="_top">SUNDIALS</a> should be readily packaged by most Linux distributions. To use a self compiled version,
specify
<code>-DSUNDIALS_DIR=/path/to/sundials</code> to the deal.II CMake call.
</p>
</dd>
<dt><a name="SymEngine"/>
<a href="https://symengine.github.io/" target="_top">SymEngine</a></dt>
<dd>
<p>
<a href="https://github.com/symengine/symengine/" target="_top">SymEngine</a> is a symbolic manipulation package, implementing the building blocks of a computer algebra system (CAS) similar to <a href="https://www.sympy.org/en/index.html" target="_top">SymPy</a>. In particular, it can be used for symbolic differentiation. For using
<a href="https://symengine.github.io/" target="_top">SymEngine</a> with deal.II, version 0.4 or newer is required. To use a self compiled version, pass
<code>-DSYMENGINE_DIR=/path/to/symengine</code> to the deal.II CMake call.
</p>
</dd>
<dt><a name="tbb"></a><a href="http://www.threadingbuildingblocks.org/"
target="_top">Threading Building Blocks (TBB)</a></dt>
<dd>
<p>
The <a href="http://www.threadingbuildingblocks.org/" target="_top">Threading Building Blocks (TBB)</a> is a library that provides advanced services for using multiple processor cores on a single machine and is used in <acronym>deal.II</acronym> to parallelize many operations. If not found in a system-wide location, <code>cmake</code> will resort to the version bundled as part of the <acronym>deal.II</acronym> download. It is always enabled unless threads are explicitly disabled,
see <a href="#optional">above</a>.
</p>
</dd>
<dt><a name="trilinos"></a><a href="http://trilinos.org" target="_top">Trilinos</a></dt>
<dd>
<p>
<a href="http://trilinos.org"
target="_top">Trilinos</a> is a library for
parallel linear algebra and all sorts of other
things as well. To interface with a self compiled
version of <a href="http://trilinos.org"
target="_top">Trilinos</a>
add <code>-DTRILINOS_DIR=/path/to/trilinos</code>
to the argument list
for <code>cmake</code>. Alternatively, you can
also set an environment
variable <code>TRILINOS_DIR</code>
and <code>cmake</code> will pick up this path.
</p>
<p>
To disable the Trilinos interfaces in cases where
<code>cmake</code> automatically finds it, use
<code>-DDEAL_II_WITH_TRILINOS=OFF</code>. More details about compatibility and configuration can be found
<a href="external-libs/trilinos.html" target="body">here</a>.
</p>
</dd>
<dt><a name="umfpack"></a><a href="http://faculty.cse.tamu.edu/davis/suitesparse.html"
target="_top">UMFPACK</a></dt>
<dd>
<p>
<a href="http://faculty.cse.tamu.edu/davis/suitesparse.html">UMFPACK</a>, which is part of SuiteSparse, is a sparse direct solver that we often use in prototype codes where the goal is to simply get a linear system solved robustly.
The interface will be enabled by default, either using a version installed on your system of using a version that comes bundled with
<acronym>deal.II</acronym>. It can be disabled explicitly by using the
<code>-DDEAL_II_WITH_UMFPACK=OFF</code> argument. To use a self compiled version, pass the argument
<code>-DUMFPACK_DIR=/path/to/umfpack</code> to the
<code>cmake</code> command.
</p>
<p>
SuiteSparse has its own license. To use it with
deal.II, please read it and make sure that you agree
with it. You can find the license of SuiteSparse inside
the SuiteSparse download at the link given above. We
include UMFPACK in the deal.II repository courtesy of
its author, <a href="http://faculty.cse.tamu.edu/davis/welcome.html">Timothy A. Davis</a>.
</p>
</dd>
</dl>
<dt><a name="zlib"/>
<a href="http://zlib.net/" target="_top">zlib</a></dt>
<dd>
<p>
<a href="http://zlib.net/" target="_top">zlib</a> is a software library used for lossless data-compression. It is used in deal.II whenever compressed data is to be written.
<a href="http://zlib.net/" target="_top">zlib</a> should be readily packaged by most Linux distributions. To use a self compiled version, pass
<code>-DZLIB_DIR=/path/to/zlib</code> to the deal.II CMake call.
</p>
</dd>
<a name="conf-details" />
<h4>More information on configuring and building the library</h4>
<p>
The <acronym>deal.II</acronym> <code>cmake</code> system allows far greater control over what exactly is configured or built than just the outline above. If you want to learn more about this, take a look
<a href="users/cmake.html">here</a>. You might also be interested in
<a href="users/cmakelists.html">CMake for user projects</a> or
<a href="developers/cmake-internals.html">build system internals</a>.
</p>
<a name="license"></a>
<h2>License</h2>
<p>
The deal.II library is free software; you can use it, redistribute it, and/or modify it under the terms of the
<a href="http://www.gnu.org/licenses/lgpl-2.1.html">GNU Lesser General
Public License</a> (LGPL) as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
</p>
<p>
This allows you to use the library free of charge for private, academic, or commercial use (under the terms of the LGPL v2.1 or later). You are guaranteed full access to the source code and are encouraged to help in the further development of the library.
Follow
<a href="http://www.dealii.org/license.html" target="body">this
link</a> for detailed information.
</p>
<p>
Please note:</p>
<ul>
<li>
Detailed license information can be found following
<a href="http://www.dealii.org/license.html" target="body">this link</a>.
</li>
<li>
<b>As a contributor to this project, you agree that any of your
contributions be licensed under the same terms and conditions as
the license of the deal.II project granted to you.</b>
</li>
<li>
We, <a href="http://www.dealii.org/authors.html" target="_top">the deal.II Authors</a>, do not require copyright assignments for contributions. This means that the copyright for code contributions in the deal.II project is held by its respective
contributors who have each agreed to release their contributed code under the terms of the LGPL v2.1 or later.
</li>
<li>
In addition to the terms imposed by the LGPL (version 2.1 or later), we ask for the courtesy that scientific publications presenting results obtained with this libraries acknowledge its use. Please cite one of the papers referenced
<a href="http://www.dealii.org/publications.html">here</a>.
</li>
<li>
<acronym>deal.II</acronym> can interface with a number of <a href="#optional-software">other packages</a> that you either have to install yourself. They are, of course, covered by their own licenses. In addition, deal.II comes bundled with
copies of
<a href="http://faculty.cse.tamu.edu/davis/suitesparse.html">
UMFPACK</a>,
<a href="http://threadingbuildingblocks.org/" target="_top">Threading Building Blocks</a>,
<a href="http://www.boost.org/" target="_top">BOOST</a> and
<a href="http://muparser.beltoforion.de/" target="_top">muparser</a>, courtesy of their authors. These are also covered by their own licenses; please refer to their webpages for more information.
</li>
</ul>
<hr />
<div class="right">
<a href="http://validator.w3.org/check?uri=referer" target="_top">
<img style="border:0" src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
<a href="http://jigsaw.w3.org/css-validator/check/referer" target="_top">
<img style="border:0;width:88px;height:31px" src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
</div>
</body>
</html>