forked from dftbplus/dftbplus
-
Notifications
You must be signed in to change notification settings - Fork 4
/
INSTALL.rst
650 lines (466 loc) · 28.5 KB
/
INSTALL.rst
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
*****************************
Building and installing DFTB+
*****************************
If you have problems with the build, you can find suggestions for some
frequently occurring scenarios in the `Troubleshooting <#troubleshooting>`_
section at the bottom.
Requirements
============
In order to compile DFTB+, you need the following software components:
* Fortran compiler supporting Fortran 2008 and OpenMP 4.0
* C compiler
* C++ compiler (when built with ELSI/PEXSI or ChIMES support)
* CMake (version 3.16 or newer)
* GNU make
* LAPACK/BLAS libraries (or compatible equivalents)
* Python (version >= 3.2) for the source preprocessor
Fortran compiler
----------------
The following Fortran compilers are known to build DFTB+ correctly:
* GNU >= 10
* Intel >= 2021
* NAG >= 7.1 (when built without OpenMP support)
The following Fortran compilers are known to fail to build DFTB+:
* NAG (when built with OpenMP support, unsupported OpenMP 4.0 constructs, last
tested version: 7.1)
* NVIDIA (internal compiler error & unsupported OpenMP 4.0 constructs, last
tested version: 22.3)
Older versions of the compilers above are likely to fail due to missing Fortran
features and/or compiler bugs. Compilers by other vendors may work, but have not
been tested extensively (see also `Tested build environments
<#tested-build-environments>`_ and `Testing DFTB+ <#testing-dftb>`_).
Optional extra dependencies
---------------------------
Additionally there are optional requirements for some DFTB+ features:
* ScaLAPACK (version 2.0 or later) and a Fortran aware MPI framework, if you
want to build the MPI-parallelised version of the code.
* In addition to ScaLAPACK, for MPI parallel builds it is recommended
to use the `ELSI <https://wordpress.elsi-interchange.org/>`_ library
for large scale systems (version 2.6.x of the library, with partial
support of 2.5.0). If ELSI was compiled with PEXSI included, you
will also need a C++ compiler.
* The ARPACK-ng library if using the excited state DFTB functionality.
* The `MAGMA <https://icl.cs.utk.edu/magma/>`_ library for GPU
accelerated computation (note that within ELSI, the ELPA library
also supports distributed multiple GPUs if compiled with the correct
options).
* The `PLUMED2 <https://github.com/plumed/plumed2>`_ library for
metadynamics simulations. If you build DFTB+ with MPI, the linked
PLUMED library must also be MPI-aware (and must have been built with
the same MPI-framework as DFTB+).
External library requirements
-----------------------------
* **Make sure that all external libraries are compiled with the same kind models
for the numeric variables** (same integer size and floating point precision)
as DFTB+. Also, they should preferably have been built with the same compiler
and with similar compiler flags to DFTB+. (See the Troubleshooting section for
further information.)
* External libraries in non-standard locations (as is typical on many
HPC-systems using environment modules) can only be reliable found by CMake if
their library path occurs in the ``CMAKE_PREFIX_PATH`` environment
variable. **Make sure that your CMAKE_PREFIX_PATH environment variable
contains all relevant library paths!**
Requirements for testing DFTB+
------------------------------
In order to execute the code tests and validate them against precalculated
results, you will additionally need:
* Python (version >= 3.2) with NumPy
* The Slater-Koster data used in the tests (see below)
Tested build environments
-------------------------
DFTB+ is regularly built and tested for both serial and MPI environments on the
following architectures:
+---------------+----------------------+-------------+------------------+-----+
| Architecture | Compiler | MPI | Ext. libraries |Notes|
+===============+======================+=============+==================+=====+
| x86_64 / | GNU Fortran/C 10.1 | OpenMPI 4.0 | OpenBlas 0.3.10, | |
| Linux | | | ScaLAPACK 2.1, | |
| | | | ELSI 2.6.1 | |
+---------------+----------------------+-------------+------------------+-----+
| x86_64 / | GNU Fortran/C 11.2 | OpenMPI 4.1 | OpenBlas 0.3.18, | |
| Linux | | | ScaLAPACK 2.1, | |
| | | | ELSI 2.8.2 | |
+---------------+----------------------+-------------+------------------+-----+
| x86_64 / | GNU Fortran/C 12.2 | OpenMPI 4.1 | OpenBlas 0.3.21, | |
| Linux | | | ScaLAPACK 2.2, | |
| | | | ELSI 2.9.1 | |
+---------------+----------------------+-------------+------------------+-----+
| x86_64 / | Intel Fortran/C | IntelMPI | MKL 2021, | |
| Linux | 2021.1 | 2021.1 | ELSI 2.8.2 | |
+---------------+----------------------+-------------+------------------+-----+
| x86_64 / | Intel Fortran/C | IntelMPI | MKL 2022, | |
| Linux | 2022.1 | 2022.1 | ELSI 2.8.2 | |
+---------------+----------------------+-------------+------------------+-----+
| x86_64 / | NAG Fortran 7.1 | MPICH 3.4 | OpenBlas 0.3.18 | [1] |
| Linux | GNU C 11.2 | | ScaLAPACK 2.1 | |
+---------------+----------------------+-------------+------------------+-----+
| x86_64 / | GNU Fortran/C 12.2 | MPICH 4.1.1 | OpenBlas 0.3.23 | [2] |
| OS X | | | | |
+---------------+----------------------+-------------+------------------+-----+
| x86_64 / | GNU Fortran/C 12.2 | OpenMPI 4.1 | OpenBlas 0.3.23 | [2] |
| OS X | | | | |
+---------------+----------------------+-------------+------------------+-----+
Notes:
[1] Only Debug build is tested regulary with OpenMP turned off and without ELSI.
[2] Only partial testing
Obtaining the source
====================
The source code of the last stable release can be downloaded from the `DFTB+
homepage <https://www.dftbplus.org/download/dftb-stable/>`_.
Alternatively you can clone the `public git repository
<https://github.com/dftbplus/dftbplus>`_. The tagged revisions correspond to
stable releases, while the default branch contains the latest development
version. ::
git clone https://github.com/dftbplus/dftbplus.git
cd dftbplus
The project uses git-submodules for some external dependencies, which will be
automatically retrieved during configuration.
Optional extra components
-------------------------
Some optional software components are not distributed with the DFTB+ source code
and are also not retrieved automatically. If these are required, you can
download these components by using the `get_opt_externals` utility, e.g.::
./utils/get_opt_externals
This will download all license compatible optional external components. These
include the Slater-Koster (slako) data for testing the compiled code.
For more information see the detailed help for this tool by issuing
``./utils/get_opt_externals -h``.
Slater-Koster file locations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The DFTB+ code checks the shell variable `DFTBPLUS_PARAM_DIR` when
setting the path to check the Prefix keyword for finding data. If
unset, it assumes the local directory as the starting path.
Building
========
**Important note:** CMake caches its variables in the `CMakeCache.txt` file in
the build folder (e.g. ``_build/CMakeCache.txt``). Make sure to delete this file
before re-running CMake if you have changed variables in `config.cmake` or in
the toolchain files in the `sys/` folder. (Deleting the `CMakeCache.txt` file is
not necessary if you change a variable via the ``-D`` command line option.)
In order to build DFTB+ carry out the following steps:
* Inspect the `config.cmake` file and customise the global build parameters. (If
you are unsure, leave the defaults as they are.)
* Invoke CMake to configure the build. Specify the installation destination
(e.g. ``$HOME/opt/dftb+``) and pass an arbitrary folder (e.g. ``_build``) for
the build and the directory containing the source files (e.g. ``.``) as
arguments to CMake. Additionally define your Fortran and C compilers as
environment variables, e.g. (in a BASH compatible shell)::
FC=gfortran CC=gcc cmake -DCMAKE_INSTALL_PREFIX=$HOME/opt/dftb+ -B _build .
Based on the detected compilers, the build system will read further settings
from a corresponding toolchain file in the `sys/` folder. Either from a
compiler specific one (e.g. `gnu.cmake`, `intel.cmake`, etc.) or the generic
one (`generic.cmake`) if the detected compiler combination does not correspond
to any of the specific settings. The selected toolchain is indicated in the
CMake output. (The toolchain file selection can be manually overridden by
setting the ``TOOLCHAIN`` CMake variable.)
You may adjust any CMake variable defined in `config.make` or in the
toolchain files by either modifying the files directly or by setting
(overriding) the variable via the ``-D`` command line option. For example, in
order to use the MKL-library with the GNU-compiler, you would have to override
the ``LAPACK_LIBRARY`` variable with the CMake command line argument ``-D``::
-DLAPACK_LIBRARY="mkl_gf_lp64;mkl_gnu_thread;mkl_core"
When needed, you can specify the complete path to a library or pass linker
options as defined variables, e.g.::
-DLAPACK_LIBRARY="/opt/openblas/libopenblas.a"
-DLAPACK_LIBRARY="-Wl,--start-group -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core -Wl,--end-group"
By default CMake searches for the external libraries in the paths specified in
the ``CMAKE_PREFIX_PATH`` environment variable. **Make sure that your
CMAKE_PREFIX_PATH environment variable is set up correctly and contains
all the relevant paths** when configuring the project, e.g. ::
CMAKE_PREFIX_PATH=/opt/elsi:/opt/custom-openblas cmake [...] -B _build .
Some of the external library finders also offer special ``_LIBRARY_DIR`` CMake
variables for setting search paths, e.g. ::
-DLAPACK_LIBRARY_DIR=/opt/custom-openblas
Setting those variables is normally not necessary, provided the right search
path is already present in the ``CMAKE_PREFIX_PATH`` environment variable.
* If the configuration was successful, start the build by ::
cmake --build _build -- -j
This will compile the code using several threads and showing only the most
relevant information.
If, for debugging purposes, you wish to see the exact compiling commands, you
should execute a serial build with verbosity turned on instead::
cmake --build _build -- VERBOSE=1
* Note: The code can be compiled with distributed memory parallelism (MPI), but
for smaller shared memory machines, you may find that the performance is
better when using OpenMP parallelism only and an optimised thread aware BLAS
library is used.
CMake options for additional functionality
------------------------------------------
A subset of the cmake comand line options are listed below (for full details,
check the `config.cmake` file in the top repository directory).
Enabling optional code functionality
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------+---------+------------------------------------------------+
|CMake option |Default |Notes |
+=================+=========+================================================+
|-DWITH_ARPACK |N |Required for some types of excited state |
| | |calculations (the Stratmann solver does not |
| | |require this library). |
+-----------------+---------+------------------------------------------------+
|-DWITH_CHIMES |N |Required for the CHiMES repulsive potentials to |
| | |be enabled. |
+-----------------+---------+------------------------------------------------+
|-DWITH_MBD |N |Required for many-body dispersion to be enabled.|
+-----------------+---------+------------------------------------------------+
|-DWITH_PLUMED |N |Required for the PLUMED meta-dynamics library to|
| | |be available for MD calculations. |
+-----------------+---------+------------------------------------------------+
|-DWITH_POISSON |N |Required for Poisson solver (also enabled for |
| | |transport builds). |
+-----------------+---------+------------------------------------------------+
|-DWITH_SDFTD3 |N |Required for 'simple' DFT-D3 dispersion to be |
| | |enabled. |
+-----------------+---------+------------------------------------------------+
|-DWITH_SOCKETS |N |Required for i-PI socket interfaces to be |
| | |available. |
+-----------------+---------+------------------------------------------------+
|-DWITH_TBLITE |N |Required for xTB hamiltonians to be enabled. |
+-----------------+---------+------------------------------------------------+
|-DWITH_TRANSPORT |N |Required for open-boundary calculations to be |
| | |enabled. |
+-----------------+---------+------------------------------------------------+
Parallelism options
^^^^^^^^^^^^^^^^^^^
+-----------------+--------+--------------------------------------------------+
|CMake option | Default| Notes |
+=================+========+==================================================+
|-DWITH_OMP | Y |OpenMP parallelism enabled in the build. |
+-----------------+--------+--------------------------------------------------+
|-DWITH_MPI | N |MPI parallelism enabled in the build. |
+-----------------+--------+--------------------------------------------------+
|-DWITH_ELSI | N |Requires that MPI is also enabled. |
+-----------------+--------+--------------------------------------------------+
|-DWITH_GPU | N |Depending on whether MPI+ELSI is enabled, this |
| | |will use GPU accelerated ELPA (if provided) or the|
| | |MAGMA library (if provided) for GPU acceleration. |
+-----------------+--------+--------------------------------------------------+
Testing DFTB+
=============
* After successful compilation, change to the build folder and execute the code
tests::
pushd _build
ctest
popd
You can also run the tests in parallel in order to speed this up. If you use
parallel testing, ensure that the number of OpenMP threads is reduced
accordingly. As an example, assuming your workstation has 4 cores and you have
set up the ``TEST_OMP_THREADS`` variable to ``2`` (in `config.cmake`), issue
::
ctest -j2
for an OpenMP compiled binary running two tests simultaneously, each using 2
cores.
If you want to test the MPI enabled binary with more than one MPI-process, you
should set the ``TEST_MPI_PROCS`` variable accordingly.
Testing with hybrid (MPI/OpenMP) parallelism can be specified by setting both,
the ``TEST_MPI_PROCS`` and ``TEST_OMP_THREADS`` variables, e.g::
set(TEST_MPI_PROCS "2" CACHE STRING "Nr. of processes used for testing")
set(TEST_OMP_THREADS "2" CACHE STRING "Nr. of OMP-threads used for testing")
Note that efficient production use of the code in this mode may require
process affinity (settings will depend on your specific MPI implementation).
The ``TEST_MPI_PROCS`` and ``TEST_OMP_THREADS`` cache variables can be updated
or changed also after the compilation by invoking CMake with the appropriate
``-D`` options, e.g.::
cmake -B _build -DTEST_MPI_PROCS=2 -DTEST_OMP_THREADS=2 .
pushd _build; ctest; popd
Testing related CMake options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Some of the command line options for CMake to modify testing behaviour before
building are below.
+------------------------+----------------------------------------------------+
|CMake option |Notes |
+========================+====================================================+
|-DTEST_MPI_PROCS |Number of MPI processes used if testing an MPI build|
| |with ctest. |
+------------------------+----------------------------------------------------+
|-DTEST_OMP_THREADS |Number of openMP processes used if testing an openMP|
| |build with ctest. |
+------------------------+----------------------------------------------------+
|-DTEST_RUNNER_TEMPLATE |Modifies the DFTB+ invocation inside the test system|
| |(for example if a specific MPI loader is required to|
| |run calculations). |
+------------------------+----------------------------------------------------+
Installing DFTB+
================
* The compiled executables, libraries, module files etc. can be copied into an
installation directory by ::
cmake --install _build
where the destination directory can be configured by the variable
``CMAKE_INSTALL_PREFIX`` (in the `config.cmake` file). The default location is
the `_install` subdirectory within the build directory.
Using DFTB+ as a library
========================
DFTB+ can be also be used as a library and linked into other simulation software
packages. In order to compile the library with its public API, make sure to set
the ``WITH_API`` option to ``TRUE`` in the CMake config file
`config.cmake`. When you install the program, it will also install the DFTB+
library, the C-include file and the Fortran module files, which are necessary
for linking DFTB+ with C and Fortran programs.
DFTB+ CMake library options
---------------------------
See `config.cmake` for details, but the main configuration options for building
are listed below.
+-------------------------+---------+-----------------------------------------+
|CMake option |Default |Notes |
+=========================+=========+=========================================+
|-DBUILD_SHARED_LIBS |N |Build libdftbplus and other components as|
| | |shared libraries. |
+-------------------------+---------+-----------------------------------------+
|-DENABLE_DYNAMIC_LOADING |N |Use shared libraries externally (where |
| | |possible) for libdftbplus. |
+-------------------------+---------+-----------------------------------------+
|-DINSTANCE_SAFE_BUILD |N |Compile libdftbplus as an instance safe |
| | |library (the build stops, if a |
| | |non-instance-safe component had been |
| | |selected) |
+-------------------------+---------+-----------------------------------------+
|-DWITH_API |N |Build the API bindings to use libdftbplus|
| | |externally. |
+-------------------------+---------+-----------------------------------------+
|-DWITH_PYTHON |N |Build the Python3 bindings for |
| | |libdftbplus. Note that this should also |
| | |be built for shared libraries. |
+-------------------------+---------+-----------------------------------------+
Linking the library in CMake based builds
-----------------------------------------
This is the preferred way of invoking the DFTB+ library into your project. In
CMake based projects you can directly use the CMake export file of DFTB+, which
is installed in the `lib/cmake/dftbplus/` folder in the installation folder. It
exports the target ``DftbPlus::DftbPlus`` which you can use to obtain all
necessary compiler, include and linking options. Your projects `CMakeLists.txt`,
should like something like below::
project(DftbPlusTest LANGUAGES Fortran C)
find_package(DftbPlus REQUIRED)
add_executable(testprogram testprogram.f90)
target_link(testprogram DftbPlus::DftbPlus)
Note, that this will link all libraries in the correct order, which were
compiled during the DFTB+ build (e.g. libs-dftd3, libnegf, etc.). It will
additionally contain target dependencies for the external libraries needed to
create standalone applications with DFTB+ (e.g. ``LAPACK::LAPACK``,
``Scalapack::Scalapack``, ``Arpack::Arpack``, ``Plumed::Plumed``,
``Magma::Magma``, etc.). You can either use the CMake find-modules shipped with
the DFTB+ source to find those libraries (and to define the corresponding
targets) or create your own, provided they define the appropriate CMake
targets. The ELSI library offers a CMake export file providing the
``elsi::elsi`` target. Make sure, that CMake can find this export file if the
DFTB+ library was compiled with ELSI support (e.g., by setting up the environment
variable ``CMAKE_PREFIX_PATH`` correctly).
Note: you may need to install ELSI (not just point the prefix path to its build system) to generate
this file correctly.
Linking the library in non-CMake based builds
---------------------------------------------
Depending on the choice of external components and whether you want to link
DFTB+ to a C or a Fortran binary, you may need different compilation flags and
linker options. You can look up the necessary compiler flags and linker options
in the `dftbplus.pc` pkg-config file, which is usually installed into the
`lib/pkgconfig` folder in the installation directory. You can either inspect the
file directly, or use the ``pkg-config`` tool::
export PKG_CONFIG_PATH=${PKG_CONFIG_PATH}:DFTBPLUS_INSTALL_FOLDER/lib/pkgconfig
pkg-config --cflags dftbplus # compilation flags (e.g. include options)
pkg-config --libs dftbplus # library linking options
pkg-config --static --libs dftbplus # library linking options for static linking
Note, that the flags and libraries shown are either for linking with Fortran or
with C, depending on the value of the configuration option
``PKGCONFIG_LANGUAGE``.
If you compile DFTB+ with ELSI, PLUMED or MAGMA-support, make sure that pkg-config can also find the
respective pkconfig files for these packages. If you enable support for these components, their
libraries are declared as dependencies in the DFTB+ pkg-config file. Note, if you compile these
libraries themselves, you may have to follow their install processes to generate suitable
pkg-config files in their specified install location(s).
For external dependencies without pkg-config files (e.g. mbd, negf), the options for linking those
libraries can not be queried via pkg-config, and they must be added manually.
Generating developer documentation
==================================
Developer documentation can be generated using the FORD source code
documentation generator by issuing ::
cd doc/dftb+/ford && ford dftbplus-project-file.md
in the main source directory. The documentation will be created in the
`doc/dftb+/ford/doc` folder.
Developer build instructions
============================
You should avoid customizing the build by directly changing variables in the
CMake config files, as your changes may accidentally be checked in into the
repository. Instead, create a customized CMake config file, where you
pre-populate the appropriate cache variables. Then use the `-C` option to load
that file::
FC=gfortran CC=gcc cmake -C custom.cmake -B _build .
The customized config file is read by CMake before the compiler detection
stage. If your config file contains toolchain dependent options, consider
defining the ``DFTBPPLUS_TOOLCHAIN`` environment variable and query it in your
config file.
Relevant CMake options
----------------------
+-------------------+--------------+------------------------------------------+
|CMake option |Default |Notes |
+===================+==============+==========================================+
|-DLCOV_REPORT |N |Generate coverage reports if using |
| | |gfortran and lcov is available. |
+-------------------+--------------+------------------------------------------+
|-CMAKE_BUILD_TYPE |RelWithDebInfo|Can generate a binary with extra checking |
| | |or profiling enabled. |
+-------------------+--------------+------------------------------------------+
|-DWITH_UNIT_TESTS |N |Build additional checking tests for |
| | |specific code routines. |
+-------------------+--------------+------------------------------------------+
Advanced build configuration (e.g. for packagers)
=================================================
Controlling the toolchain file selection
----------------------------------------
You can override the toolchain file, and select a different provided case,
passing the ``-DTOOLCHAIN`` option with the relevant name, e.g.::
-DTOOLCHAIN=gnu
or by setting the toolchain name in the ``DFTBPLUS_TOOLCHAIN`` environment
variable. If you want to load an external toolchain file instead of one from the
source tree, you can specify the file path with the ``-DTOOLCHAIN_FILE`` option
::
-DTOOLCHAIN_FILE=/some/path/myintel.cmake
or with the ``DFTBPLUS_TOOLCHAIN_FILE`` environment variable.
Similarly, you can also use an alternative build config file instead of
`config.cmake` in the source tree by specifying it with the
``-DBUILD_CONFIG_FILE`` option or by defining the ``DFTBPLUS_BUILD_CONFIG_FILE``
environment variable.
Preventing the download of external sources
-------------------------------------------
Depending on the value of the ``HYBRID_CONFIG_METHODS`` configuration variable,
some dependencies (e.g. mbd, negf, mpifx, scalapackfx) are automatically
downloaded during the configuration phase and built during the DFTB+ build
process. If you want to ensure that nothing gets downloaded during the build,
pass the variable definition ::
-DHYBRID_CONFIG_METHODS="Find"
to CMake during the configuration. In this case, CMake will only try to find
those dependencies on the system (by searching in the standard system paths and
in the locations defined in the environment variable ``CMAKE_PREFIX_PATH``) and
stop if some components were not found.
Troubleshooting
===============
* **CMake finds the wrong compiler**
CMake should be guided with the help of the environment variables ``FC``,
``CC`` (and eventually ``CXX``) to make sure it uses the right compilers,
e.g. ::
FC=gfortran CC=gcc cmake [...]
* **CMake fails to find a library / finds the wrong version of a library**
In most cases this is due to a misconfigured ``CMAKE_PREFIX_PATH`` environment
variable. It is essential, that ``CMAKE_PREFIX_PATH`` contains all paths
(besides default system paths), which CMake should search when trying to find
a library. Extend the library path if needed, e.g. ::
CMAKE_PREFIX_PATH="/opt/somelib:${CMAKE_PREFIX_PATH}" cmake [...]
* **ScaLAPACK detection on Ubuntu 20.4 LTS fails**
The OpenMPI version of ScaLAPACK on Ubuntu 20.4 LTS exports an incorrect CMake
config file (as of October 2020), which refers to an non-existent
library. Instead, set the library name with the ``SCALAPACK_LIBRARY`` variable
explicitely, e.g. ::
cmake -DSCALAPACK_LIBRARY=scalapack-openmpi [...]
which should fix the problem.
* **My library settings in a "_LIBRARIES" variable are ignored**
In order to be consistent with the naming scheme suggested by the CMake
documentation, all library related cache variables have been changed to
singular nouns, e.g. ::
cmake -DSCALAPACK_LIBRARY=scalapack-openmpi [...]
**instead** of the previous ::
cmake -DSCALAPACK_LIBRARIES=scalapack-openmpi [...]
* **Fortran libraries compiled with the Intel compiler can not be linked**
In order to enforce compliance with the Fortran 2003 standard (e.g. allowing
the automatic allocation of arrays in expressions), DFTB+ passes the
``-standard-semantics`` option to the Intel compiler. All external modern
Fortran dependencies (e.g. ELSI) must also be compiled by using the
``-standard-semantics`` or the ``-assume realloc_lhs`` option to ensure
correct linking.