Tips for ABINIT users and developers

User Tools

Site Tools

Trace:
build:configure

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
build:configure [2016/04/08 17:20] – [Linear algebra] Yann Pouillonbuild:configure [2020/08/05 16:57] (current) – [LD_LIBRARY_PATH] Jean-Michel Beuken
Line 1: Line 1:
 ====== Configuring the build of Abinit ====== ====== Configuring the build of Abinit ======
  
-//Please read the [[wiki:conventions|Conventions and formatting page]] once before everything else.//+//Please read the [[wiki:conventions|Conventions and formatting]] page at least once before everything else.// 
 + 
 + 
 +===== Tutorials for beginners ===== 
 + 
 +  * {{ :build:installing_abinit.pdf |}} 
  
 ===== The configure script ===== ===== The configure script =====
Line 55: Line 61:
 Please note that //LD_LIBRARY_PATH// is called //DYLD_LIBRARY_PATH// on MacOS. Please note that //LD_LIBRARY_PATH// is called //DYLD_LIBRARY_PATH// on MacOS.
  
-If you use GCC compilers, you may sometimes want to use the //LIBRARY_PATH// environment variable as well, in particular if the build fails while //LD_LIBRARY_PATH// has been correctly set. Contrary to the latter, //LIBRARY_PATH// is only used by the compiler at link-time and will be ignored when running an Abinit executable.+<WRAP important>**IMPORTANT** \\ //LD_LIBRARY_PATH// must be set **__to the same value__** both before configuring the build of Abinit and before running the corresponding executables. These 2 actions can happen at very different times, hence the risk of forgetting to set the variable again. Misconfiguring LD_LIBRARY_PATH is actually a common mistake beginners make when learning Abinit and the source of many questions asked on the [[https://forum.abinit.org/|Abinit Forums]].</WRAP>
  
-<WRAP important>**IMPORTANT** \\ //LD_LIBRARY_PATH// must be set **__to the same value__** both before configuring the build of Abinit and before running the corresponding executables. These 2 actions can happen at very different times, hence the risk of forgetting to set the variable again. Misconfiguring LD_LIBRARY_PATH is actually a common mistake beginners make when learning Abinit and the source of many questions asked on the [[http://forum.abinit.org/|Abinit Forums]].</WRAP>+==== LIBRARY_PATH ==== 
 + 
 +If you use GCC compilers, you may sometimes want to use the //LIBRARY_PATH// environment variable as well, in particular if the build fails while //LD_LIBRARY_PATH// has been correctly set. Contrary to the latter, //LIBRARY_PATH// is only used by the compiler at link-time and will be ignored when running an Abinit executable.
  
 ==== PYTHONPATH ==== ==== PYTHONPATH ====
  
-Python is usually installed by system administrators in a standard way on most computers. However, if you use a version of PYTHON that you have installed yourself, please make sure that the PYTHONPATH variable is properly set before configuring Abinit.+Python is usually installed by system administrators in a standard way on most computers. However, if you use custom Python modules that you have installed yourself, please make sure that the PYTHONPATH variable is properly set before configuring Abinit.
  
 ==== Language-specific variables ==== ==== Language-specific variables ====
Line 88: Line 96:
 In order to accommodate as many situations as possible, we have designed a flexible mechanism to handle config files: In order to accommodate as many situations as possible, we have designed a flexible mechanism to handle config files:
   * first, the build system looks into the build directory for a config file, which lets you import parameters for a specific build;   * first, the build system looks into the build directory for a config file, which lets you import parameters for a specific build;
-  * if not found, it looks into the source directory, which allows e.g. for build parameters related to a particular version of Abinit;+  * if not found, it looks into the source directory, which allows you to use build parameters related to a particular version of Abinit;
   * if still not found, it looks into the //~/.abinit/build%%/%%// directory, which acts as a provider of default parameters corresponding to your particular preferences;   * if still not found, it looks into the //~/.abinit/build%%/%%// directory, which acts as a provider of default parameters corresponding to your particular preferences;
   * finally, it looks into the //%%/%%etc/abinit/build%%/%%// directory, to let system administrators provide system-wide parameters for a specific computer.   * finally, it looks into the //%%/%%etc/abinit/build%%/%%// directory, to let system administrators provide system-wide parameters for a specific computer.
