Mueller Research Group - K-Point Grid Server

Research People Publications Tools and Data Tutorials Open Positions Contact Information

We have created three tools for generating efficient k-point grids: KpLib, the K-Point Grid Generator, and the K-Point Grid Server. We estimate that on average the use of the grids generated by these tools accelerates well-converged calculations by a factor of about 2 compared to conventional methods for generating Monkhorst-Pack grids.

KpLib

KpLib is a lightweight, open-sourced C++ library for searching and generating optimal generalized k-point grids for efficient integration in reciprocal space during electronic structure calcualtions. It implements novel algorithms that allow fast generation of highly efficient generalized k-point grids on-the-fly, without querying a database. We choose C++ as the programming language to assist integration with existing electronic structure codes.

To use the library, users can compile the source code and link the binaries as a common C++ library. A cmake script is provided to automate the compilation, and a simple application is shipped together with the source code to demonstrate the usage of the API. A python wrapper is also provided for python users with the help of Dr. Shyam Dwaraknath from LBNL. It is released as a package on PyPI under the name kpLib, and can be quickly installed using pip. Users can either import it as a module or use the terminal command kpGen it provides. If both the C++ API and the python wrapper don't fit your needs, you can customize your own wrapper functions easily, given that the source code uses primarily elementary data structures and has only 1122 lines,

KpLib is open-sourced at: https://gitlab.com/muellergroup/kplib. Detailed documentation of the API and its usage can be found at the homepage of the repository.

For explanations of our algorithms underlying the dynamic generation approach implemented in kpLib, users are encouraged to read our recent paper.

To receive updates and announcements regarding kpLib, the K-Point Grid Generator (see below), and the K-Point Server (see below), please subscribe to the kpoints-announce mailing list.

Please contact us at [email protected] if you encounter any difficulties.

Notice: We are excited to announce that version 1.1.1 of kpLib is now available. In this release, we have made the Python interface more flexible by allowing structures to be passed in as plain Python lists or Numpy arrays. This gives users the option to choose their preferred structure parser. Bugs were also fixed that could cause the Python interface to hang without output. Users can upgrade from the source code on gitlab or from the PyPI index. For details of the change and documentaion of the updated interface, please refer to the README of our gitlab repository.

K-Point Grid Generator

The K-point Grid Generatoris a standalone version of the K-point Grid Server. It can be used as a local application, and it provides the same functionality as the current version of the server. Updates of K-point Server are synchronized with K-point Grid Generator (i.e. all updates on K-point Server will be mirrored in K-point Grid Generator.)

A pre-built executable jar is available. To use the application, please download the tarball:

k-pointGridGenerator_2020.11.25.tar.gz

To configure the application, users need to set the variable "JAR_PATH", in the modified getKPoints script to the location where you have put the executable jar, and change the "CALL_SERVER_IF_LOCAL_MISSING" to "TRUE" if you want the script to call the server when the local program failed to be executed for some reasons. Then you can copy the script to ~/bin, and use it as any other Linux commands. We have included an instruction in the tarball for users reference.

A new database has been published on 2019.08.01. The new database is not compatible with previous version of the K-Point Grid Generator. The version number (date of release) is included in the database file names to remind users of the version of the database they are using, and a check is enforced in the code to ensure the code and database is compatible.

K-point Grid Generator is open-sourced at: https://gitlab.com/muellergroup/k-pointGridGenerator

Details about how pre-generated k-point grids are organized in the database and how K-point Grid Generator search and retrieve grids from the database are available in the Supplementary Information of our recent paper.

K-Point Grid Server

Server version 2020.11.25 (release notes) and client version C2023.04.28 (release notes) have been released. To make use of all of the features of server versions 2020.11.25 and later, it is necessary to use the getKPoints script version C2020.11.25 or later.

The k-point grid server provides efficient k-point grids for Brillouin zone integration. To use the server, please download the following files:

getKPoints is a script that calls the server.
PRECALC is an input file containing parameters for k-point grid generation.

getKPoints is a Bash script that should work on most Unix and Linux systems. To generate k-point grids using getKPoints, it needs to have execution permission and be called from the directory where the calculation input files are located. We recommend you put it somewhere in your PATH. For example, if getKPoints is placed in the directory where the input files are located, then calling:

./getKPoints

will automatically generate the k-point grids for the given input files. Currently, only VASP input file formats are supported. However, we are working to expand the support for other software.

The PRECALC file should be placed in the same directory as the rest of your input files. If the PRECALC file cannot be found, default values will be used. The available parameters for the PRECALC file are:

