comp-chem/cp2k
1
0
Fork 0
mirror of https://github.com/cp2k/cp2k.git synced 2026-07-29 06:35:28 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Reorganize dependency and electronic-structure documentation (#5481)

Browse source
This commit is contained in:
SY Wang 2026-07-01 19:23:20 +08:00 • committed by GitHub
parent 2cf3252f98
commit 9fc3e74bfe
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 633 additions and 290 deletions
Download patch file Download diff file Expand all files Collapse all files

216
docs/getting-started/build-from-source.md
View file

@ -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
<https://github.com/cp2k/cp2k/blob/master/tools/toolchain/README.md>. 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-<version>.tar.bz2` asset from the
[CP2K releases](https://github.com/cp2k/cp2k/releases) page and unpack it:
```shell
tar -xjf cp2k-<version>.tar.bz2
cd cp2k-<version>
```
```{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<version> 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:
<details>
<summary>Click to see all options (of version 1.7)</summary>
<summary>Click to see all options (version 1.9)</summary>
```
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
```
</details>
</details><br>
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 <Generator>` 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 <CP2K_REPOSITORY>
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`.

190
docs/methods/dft/gauxc.md Normal file
View file

@ -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)

9
docs/methods/dft/index.md
View file

@ -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

5
docs/methods/dft/k-points.md
View file

@ -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.

1
docs/methods/electronic_structure/index.md
View file

@ -15,4 +15,5 @@ molecular_orbitals
band/index
dos
population/index
wannier90
```

148
docs/methods/electronic_structure/wannier90.md Normal file
View file

@ -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.

354
docs/technologies/libraries.md
View file

@ -16,38 +16,55 @@ latest versions available, use the interfaces matching your compiler, and downlo
- <https://www.tacc.utexas.edu/research-development/tacc-software/gotoblas2>
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: <https://www.mpich.org/> (may require `-fallow-argument-mismatch` when building with
GCC 10)
- OpenMPI MPI: <http://www.open-mpi.org/>
```{warning}
Note that the MPI installation must match the used Fortran compiler.
```
For more information of ScaLAPACK, see <http://www.netlib.org/scalapack/>. 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: <https://www.mpich.org/> (may require `-fallow-argument-mismatch` when building with GCC
10\)
- OpenMPI: <http://www.open-mpi.org/>
```{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=<OMP_NUM_THREADS> --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 <http://www.netlib.org/scalapack/>. 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:
<https://github.com/libxsmm/libxsmm/>.
- 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: <https://github.com/hfp/libxs/>.
- [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: <https://github.com/libxsmm/libxsmm/>.
- 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 <https://gitlab.com/libxc/libxc/-/releases>
- CP2K does not make use of fourth derivates such that LIBXC may be configured with
`./configure --disable-lxc <other LIBXC configuration flags>`.
- 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 <other LIBXC configuration flags>`.
- 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 <https://cp2k.org/howto:install_with_plumed> 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 <https://github.com/atztogo/spglib>
- The library can be downloaded from <https://github.com/atztogo/spglib>
- 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 <https://github.com/electronic-structure/SIRIUS>
- 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 <https://electronic-structure.github.io/SIRIUS-doc/> for more information.
- The code is available at <https://github.com/electronic-structure/SIRIUS>.
- 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 <https://electronic-structure.github.io/SIRIUS-doc/> 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 <https://github.com/eth-cscs/COSMA> 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 <https://brehm-research.de/libvori> for more information.
- LibVori also enables support for the BQB file format for compressed trajectories, please see
<https://brehm-research.de/bqb> 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 <https://github.com/ICAMS/lammps-user-pace>
- 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 <https://github.com/dftd4/dftd4>
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 <https://github.com/dftd4/dftd4>
- 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
<https://github.com/StefanoSanvitoGroup/libsmeagol>.
libsmeagol is an external library to compute electron transport properties using Non-Equilibrium
Green Functions (NEGF) method. The library can be downloaded from
<https://github.com/StefanoSanvitoGroup/libsmeagol>.
- 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 <https://github.com/trex-coe/trexio>
- For more information see <https://trex-coe.github.io/trexio/index.html>.
@ -342,19 +301,22 @@ for LibFCI can be enabled by passing `-DCP2K_USE_LIBFCI=ON` to CMake.
- LibFCI can be downloaded from <https://github.com/DCM-Uni-Paderborn/libfci>
## 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 <https://github.com/nomad-coe/greenX>
- For more information see <https://nomad-coe.github.io/greenX/>.
## 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 <https://github.com/tblite/tblite>
- 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
<https://https://mimic-project.org>
- For more information about the framework and supported programs see <https://mimic-project.org>
- Pass `-DCP2K_USE_MIMIC=ON` to CMake