-Of these 4 possibilities, the first file encountered is processed and the build system goes on without looking for more files.+Of these 4 possibilities, the first file encountered is processed and the build system goes on without looking for more files. In other words, config files are not cumulative. For example, if a user has a //~/.abinit/build/my_host.ac//, the system-wide defaults found in //%%/%%etc/abinit/build/my_host.ac// will always be ignored.
  
 Since many developers of Abinit work on shared filesystems, the build system looks by default for a file called //`hostname`.ac//, where `hostname` represents the result of the following command, that you can type in a shell to know how to name your config files (do not type the dollar signs): Since many developers of Abinit work on shared filesystems, the build system looks by default for a file called //`hostname`.ac//, where `hostname` represents the result of the following command, that you can type in a shell to know how to name your config files (do not type the dollar signs):
Line 108: Line 116:
 ===== Tuning configure options ===== ===== Tuning configure options =====
  
-<WRAP tip>**Important tip** \\ The options of //configure// are fully documented in the //~abinit/doc/build/config-template.ac// file. Even if the wiki is updated quickly to reflect the changes made to this file, there may sometimes be a slight delay before both documents are synchronized. If you find a discrepancy between the wiki and //config-template.ac//, please let us know as soon as possible so that we can fix it.</WRAP>+<WRAP tip>**Important tip** \\ The options of //configure// are fully documented in the //~abinit/doc/build/config-template.ac// file. Even if the wiki is updated quickly to reflect the changes made to this file, there may sometimes be a slight delay before both documents are synchronized. If you find a discrepancy between the wiki and //config-template.ac//, please let us know as soon as possible so that we can fix it -- or fix it yourself if you have write permission on this wiki.</WRAP>
  
-==== Compilers ====+The build system of Abinit is quite modular and is composed of logical blocks addressing each a specific configuration issue. The following documents will help you tune the build parameters depending on what you want to adjust.
  
-Coming soon ...+//[[build:compilers|Configuring compilers]]// helps you select C, C++ and Fortran compilers, and find the best compromise between performance and reliability for your architecture. It includes a section on preprocessors and the corresponding platform-specific issues.
  
-==== Serial and parallel architectures ====+//[[build:multicore_architectures|Configuring multicore architectures]]// shows how to configure OpenMP-, MPI-, and GPU-enabled architectures, as well as how to force a build to remain serial.
  
-OpenMP, MPI, GPU, ...+//[[build:linear_algebra|Configuring linear algebra]]// explains how to configure linear algebra support for your particular situation.
  
