From 9fc3e74bfed7d2aeda081dfbe252eba3852af0b8 Mon Sep 17 00:00:00 2001 From: SY Wang Date: Wed, 1 Jul 2026 19:23:20 +0800 Subject: [PATCH] Reorganize dependency and electronic-structure documentation (#5481) --- docs/getting-started/build-from-source.md | 216 ++++++----- docs/methods/dft/gauxc.md | 190 ++++++++++ docs/methods/dft/index.md | 9 +- docs/methods/dft/k-points.md | 5 +- docs/methods/electronic_structure/index.md | 1 + .../methods/electronic_structure/wannier90.md | 148 ++++++++ docs/technologies/libraries.md | 354 ++++++++---------- 7 files changed, 633 insertions(+), 290 deletions(-) create mode 100644 docs/methods/dft/gauxc.md create mode 100644 docs/methods/electronic_structure/wannier90.md diff --git a/docs/getting-started/build-from-source.md b/docs/getting-started/build-from-source.md index b545083145..791f93da06 100644 --- a/docs/getting-started/build-from-source.md +++ b/docs/getting-started/build-from-source.md @@ -1,59 +1,121 @@ # Build from Source CP2K uses the [CMake](https://cmake.org) build system, which detects dependencies and controls the -compilation process. The dependencies have to be installed in advance. +compilation process. This page describes how to obtain a complete CP2K source tree and build it with +its dependencies. -Currently, CP2K offers two convenient ways for building CP2K from source with its dependencies: +## Obtaining source code -- The toolchain scripts, which customize and install the required dependencies in a single step, - thereby preparing the environment for compiling CP2K. Run `install_cp2k_toolchain.sh` under - `cp2k/tools/toolchain` to perform the toolchain steps; for detailed information, see - . After building toolchain, - you can use `build_cp2k.sh` to build and install CP2K with prepared toolchain environment. -- The `make_cp2k.sh` script, a more modern and automated approach which leverages - [Spack](https://spack.readthedocs.io) to install the dependencies and subsequently build CP2K. +CP2K is available as a versioned release tarball or through the Git repository. The directory +produced by either method is the root of the CP2K source tree, referred to below as `CP2K_ROOT`. + +### Release tarballs + +For a stable released version, download the versioned `cp2k-.tar.bz2` asset from the +[CP2K releases](https://github.com/cp2k/cp2k/releases) page and unpack it: + +```shell +tar -xjf cp2k-.tar.bz2 +cd cp2k- +``` + +```{tip} +It's strongly recommended to use the versioned release tarball rather than GitHub's automatically +generated `Source code` archive, especially for version <=2025.2. The versioned tarball is the +release artifact and contains any source components bundled for that release. +``` + +### Git checkout + +A Git checkout is appropriate for development builds or when a particular branch is required: + +```shell +git clone --recursive https://github.com/cp2k/cp2k.git cp2k +cd cp2k +``` + +To check out a supported release branch, replace the branch name as appropriate: + +```shell +git clone --recursive -b support/v https://github.com/cp2k/cp2k.git cp2k +cd cp2k +``` + +The `--recursive` is important for versions \<=2025.2, since it includes the DBCSR submodule. If the +repository was cloned without `--recursive`, initialize the required submodule before building: + +```shell +git submodule update --init --recursive +``` + +```{warning} +When configuring CP2K with CMake after building the toolchain inside a CP2K Git checkout with tags, +DBCSR revision detection can use the enclosing CP2K repository and generate incorrect DBCSR version +metadata, causing CMake report an error regarding the DBCSR package discovery; see +[issue #5184](https://github.com/cp2k/cp2k/issues/5184). Therefore, use the versioned release +artifact rather than a Git tag for released CP2K versions. +``` + +## Setting up dependencies and building CP2K + +At a minimum, CP2K requires a modern C and Fortran compiler, +[DBCSR](https://github.com/cp2k/dbcsr/), BLAS, and LAPACK. MPI builds additionally require MPI and +ScaLAPACK. For currently supported compilers, see the +[GitHub Wiki page](https://github.com/cp2k/cp2k/wiki/Compiler-Support). + +Detailed descriptions of available dependencies can be found in the technologies section: + +- **[](../technologies/eigensolvers/index)** +- **[](../technologies/accelerators/index)** +- **[](../technologies/libraries)** + +The following two methods provide a CP2K-managed dependency stack. For a manually managed +environment, use the CMake configuration described below. + +### Toolchain-based build + +The toolchain scripts under `tools/toolchain` build a CP2K-compatible dependency stack and prepare +the environment for a subsequent CP2K build. Use `./install_cp2k_toolchain.sh --help` to display the +help message and the complete list of options. + +To build CP2K with the toolchain, run `install_cp2k_toolchain.sh` from `tools/toolchain` with the +desired toolchain options to configure and install the requested dependencies, then use +`build_cp2k.sh` to build and install CP2K accordingly. ```{note} -- The toolchain does not cover all optional dependencies due to their complicated dependencies - requirements, such as DLA-Future. SIRIUS with complete support (including DFT-D4 and NLCG) is - also unavailable via toolchain due to the same reason. -- The latter approach with Spack is only available for the current -[CP2K master branch](https://github.com/cp2k/cp2k) and CP2K release versions `2026.02` and newer. +The toolchain does not cover every optional dependency or feature combination, such as DLA-Future, +PEXSI, and optional SIRIUS features including NLCG. If these features are needed, it's recommended +to choose the Spack-based method. ``` -## make_cp2k.sh +### Spack-based build via `make_cp2k.sh` -The `make_cp2k.sh` script supports and facilitates the build of CP2K and its dependencies from -scratch using [Spack](https://spack.readthedocs.io) and -[CMake](https://cmake.org/cmake/help/latest/index.html). The build is performed locally within the -folder `CP2K_ROOT` which defaults to the current working directory. This should be a `cp2k` folder -containing the CP2K source tree which can be download with +`make_cp2k.sh` installs the selected dependency stack with [Spack](https://spack.readthedocs.io) and +then configures, builds, and installs CP2K with +[CMake](https://cmake.org/cmake/help/latest/index.html). It operates in `CP2K_ROOT`, the root of the +CP2K source tree. -``` -> git clone https://github.com/cp2k/cp2k.git cp2k +```{note} +This build path is only available on the current CP2K master branch and CP2K release versions +`2026.2` and newer. ``` -and after +Run the script with its default options: -``` -> cd cp2k +```console +./make_cp2k.sh ``` -this script can be run using the default options with - -``` -> ./make_cp2k.sh -``` - -The flags `-h` or `--help` print the available options. +Use `./make_cp2k.sh --help` to display the complete list of options:
-Click to see all options (of version 1.7) +Click to see all options (version 1.9) ``` Usage: make_cp2k.sh [-bd | --build_deps] [-bd_only | --build_deps_only] + [-bp | --build_path PATH] [-bsl | --build_static_libcp2k] [-bt | --build_type (Debug | Release | RelWithDebInfo)] [-cray] @@ -68,7 +130,7 @@ Usage: make_cp2k.sh [-bd | --build_deps] [-mpi | --mpi_mode (mpich | no | openmpi)] [-np | --num_packages #PACKAGES] [-rc | --rebuild_cp2k] - [-t | -test "TESTOPTS"] + [-t | --test "TESTOPTS"] [-uc | --use_cache (folder | minio | no | none)] [-ue | --use_externals] [-v | --verbose] @@ -76,11 +138,11 @@ Usage: make_cp2k.sh [-bd | --build_deps] Flags: --build_deps : Force a rebuild of all CP2K dependencies from scratch (removes the spack folder) --build_deps_only : Rebuild ONLY the CP2K dependencies from scratch (removes the spack folder) - --build_static_libcp2k: Build a static CP2K library libcp2k.a instead of the default shared one libcp2k.so" - --build_type : Set preferred CMake build type for CP2K (default: Release) - --cp2k_version : CP2K version to be built (default: psmp) + --build_path : Define the CP2K build path (default: ${CP2K_ROOT}) + --build_static_libcp2k: Build a static CP2K library libcp2k.a instead of the default shared one libcp2k.so + --build_type : Set preferred CMake build type for CP2K (default: "Release") + --cp2k_version : CP2K version to be built (default: "psmp") -cray : Use Cray specific spack configuration - --disable_local_cache : Don't add local spack cache --enable_feature : Enable feature or package (default: all) --disable_feature : Disable feature or package --help : Print this help information @@ -88,7 +150,7 @@ Flags: --gpu_model : Select GPU model (default: none) --install_path : Define the CP2K installation path (default: ./install) -j : Maximum number of processes used in parallel - --mpi_mode : Set preferred MPI mode (default: mpich) + --mpi_mode : Set preferred MPI mode (default: "mpich") --num_packages : Maximum number of packages built by spack in parallel (default: 4) --rebuild_cp2k : Rebuild CP2K: removes the build folder (default: no) --test : Perform a regression test run after a successful build @@ -107,67 +169,45 @@ Hints: (see also --build_deps flag) - The folder ${CP2K_ROOT}/install is updated after each successful run -Packages: all | ace | cosma | deepmd | dftd4 | dlaf | elpa | fftw3 | greenx | hdf5 | libint2 | - libsmeagol | libtorch | libvdwxc | libxsmm | mimic | openpmd | pexsi | plumed | sirius | - spfft | spglib | spla | tblite | trexio | vori +Packages: all | ace | cosma | deepmd | dftd4 | dlaf | elpa | fftw3 | gauxc | greenx | hdf5 | libfci | + libint | libsmeagol | libtorch | libvdwxc | libxs | mimic | openpmd | pexsi | plumed | + sirius | spfft | spglib | spla | tblite | trexio | vori Features: cray_pm_accel_energy | cusolver_mp | dbm_gpu | elpa_gpu | grid_gpu | pw_gpu | spla_gemm_offloading | unified_memory ``` -
+
-The first run will take longer as it will build all requested CP2K dependencies with Spack. The -Spack installation is kept fully local in the subfolder `cp2k/spack` which corresponds to the -`tools/toolchain/install` folder created by the CP2K toolchain. +`make_cp2k.sh` creates and reuses the following directories below `CP2K_ROOT`: -Subsequent runs of the `make_cp2k.sh` script will use the software stack from that `cp2k/spack` -folder. A rebuild of all CP2K dependencies can be enforced simply by removing or renaming the folder -`cp2k/spack`. The latter allows for keeping different software stacks (see also `-bd` and `-bd_only` -flags). +- `spack/` contains the local Spack installation and dependency stack. Remove or rename it to + rebuild all dependencies from scratch; `--build_deps` and `--build_deps_only` provide the same + behavior from the script. +- `build/` contains the CMake build tree. Remove or rename it, or use `--rebuild_cp2k`, to + reconfigure and rebuild CP2K from scratch. +- `install/` contains the installed CP2K files and is updated after each successful build. -It is recommended to store already compiled packages in a cache (default). This will accelerate the -(re)build of the CP2K dependencies with Spack significantly (see -uc flag). +By default, compiled packages are also stored in a local cache. This significantly accelerates later +dependency builds; see `--use_cache` for the available cache backends. -After the CP2K dependencies are built with Spack, CP2K itself is built and installed using `CMake` -in the subfolders `cp2k/build` and `cp2k/install`, respectively. +#### Testing -Subsequent runs of the script will use the CMake configuration in the subfolder `cp2k/build`. A -rebuild of CP2K from scratch can be enforced by removing or renaming that subfolder. +Add `-t` or `--test` followed by `TESTOPTS` to run a regression test after a successful build: -A CP2K regression run can be launched automatically by adding the flag `-t ""` (or `--test ""`). -This flag expects a string with the `TESTOPTS`, e.g. - -``` -> ./make_cp2k.sh -t "--maxtasks 8 --restrictdir QS/regtest-gpw-1" +```console +./make_cp2k.sh --test "--maxtasks 16 --flagslow" ``` -Alternatively, the script `cp2k/install/bin/run_tests` can be launched after a successful CP2K -build. Usage examples are printed at the end of a (successful) `make_cp2k.sh` run. +Alternatively, run `install/bin/run_tests` after a successful build. The script prints usage +examples at the end of a successful run. -### Docker containers +## CMake configuration options -Check the folder [`cp2k/tools/docker`](https://github.com/cp2k/cp2k/tree/master/tools/docker) for -Docker files with the name pattern `Dockerfile.test_spack_*` like `Dockerfile.test_spack_psmp` to -build Docker containers using `make_cp2k.sh`. Each Docker file provides a usage example in its -header which employs [`podman`](https://docs.podman.io/en/latest/) for building the CP2K docker -containers. +Detailed descriptions of most build options can be found in the technologies section together with +description of available dependencies. -## Dependencies and build options - -At a minimum CP2K requirements a modern C and Fortran compiler, -[DBCSR](https://github.com/cp2k/dbcsr/), BLAS, and LAPACK. For parallel builds it also needs at -least MPI and ScaLAPACK. - -For currently supported compilers, see [here](https://www.cp2k.org/dev:compiler_support). - -Detailed descriptions of most build options can be found in the technologies section: - -- **[](../technologies/eigensolvers/index)** -- **[](../technologies/accelerators/index)** -- **[](../technologies/libraries)** - -There are some other important general options you may want to know: +Here are some other important general options you may want to know: - `-G ` Specifies which type of build files would be generated. Default is `Unix Makefiles`, which generates a GNU Makefile and allows you to build with running `make` in @@ -208,6 +248,7 @@ cd mkdir build/ cmake -S . -B build \ -GNinja \ + -DCP2K_USE_MPI=ON \ -DCP2K_USE_LIBXC=ON \ -DCP2K_USE_LIBINT2=ON \ -DCP2K_USE_SPGLIB=ON \ @@ -215,13 +256,14 @@ cmake -S . -B build \ -DCP2K_USE_SPLA=ON \ -DCP2K_USE_SIRIUS=ON \ -DCP2K_USE_COSMA=ON \ - -DCP2K_USE_ACCEL=CUDA -DCP2K_WITH_GPU=A100 + -DCP2K_USE_ACCEL=CUDA \ + -DCP2K_WITH_GPU=A100 cmake --build build -j 32 cmake --install build ``` - The commands `cmake --build build -j 32` and `cmake --install build` can be replaced by a single - command `cmake --build build --target install -j 32` + command `cmake --build build --target install -j 32`. - If you want to clean your build cache after installing in order to save space, simply run - `cmake --build build --target clean` + `cmake --build build --target clean`. diff --git a/docs/methods/dft/gauxc.md b/docs/methods/dft/gauxc.md new file mode 100644 index 0000000000..94e1fdf1f5 --- /dev/null +++ b/docs/methods/dft/gauxc.md @@ -0,0 +1,190 @@ +# GauXC + +[GauXC](https://github.com/wavefunction91/GauXC) provides an external exchange-correlation (XC) +integrator for Quickstep. It can evaluate selected conventional functionals and GauXC OneDFT models, +including SKALA models, through the [GAUXC](#CP2K_INPUT.FORCE_EVAL.DFT.XC.XC_FUNCTIONAL.GAUXC) +section. + +The CP2K interface currently provides two distinct paths: + +- The default molecular-quadrature path evaluates the XC contribution through GauXC's atom-centered + molecular grid. It is intended primarily for isolated calculations. +- The experimental native-grid path (`NATIVE_GRID T`) evaluates SKALA TorchScript models from the + CP2K GPW real-space grid. It has a different support scope and should be treated separately from + the molecular-quadrature path. + +## Basic Input + +GauXC is selected as the only XC functional in the +[XC_FUNCTIONAL](#CP2K_INPUT.FORCE_EVAL.DFT.XC.XC_FUNCTIONAL) section. The following fragment selects +a conventional functional evaluated by GauXC: + +```text +&XC + &XC_FUNCTIONAL + &GAUXC + FUNCTIONAL PBE + &END GAUXC + &END XC_FUNCTIONAL +&END XC +``` + +A non-`NONE` model selects a GauXC OneDFT model. The model can be a `.fun` file or an installed +model name. The underlying functional is optional in this case and defaults to `PBE`: + +```text +&XC + &XC_FUNCTIONAL + &GAUXC + MODEL path/to/model.fun + &END GAUXC + &END XC_FUNCTIONAL +&END XC +``` + +The `.fun` format and available model checkpoints are defined by GauXC rather than CP2K. `.fun` +files use TorchScript serialization. The official Skala 1.1 checkpoint can be downloaded together +with GauXC in toolchain, or from Hugging Face with the `hf` command provided by the +`huggingface_hub` package: + +```bash +hf download microsoft/skala-1.1 skala-1.1.fun --local-dir . +``` + +Select the downloaded checkpoint with `MODEL ./skala-1.1.fun`. Alternatively, set +`GAUXC_SKALA_MODEL` to its path and use `MODEL SKALA`. See the +[GauXC/Skala model documentation](https://microsoft.github.io/skala/gauxc/c-library.html#download-checkpoint-from-huggingface) +for the model interface and available checkpoints. Obtain `.fun` files only from trusted sources. + +The molecular-quadrature OneDFT/SKALA path defaults to `GRID SUPERFINE` and +`PRUNING_SCHEME UNPRUNED` unless these settings are provided explicitly. These settings are +recommended for force checks; coarser grids are accuracy settings and should be converged for the +target calculation. + +## Molecular-Quadrature Path + +The default path uses GauXC's molecular quadrature. It is the established interface for isolated +Quickstep calculations, including energy, XC potential, and nuclear-gradient calculations within its +supported scope. + +### Periodic Reference Calculations + +Periodic inputs are not a compact periodic GauXC implementation. To use the molecular path in a +periodic input as an isolated-cell reference calculation, explicitly set `PERIODIC_REFERENCE` to +`T`: + +```text +&GAUXC + PERIODIC_REFERENCE T +&END GAUXC +``` + +This reference path is restricted to all of the following: + +- `PERIODIC XYZ`; +- Gamma-point calculations with one AO image; +- `METHOD GPW` with GTH pseudopotentials. + +It uses a molecular quadrature and must not be used to validate compact periodic materials. Periodic +neighbor-cell AO blocks, k-points, compact-cell quadrature, and periodic stress tensors require a +dedicated periodic GauXC interface. + +### OneDFT and SKALA Runtime Controls + +`ONEDFT_ATOM_CHUNK_SIZE` controls atom-blocked Torch inference. A positive value selects the number +of atoms per block, zero disables chunking, and the default lets GauXC or the +`GAUXC_ONEDFT_ATOM_CHUNK_SIZE` environment variable choose the policy. + +For MPI calculations, `SKALA_RUNTIME` controls the communicator used for OneDFT/SKALA energy and +potential evaluation. `AUTO` uses the force-evaluation communicator for closed-shell calculations +and a replicated rank-local runtime for open-shell calculations. The corresponding +`ONEDFT_GRADIENT_RUNTIME` setting defaults to a conservative replicated runtime for nuclear +gradients. Select `MPI` only with a GauXC installation that supports distributed OneDFT gradients. + +### GAPW and Other Restrictions + +- Conventional GauXC with `METHOD GAPW` requires all-electron potentials. With pseudopotentials, + `METHOD GAPW` is available only for OneDFT/SKALA-style models and evaluates the molecular + AO/valence-density XC term directly. +- OneDFT/SKALA with `METHOD GAPW` and GTH/ECP pseudopotentials currently supports energies only; + forces and molecular virials are unavailable. CP2K's GAPW one-center XC correction is not used on + this path. +- `METHOD GAPW_XC`, NLCC pseudopotentials with OneDFT/SKALA, and non-local `VDW_POTENTIAL` + corrections are not supported by the molecular GauXC path. +- Higher-XC-derivative response and kernel properties are not available through GauXC. Real-time + propagation is also unsupported. + +`MOLECULAR_VIRIAL` is a finite-system diagnostic constructed from GauXC nuclear gradients; it is not +a periodic stress tensor. + +## Experimental Native-Grid SKALA Path + +`NATIVE_GRID T` bypasses GauXC's molecular quadrature and evaluates a SKALA TorchScript model from +CP2K's GPW real-space grid. It is an experimental path for energy, XC potential, and +nuclear-gradient/stress calculations with one GAUXC functional. Unlike the molecular path, it can +cover selected isolated and periodic GPW/GAPW calculations, including k-point density matrices. + +A minimal native-grid input is: + +```text +&XC + &XC_FUNCTIONAL + &GAUXC + MODEL SKALA + NATIVE_GRID T + NATIVE_GRID_DIAGNOSTICS T + &END GAUXC + &END XC_FUNCTIONAL +&END XC +``` + +`NATIVE_GRID_DIAGNOSTICS T` prints the electron count, spin moment, and summed grid weights of the +feature block supplied to Torch. This is useful when validating a model or a periodic setup. + +### CUDA and MPI + +The CPU TorchScript path is limited to non-k-point calculations. K-point calculations require a +CUDA-capable LibTorch installation and: + +```text +&GAUXC + NATIVE_GRID T + NATIVE_GRID_USE_CUDA T + NATIVE_GRID_CUDA_DEVICE -1 +&END GAUXC +``` + +A negative `NATIVE_GRID_CUDA_DEVICE` assigns the MPI-local rank to a visible CUDA device. A +non-negative value selects that visible device explicitly. CUDA TorchScript exports containing +hard-coded device constants may still require a rank-local `CUDA_VISIBLE_DEVICES` setting. + +`NATIVE_GRID_ATOM_CHUNKS T` distributes the model evaluation in atom blocks for MPI calculations and +can reduce peak CUDA memory. `NATIVE_GRID_ATOM_CHUNK_MAX_ROWS` further limits the number of +atom-grid rows handled by one Torch call when needed. + +### Current Scope + +The native-grid path supports regular-grid GPW/GTH calculations and selected GAPW calculations. For +GAPW with GTH/ECP pseudopotentials, only regular-grid feature kinds are supported; PAW and +one-center GAPW pseudopotential contributions are not implemented. `METHOD GAPW_XC`, ROKS, ADMM, and +non-k-point multiple-image calculations are also outside the current scope. + +Because this is an experimental interface, validate energies, forces, and stresses for the chosen +model and system before using it for production calculations. + +## Troubleshooting + +- `CP2K_GAUXC_STATUS_STDERR=1` mirrors GauXC status messages to standard error. This can be useful + when a launcher or CI system does not retain the CP2K output file after an external-library + failure. +- TorchScript models require a LibTorch installation compatible with CP2K's BLAS and OpenMP runtime. + Pre-built LibTorch bundles can conflict with a CP2K build using oneMKL; use a compatible BLAS + stack or build LibTorch against the selected dynamic stack when this occurs. +- `OUTPUT_PATH` writes GauXC molecule and basis-set diagnostics to an existing directory. It + requires GauXC to have been built with HDF5 support. + +## See Also + +- [](../../technologies/libraries) +- [](gpw) +- [](gapw) diff --git a/docs/methods/dft/index.md b/docs/methods/dft/index.md index 6d56340463..0224841612 100644 --- a/docs/methods/dft/index.md +++ b/docs/methods/dft/index.md @@ -8,14 +8,15 @@ maxdepth: 2 gpw gapw hartree-fock/index +basis_sets +pseudopotentials +k-points +cutoff local_ri constrained cneo linear_scaling -k-points -basis_sets -pseudopotentials -cutoff +gauxc ``` Density functional theory in CP2K is primarily provided by the Quickstep module. Most production diff --git a/docs/methods/dft/k-points.md b/docs/methods/dft/k-points.md index 12e375c6ed..fc8baa2218 100644 --- a/docs/methods/dft/k-points.md +++ b/docs/methods/dft/k-points.md @@ -211,9 +211,8 @@ additional requirements are documented separately: k-point MO output. Molden output is not available for k-point calculations. - [](hartree-fock/ri_kpoints) documents RI-HFX with k-point sampling and includes a band-structure example. -- [&WANNIER90](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.WANNIER90) is an experimental interface. With - [KPOINTS_SOURCE](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.WANNIER90.KPOINTS_SOURCE) set to `SCF`, it can - use the full SCF mesh from `&DFT%KPOINTS`; Wannier90 export requires a complete mesh. +- [](../electronic_structure/wannier90) documents the experimental Wannier90 interface, including + export from the SCF k-point mesh and the treatment of symmetry-reduced SCF meshes. - [](../optimization/geometry_and_cell_opt) describes geometry and cell optimization. Their interaction with experimental atomic k-point symmetry is discussed below. diff --git a/docs/methods/electronic_structure/index.md b/docs/methods/electronic_structure/index.md index 753958b48d..03a0947149 100644 --- a/docs/methods/electronic_structure/index.md +++ b/docs/methods/electronic_structure/index.md @@ -15,4 +15,5 @@ molecular_orbitals band/index dos population/index +wannier90 ``` diff --git a/docs/methods/electronic_structure/wannier90.md b/docs/methods/electronic_structure/wannier90.md new file mode 100644 index 0000000000..ec79ea7267 --- /dev/null +++ b/docs/methods/electronic_structure/wannier90.md @@ -0,0 +1,148 @@ +# Wannier90 interface + +CP2K can generate the input and matrix files required by [Wannier90](https://wannier.org/) through +[&WANNIER90](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.WANNIER90). The interface is experimental. It prepares +the k-point mesh, eigenvalues, and overlap matrices from a periodic Quickstep calculation; the +subsequent construction and use of Wannier functions are performed by Wannier90. + +Wannier90 requires a complete, uniformly weighted k-point mesh with its nearest-neighbour +connectivity. A high-symmetry band path is not a suitable input mesh. See [](../dft/k-points) for +k-point sampling and convergence. + +## Basic workflow + +1. Run a periodic, diagonalization-based SCF calculation with a converged k-point mesh and enough + bands for the intended Wannierization. +1. Enable `&DFT%PRINT%WANNIER90`. CP2K writes the Wannier90 input and data files. +1. Add the Wannier90 settings specific to the calculation, such as projections, disentanglement + windows, or post-processing options, to the generated `.win` file, then run Wannier90 with the + same seed name. + +For example, the following exports a four-function Wannierization using the k-point mesh already +used by the SCF calculation: + +```text +&FORCE_EVAL + &DFT + &KPOINTS + SCHEME MONKHORST-PACK 6 6 6 + &END KPOINTS + &PRINT + &WANNIER90 + SEED_NAME silicon + KPOINTS_SOURCE SCF + WANNIER_FUNCTIONS 4 + ADDED_MOS 4 + &END WANNIER90 + &END PRINT + &END DFT +&END FORCE_EVAL +``` + +[WANNIER_FUNCTIONS](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.WANNIER90.WANNIER_FUNCTIONS) sets the number of +Wannier functions. [ADDED_MOS](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.WANNIER90.ADDED_MOS) provides +additional bands for the export, and +[EXCLUDE_BANDS](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.WANNIER90.EXCLUDE_BANDS) can remove selected bands +from it. Choose the exported band window and the subsequent Wannier90 settings for the particular +material and target property. + +## Generated files + +With `SEED_NAME silicon`, CP2K writes the following Wannier90 files: + +- `silicon.win`: a starting Wannier90 input file containing the cell, atomic positions, exported + band count, and k-point mesh; +- `silicon.mmn`: overlap matrices between neighbouring k-points; +- `silicon.eig`: eigenvalues for the exported bands; and +- `silicon.amn`: an identity projection matrix, only when `USE_BLOCH_PHASES T` is used. + +CP2K regenerates these files when the calculation is run. Preserve a separate copy of a completed +Wannier90 input file, or add project-specific settings after the CP2K export has finished. + +## Selecting the k-point source + +[KPOINTS_SOURCE](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.WANNIER90.KPOINTS_SOURCE) selects how CP2K builds +the export mesh. + +### Use the SCF mesh + +`KPOINTS_SOURCE SCF` uses the k-point mesh from `&DFT%KPOINTS`. It supports explicit Gamma, +Monkhorst--Pack, MacDonald, and equally weighted `GENERAL` meshes, and is the preferred choice when +the Wannier90 export should match the SCF calculation: + +```text +&DFT + &KPOINTS + SCHEME MONKHORST-PACK 6 6 6 + &END KPOINTS + &PRINT + &WANNIER90 + KPOINTS_SOURCE SCF + ... + &END WANNIER90 + &END PRINT +&END DFT +``` + +`KPOINTS_SOURCE SCF` requires an active `&DFT%KPOINTS` section. For an explicit `GENERAL` mesh, the +points must have equal weights and must form a complete mesh from which Wannier90 connectivity can +be constructed. If CP2K cannot infer the mesh dimensions, set +[MP_GRID](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.WANNIER90.MP_GRID) explicitly. + +When the SCF calculation used k-point symmetry reduction, CP2K regenerates the corresponding full +mesh for the export. Wannier90 needs that full mesh even though the SCF calculation solved only its +irreducible subset. + +### Use a separate Monkhorst--Pack mesh + +`KPOINTS_SOURCE MP_GRID` is the historical default. It builds a full Monkhorst--Pack mesh from +[MP_GRID](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.WANNIER90.MP_GRID), independently of the SCF k-point +setup: + +```text +&PRINT + &WANNIER90 + KPOINTS_SOURCE MP_GRID + MP_GRID 6 6 6 + ... + &END WANNIER90 +&END PRINT +``` + +This path performs the necessary full-mesh diagonalizations for the Wannier90 files. It can be used +when the SCF calculation is Gamma-only or when the export mesh intentionally differs from the SCF +mesh, but using a separately chosen mesh requires its own convergence assessment. + +## Reusing SCF orbitals + +With `KPOINTS_SOURCE SCF`, [REUSE_SCF_MOS](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.WANNIER90.REUSE_SCF_MOS) +is enabled by default. CP2K reuses the SCF orbital coefficients directly when the SCF mesh is +already complete. It can also reconstruct some time-reversal and atomic-symmetry-related points from +a symmetry-reduced SCF mesh. + +The reconstruction is only used when the exported band window is suitable. In particular, a +symmetry-reconstructed window must contain complete degenerate subspaces. If it cuts through a +degenerate subspace, CP2K falls back to a full-mesh diagonalization before writing the Wannier90 +files. This fallback is intentional and preserves a well-defined exported subspace. + +[VALIDATE_REUSE_SCF_MOS](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.WANNIER90.VALIDATE_REUSE_SCF_MOS) builds a +full-mesh reference and compares it with the reconstructed orbitals. It is expensive and intended +for development and diagnostic use, not routine production calculations. + +## Bloch phases and projections + +[USE_BLOCH_PHASES](#CP2K_INPUT.FORCE_EVAL.DFT.PRINT.WANNIER90.USE_BLOCH_PHASES) applies the CP2K +Bloch-phase gauge and writes an identity `.amn` projection file. It is valid only when +`WANNIER_FUNCTIONS` equals the number of exported bands. Disentanglement calculations, or any case +with fewer Wannier functions than exported bands, still require explicit Wannier90 projections. + +## Limitations + +The CP2K Wannier90 interface is experimental. In particular: + +- use a complete k-point mesh rather than a band path; +- verify the convergence of the SCF and export meshes for the target quantity; +- inspect CP2K output when exporting from a symmetry-reduced SCF mesh, since CP2K may reconstruct + the missing orbitals or fall back to full-mesh diagonalization; and +- consult the Wannier90 documentation for localization, projection, disentanglement, interpolation, + and post-processing settings that are not controlled by CP2K. diff --git a/docs/technologies/libraries.md b/docs/technologies/libraries.md index dcd706c4b5..878aa47edc 100644 --- a/docs/technologies/libraries.md +++ b/docs/technologies/libraries.md @@ -16,38 +16,55 @@ latest versions available, use the interfaces matching your compiler, and downlo - Please note that the BLAS/LAPACK implementation used by CP2K needs to be thread-safe (OpenMP). -Examples are the sequential variant of the Intel MKL, the Cray libsci, the OpenBLAS OpenMP variant -and the reference BLAS/LAPACK packages. Usually the CMake step of CP2K will auto-detect the type of -BLAS and SCALAPACK and then use the right configuration to ensure the code is thread-safe; however, -if you encounter problems when compiling with MKL, try passing -`-DCP2K_BLAS_VENDOR=MKL -DCP2K_SCALAPACK_VENDOR=MKL` to CMake. MKL with multiple OpenMP threads in -CP2K requires that CP2K was compiled with the Intel compiler. +Examples are the sequential or thread variant of the Intel MKL, the Cray libsci, the OpenBLAS OpenMP +variant and the reference BLAS/LAPACK packages. Usually the CMake step of CP2K will auto-detect the +type of BLAS and SCALAPACK and then use the right configuration to ensure the code is thread-safe; +however, if detection is ambiguous, `-DCP2K_BLAS_VENDOR=MKL` and `-DCP2K_SCALAPACK_VENDOR=MKL` can +be used for a oneMKL installation -On the Mac, BLAS and LAPACK may be provided by Apple's Accelerate framework. If using this -framework, `-DCP2K_BLAS_VENDOR=Apple` must be passed to CMake to account for some interface -incompatibilities between Accelerate and reference BLAS/LAPACK. +On the Mac, BLAS and LAPACK can be provided by either OpenBLAS or Apple's Accelerate framework. + +## DBCSR (required, block-sparse matrix operations) + +CP2K requires [DBCSR](https://github.com/cp2k/dbcsr/) for block-sparse matrix operations. It is +found automatically by CMake. For MPI builds, DBCSR must also have been built with MPI support. The +CP2K toolchain, Spack, and a compatible external DBCSR installation are supported ways to provide +it. ## MPI and ScaLAPACK (required for MPI parallel builds) MPI (version 3 or later) and SCALAPACK are needed for parallel code. (Use the latest versions available and download all patches!). -```{Warning} -Note that your MPI installation must match the used Fortran compiler. If your computing -platform does not provide MPI, there are several freely available alternatives: - -- MPICH MPI: (may require `-fallow-argument-mismatch` when building with - GCC 10) -- OpenMPI MPI: +```{warning} +Note that the MPI installation must match the used Fortran compiler. ``` -For more information of ScaLAPACK, see . ScaLAPACK can be part of -ACML (AMD) or cluster MKL (Intel); these libraries are recommended on the corresponding machines if -available. +If your computing platform does not provide MPI, there are several freely available implementations: -CP2K assumes that the MPI library implements MPI version 3. Older versions of MPI (e.g., MPI 2.0) -are not supported. CP2K can make use of the `mpi_f08` module. If its use is requested, pass -`-DCP2K_USE_MPI_F08=ON` to CMake. +- MPICH: (may require `-fallow-argument-mismatch` when building with GCC + 10\) +- OpenMPI: + +```{note} +Open MPI applies process binding by default. This can affect hybrid MPI+OpenMP runs because the +launcher does not infer the number of OpenMP threads required by each MPI rank. A binding that is +appropriate for an MPI-only calculation can therefore leave each rank with too few CPUs for its +OpenMP threads. + +For hybrid runs, inspect the resulting mapping and binding, for example with +`mpirun --display map,bind ...`. Depending on the scheduler allocation and node topology, either +disable binding with `--bind-to none` or explicitly allocate the required number of cores per rank, +for example with `--map-by slot:PE= --bind-to core`. +``` + +CP2K assumes that the MPI library implements MPI version 3; older versions of MPI (e.g., MPI 2.0) +are not supported. CP2K can make use of the `mpi_f08` module; pass `-DCP2K_USE_MPI_F08=ON` to CMake +to enable it. + +For more information of ScaLAPACK, see . ScaLAPACK can be part of +AOCL (AMD) or oneMKL (Intel); these libraries are recommended on the corresponding machines if +available. ## FFTW (improved performance of FFTs) @@ -58,170 +75,100 @@ to install and use FFTW3. The current version of CP2K works with FFTW 3.X (pass FFTW is also provided by MKL. If you have MKL but still want to use standalone FFTW3, pass `-DCP2K_USE_FFTW3_WITH_MKL=ON` to CMake. -```{Warning} +```{warning} Note that FFTW must know the Fortran compiler you will use in order to install properly (e.g., `export F77=gfortran` before configure if you intend to use gfortran). ``` -Since CP2K is OpenMP parallelized, the FFTW3 threading library libfftw3_omp (or libfftw3_threads) is -required. Pass `-DCP2K_ENABLE_FFTW3_OPENMP_SUPPORT=ON` or `-DCP2K_ENABLE_FFTW3_THREADS_SUPPORT=ON` -respectivly to CMake. +Since CP2K is OpenMP parallelized, CP2K enables the FFTW3 OpenMP interface by default +(`-DCP2K_ENABLE_FFTW3_OPENMP_SUPPORT=ON`); the FFTW installation must therefore provide +`libfftw3_omp`. The alternative threads interface can be selected with +`-DCP2K_ENABLE_FFTW3_THREADS_SUPPORT=ON`, which requires `libfftw3_threads`. -```{Warning} +```{important} Support for FFTW is required for some features, especially systems with very large block sizes/grid sizes. A future release of CP2K may make FFTW a hard dependency. Please consider CP2K to be compiled with support for FFTW. ``` -## LIBINT (enables methods including HF exchange) +## LIBINT (ERI calculation for HFX) -- Hartree-Fock exchange requires the LIBINT package to calculate ERI. -- Pass `-DCP2K_USE_LIBINT2=ON` to CMake to enable LIBINT. -- It's always suggested to build LIBINT with toolchain or Spack. If you want to build it yourself, - download a CP2K-configured LIBINT library from our - [CP2K server](https://www.cp2k.org/static/downloads/), then build and install LIBINT by following - the instructions provided [here](https://github.com/cp2k/cp2k/blob/master/tools/libint/README.md). - Note that using a library configured for higher maximum angular momentum will increase build time - and binary size of CP2K binary (assuming static linking). -- CP2K is not hardwired to these provided libraries and any other LIBINT library (version >= 2.5.0) - should be compatible as long as it was compiled with `--enable-eri=1` and default ordering. -- Avoid debugging information (`-g` or `-g2` flag) for compiling LIBINT since this will increase - library size by a large factor. +[Libint2](https://github.com/evaleev/libint) provides the electron-repulsion integrals required for +Hartree--Fock exchange and related methods. -## LIBXSMM (improved performance for matrix multiplication) +- Pass `-DCP2K_USE_LIBINT2=ON` to CMake to enable Libint2. +- The CP2K toolchain and Spack are the recommended ways to obtain a compatible Libint2 build. For a + manual build, CP2K-configured Libint source packages are available from the + [CP2K download server](https://www.cp2k.org/static/downloads/); see also + [the CP2K Libint instructions](https://github.com/cp2k/cp2k/blob/master/tools/libint/README.md). A + library configured for a higher maximum angular momentum increases CP2K compilation time and, + particularly for static builds, the binary size. +- CP2K is not restricted to these source packages. A manually built installation must provide + electron-repulsion integrals (`--enable-eri=1`) with Libint's default ordering, export a CMake + package, and include the Fortran interface (`libint_f.mod`). +- Avoid compiling Libint with extensive debug information unless it is specifically required, since + this can increase the library size substantially. -- A library for matrix operations and deep learning primitives: - . -- Pass `-DCP2K_USE_LIBXSMM=ON` to CMake to enable it. +## LIBXS (improved performance for matrix multiplication) + +- A library for matrix operations and deep learning primitives: . +- [LIBXS](https://github.com/hfp/libxs/) provides optimized matrix operations used by CP2K and is + required when using CP2K's OpenCL backend. +- Pass `-DCP2K_USE_LIBXS=ON` to CMake to enable it. + +## LIBXSTREAM (OpenCL offload runtime) + +- [LIBXSTREAM](https://github.com/hfp/libxstream) provides the stream and memory-management layer + used by CP2K's OpenCL offload backend. +- It is required automatically when configuring OpenCL acceleration with `-DCP2K_USE_ACCEL=OPENCL`; + there is no separate `CP2K_USE_LIBXSTREAM` option. +- OpenCL builds also require LIBXS. For a manual build, make both LIBXSTREAM and the OpenCL + development files discoverable by CMake, for example through `CMAKE_PREFIX_PATH`. +- See [](./accelerators/opencl.md) for OpenCL runtime and backend-specific requirements. + +## LIBXSMM (JIT-kernel provider of libXS) + +- A library that provide a JIT-kernel for LibXS: . +- Pass `-DCP2K_USE_LIBXSMM=ON` to CMake to enable it; this is only valid when `-DCP2K_USE_LIBXS=ON` + is passed. +- The integration of LIBXS and LIBXSMM is done through `libxs_jit.F` that is provided by LIBXS but + compiled by DBCSR and CP2K. - LIBXSMM can be used with both CUDA and HIP backends (see [](./accelerators/index.md)). ## LIBXC (wider choice of xc functionals) +LIBXC is a library that provides wider choice of XC functionals. + - The latest version of LIBXC can be downloaded from -- CP2K does not make use of fourth derivates such that LIBXC may be configured with - `./configure --disable-lxc `. -- During the installation, the directories `$(LIBXC_DIR)/lib` and `$(LIBXC_DIR)/include` are - created. +- CP2K makes use of third derivates but does not use fourth derivates, so LIBXC may be configured + with `cmake .. -DDISABLE_KXC=OFF `. - Pass `-DCP2K_USE_LIBXC=ON` to CMake. +- [LIBXSMM](https://github.com/libxsmm/libxsmm/) provides just-in-time kernels for LIBXS. ## GauXC (xc integration library) GauXC can be used to evaluate selected exchange-correlation functionals through an external integrator. -- Pass `--with-gauxc=install` to the toolchain installer. The toolchain build enables GauXC - OneDFT/SKALA support and therefore also installs libtorch. -- Pass `-DCP2K_USE_GAUXC=ON` to CMake. -- GauXC in CP2K is primarily an energy, potential, and nuclear-gradient path for isolated QS - systems. A limited isolated-cell reference path can be enabled with `PERIODIC_REFERENCE T` for - Gamma-only, single-image `METHOD GPW` calculations with GTH pseudopotentials in periodic - `PERIODIC XYZ` inputs. This opt-in path keeps molecular validation inputs usable when CP2K is run - with periodic boundary conditions, but it still uses GauXC's molecular quadrature. It must not be - used as validation for compact periodic materials. k-points, periodic neighbour-cell AO blocks, - compact-cell quadrature, GAPW/GAPW_XC, and periodic stress tensors require a dedicated periodic - GauXC design. OneDFT/SKALA gradients under MPI are evaluated with a replicated single-rank GauXC - runtime on each CP2K rank because GauXC does not yet provide distributed OneDFT gradients. -- OneDFT/SKALA is selected in the `&GAUXC` subsection with a non-`NONE` `MODEL`, for example a - `.fun` model file or a GauXC-installed model name. The `FUNCTIONAL` keyword is optional for - OneDFT/SKALA inputs and defaults to `PBE`; `MODEL SKALA` inputs do not need an explicit - `FUNCTIONAL PBE` line. -- `ONEDFT_ATOM_CHUNK_SIZE` can be used to control the GauXC OneDFT/SKALA Torch atom blocking from - CP2K. A positive value requests atom-by-atom chunks of that size, zero disables atom chunking, and - the default leaves GauXC's model policy or `GAUXC_ONEDFT_ATOM_CHUNK_SIZE` environment setting in - control. -- `GAUXC_GRADIENT_MPI_RUNTIME=1` is an experimental runtime override for testing GauXC versions that - provide distributed OneDFT nuclear gradients. The default remains the conservative replicated - single-rank gradient runtime for MPI calculations. -- `CP2K_GAUXC_STATUS_STDERR=1` mirrors GauXC status messages to standard error. This is useful when - launcher or CI logs hide the CP2K output file after an external-library failure. -- Some OpenBLAS/libtorch combinations can be sensitive to BLAS symbol resolution for TorchScript - models using batched matrix products. If a SKALA run crashes in `cblas_sgemm_batch`, use a - compatible BLAS setup or ensure `libtorch_cpu.so` is loaded before `libopenblas.so`. -- `METHOD GAPW` with OneDFT/SKALA is a molecular GauXC matrix path. GauXC evaluates the full XC term - directly on its molecular quadrature from the AO density. For pseudopotential inputs this is the - smooth valence density, so CP2K's local/semi-local GAPW one-center XC correction is not used for - OneDFT/SKALA. GAPW pseudopotential inputs currently support energies only in this path; nuclear - gradients and molecular virials require a dedicated derivative of the molecular AO/valence-density - XC path. NLCC pseudopotentials remain unsupported because the frozen core density would need a - SKALA-consistent feature definition. -- `METHOD GAPW_XC` with GauXC remains disabled pending a dedicated design for the smooth-density and - one-center XC terms. It must not be used for non-local OneDFT/SKALA models. -- A true compact-cell periodic GauXC path needs a new GauXC interface rather than only a CP2K input - change. The missing pieces are an explicit cell/lattice descriptor, a unit-cell quadrature or - CP2K-grid task interface, periodic AO images or an equivalent periodic density representation, - return of the periodic XC matrix to CP2K's image/k-point layout, and separate force/stress - derivatives. PBE-through-GauXC on compact Gamma-only `METHOD GPW` test cells should be the first - quantitative validation target for that interface. -- A CP2K-native SKALA grid path is a separate research direction from periodic GauXC. The SKALA - TorchScript protocol requires the meta-GGA grid features `density`, `grad`, and `kin`, the - integration features `grid_coords` and `grid_weights`, and the per-atom packing metadata - `atomic_grid_weights`, `atomic_grid_sizes`, `atomic_grid_size_bound_shape`, and - `coarse_0_atomic_coords`. For Gamma-only periodic `METHOD GPW` this maps naturally to CP2K's - regular real-space grid for the density, gradient, kinetic-energy density, grid coordinates, and - weights. The non-local SKALA part still requires an explicit, validated atom-to-grid partition - before it can be considered a compact periodic implementation. MPI runs gather the local GPW grid - features into the same atom-partitioned feature block on every rank and evaluate the Torch model - redundantly; this is a correctness path for distributed CP2K grids, not yet a scalable distributed - SKALA integration algorithm. -- For such a native SKALA path the first useful implementation target is energy, VXC, and nuclear - gradients on Gamma-only `METHOD GPW` with GTH pseudopotentials, `FUNCTIONAL PBE`, one `GAUXC` - functional, and a single image. The force path combines CP2K's regular GPW density-response - integration with the explicit Torch autograd derivative of the SKALA coarse atomic coordinates. - The current atom partition is a fixed nearest-atom partition between assignment changes; periodic - stress, k-points, ROKS, ADMM, and NLCC pseudopotentials should remain separate validation steps. - `METHOD GAPW` is not enabled in this native grid path yet: a valid GAPW extension has to - reconstruct not only an all-electron density on the CP2K grid, but also the corresponding density - gradients and kinetic-energy density entering the SKALA features. GAPW pseudopotential - augmentation corrections remain a separate methodological problem. -- The first native-grid GAPW target should be all-electron GAPW only. The required design is to - build a SKALA feature block from the reconstructed all-electron density, gradient, and - kinetic-energy density on a well-defined grid and validate it against the molecular all-electron - GauXC matrix path before adding pseudopotential augmentation corrections, `GAPW_XC`, periodic - stresses, or k-points. -- `NATIVE_GRID_DIAGNOSTICS T` prints the electron count, spin moment, and summed grid weights of the - CP2K-native SKALA feature block passed to Torch. This is intended for compact RKS/UKS, - wrapped-cell atom-partition, and MPI/OpenMP validation runs. -- `NATIVE_GRID_USE_CUDA T` evaluates the experimental CP2K-native SKALA Torch model on CUDA if the - linked libtorch provides CUDA support. This is an explicit opt-in because CUDA-exported SKALA - models can create internal ragged-index tensors on CUDA. -- `NATIVE_GRID_CUDA_DEVICE` controls the visible CUDA device used by the native-grid Torch path. The - default value `0` preserves the previous behavior of using logical `cuda:0`. A negative value maps - the MPI-local rank to a visible CUDA device, so multi-rank jobs can use multiple logical CUDA - devices. The Torch wrapper loads TorchScript models through CPU and then moves them to the - selected CUDA device, and guards Torch calls with that device so rank-local model internals and - input tensors stay on the same GPU. Some CUDA-exported TorchScript models still embed `cuda:0` - graph constants; those exports need per-rank `CUDA_VISIBLE_DEVICES` set before CP2K starts. When - CUDA is enabled the native-grid diagnostic output also prints the selected logical and visible - device for each real-space-grid rank. -- Molecular CDFT and mixed CDFT-CI energy calculations can be used with the GauXC matrix path. SKALA - CDFT coverage is currently limited to smoke tests of the energy and constraint-potential path. -- Response/kernel properties requiring higher XC derivatives are not supported by the GauXC path and - abort explicitly. -- Supported OneDFT/SKALA force checks use `GRID SUPERFINE` and `PRUNING_SCHEME UNPRUNED` by default. - Coarser explicit GauXC grids are allowed, but should be treated as accuracy settings. -- `MOLECULAR_VIRIAL` is a finite-system force diagnostic from GauXC nuclear gradients, not a - periodic stress tensor. -- SKALA regression tests are technical smoke and force-consistency checks. They do not constitute - scientific validation of the SKALA model. +- Libtorch is required for OneDFT/SKALA support. +- Pass `-DCP2K_USE_GAUXC=ON` to CMake to enable GauXC. An MPI-enabled CP2K build requires a GauXC + installation built with MPI support. +- TorchScript-based GauXC models require a libtorch installation compatible with CP2K's BLAS and + OpenMP runtime. Pre-built libtorch bundles can conflict with a CP2K build using oneMKL; use a + compatible generic BLAS stack or rebuild libtorch against the selected dynamic stack when this + occurs. +- See [](../methods/dft/gauxc) for input, supported calculation types, and current limitations. ## PEXSI (low scaling SCF method) -The Pole EXpansion and Selected Inversion (PEXSI) method requires the PEXSI library and two -dependencies (ParMETIS or PT-Scotch and SuperLU_DIST). +The Pole EXpansion and Selected Inversion (PEXSI) method requires an MPI build and a compatible +PEXSI CMake package. PEXSI itself depends on a sparse-direct-solver and graph-partitioning stack, +typically SuperLU_DIST together with ParMETIS or PT-Scotch. -- PEXSI is only available via a Spack build of CP2K. -- Pass `-DCP2K_USE_PEXSI=ON` to CMake. - -Below are some additional hints that may help in the compilation process: - -- For building PT-Scotch, the flag `-DSCOTCH_METIS_PREFIX` in `Makefile.inc` must not be set and the - flag `-DSCOTCH_PTHREAD` must be removed. -- For building SuperLU_DIST with PT-Scotch, you must set the following in `make.inc`: - -```shell -METISLIB = -lscotchmetis -lscotch -lscotcherr -PARMETISLIB = -lptscotchparmetis -lptscotch -lptscotcherr -``` +- Pass `-DCP2K_USE_PEXSI=ON` to CMake to enable PEXSI. +- Spack is the most convenient supported route for provisioning the complete PEXSI dependency stack. + Manual builds are also possible when a compatible PEXSI installation and its dependencies are + available to CMake. It's not supported to install PEXSI through toolchain ## PLUMED (enables various enhanced sampling methods) @@ -231,46 +178,57 @@ See for full instructions. ## spglib (crystal symmetries tools) -A library for finding and handling crystal symmetries +Spglib is a library for finding and handling crystal symmetries. -- The spglib can be downloaded from +- The library can be downloaded from - For building CP2K with the spglib pass `-DCP2K_USE_SPGLIB=ON` to CMake. ## SIRIUS (plane wave calculations) SIRIUS is a domain specific library for electronic structure calculations with plane wave method. -- The code is available at -- For building CP2K with SIRIUS pass `-DCP2K_USE_SIRIUS=ON` to CMake. -- Pass `-DCP2K_USE_LIBVDWXC=ON` if support is activated in SIRIUS. -- Pass `-DCP2K_USE_SIRIUS_DFTD3=ON` when sirius is compiled with dftd3 support. -- Pass `-DCP2K_USE_SIRIUS_DFTD4=ON` when sirius is compiled with dftd4 support. -- Pass `-DCP2K_USE_SIRIUS_NLCG=ON` when sirius is compiled with nlcg support. -- Pass `-DCP2K_USE_SIRIUS_VCSQNM=ON` when sirius is compiled with variable cell relaxation support. -- See for more information. +- The code is available at . +- SIRIUS support requires an MPI build. Pass `-DCP2K_USE_SIRIUS=ON` to CMake to enable it. +- SIRIUS has its own dependency stack, commonly including HDF5, SpFFT, SPLA, and eigensolver + libraries. It's recommended to build SIRIUS through Spack to get all features enabled. +- Pass `-DCP2K_USE_LIBVDWXC=ON` when the selected SIRIUS build provides libvdwxc support. +- Pass `-DCP2K_USE_SIRIUS_DFTD3=ON` when SIRIUS was built with DFT-D3 support. +- Pass `-DCP2K_USE_SIRIUS_DFTD4=ON` when SIRIUS was built with DFT-D4 support. +- Pass `-DCP2K_USE_SIRIUS_NLCG=ON` when SIRIUS was built with NLCG support. +- Pass `-DCP2K_USE_SIRIUS_VCSQNM=ON` when SIRIUS was built with variable-cell-relaxation support. +- See for build options and supported features. ## COSMA (Distributed Communication-Optimal Matrix-Matrix Multiplication Algorithm) -- COSMA is an alternative for the pdgemm routine included in ScaLAPACK. The library supports both - CPU and GPUs. +COSMA is an alternative for the pdgemm routine included in ScaLAPACK. The library supports both CPU +and GPUs. + - Pass `-DCP2K_USE_COSMA=ON` to CMake to enable support for COSMA. - See for more information. ## LibVori (Voronoi Integration for Electrostatic Properties from Electron Density) -- LibVori is a library which enables the calculation of electrostatic properties (charge, dipole - vector, quadrupole tensor, etc.) via integration of the total electron density in the Voronoi cell - of each atom. +LibVori is a library which enables the calculation of electrostatic properties (charge, dipole +vector, quadrupole tensor, etc.) via integration of the total electron density in the Voronoi cell +of each atom. + - Pass `-DCP2K_USE_VORI=ON` to CMake to enable support for LibVori. - See for more information. - LibVori also enables support for the BQB file format for compressed trajectories, please see for more information as well as the `bqbtool` to inspect BQB files. -## Torch (Machine Learning Framework needed for NequIP) +## Torch (PyTorch C++ library) -- The C++ API of PyTorch can be downloaded from https://pytorch.org/get-started/locally/. +LibTorch is the C++ distribution of PyTorch. CP2K uses it for the NequIP interface and for GauXC +OneDFT/SKALA models. + +- LibTorch can be downloaded from the + [PyTorch installation page](https://pytorch.org/get-started/locally/). - Pass `-DCP2K_USE_LIBTORCH=ON` to CMake to enable support for libtorch. +- For GPU acceleration, choose a LibTorch distribution compatible with the available backend and + hardware, such as CUDA for an NVIDIA GPU or ROCm for a supported AMD GPU. Refer to the PyTorch + installation page for current platform, driver, and runtime requirements. ```{caution} Note that currently pre-built libtorch bundle (up to 2.12.1) is not compatible with CP2K's external @@ -284,15 +242,14 @@ The SPLA library is a hard dependency of SIRIUS but can also be used as a standa provides a generic interface to the blas gemm family with offloading on GPU. Offloading supports both CUDA and ROCm (HIP), making the functionality available on both NVIDIA and AMD GPUs. -To make the functionality available, pass `-DCP2K_USE_SPLA_GEMM_OFFLOADING=ON` to CMake and compile -SPLA with Fortran interface and GPU support. Please note that only the functions replacing the dgemm -calls with `offload_dgemm` will eventually be offloaded to the GPU. The SPLA library has internal -criteria to decide if it is worth to do the operation on GPU or not. Calls to `offload_dgemm` also -accept pointers on GPU or a combination of them. +SPLA support requires an MPI build and is enabled with `-DCP2K_USE_SPLA=ON`. To offload eligible +`dgemm` operations, additionally pass `-DCP2K_USE_SPLA_GEMM_OFFLOADING=ON` and enable CUDA or HIP. +SPLA must be built with its Fortran interface and a GPU backend. SPLA decides at runtime whether an +individual operation is suitable for offloading. ## DeePMD-kit (wider range of interaction potentials) -DeePMD-kit - Deep Potential Molecular Dynamics. Support for DeePMD-kit can be enabled by passing +DeePMD-kit provides Deep Potential models. Support for its C interface can be enabled by passing `-DCP2K_USE_DEEPMD=ON` to CMake. - DeePMD-kit C interface can be downloaded from @@ -301,8 +258,8 @@ DeePMD-kit - Deep Potential Molecular Dynamics. Support for DeePMD-kit can be en ## ACE (atomic cluster expansion ML potentials) -Atomic cluster expansion for accurate and transferable interatomic potentials support can be enabled -by passing `-DCP2K_USE_ACE=ON` to CMake. +Atomic cluster expansion potentials from ML-PACE for accurate and transferable interatomic +potentials support can be enabled by passing `-DCP2K_USE_ACE=ON` to CMake. - the library files can be downloaded from - use cmake/make to compile. There is no install, just ensure that the cp2k build process links in @@ -312,16 +269,18 @@ by passing `-DCP2K_USE_ACE=ON` to CMake. ## DFTD4 (dispersion correction) -- dftd4 - Generally Applicable Atomic-Charge Dependent London Dispersion Correction. -- Please always use the CMake-built dftd4 package rather than the Meson-built one for CP2K. -- For more information see +DFTD4 provides the Generally Applicable Atomic-Charge Dependent London Dispersion Correction. + +- Please use the CMake-built dftd4 package rather than the Meson-built one for CP2K. +- For more information, see - Pass `-DCP2K_USE_DFTD4=ON` to CMake. ## libsmeagol (electron transport calculation with current-induced forces) -- libsmeagol is an external library to compute electron transport properties using Non-Equilibrium - Green Functions (NEGF) method. The library can be downloaded from - . +libsmeagol is an external library to compute electron transport properties using Non-Equilibrium +Green Functions (NEGF) method. The library can be downloaded from +. + - libsmeagol depends on an MPI library and can only be linked with MPI parallel CP2K binaries. - During the installation, the directories `$(LIBSMEAGOL_DIR)/lib` and `$(LIBGRPP_DIR)/obj` are created. @@ -329,8 +288,8 @@ by passing `-DCP2K_USE_ACE=ON` to CMake. ## TREXIO (unified computational chemistry format) -TREXIO - Open-source file format and library. Support for TREXIO can be enabled by passing -`-DCP2K_USE_TREXIO=ON` to CMake. +TREXIO is an open-source file format and library. Support can be enabled by passing +`-DCP2K_USE_TREXIO=ON` to CMake. HDF5 is required. - TREXIO library can be downloaded from - For more information see . @@ -342,19 +301,22 @@ for LibFCI can be enabled by passing `-DCP2K_USE_LIBFCI=ON` to CMake. - LibFCI can be downloaded from -## GREENX (basically functionality for GreenX methods (RPA, GW, Laplace-MP2 etc.) +## GREENX (GreenX methods such as RPA, GW, and Laplace-MP2) -greenX - Open-source file format and library. Support for greenX can be enabled by passing -`-DCP2K_USE_GREENX=ON` to CMake. +GreenX provides functionality for GreenX methods such as RPA, GW, and Laplace-MP2. Support can be +enabled by passing `-DCP2K_USE_GREENX=ON` to CMake. - GREENX library can be downloaded from - For more information see . ## TBLITE (semiempirical method) -- tblite - Light-weight tight-binding framework -- With tblite you can calculate using GFN2-xTB method. +TBLITE is a lightweight tight-binding framework that provides the GFN2-xTB method. + - Please always use the CMake-built tblite package rather than the Meson-built one for CP2K. +- A CMake build of tblite from source also installs DFT-D4 and s-dftd3. Therefore, no separate DFTD4 + installation is needed when tblite is enabled; s-dftd3 also provides parameters for additional XC + functionals. - For more information see - Pass `-DCP2K_USE_TBLITE=ON` to CMake. @@ -380,7 +342,7 @@ as part of DFLAGS may or may not work. MiMiC - Multiscale simulation framework -- Interface realized through MCL library, which can be downloaded from +- Its interface is realized through the MCL library, which can be downloaded from - For more information about the framework and supported programs see - Pass `-DCP2K_USE_MIMIC=ON` to CMake