Parameter	Allowed values	Default Value	Explanation
INCLUDEGAMMA	TRUE / FALSE / AUTO	AUTO	Determines if the grid will contain the gamma point. AUTO selects the grid with the smallest number of irreducible k-points.
MINDISTANCE*	Numeric (Angstroms)	0	The minimum allowed distance between lattice points on the real-space superlattice (r_min in our paper). This determines the density of the k-point grid.
MINTOTALKPOINTS*	Numeric	1	The minimum allowed number of total k-points in the Brillouin zone.
KPPRA*	Numeric	1	The minimum allowed number of k-points per reciprocal atom. We do not advise setting a value for KPPRA for systems with less than three periodic dimensions. For example, if KPPRA were used to set the k-point density for a two-dimensional slab, doubling the thickness of the slab would cut the density of the k-point grid roughly in half. This is probably not the desired behavior. In this case, we recommend using MINDISTANCE instead.
GAPDISTANCE	Numeric (Angstroms)	7	This parameter is used to auto-detect slabs, nanowires, and nanoparticles. If there is a gap (vacuum) that is at least GAPDISTANCE wide in the provided structure, the k-point density in the corresponding direction will be reduced accordingly.
REMOVE_SYMMETRY	NONE / STRUCTURAL/ TIME_REVERSAL/ ALL	NONE	An optional flag to control the symmetry operations that reduces the k-point grid. The default value, NONE, will try to maximize the number of symmetry operations used to reduce the k-point grid based on the provided input files. STRUCTURAL removes all structural symmetry operations when generating the grid, retaining only time-reversal symmetry. TIME_REVERSAL removes time-reversal symmetry, retaining only structural symmetry. ALL removes all symmetry operations from consideration, so symmetry is not used to reduce the k-point grid.
TRICLINIC_SEARCH_DEPTH	Numeric	729	This parameter controls the upper limit of the size of the grids that are searched before using a scale factor for triclinic structures. Generally speaking, a larger value will result in more extensive searches for k-point grids in some cases, which may return a better k-point grid but may also take more time. A larger value will also increase the maximum number of total k-points the server can return for triclinic structures. This flag only affects triclinic systems and is preferred over LOW_SYMMETRY_SEARCH_DEPTH.
MONOCLINIC_SEARCH_DEPTH	Numeric	1728	This parameter controls the upper limit of the size of the grids that are searched before using a scale factor for monoclinic structures. Generally speaking, a larger value will result in more extensive searches for k-point grids in some cases, which may return a better k-point grid but may also take more time. A larger value will also increase the maximum number of total k-points the server can return for monoclinic structures. This flag only affects monoclinic systems and is preferred over LOW_SYMMETRY_SEARCH_DEPTH.
LOW_SYMMETRY_SEARCH_DEPTH	Numeric	729	This parameter controls the upper limit of the size of the grids that are searched before using a scale factor for triclinic and monoclinic structures. Generally speaking, a larger value will result in more extensive searches for k-point grids in some cases, which may return a better k-point grid but may also take more time. This flag only affects triclinic and monoclinic systems. This flag is deprecated since version 2019.06.14 and will be removed in future releases. It is overriden by MONOCLINIC_SEARCH_DEPTH and TRICLINIC_SEARCH_DEPTH if they are present.
HEADER	VERBOSE / SIMPLE	SIMPLE	Sets the verbosity of the grid information written to the file.
WRITE_LATTICE_VECTORS	TRUE / FALSE	FALSE	If TRUE, generating basis vectors of a grid will be written in KPOINTS. Otherwise, explicit list of k-points will be used. Note this parameter is exclusively meant for VASP.6 and later versions. It could lead to incorrect results for VASP versions earlier than 6. Using the format of generating vectors can be espeically beneficial for calculations in which k-points weights may be adjusted, such as calculations of phonon. It also allow tetrahedron integration (ISMEAR=-5) in VASP without providing a connection table. When TRUE, generating vectors will also be printed to screen in addition to be saved to KPOINTS. When FALSE, list of k-points will be directly saved to KPOITNS without being printed out to standard output.

*If the PRECALC file does not include at least one of MINDISTANCE, MINTOTALKPOINTS, or KPPRA, then MINDISTANCE=28.1 will be used to determine grid density.

Below is an example of a PRECALC file:

MINDISTANCE=20
INCLUDEGAMMA=FALSE

Selecting MINDISTANCE

The selection of MINDISTANCE (r_min in our paper) determines the density of the k-point grid generated. The number of k-points in the returned grid will scale roughly as MINDISTANCE^d, where "d" is the number of periodic dimension (e.g. d=3 for bulk materials and d=2 for slab calculations). To get the best performance, we recommend you select a value of MINDISTANCE carefully. Listed in the table below are good starting values for MINDISTANCE for a given metal / non-metal and a desired calculation accuracy. Please note that the values below are provided for reference purposes only and the only way to know for sure whether the desired accuracy has been achieved or not is by testing it.

Desired Accuracy	MINDISTANCE for Metals	MINDISTANCE for Non-Metals
1 meV / atom	50	31.5
3 meV / atom	35.4	19.8
10 meV / atom	28.1	18

MINDISTANCE (r_min) can be related to other parameters used to specify the minimum grid density: k-points per reciprocal atom (kAtom), k-points per reciprocal cubic Angstrom (kVol), and the length of the longest vector in the Minkowski-reduced representation of the k-point lattice in reciprocal space (kDist). To do this, we match the percentage of calculations that converge for a given level of accuracy for different different parameters. The comparison is shown below (click image to enlarge):