# KpLib
[](
https://pypi.org/project/kpLib/)
[](https://doi.org/10.1016/j.commatsci.2020.110100)
[](https://gitlab.com/muellergroup/kplib/commits/master)
KpLib is a C++ library for finding the optimal Generalized Monkhorst-Pack k-points grid. It can be imported into electronic-structure packages as a generator of efficient generalized *k*-point grids, or be integrated into user scripts through the Python interface `kpLib`.
For questions of KpLib and underlying algorithms, you are welcomed to check our paper at [here](https://doi.org/10.1016/j.commatsci.2020.110100) or send emails to kpoints@jhu.edu.
**Note**: We have fixed in `v.1.1.0` (2023.04.08) a few bugs of the Python interface causing scripts to hang for monoclinic and trigonal system in $hR$ representation. We also reduced dependencies of external Python packages to the minimum to let users choose their favoriate package for structure IO. Please check the [RELEASE.md](https://gitlab.com/muellergroup/kplib/-/blob/master/RELEASE.md) note for details.
# Usage
## Route I: Integrating KpLib as a C++ library in simulation package
---
## Compile KpLib as a library
We use `cmake` to detect native build environment and generate native build files. For Unix-like operating systems, users can build the project by:
$ git clone https://gitlab.com/muellergroup/kplib.git
$ cd kplib
$ mkdir build
$ cd build
$ cmake ..
$ make
Then you can find a static library at `build/libkpoints.a` and a dynamic library at `build/libkpoints.so`.
## Use KpLib in C++ Code
There are basically two steps:
1. Copy the header file `src/kPointLatticeGenerator.h` to your `include` folder, and add the following line to your source code
#include "kPointLatticeGenerator.h"
2. Link the library at the linking stage.
For example, to link the static library and compile the object `myapp.o` to the final executable `myapp`, you can
$ g++ myapp.o -L /path/to/lib libkpoints.a -o myapp
If you want to use the dynamic library, you can
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/lib
$ g++ myapp.o -L /path/to/lib -lkpoints -o myapp
The first line tells the loader, `ld`, where to find the shared library at runtime, since the dynamic linkage only puts a reference of the library in the executable.
Then you are ready to go!
An explanation of the API with more details can be found below, together with a demo C++ program (`demo_kplib/src`) created to demonstrate the usage of this API in C++ environment and the conventions the API assumes.
## Route II: Use KpLib as a Python package
---
## Installation
### **Install from PyPI using `pip`**
This will install the core KpLib module with minimal third-party dependencies. User will need to parse input structures and write out generated *K*-point grid using their favorite matsci packages (e.g. `ase` and `pymatgen`).
```
$ pip install --user pybind11 build wheel
$ pip install --user kplib # Install only the core kplib package.
$ pip install --user kplib[cli] # To install the CLI tool `kpgen`.
# This will also install `pymatgen` and `click`
```
### **Install from source using `pip`**
The Python interface is a thin wrapper of the C++ library. Building from source should be straight forward. It also provides a way to install a CLI command to be called in terminal (requiring `pymatgen` for IO).
Step 1. Download source code from https://gitlab.com/muellergroup/kplib.
```
$ git clone https://gitlab.com/muellergroup/kplib.git
```
Step 2. The C++-Python interface is written using `pybind11`, and the `setup.py` imports it at the beginning for compiling the C++ code into a Python external module. So, it should be installed before installing `kpLib`.
```
$ pip install --user pybind11
$ pip install --user build wheel # Python build toolchain that you might already have.
```
Step 3. If you would like to choose your own structure parser (such as `pymatgen`, `ase` and other wonderful packages), you can install only the core module of `kpLib` with a minimal dependencies:
```
$ cd kplib
$ pip install --user .
```
If you would like to use the CLI command tool `kpgen`, you can use the following code to install `kpLib`. This will additionally install `pymatgen` (as a parser) and `click` (to provide a nice CLI interface):
```
$ cd kplib
$ pip install --user .[cli]
$ which kpgen
```
If you want to test your installation, you can install `kpLib` with dependencies
that enables the test suite (`pymatgen` and `pytest`). After installation, you can run tests to make sure everything is correctly installed.
```
$ cd kplib
$ pip install --user .[tests]
$ pytest
```
## Using KpLib in Python script
The `kpLib` Python package is written in the way to provide an interface
for the core KpLib function and allow maximal usage flexibility. The choice
of packages for parsing input structure and for writing the generated k-points
grid to a desired format is left to users. The following section will first
describe the signature of the `get_kpoints` function, and then give two
example scripts using the two popular packages `pymatgen` and `ase` for I/O.
`kpLib.interface::get_kpoints` is the core and only function the `kpLib` Python
package provides. Its signature is as follows:
```
def get_kpoints(
lattice: List[List[float]] or numpy.ndarray,
fractional_coords: List[List[float]] or numpy.ndarray,
atomic_numbers: List[int] or Tuple[int],
min_distance: float = 0.1,
min_total_kpoints: int = 1,
include_gamma: str = "auto",
symprec: float = 1e-5,
use_scale_factor: bool = False,
) -> Dict
```
`get_kpoints` uses the 3 positional arguments to define a structure. The rest of the keyword
arguments define requirements of the output *K*-point grid. The size requirement of *K*-point grids is defined by `min_distance` and `min_total_kpoints`. They can be used
separately or together. We recommand using `min_distance`. For an example of correlating
the conventional way of specifying a Monkhorst-Pack grid by three integers
`m1 x m2 x m3` to `min_distance`, see the section below.
The meaning of all arguments are as follows:
- `lattice`: A 3x3 matrix representing the lattice vectors of the unit cell of the input structure. Each row represents a vector, i.e. in the format of [**a**, **b**, **c**]. It can be a list of list or a `numpy.ndarray`.
- `fractional_coords`: A list of 3-dimensional coordinates in the fractional format relative to the lattice vectors. It can be a list of list or a `numpy.ndarray`.
- `atomic_numbers`: A list of atomic numbers, the i-th number of which defines the element of the i-th atom at the position `fractional_coords[i]`. It can be a list or a tuple.
- `min_distance`: The minimum required distance in real-space between any pair of lattice points in the superlattice corresponding to the returned *K*-point grid. It specifys the
size of the required *K*-point grid and has a unit of Angstrom. The larger the value of
`min_distance`, the denser the returned grid will be (i.e., more symmetrically distinct
*K*-point).
- `min_total_kpoints`: Minimum number of total *K*-points required in the returned
*K*-point grid. Note, it is not the number of symmetrically distinct *K*-points that
are actually used in a calculation. The total set of *K*-points will be reduced by symmetry
to the minimal set of distinct *K*-points, which will be used in a calculation.
- `include_gamma`: It can have values `true` or `false`, or `auto`. Use `true`
to include the Gamma point (i.e. [0, 0, 0] of reciprocal space) in the return grid.
Use `false` to exclude the Gamma point. Use `auto` to let kplib choose between
the two types of grid and return the one with a smaller number of symmetrically
distinct *K*-points. If they have the same number of distinct *K*-points, return
the one with larger effecitive min_distance.
- `symprec`: Precision in real space when determining structure symmetries. The default
is `1E-5`. Atomic coordinates with a difference less than `symprec` will be determined
as equivalent. If you want to include more symmetries, use a larger value.
- `use_scale_factor`: A scheme to speed up the search at the cost of returning a sub-optimial
*K*-point grid. Default behaviour is to not use the scheme. You can consider use this scheme
when the code takes a very long time to return a grid. For a detailed explanation,
see the end of this README.
The `get_kpoints` function returns the *K*-point grid as a `dict`. The keys are:
- `min_periodic_distance`: The minimum distance between any pair of lattice points of the real-space superlattice corresponding to the returned *K*-point grid.
- `num_distinct_kpts`: The number of symmetrically distinct *K*-points. This is the number of
*K*-points actually used in a calculation.
- `distinct_coords`: Fractional coordinates of symmetrically distinct *K*-points.
- `distinct_weights`: Weights of corresponding symmetrically distinct *K*-point in `distinct_coords`.
- `num_total_kpts`: The number of total *K*-points.
- `coords`: Fractional coordinates of all *K*-points.
- `weights`: Weights of corresponding *K*-points in `coords`.
Usually the coordinates and weights of distinct *K*-points are enough to define an
input file of a calculation.
### **Making sense of "`min_distance`"**
"Minimum distance" means the minimum periodic distance between any pairs of
lattice points on a real-space lattice. The reciprocal lattice of a primitive unit cell
is a supercell in the reciprocal space of the reciprocal lattice of a super cell in real space. It implys each *K*-point grid corresponds to a real-space superlattice. Therefore, we can use the "minimum distance" of a real-space superlattice to specify the size its corresponding *K*-point grid in the reciprocal space. The larger the `min_distance`, the larger the supercell and hence the denser the *K*-point grid.
For example, consider an artificial tetragonal structure with a lattice as $[[2, 0, 0], [0, 2, 0], [0, 0, 3]]$ and a single atom at the origin. Its space group is $P4/mmm$. A traditional Monkhorst-Pack 4x4x4 grid with the Gamma point would correspond to a supercell of $[[8, 0, 0], [0, 8, 0], [0, 0, 12]]$ and has **18** symmetrically distinct *K*-points. The minimum periodic distance in this case is 8 Angstroms.
When using `kpLib` with `min_distance` = 8, the Gamma-centered result would have only
**9** symmetrically distinct *K*-points and an effective minimum distance of 8.485. For
shifted grids, the result would be a grid with **6** symmetrically distinct *K*-points
and an effective minimum distance of 8. Similar calculation accuracy but three times
less the number of distinct *K*-points.
### **Example Python Scripts**
Here, we give two examples of using `kpLib` in Python script, using the popular
[`pymatgen`](https://pymatgen.org/) and [`ase`](https://wiki.fysik.dtu.dk/ase/)
packages respectively for IO.
```python
from kplib import get_kpoints
from pymatgen.core import Structure
from pymatgen.io.vasp.inputs import Kpoints, Kpoints_supported_modes
struct = Structure.from_file("./POSCAR")
kpts = get_kpoints(struct.lattice.matrix,
struct.frac_coords,
struct.atomic_numbers,
min_distance=25.0,
include_gamma="auto")
kpoints_file = Kpoints(style=Kpoints_supported_modes.Reciprocal,
num_kpts=kpts["num_distinct_kpts"]
kpts=kpts["distinct_coords"],
kpts_weights=["distinct_weights"])
kpoints_file.write_file("./KPOINTS")
```
```python
from kpLib.interface import get_kpoints
import ase
struct = ase.io.read("./POSCAR", format="vasp")
kpts = get_kpoints(struct.get_cell()[:],
struct.get_scaled_positions(), # Note: the atomic coordinates are in fractional format, not Cartesian.
struct.get_atomic_numbers(),
min_distance=25.0,
include_gamma="gamma")
# ... User can then use the kpts dict to build VASP calculator and perform other tasks
```
## Command-line interface `kpgen`
For users' convenience, the Python package also provides a command-line interface
that can be called in terminal. It uses `pymatgen` as a structure parser and
output the *K*-point grid to a vasp-format `KPOINTS` file.
A simple example is:
```bash
$ kpgen -g auto -d 25.0 ./POSCAR ./KPOINTS
```
`-g` is short for `--gamma` and it defined the type of *K*-point grid, a gamma-centered, shifted or
auto-determined grid. `-d` is short for `--distance` and specifies `min_distance`. This is a simple
wrapper of the `get_kpionts` function discussed above. All the options
that `get_kpoints` accepts, this CLI accepts. Use `kpgen --help` to get a full list of
permitted arguments and options.
The default `pip install kplib` does not install this CLI. To enable this feature, after
cloning the source code, run:
```bash
$ pip install --user .[cli]
```
The "`[cli]`" part instructs the `setup.py` to install `pymatgen` and `click`.
# How to cite
If you use the kplib or the *K*-point Grid Generator in generating generalized *k*-point grids, please cite the following paper:
Wang, Y., Wisesa, P., Balasubramanian, A., Dwaraknath, S. & Mueller, T. Rapid generation of optimal generalized Monkhorst-Pack grids. Comp Mater Sci, 110100, doi:https://doi.org/10.1016/j.commatsci.2020.110100 (2020).
# Documentation
## Conventions
This section specifies the conventions we assume in the arguments to the
`KPointLatticeGenerator` constructor in C++. The Python interface `kpLib` is written
in the same manner that aligns with these conventions.
### **Lattice Vectors**
Lattice vectors are expressed as row vectors in the lattice matrix:
```C++
double primtiveVectors[3][3] = {{a_x, a_y, a_z},
{b_x, b_y, b_z},
{c_a, c_z, c_y}}
```
### **Point Operators**
Each operatir is a 3x3 integer matrix, representing how a **fractional coordinate** in the **primitive lattice basis** is transformed under this operation.
```
int latticePointOperations[][3][3];
```
Because of the lattice vectors are expressed as rows, each symmetry operation is done through ${x'}^T = {x}^T\cdot R$.
### **Conventional Lattice Vectors**
The algorithm we developed to efficiently iterate symmetry-preserving superlattices assumes
the following conditions on the input conventional lattice vectors, additional to the usual
conventions (e.g., see the standard unit cell in [`spglib` documentation](https://spglib.readthedocs.io/en/latest/definition.html#spglib-conventions-of-standardized-unit-cell)).
* For all crystal sysmtes, except for **triclinic**, the $\mathbf{c}$-vector should be along the axis
of the highest-order rotational operation, i.e the 4-fold, 6-fold, 3-fold, 4-fold, any 2-fold,
and 2-fold rotation for **cubic**, **hexagonal**, **trigonal**, **tetragonal**,
**orthorhombic**, and **monoclinic** lattices, respectively. This direction is commonly
referred as the "primary symmetry direction" in crystallography textbooks. The conventions
in the International Tables of Crystallograph (see [Chapter 9.1](https://it.iucr.org/Ab/ch9o1v0001/)) already satisfy this except for monoclinic lattice.
* For monoclinic crystal system, the international convention assumes the $\mathbf{b}$-unique setting, in which the $\beta$ angle is the non-acute angle, the two-fold rotation axis is along the $\mathbf{b}$ vector and the one-face-centered lattice point in the $\mathbf{a}$-$\mathbf{b}$ plane (i.e. "C" in the space group symbol). But kplib library assumes the two-fold rotation to be along the $\mathbf{c}$-vector, or in other words, the $\mathbf{b}$-unique setting. A simple transformation is to just rotate the vectors like the following: $\mathbf{b} \rightarrow \mathbf{c}$, $\mathbf{c} \rightarrow \mathbf{a}$, and $\mathbf{a} \rightarrow \mathbf{b}$.
* For **trigonal** lattices, no matter in $hR$ or $hP$ representation, the conventional lattices should be primitive hexagonal lattices, i.e. the rhombohedrally-centered hexagonal lattice. This is the same as the international convention.
The algorithm doesn't put constraints on triclinic system, or on the centering type of orthorhombic
lattices.
(Note: User could get the primary directions from the point symmetry opeartions.)
## The C++ API
#### Class: `KPointLatticeGenerator`
```C++
template <typename T>
using Tensor = std::vector<std::vector<T>>;
/**
* Constructor.
*
* To see how the variables are defined, check the "Conventions" section below)
*
* @param primVectorsArray 3x3 matrix with primitive lattice vectors in rows.
* @param conventionalVectorsArray 3x3 matrix with conventional lattice vectors in rows.
* @param latticePointOperatorsArray point operators of the Laue Class
of the input structure, expressed
in the basis of primitive lattice vectors
* @param numOperators number of point operators in above array
* @param isConventionalHexaognal whether the conventional lattice is
hexagonal
*/
KPointLatticeGenerator(const double primVectorsArray[][3],
const double conventionalVectorsArray[][3],
const int latticePointOperatorsArray[][3][3],
const int numOperators,
const bool isConventionalHexagonal);
/*
* Specify whether to generate a gamma-centered grid or a shifted grid.
* The available shifts are:
* {{0.0, 0.0, 0.5}, {0.0, 0.5, 0.0}, {0.5, 0.0, 0.0}, {0.5, 0.5, 0.0},
* {0.5, 0.0, 0.5}, {0.0, 0.5, 0.5}, {0.5, 0.5, 0.5}}
* Basiclly, side centers, face centers and the body center.
*
* @param includeGamma TRUE: gamma-centered grid
* FALSE: grid with one of the above shift
* AUTO: search both shifted and gamma-centered grid
* and return the best one.
*/
enum INCLUDE_GAMMA { TRUE, FALSE, AUTO };
void includeGamma(INCLUDE_GAMMA includeGamma);
/*
* @param minDistance The returned grid should have a corresponding
* real-space superlattice whose "minimum periodic distance"
* is no smaller than this value.
* @param minSize Minimum number of total k-points of grids returned.
*/
KPointLattice getKPointLattice(const double minDistance,
const int minSize);
```
#### Class: `KPointLattice`
It's meant to hold the found k-point grid and provide query functions.
The main query routines of this type:
```
double getMinPeriodicDistance();
int getNumDistinctKPoints();
int numTotalKPoints();
/*
* @return Tensor<double> 2D arrays of coordinates. It's basically a wrapper
* of "double coords[][3]".
*/
Tensor<double> getKPointCoordinates();
/*
* @return vector<int> 1D array of k-points weights.
*/
std::vector<int> getKPointWeights();
```
## Example: Using KpLib in C++ Code -- `demo_kplib`
To demonstrate the usage of the kpbib, we implemented a simple C++ application to generate optimized Generalised Monkhorst-Pack k-point grids. It use `spglib` to find symmetries ([Togo and Tanaka, 2010](https://atztogo.github.io/spglib/index.html)) and output the k-point grid in the format of VASP KPOINTS file.
It is under the folder `demo_kplib`. We have included a pre-built binary of the spglib library. User can also choose to build the latest version of `spglib` from source and replace it. The executable `demo_kplib` can be built following these commands:
$ cd demo_kplib
$ mkdir build
$ cd build
$ cmake ..
$ make
The binary will be placed at `./build/demo_kplib`. To call it, use:
$ ./demo_kplib /path/to/POSCAR /path/to/PRECALC > KPOINTS
The `POSCAR` is one of the standard VASP input file. The `PRECALC` file is the input file of `demo_kplib` and users can find its specifications on our [website](http://muellergroup.jhu.edu/K-Points.html). Since it's for demonstration purposes, only the parameters `MINDISTANCE`, `MINTOTALKPOINTS`, and `INCLUDEGAMMA` are valid.
Examples of using this app for different crystal systems can be found in `demo_kplib/examples`. `KPOINTS_ref`
are `KPOINTS` files generated by [our server](http://muellergroup.jhu.edu/K-Points.html). `KPOINTS_kplib`
are files created by the `demo_kplib` app.
For a stand-alone application with more funcnalities, like automatic detection of slabs, please check our ***K*-point Grid Generator** and ***K*-point Server**.
### **Code snippet of demo_kpib**
Below are excerpts from the `demo_kplib` application to show how to use the KpLib API.
`demo_kplib/src/main.cpp`:
```C++
#include "kPointLatticeGenerator.h"
#include "utils.h"
#include "precalc.h"
#include "poscar.h"
#include <iostream>
int main(int argc, char **argv) {
if (argc < 3) {
std::cerr << "Usage: ./main /path/to/POSCAR /path/to/PRECALC"
<< std::endl;
return 1;
}
// Parse POSCAR and PRECALC.
Poscar poscar;
poscar.readFromPoscar(std::string(argv[1]));
Precalc precalc(argv[2]);
// Execute the main routines.
KPointLatticeGenerator generator = initializeKPointLatticeGeneratorObject(
poscar.primitiveLattice, poscar.coordinates, poscar.atomTypes);
if (precalc.getIncludeGamma() == "TRUE") {
generator.includeGamma(TRUE);
} else if (precalc.getIncludeGamma() == "FALSE") {
generator.includeGamma(FALSE);
} else if (precalc.getIncludeGamma() == "AUTO") {
generator.includeGamma(AUTO);
}
KPointLattice latticeGamma = generator.getKPointLattice(precalc.getMinDistance(),
precalc.getMinTotalKpoints());
outputLattice(latticeGamma);
}
```
`demo_kplib/src/utils.cpp`:
```C++
#include "utils.h"
#include "spglib.h"
... // other includes and functions
// Wrapper of the KPointLatticeGenerator constructor.
KPointLatticeGenerator initializeKPointLatticeGeneratorObject(
Tensor<double> primitiveLattice,
Tensor<double> coordinates,
std::vector<int> atomTypes) {
double primLatticeArray[3][3] = {0};
double conventionalLatticeArray[3][3] = {0};
int rotation[192][3][3] = {0};
int size = 0;
bool isConventionalHexagonal = false;
// use spglib to get necessary parameters for the consturctor
// of KPointLatticeGenerator.
...
KPointLatticeGenerator generator = KPointLatticeGenerator(primLatticeArray,
conventionalLatticeArray, rotation, size, isConventionalHexagonal);
if (useScaleFactor == "TRUE") {
generator.useScaleFactor(spaceGroup); // Otherwise, use the fully dynamic search.
}
return generator;
}
```
## Using scale factor to accelerate search
Scale factor is a scheme implemented to speed up the search of optimized generalized
grids at the cost of returning a sub-optimal *K*-point grid. It is controlled
by `KPointsLatticeGenerator::useScaleFactor` in the C++ library and the flag `use_scale_factor`
in the Python interface.
When `use_scale_factor` is set to `True` in `kpLib.interface::get_kpoints` function or in
the CLI command `kpgen`, the code will
search exhaustively up to a pre-defined threshold of total number of *K*-points. If no grids are
found with effective minimum distance at least `min_distance`,
the user-given `min_distance` will be divide by `n` and then kplib search again for a grid
satifying `min_distance/n`. If there are still no valid grids, kplib will increment `n` by 1
and search again until it find a valid grid. When a valid grid is finally found,
the grid will be scaled up by `n` (i.e. total number of *K*-points is increased by `n^3`
times) before being returned to satisfy the `min_distance` requirement.
Currently the maximum value of `n` is set to 3. The thresholds of maximum total number of
*K*-points for exhaustive search are 729 (9x9x9) for triclinic structures,
1728 (12x12x12) for monoclinic structures, 5832 (18x18x18) for orthorhombic, tetragonal,
trigonal and hexagonal structures, and 46656 (36x36x36) for cubic structures. User can
increase the maximum value of `n` and these thresholds in
`KPointLatticeGenerator::useScaleFactor` and recompile.
The C++ library turns on and off this scheme through the function
`KPointLatticeGenerator::useScaleFactor`. It accepts the space group numbers of input structures
to provide the flexibility of selectively using this scheme for a subset of user selected lattice
types.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/muellergroup/kplib",
"name": "kpLib",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Computational Materials Science,Materials Simulation,Electronic Structure,K-points,kpoint,Density Functional Theory,DFT,VASP,Crystal",
"author": "Yunzhe Wang",
"author_email": "ywang393@jhu.edu",
"download_url": "https://files.pythonhosted.org/packages/e3/ce/820745322bf79f17bb258d1affe0ad43d483312418bd3387f1c22911911c/kpLib-1.1.1.tar.gz",
"platform": null,
"description": "# KpLib\n\n[](\nhttps://pypi.org/project/kpLib/)\n[](https://doi.org/10.1016/j.commatsci.2020.110100)\n[](https://gitlab.com/muellergroup/kplib/commits/master)\n\n\nKpLib is a C++ library for finding the optimal Generalized Monkhorst-Pack k-points grid. It can be imported into electronic-structure packages as a generator of efficient generalized *k*-point grids, or be integrated into user scripts through the Python interface `kpLib`.\n\nFor questions of KpLib and underlying algorithms, you are welcomed to check our paper at [here](https://doi.org/10.1016/j.commatsci.2020.110100) or send emails to kpoints@jhu.edu.\n\n**Note**: We have fixed in `v.1.1.0` (2023.04.08) a few bugs of the Python interface causing scripts to hang for monoclinic and trigonal system in $hR$ representation. We also reduced dependencies of external Python packages to the minimum to let users choose their favoriate package for structure IO. Please check the [RELEASE.md](https://gitlab.com/muellergroup/kplib/-/blob/master/RELEASE.md) note for details.\n\n# Usage\n\n## Route I: Integrating KpLib as a C++ library in simulation package\n---\n## Compile KpLib as a library\nWe use `cmake` to detect native build environment and generate native build files. For Unix-like operating systems, users can build the project by:\n\n $ git clone https://gitlab.com/muellergroup/kplib.git\n $ cd kplib\n $ mkdir build\n $ cd build\n $ cmake ..\n $ make\n\nThen you can find a static library at `build/libkpoints.a` and a dynamic library at `build/libkpoints.so`.\n\n## Use KpLib in C++ Code\n\nThere are basically two steps:\n\n1. Copy the header file `src/kPointLatticeGenerator.h` to your `include` folder, and add the following line to your source code\n\n #include \"kPointLatticeGenerator.h\"\n\n2. Link the library at the linking stage.\n\n For example, to link the static library and compile the object `myapp.o` to the final executable `myapp`, you can\n\n $ g++ myapp.o -L /path/to/lib libkpoints.a -o myapp\n\n If you want to use the dynamic library, you can\n\n $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/lib\n $ g++ myapp.o -L /path/to/lib -lkpoints -o myapp\n\n The first line tells the loader, `ld`, where to find the shared library at runtime, since the dynamic linkage only puts a reference of the library in the executable.\n\nThen you are ready to go!\n\nAn explanation of the API with more details can be found below, together with a demo C++ program (`demo_kplib/src`) created to demonstrate the usage of this API in C++ environment and the conventions the API assumes.\n\n## Route II: Use KpLib as a Python package\n---\n## Installation\n\n### **Install from PyPI using `pip`**\nThis will install the core KpLib module with minimal third-party dependencies. User will need to parse input structures and write out generated *K*-point grid using their favorite matsci packages (e.g. `ase` and `pymatgen`). \n\n```\n$ pip install --user pybind11 build wheel\n$ pip install --user kplib # Install only the core kplib package. \n$ pip install --user kplib[cli] # To install the CLI tool `kpgen`. \n # This will also install `pymatgen` and `click`\n```\n\n### **Install from source using `pip`**\nThe Python interface is a thin wrapper of the C++ library. Building from source should be straight forward. It also provides a way to install a CLI command to be called in terminal (requiring `pymatgen` for IO).\n\n\nStep 1. Download source code from https://gitlab.com/muellergroup/kplib.\n```\n$ git clone https://gitlab.com/muellergroup/kplib.git\n```\n\nStep 2. The C++-Python interface is written using `pybind11`, and the `setup.py` imports it at the beginning for compiling the C++ code into a Python external module. So, it should be installed before installing `kpLib`.\n```\n$ pip install --user pybind11\n$ pip install --user build wheel # Python build toolchain that you might already have.\n```\n\nStep 3. If you would like to choose your own structure parser (such as `pymatgen`, `ase` and other wonderful packages), you can install only the core module of `kpLib` with a minimal dependencies:\n```\n$ cd kplib\n$ pip install --user .\n```\n\nIf you would like to use the CLI command tool `kpgen`, you can use the following code to install `kpLib`. This will additionally install `pymatgen` (as a parser) and `click` (to provide a nice CLI interface):\n```\n$ cd kplib\n$ pip install --user .[cli]\n$ which kpgen\n```\n\nIf you want to test your installation, you can install `kpLib` with dependencies\nthat enables the test suite (`pymatgen` and `pytest`). After installation, you can run tests to make sure everything is correctly installed.\n```\n$ cd kplib\n$ pip install --user .[tests]\n$ pytest\n```\n\n## Using KpLib in Python script\nThe `kpLib` Python package is written in the way to provide an interface\nfor the core KpLib function and allow maximal usage flexibility. The choice\nof packages for parsing input structure and for writing the generated k-points\ngrid to a desired format is left to users. The following section will first\ndescribe the signature of the `get_kpoints` function, and then give two\nexample scripts using the two popular packages `pymatgen` and `ase` for I/O.\n\n`kpLib.interface::get_kpoints` is the core and only function the `kpLib` Python\npackage provides. Its signature is as follows:\n```\ndef get_kpoints(\n lattice: List[List[float]] or numpy.ndarray,\n fractional_coords: List[List[float]] or numpy.ndarray,\n atomic_numbers: List[int] or Tuple[int],\n min_distance: float = 0.1,\n min_total_kpoints: int = 1,\n include_gamma: str = \"auto\",\n symprec: float = 1e-5,\n use_scale_factor: bool = False,\n) -> Dict\n```\n`get_kpoints` uses the 3 positional arguments to define a structure. The rest of the keyword\narguments define requirements of the output *K*-point grid. The size requirement of *K*-point grids is defined by `min_distance` and `min_total_kpoints`. They can be used\nseparately or together. We recommand using `min_distance`. For an example of correlating\nthe conventional way of specifying a Monkhorst-Pack grid by three integers\n`m1 x m2 x m3` to `min_distance`, see the section below.\n\nThe meaning of all arguments are as follows:\n- `lattice`: A 3x3 matrix representing the lattice vectors of the unit cell of the input structure. Each row represents a vector, i.e. in the format of [**a**, **b**, **c**]. It can be a list of list or a `numpy.ndarray`.\n- `fractional_coords`: A list of 3-dimensional coordinates in the fractional format relative to the lattice vectors. It can be a list of list or a `numpy.ndarray`.\n- `atomic_numbers`: A list of atomic numbers, the i-th number of which defines the element of the i-th atom at the position `fractional_coords[i]`. It can be a list or a tuple.\n- `min_distance`: The minimum required distance in real-space between any pair of lattice points in the superlattice corresponding to the returned *K*-point grid. It specifys the \nsize of the required *K*-point grid and has a unit of Angstrom. The larger the value of \n`min_distance`, the denser the returned grid will be (i.e., more symmetrically distinct \n*K*-point).\n- `min_total_kpoints`: Minimum number of total *K*-points required in the returned \n*K*-point grid. Note, it is not the number of symmetrically distinct *K*-points that\nare actually used in a calculation. The total set of *K*-points will be reduced by symmetry\nto the minimal set of distinct *K*-points, which will be used in a calculation.\n- `include_gamma`: It can have values `true` or `false`, or `auto`. Use `true`\nto include the Gamma point (i.e. [0, 0, 0] of reciprocal space) in the return grid.\nUse `false` to exclude the Gamma point. Use `auto` to let kplib choose between\nthe two types of grid and return the one with a smaller number of symmetrically\ndistinct *K*-points. If they have the same number of distinct *K*-points, return\nthe one with larger effecitive min_distance.\n- `symprec`: Precision in real space when determining structure symmetries. The default\nis `1E-5`. Atomic coordinates with a difference less than `symprec` will be determined\nas equivalent. If you want to include more symmetries, use a larger value.\n- `use_scale_factor`: A scheme to speed up the search at the cost of returning a sub-optimial\n*K*-point grid. Default behaviour is to not use the scheme. You can consider use this scheme\nwhen the code takes a very long time to return a grid. For a detailed explanation,\nsee the end of this README.\n \nThe `get_kpoints` function returns the *K*-point grid as a `dict`. The keys are:\n\n- `min_periodic_distance`: The minimum distance between any pair of lattice points of the real-space superlattice corresponding to the returned *K*-point grid.\n- `num_distinct_kpts`: The number of symmetrically distinct *K*-points. This is the number of\n*K*-points actually used in a calculation.\n- `distinct_coords`: Fractional coordinates of symmetrically distinct *K*-points.\n- `distinct_weights`: Weights of corresponding symmetrically distinct *K*-point in `distinct_coords`.\n- `num_total_kpts`: The number of total *K*-points.\n- `coords`: Fractional coordinates of all *K*-points.\n- `weights`: Weights of corresponding *K*-points in `coords`.\n\nUsually the coordinates and weights of distinct *K*-points are enough to define an\ninput file of a calculation.\n\n### **Making sense of \"`min_distance`\"**\n\"Minimum distance\" means the minimum periodic distance between any pairs of \nlattice points on a real-space lattice. The reciprocal lattice of a primitive unit cell \nis a supercell in the reciprocal space of the reciprocal lattice of a super cell in real space. It implys each *K*-point grid corresponds to a real-space superlattice. Therefore, we can use the \"minimum distance\" of a real-space superlattice to specify the size its corresponding *K*-point grid in the reciprocal space. The larger the `min_distance`, the larger the supercell and hence the denser the *K*-point grid.\n\nFor example, consider an artificial tetragonal structure with a lattice as $[[2, 0, 0], [0, 2, 0], [0, 0, 3]]$ and a single atom at the origin. Its space group is $P4/mmm$. A traditional Monkhorst-Pack 4x4x4 grid with the Gamma point would correspond to a supercell of $[[8, 0, 0], [0, 8, 0], [0, 0, 12]]$ and has **18** symmetrically distinct *K*-points. The minimum periodic distance in this case is 8 Angstroms.\n\nWhen using `kpLib` with `min_distance` = 8, the Gamma-centered result would have only\n**9** symmetrically distinct *K*-points and an effective minimum distance of 8.485. For\nshifted grids, the result would be a grid with **6** symmetrically distinct *K*-points\nand an effective minimum distance of 8. Similar calculation accuracy but three times\nless the number of distinct *K*-points.\n\n### **Example Python Scripts**\nHere, we give two examples of using `kpLib` in Python script, using the popular \n[`pymatgen`](https://pymatgen.org/) and [`ase`](https://wiki.fysik.dtu.dk/ase/)\npackages respectively for IO.\n\n\n```python\nfrom kplib import get_kpoints\nfrom pymatgen.core import Structure\nfrom pymatgen.io.vasp.inputs import Kpoints, Kpoints_supported_modes\n\nstruct = Structure.from_file(\"./POSCAR\")\n\nkpts = get_kpoints(struct.lattice.matrix,\n struct.frac_coords,\n struct.atomic_numbers, \n min_distance=25.0, \n include_gamma=\"auto\")\n\nkpoints_file = Kpoints(style=Kpoints_supported_modes.Reciprocal,\n num_kpts=kpts[\"num_distinct_kpts\"]\n kpts=kpts[\"distinct_coords\"],\n kpts_weights=[\"distinct_weights\"])\nkpoints_file.write_file(\"./KPOINTS\")\n```\n\n```python\nfrom kpLib.interface import get_kpoints\nimport ase\n\nstruct = ase.io.read(\"./POSCAR\", format=\"vasp\")\nkpts = get_kpoints(struct.get_cell()[:], \n struct.get_scaled_positions(), # Note: the atomic coordinates are in fractional format, not Cartesian.\n struct.get_atomic_numbers(), \n min_distance=25.0,\n include_gamma=\"gamma\")\n\n# ... User can then use the kpts dict to build VASP calculator and perform other tasks\n```\n\n## Command-line interface `kpgen`\nFor users' convenience, the Python package also provides a command-line interface \nthat can be called in terminal. It uses `pymatgen` as a structure parser and \noutput the *K*-point grid to a vasp-format `KPOINTS` file.\n\nA simple example is:\n```bash\n$ kpgen -g auto -d 25.0 ./POSCAR ./KPOINTS\n```\n`-g` is short for `--gamma` and it defined the type of *K*-point grid, a gamma-centered, shifted or\nauto-determined grid. `-d` is short for `--distance` and specifies `min_distance`. This is a simple \nwrapper of the `get_kpionts` function discussed above. All the options \nthat `get_kpoints` accepts, this CLI accepts. Use `kpgen --help` to get a full list of \npermitted arguments and options.\n\nThe default `pip install kplib` does not install this CLI. To enable this feature, after \ncloning the source code, run:\n```bash\n$ pip install --user .[cli]\n```\nThe \"`[cli]`\" part instructs the `setup.py` to install `pymatgen` and `click`.\n\n# How to cite\nIf you use the kplib or the *K*-point Grid Generator in generating generalized *k*-point grids, please cite the following paper:\n\nWang, Y., Wisesa, P., Balasubramanian, A., Dwaraknath, S. & Mueller, T. Rapid generation of optimal generalized Monkhorst-Pack grids. Comp Mater Sci, 110100, doi:https://doi.org/10.1016/j.commatsci.2020.110100 (2020).\n\n# Documentation\n\n## Conventions\nThis section specifies the conventions we assume in the arguments to the \n`KPointLatticeGenerator` constructor in C++. The Python interface `kpLib` is written\nin the same manner that aligns with these conventions.\n\n### **Lattice Vectors**\nLattice vectors are expressed as row vectors in the lattice matrix:\n```C++\ndouble primtiveVectors[3][3] = {{a_x, a_y, a_z},\n {b_x, b_y, b_z},\n {c_a, c_z, c_y}}\n```\n\n### **Point Operators**\n\nEach operatir is a 3x3 integer matrix, representing how a **fractional coordinate** in the **primitive lattice basis** is transformed under this operation.\n\n```\nint latticePointOperations[][3][3];\n```\n\nBecause of the lattice vectors are expressed as rows, each symmetry operation is done through ${x'}^T = {x}^T\\cdot R$.\n\n### **Conventional Lattice Vectors**\n\nThe algorithm we developed to efficiently iterate symmetry-preserving superlattices assumes\nthe following conditions on the input conventional lattice vectors, additional to the usual\nconventions (e.g., see the standard unit cell in [`spglib` documentation](https://spglib.readthedocs.io/en/latest/definition.html#spglib-conventions-of-standardized-unit-cell)).\n\n* For all crystal sysmtes, except for **triclinic**, the $\\mathbf{c}$-vector should be along the axis \nof the highest-order rotational operation, i.e the 4-fold, 6-fold, 3-fold, 4-fold, any 2-fold, \nand 2-fold rotation for **cubic**, **hexagonal**, **trigonal**, **tetragonal**, \n**orthorhombic**, and **monoclinic** lattices, respectively. This direction is commonly \nreferred as the \"primary symmetry direction\" in crystallography textbooks. The conventions\nin the International Tables of Crystallograph (see [Chapter 9.1](https://it.iucr.org/Ab/ch9o1v0001/)) already satisfy this except for monoclinic lattice.\n\n* For monoclinic crystal system, the international convention assumes the $\\mathbf{b}$-unique setting, in which the $\\beta$ angle is the non-acute angle, the two-fold rotation axis is along the $\\mathbf{b}$ vector and the one-face-centered lattice point in the $\\mathbf{a}$-$\\mathbf{b}$ plane (i.e. \"C\" in the space group symbol). But kplib library assumes the two-fold rotation to be along the $\\mathbf{c}$-vector, or in other words, the $\\mathbf{b}$-unique setting. A simple transformation is to just rotate the vectors like the following: $\\mathbf{b} \\rightarrow \\mathbf{c}$, $\\mathbf{c} \\rightarrow \\mathbf{a}$, and $\\mathbf{a} \\rightarrow \\mathbf{b}$.\n\n* For **trigonal** lattices, no matter in $hR$ or $hP$ representation, the conventional lattices should be primitive hexagonal lattices, i.e. the rhombohedrally-centered hexagonal lattice. This is the same as the international convention.\n\nThe algorithm doesn't put constraints on triclinic system, or on the centering type of orthorhombic \nlattices.\n\n(Note: User could get the primary directions from the point symmetry opeartions.)\n\n## The C++ API\n\n#### Class: `KPointLatticeGenerator`\n```C++\ntemplate <typename T>\nusing Tensor = std::vector<std::vector<T>>;\n/**\n * Constructor.\n *\n * To see how the variables are defined, check the \"Conventions\" section below)\n *\n * @param primVectorsArray 3x3 matrix with primitive lattice vectors in rows.\n * @param conventionalVectorsArray 3x3 matrix with conventional lattice vectors in rows.\n * @param latticePointOperatorsArray point operators of the Laue Class\n of the input structure, expressed\n in the basis of primitive lattice vectors\n * @param numOperators number of point operators in above array\n * @param isConventionalHexaognal whether the conventional lattice is\n hexagonal\n */\nKPointLatticeGenerator(const double primVectorsArray[][3],\n const double conventionalVectorsArray[][3],\n const int latticePointOperatorsArray[][3][3],\n const int numOperators,\n const bool isConventionalHexagonal);\n/*\n * Specify whether to generate a gamma-centered grid or a shifted grid.\n * The available shifts are:\n * {{0.0, 0.0, 0.5}, {0.0, 0.5, 0.0}, {0.5, 0.0, 0.0}, {0.5, 0.5, 0.0},\n * {0.5, 0.0, 0.5}, {0.0, 0.5, 0.5}, {0.5, 0.5, 0.5}}\n * Basiclly, side centers, face centers and the body center.\n *\n * @param includeGamma TRUE: gamma-centered grid\n * FALSE: grid with one of the above shift\n * AUTO: search both shifted and gamma-centered grid\n * and return the best one.\n */\nenum INCLUDE_GAMMA { TRUE, FALSE, AUTO };\nvoid includeGamma(INCLUDE_GAMMA includeGamma);\n/*\n * @param minDistance The returned grid should have a corresponding\n * real-space superlattice whose \"minimum periodic distance\"\n * is no smaller than this value.\n * @param minSize Minimum number of total k-points of grids returned.\n */\nKPointLattice getKPointLattice(const double minDistance,\n const int minSize);\n```\n\n#### Class: `KPointLattice`\nIt's meant to hold the found k-point grid and provide query functions.\nThe main query routines of this type:\n```\ndouble getMinPeriodicDistance();\nint getNumDistinctKPoints();\nint numTotalKPoints();\n\n/*\n * @return Tensor<double> 2D arrays of coordinates. It's basically a wrapper\n * of \"double coords[][3]\".\n */\nTensor<double> getKPointCoordinates();\n\n/*\n * @return vector<int> 1D array of k-points weights.\n */\nstd::vector<int> getKPointWeights();\n```\n\n## Example: Using KpLib in C++ Code -- `demo_kplib`\n\nTo demonstrate the usage of the kpbib, we implemented a simple C++ application to generate optimized Generalised Monkhorst-Pack k-point grids. It use `spglib` to find symmetries ([Togo and Tanaka, 2010](https://atztogo.github.io/spglib/index.html)) and output the k-point grid in the format of VASP KPOINTS file.\n\nIt is under the folder `demo_kplib`. We have included a pre-built binary of the spglib library. User can also choose to build the latest version of `spglib` from source and replace it. The executable `demo_kplib` can be built following these commands:\n\n $ cd demo_kplib\n $ mkdir build\n $ cd build\n $ cmake ..\n $ make\n\nThe binary will be placed at `./build/demo_kplib`. To call it, use:\n\n $ ./demo_kplib /path/to/POSCAR /path/to/PRECALC > KPOINTS\n\nThe `POSCAR` is one of the standard VASP input file. The `PRECALC` file is the input file of `demo_kplib` and users can find its specifications on our [website](http://muellergroup.jhu.edu/K-Points.html). Since it's for demonstration purposes, only the parameters `MINDISTANCE`, `MINTOTALKPOINTS`, and `INCLUDEGAMMA` are valid.\n\nExamples of using this app for different crystal systems can be found in `demo_kplib/examples`. `KPOINTS_ref`\nare `KPOINTS` files generated by [our server](http://muellergroup.jhu.edu/K-Points.html). `KPOINTS_kplib`\nare files created by the `demo_kplib` app.\n\nFor a stand-alone application with more funcnalities, like automatic detection of slabs, please check our ***K*-point Grid Generator** and ***K*-point Server**.\n\n### **Code snippet of demo_kpib**\n\nBelow are excerpts from the `demo_kplib` application to show how to use the KpLib API.\n\n`demo_kplib/src/main.cpp`:\n```C++\n#include \"kPointLatticeGenerator.h\"\n#include \"utils.h\"\n#include \"precalc.h\"\n#include \"poscar.h\"\n#include <iostream>\n\nint main(int argc, char **argv) {\n if (argc < 3) {\n std::cerr << \"Usage: ./main /path/to/POSCAR /path/to/PRECALC\"\n << std::endl;\n return 1;\n }\n // Parse POSCAR and PRECALC.\n Poscar poscar;\n poscar.readFromPoscar(std::string(argv[1]));\n Precalc precalc(argv[2]);\n\n // Execute the main routines.\n KPointLatticeGenerator generator = initializeKPointLatticeGeneratorObject(\n poscar.primitiveLattice, poscar.coordinates, poscar.atomTypes);\n\n if (precalc.getIncludeGamma() == \"TRUE\") {\n generator.includeGamma(TRUE);\n } else if (precalc.getIncludeGamma() == \"FALSE\") {\n generator.includeGamma(FALSE);\n } else if (precalc.getIncludeGamma() == \"AUTO\") {\n generator.includeGamma(AUTO);\n }\n\n KPointLattice latticeGamma = generator.getKPointLattice(precalc.getMinDistance(),\n precalc.getMinTotalKpoints());\n\n outputLattice(latticeGamma);\n}\n```\n\n`demo_kplib/src/utils.cpp`:\n```C++\n#include \"utils.h\"\n#include \"spglib.h\"\n... // other includes and functions\n\n// Wrapper of the KPointLatticeGenerator constructor.\nKPointLatticeGenerator initializeKPointLatticeGeneratorObject(\n Tensor<double> primitiveLattice,\n Tensor<double> coordinates,\n std::vector<int> atomTypes) {\n\n double primLatticeArray[3][3] = {0};\n double conventionalLatticeArray[3][3] = {0};\n int rotation[192][3][3] = {0};\n int size = 0;\n bool isConventionalHexagonal = false;\n\n // use spglib to get necessary parameters for the consturctor\n // of KPointLatticeGenerator.\n ...\n\n KPointLatticeGenerator generator = KPointLatticeGenerator(primLatticeArray,\n conventionalLatticeArray, rotation, size, isConventionalHexagonal);\n if (useScaleFactor == \"TRUE\") {\n generator.useScaleFactor(spaceGroup); // Otherwise, use the fully dynamic search.\n }\n return generator;\n\n}\n```\n\n## Using scale factor to accelerate search\n\nScale factor is a scheme implemented to speed up the search of optimized generalized\ngrids at the cost of returning a sub-optimal *K*-point grid. It is controlled\nby `KPointsLatticeGenerator::useScaleFactor` in the C++ library and the flag `use_scale_factor`\nin the Python interface.\n\nWhen `use_scale_factor` is set to `True` in `kpLib.interface::get_kpoints` function or in \nthe CLI command `kpgen`, the code will \nsearch exhaustively up to a pre-defined threshold of total number of *K*-points. If no grids are \nfound with effective minimum distance at least `min_distance`,\nthe user-given `min_distance` will be divide by `n` and then kplib search again for a grid \nsatifying `min_distance/n`. If there are still no valid grids, kplib will increment `n` by 1 \nand search again until it find a valid grid. When a valid grid is finally found, \nthe grid will be scaled up by `n` (i.e. total number of *K*-points is increased by `n^3` \ntimes) before being returned to satisfy the `min_distance` requirement.\nCurrently the maximum value of `n` is set to 3. The thresholds of maximum total number of \n*K*-points for exhaustive search are 729 (9x9x9) for triclinic structures, \n1728 (12x12x12) for monoclinic structures, 5832 (18x18x18) for orthorhombic, tetragonal, \ntrigonal and hexagonal structures, and 46656 (36x36x36) for cubic structures. User can \nincrease the maximum value of `n` and these thresholds in \n`KPointLatticeGenerator::useScaleFactor` and recompile.\n\nThe C++ library turns on and off this scheme through the function\n`KPointLatticeGenerator::useScaleFactor`. It accepts the space group numbers of input structures\nto provide the flexibility of selectively using this scheme for a subset of user selected lattice\ntypes.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Library for generating highly-efficient generalized Monkhorst-Pack K-point grids to accelerate electronic structure calculations, like DFT.",
"version": "1.1.1",
"split_keywords": [
"computational materials science",
"materials simulation",
"electronic structure",
"k-points",
"kpoint",
"density functional theory",
"dft",
"vasp",
"crystal"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e3ce820745322bf79f17bb258d1affe0ad43d483312418bd3387f1c22911911c",
"md5": "4700a953a0231cc18205a879c298902d",
"sha256": "a7b8d51e77e383d69ab5896a6a79a7fc02def93a9ab0f2e32407afb2a7060731"
},
"downloads": -1,
"filename": "kpLib-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "4700a953a0231cc18205a879c298902d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 149972,
"upload_time": "2023-04-09T05:10:53",
"upload_time_iso_8601": "2023-04-09T05:10:53.109262Z",
"url": "https://files.pythonhosted.org/packages/e3/ce/820745322bf79f17bb258d1affe0ad43d483312418bd3387f1c22911911c/kpLib-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-09 05:10:53",
"github": false,
"gitlab": true,
"bitbucket": false,
"gitlab_user": "muellergroup",
"gitlab_project": "kplib",
"lcname": "kplib"
}
JSON