MonkhorstPackGrid

class MonkhorstPackGrid(na=None, nb=None, nc=None, symmetries=None, force_timereversal=None, k_point_shift=None, shift_to_gamma=None)
Parameters:

  • na (Positive int) – Number of k-points in A direction.
    Default: 1

  • nb (Positive int) – Number of k-points in B direction.
    Default: 1

  • nc (Positive int) – Number of k-points in C direction.
    Default: 1

  • symmetries (list(n_symmetries) of (array(3, 3), array(3)).) – A list of user-defined symmetries used for the reduction of the k-points in integration.
    Default: Empty list, which means ATK will determine the relevant symmetries.

  • force_timereversal (bool) – Always enforce time reversal symmetry.
    Default: True (False with spin-orbit or noncollinear spin)

  • k_point_shift (list(3) of float) – Optional k-point shift in fractional coordinates. This option is mutually exclusive to shift_to_gamma.
    Default: Determined internally depending on the value of shift_to_gamma.

  • shift_to_gamma (list(3) of bool | bool) – Shift grid so that \(\Gamma\) (0.0, 0.0, 0.0) is included along all or certain directions. This option is mutually exclusive to k_point_shift.
    Default: True (Not active if k_point_shift is specified)

allKpoints()
Returns:

All the k-points of the MonkhorstPackGrid before symmetry reduction.

Return type:

ndarray(N,3) of float where N is the number of k-points.

allKpointsWeights()
Returns:

The weight of all k-points before symmetry reduction.

Return type:

ndarray(n) for float where n is the number of k-points before symmetry reduction.

disableTimereversal()

After construction of the MonkhorstPackGrid, the time reversal symmetry can be disabled using this function.

foldoutMapVector()

Query method for getting the map between the symmetry reduced k-points and unreduced k-points.

Returns:

A list with indices matching the k-points in the symmetry reduced set and in the unreduced set.

Return type:

ndarray(N) with integer values between 0 and M-1. N is the number of k-points in the unreduced set, M is the number of k-points in the reduced set.

forceTimereversal()
Returns:

Whatever force_timereversal is enabled or disabled.

Return type:

bool

kPointShift()
Returns:

The k_point_shift which the k-points are shifted with.

Return type:

list(3) of float

kpoints()
Returns:

The symmetry reduced kpoints.

Return type:

ndarray(N,3) of float where N is the number of symmetry reduced k-points.

kpointsWeights()
Returns:

The weights of the symmetry reduced k-points.

Return type:

ndarray(n) for floats, where n is the number of unreduced number of k-points.

na()
Returns:

The number of k-points along the kA-direction.

Return type:

int

nb()
Returns:

The number of k-points along the kB-direction.

Return type:

int

nc()
Returns:

The number of k-points along the kC-direction.

Return type:

int

shiftToGamma()
Returns:

Whatever the k-points are shifted to the \(\Gamma\).

Return type:

bool

symmetries()
Returns:

The symmetries to apply for reducing the k-points.

Return type:

list(n_symmetries) of (array(3, 3), array(3)).

uniqueString()

Return a unique string representing the state of the object.

Usage Examples

Define a 2x5x3 Monkhorst-Pack k-point grid. Calculate the irreducible k-points using the time reversal symmetry and mirror symmetry in the A direction. Print out the relation between the full k-point set and the irreducible set:

# Make a  MonkhorstPackGrid with mirror symmetry in A direction and time reversal symmetry
symmetries = [( numpy.array([[-1,0,0], [0,1,0], [0,0,1]]), numpy.zeros(3))]
mpg = MonkhorstPackGrid(2, 5, 3, symmetries=symmetries)

# Get the kpoints
irreducible_kpoints = mpg.kpoints()
irreducible_weights = mpg.kpointsWeights()

all_kpoints = mpg.allKpoints()

# Print out the irreducible kpoints
print(len(irreducible_kpoints), ' irreducible kpoints')
for kp, w in zip(irreducible_kpoints, irreducible_weights):
    print(kp, w*len(all_kpoints))

# Get the map from the full kpoints to the irreducible part
fold_out_map = mpg.foldoutMapVector()

# Print out the relation between the full and irreducible set
print(len(all_kpoints), '  kpoints')
for i, kp in enumerate(all_kpoints):
    print(kp, ' -> ', irreducible_kpoints[fold_out_map[i]])

monkhorstpackgrid.py

Notes

Make a uniform k-point grid according to procedure of Monkhorst and Pack [1],

\[\begin{split}&& {\bf k}_{prs} = u_{p}\, {\bf b}_{1} + u_{r}\, {\bf b}_{2} + u_{s}\, {\bf b}_{3}, \\ && u_{r} = (2 r - q - 1)/2q \,\,\,\,\,\,\,\,\, (r=1,2,3,...,q),\end{split}\]

where \({\bf k}_{prs}\) are the k-vectors corresponding to the special points of the k-grid, \({\bf b}_{1}\), \({\bf b}_{2}\), and \({\bf b}_{3}\) are the reciprocal lattice vectors, \(u_{r}\) is the sequence of numbers, and \(q^{3}\) is the total number of the k-points used to sample the Brillouin zone.

  • The original Monkhorst-Pack procedure assumes that odd k-point grids include the \(\Gamma\) point while even k-point grids avoid the \(\Gamma\) point.

  • It is possible and often advantageous to shift the grid by \(\Delta k\). For example, one may need to include the \(\Gamma\) point for cubic and hexagonal lattices.

  • When the time-reversal symmetry of the Schrödinger equation is preserved, it is possible to take advantage of the inversion symmetry to reduce the number of k-points used for sampling the Brillouin zone. This is done by default in QuantumATK.

  • If the time-reversal symmetry of the Schrödinger equation is broken, e.g., by spin-orbit interaction, the inversion symmetry cannot be adopted to reduce the number of k-points. The time-reversal symmetry can be turned off, by using the force_timereversal keyword.