-==== Linear algebra ==== +//[[build:fft|Configuring Fast Fourier Transforms]]// guides you to select the best FFT algorithm for your particular situation.
- +
-Linear algebra is the most critical dependency to consider, since Abinit could not be built nor run without it. It is also the most complex one, due to: +
-  * the different components to select and their various interactions with external factors, e.g. using ScaLAPACK only makes sense if your environment supports MPI; +
-  * the way each component is provided, e.g. one component per library or all components in one library; +
-  * the tremendous diversity of the available implementations, with several of them present on the same computer at once. +
- +
-It logically corresponds to the most complex core block of the build system. On one side, there are //__vendors__//, who develop specific components for specific architectures. On another side, there are //__architectures__//, which include various technological variants and offer various degrees of parallelism. And on a third side, there are //__components__//, defined by the kind of mathematical operations they provide and the architectures they aim at. +
- +
-We have designed our implementation to cover the highest possible number of cases, while preserving a relative simplicity in the configuration of their parameters. For this, we have grouped the 3 above concepts under //flavors// that users select depending on their situations and preferences. +
- +
-Take your time to read this section and feel free to come back as many times as you wish. +
- +
-The following table summarizes the linear algebra components supported by Abinit: +
- +
-^ Component ^ Type      ^ Flavors                                       ^ Remarks                          ^ +
-| blas      | Mandatory | acml, asl, essl, atlas, mkl, netlib, openblas | Required by all other components | +
-| lapack    | Mandatory | acml, asl, essl, mkl, netlib                  | Requires BLAS                    | +
-| lapacke   | Optional  | essl, mkl, netlib                             | Requires LAPACK                  | +
-| scalapack | Optional  | mkl, netlib                                   | Requires MPI and LAPACK          | +
-| elpa      | Optional  | elpa2014, elpa2015                            | Requires MPI and LAPACK          | +
-| plasma    | Optional  | plasma1                                       | Requires OpenMP, with caveats    | +
-| magma     | Optional  | magma10, magma15                              | Requires MPI and GPU             | +
- +
-By default, the build system assumes that you want the fastest possible linear algebra operations. When no linear algebra option is specified, it thus looks for each component as soon as its prerequisites are met. The only required components are BLAS and LAPACK, since Abinit relies on them in each and every situation. The other components are enabled only if their prerequisites are met, their detection succeeds, and are proved working. +
- +
-To deal more easily with the various linear algebra implementations that can be used concurrently on the same computer, Abinit provides the //with_linalg_flavor// option. It will tune the detection tests made by the build system so that the probability of finding the correct libraries and setting-up the environment is maximized. +
- +
-<WRAP tip>Please note that, when using //with_linalg_flavor//, the //LD_LIBRARY_PATH// and //PATH// environment variables must be properly set for the detection to succeed, in particular if you do not specify any other linear algebra option.</WRAP> +
- +
-You can tune the detection mechanism through the //with_linalg_flavor// option in 3 ways: +
-  * by just specifying a plus-separated list of flavors, in which case the build system will figure out how to assign which flavor to which component; +
-  * architecture-wise, by specifying a comma-separated list of //arch:value// statements, where //arch// can be //serial//, //openmp//, //mpi//, or //gpu//, and //value// is a plus-separated list of flavors; +
-  * component-wise, by specifying a comma-separated list of //component:value// statements, where //component// is one of the keywords from the first column of the above table, and //value// is a corresponding flavor -- only one is permitted in this case. +
- +
-Please note that you can only use one of these 3 methods at a time. Mixes are explicitly forbidden. Omitting an architectural item or a linear algebra component with the 2 latter methods will be equivalent to disabling this element. +
- +
-__Example 1__: +
-<code>with_linalg_flavor="openblas+netlib"</code> +
-will cause the build system to look for OpenBLAS for the //blas// component and use Netlib for the other ones, i.e. //lapack// for the serial case and //scalapack// if MPI is enabled in the current build. Unspecified components will be detected using the default behavior, e.g. the build system will look for all available implementations of //elpa// if MPI is enabled but do nothing if MPI is disabled. +
- +
-__Example 2__: +
-<code>with_linalg_flavor="serial:atlas+netlib,mpi:netlib,gpu:magma15"</code> +
-will cause the build system to look for Atlas for //blas//, Netlib for //lapack// and //scalapack//, and MAGMA 1.5 for //magma//. However, it will never look for //elpa//, since it has not been explicitly stated, and will stop with an error if one of the specified elements is not present or not working. When using this method, you must specify the //serial// block and make sure its value will provide the //blas// and //lapack// components. +
- +
-__Example 3__: +
-<code>with_linalg_flavor="blas:atlas,lapack:netlib,elpa:elpa2015"</code> +
-will cause the build system to look for the //blas//, //lapack// and //elpa// components, but not for //scalapack//, even if MPI is enabled. It will also fail if any component is missing or not working. When using this method, you must specify the //blas// and //lapack// components. +
- +
-The other options provide hints to the build system and determine which kinds of tests will be performed: +
-  * //with_linalg_fcflags// defines which Fortran compiler flags should be applied at compile time; this is useful for compilers providing native linear algebra support; +
-  * //with_linalg_ldflags// defines which flags should be passed to the linker when building programs; this is useful for compilers providing native linear algebra support; +
-  * //with_linalg_incs// defines which include flags should be applied at compile time; this option is only useful for LAPACKe; +
-  * //with_linalg_libs// defines which libraries should be linked with the programs performing linear algebra operations. +
- +
-==== Optional features ==== +
- +
-The capabilities of Abinit can be enhanced by the use of optional external packages. The corresponding options of //configure// all follow the same scheme: +
-  * //enable_**package**//, to trigger the detection and build of the corresponding feature; +
-  * //with_**package**//, to specify the install prefix of a package; +
-  * //with_**package**_bins//, to specify where to look for the executables of a package (when applies); +
-  * //with_**package**_incs//, to specify include flags when compiling code that uses the package (when applies); +
-  * //with_**package**_libs//, to specify package libraries to link the code with (when applies). +
-In each of the previous items, **package** will be replaced by the names listed below. Please note that the use of //with_**package**// is incompatible with the other //with_*// options, since it defines the values specified by these options in a possibly conflicting way. If you try to use both schemes, //configure// will fail and ask you to choose only one of them. +
- +
-The //with_**package**// option expects a directory as argument. For example, if you specify: +
-<code>with_fox="/path/to/fox"</code>, the //configure// script will look for: +
-  * binaries in ///path/to/fox/bin//; +
-  * include files in ///path/to/fox/include//; +
-  * libraries in ///path/to/fox/lib// and ///path/to/fox/lib64//. +
- +
-The following table summarizes the available optional features of Abinit. To enable them, you will have to make sure that the corresponding [[build:extdeps|external dependencies of Abinit]] are correctly installed on your system before configuring Abinit. +
- +
-^ Package   ^ Status       ^ Description                                    ^ +
-| BigDFT    | Development  | Wavelets for low-dimensional systems           | +
-| ETSF_IO   | Mature       | Platform-independent data exchange             | +
-| FoX       | Mature       | Fortran XML I/O                                | +
-| Libpspio  | Experimental | Reading of atomic data in many formats         | +
-| LibXC     | Mature       | More than 300 exchange-correlation functionals | +
-| LibYAML   | Experimental | Fortran YAML I/O                               | +
-| Wannier90 | Mature       | Maximally-Localized Wannier Functions (MLWFs)  | +
- +
-The following table indicates which options are allowed for each package and whether it is enabled by default. For purely optional packages, the default is to disable them, whereas packages transitioning from optional to mandatory are usually enabled by default. In the following, to determine the names of the options, just replace the stars by the corresponding package IDs. +
- +
-^ Package ID ^ Default  ^ with_* ^ with_*_bins ^ with_*_incs ^ with_*_libs ^ +
-| bigdft     | Disabled | Yes    | No          | Yes         | Yes         | +
-| etsf_io    | Disabled | Yes    | No          | Yes         | Yes         | +
-| fox        | Disabled | Yes    | No          | Yes         | Yes         | +
-| libpspio   | Disabled | Yes    | No          | Yes         | Yes         | +
-| libxc      | Enabled  | Yes    | No          | Yes         | Yes         | +
-| libyaml    | Disabled | Yes    | No          | Yes         | Yes         | +
-| wannier90  | Disabled | Yes    | Yes         | Yes         | Yes         | +
- +
-For instance, LibXC support is enabled by default, and there are //with_libxc//, //with_libxc_incs//, and //with_libxc_libs// options, but there is no //with_libxc_bins// option. +
- +
-All these options cen be overridden by //with_extdeps_prefix//, which tells the //configure// script that all external dependencies have been installed in the same place. This option is mutually exclusive with the use of any other //with_*// option for optional features. If you decide to use it, it must be the only one. +
- +
-===== Environment variables ===== +
-Coming soon ...+
  
-===== Useful configure tips and tricks ===== +//[[build:feature_triggers|Configuring feature triggers]]// provides you with useful advice on how to enhance the capabilities of Abinit with external packages.
-Coming soon ...+
build/configure.1460128851.txt.gz · Last modified: 2016/04/08 17:20 by Yann Pouillon