K-Point Grid Generator

A stand-alone version of the K-point Grid Server has been created and tested. It can be used as a local application, and provides the same functionality as the current version of the server.

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

k-pointGridGenerator_2019.06.14.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.05.14. 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.

Open-sourcing of the source code is also on agenda and a public repository will be available soon.

K-Point Grid Server

Server version 2019.06.14 (release notes) and client version C2016.06.06 (release notes) have been released.

To make use of all of the features of server versions 2016.06.06 and later, it is necessary to use the getKPoints script version C2016.06.06 or later.

To receive updates and announcements regarding the k-point server, please subscribe to the kpoints-announce mailing list.

Please contact us at kpoints@jhu.edu if you encounter any difficulties.

The k-point grid server provides efficient k-point grids for Brillouin zone integration. We estimate that on average the use of these grids accelerates well-converged calculations by a factor of about 2 compared to conventional methods for generating Monkhorst-Pack grids.

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 (rmin 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. This flag only affects triclinic system 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. This flag only affects monoclinic system 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.

*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 (rmin 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 MINDISTANCEd, 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 (rmin) 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):

Additional details and benchmark information can be found in our paper.

How to cite

If you would like to cite the k-point grid server, please cite the following paper:

Efficient generation of generalized Monkhorst-Pack grids through the use of informatics
Pandu Wisesa, Kyle A. McGill, and Tim Mueller
Physical Review B 93, 155109 (2016)

The version history for the server can be found here.

The version history for the client can be found here.

To receive updates and announcements regarding the k-point server, please subscribe to the kpoints-announce mailing list.

If you have any questions or comments, please contact us at kpoints@jhu.edu.

<- Tools and Data home