lattice module¶

This module, lattice.py contains the setup and lattice related routines, including both the real and reciprocal part of it.

Contains routines to setup the lattice.

class lattice.Lattice(param, location=None, filename=None)¶

Bases: object

Contains routines to set up the system atmosphere.

This includes the unit cell, the BZ and IBZ k-point mesh etc.

Read the YAML cell configuration file (cellparams.yml by default is used to read basic cell parameters if for instance this is not set up by other inputs in the interface)

Parameters:	param : object A Param() object containing the parameters of the general configuration file.

class Kmesh¶

Bases: object

Data container for the k-point mesh generation.

Currently not used throughout the program, only for the intial setup.

Todo

Incorporate this class into the whole program.

cart_to_dir(self, v, real=False)¶

Calculates the direct vector if the input is a vector in cartesian coordinates.

Parameters:	v: ndarray Dimension: (3) The input direct vector. real: boolean If set to False, the reciprocal unitcell is used, is set to True, the unitcell is used.
Returns:	ndarray Dimension: (3) The cartesian vector.

Notes

Typically the transformation in reciprocal space is

where $\\vec{k}$ and $\\vec{k}'$ is the reciprocal vector in direct and cartesian coordinate systems, respectively. Here, B is the reciprocal unit cell.

check_for_duplicate_points(self)¶

Checks for duplicate k-points. This is currently not supported.

Parameters:	None
Returns:	None

check_lattice(self)¶

Checks if the celldata is present and that the most important parameters are defined.

Parameters:	None
Returns:	None

check_mesh(self)¶

Checks that the most important parameters for the k-point mesh have been set.

Parameters:	None
Returns:	None

create_kmesh(self, ksampling=None, shift=array([0, 0, 0], dtype=int32), halfscale=True, borderless=False)¶

Returns the k point mesh.

Parameters:

Parameters:	ksampling: ndarray, optional Dimension: (3) Contains the k - point sampling points along each direction. If not supplied the ksampling of the current Lattice() object is used. shift: ndarray, optional Dimension: (3) Contains the shift for the k - point mesh generation. If not supplied the default is set to[0.0, 0.0, 0.0] halfscale: boolean Selects if the BZ mesh should go from -0.5 to 0.5 or -1.0 to 1.0. If not supplied, the default is set to True. borderless: boolean Selects if the BZ border points should be included in the mesh generation. True selects borderless, e.g. -0.5, 0.5 etc. are excluded.
Returns:	mapping_bz_to_ibz: ndarray Dimension: (N, 3) Contains a mapping table such that it is possible to go from the BZ to the IBZ mesh. Stored in the current Lattice() object. mapping_ibz_to_bz: ndarray Dimension: (M, 3) Contains a mapping table such that it is possible to go from the IBZ to the BZ mesh. Stored in the current Lattice() object. kmesh: ndarray Dimension: (N, 3) The k - point mesh in the full BZ for N sampling points determined by the multiplication of the content of ksampling. Stored in the current Lattice() object. kmesh_ibz: ndarray Dimension: (M, 3) The k - point mesh in the irreducible BZ. The number of points M is dependent on the symmetry. Usually M < N. Stored in the current Lattice() object. ksampling: ndarray Dimension: (3) The full BZ k - point sampling in each direction. Stored in the current Lattice() object.

ksampling: ndarray, optional: Dimension: (3)

Contains the k - point sampling points along each direction. If not supplied the ksampling of the current Lattice() object is used.
shift: ndarray, optional: Dimension: (3)

Contains the shift for the k - point mesh generation. If not supplied the default is set to[0.0, 0.0, 0.0]
halfscale: boolean: Selects if the BZ mesh should go from -0.5 to 0.5 or -1.0 to 1.0. If not supplied, the default is set to True.
borderless: boolean: Selects if the BZ border points should be included in the mesh generation. True selects borderless, e.g. -0.5, 0.5 etc. are excluded.

Returns:

mapping_bz_to_ibz: ndarray: Dimension: (N, 3)

Contains a mapping table such that it is possible to go from the BZ to the IBZ mesh. Stored in the current Lattice() object.
mapping_ibz_to_bz: ndarray: Dimension: (M, 3)

Contains a mapping table such that it is possible to go from the IBZ to the BZ mesh. Stored in the current Lattice() object.
kmesh: ndarray: Dimension: (N, 3)

The k - point mesh in the full BZ for N sampling points determined by the multiplication of the content of ksampling. Stored in the current Lattice() object.
kmesh_ibz: ndarray: Dimension: (M, 3)

The k - point mesh in the irreducible BZ. The number of points M is dependent on the symmetry. Usually M < N. Stored in the current Lattice() object.
ksampling: ndarray: Dimension: (3)

The full BZ k - point sampling in each direction. Stored in the current Lattice() object.

Notes

This routines use spglib, an excellent tool written by A. Togo.

dir_to_cart(self, v, real=False)¶

Calculates the cartesian vector if the input is a vector in direct coordinates.

Parameters:	v: ndarray Dimension: (3) The supplied cartesian vector. real: boolean If set to False, the reciprocal unitcell is used, is set to True, the unitcell is used.
Returns:	ndarray Dimension: (3) The direct vector.

Notes

Typically the transformation in reciprocal space is

where $\\vec{k}$ and $\\vec{k}'$ is the reciprocal vector in direct and cartesian coordinate systems, respectively. Here, B is the reciprocal unit cell.

fetch_bz_border(self, kmesh=None, direct=True)¶

Returns the BZ border in direct or cartesian coordinates

Parameters:	kmesh: ndarray, optional Dimension: (N, 3) The k - point mesh for N k - points. If not supplied, the value of the current Lattice() is used. direct: boolean, optional Selects if direct coordinates are to be returned (True, default) or cartesian(False).
Returns:	ndarray Dimension: (3) Contains the BZ border points(largest coordinate along each axis).

fetch_iksampling(self)¶

Fetches the a denser k-point sampling which is for instance used when one would like to interpolate

Parameters:	None
Returns:	iksampling : ndarray Dimension: (3) The number of requested k-point sampling along each reciprocal unit vector.

fetch_kmesh(self, direct=True, ired=False)¶

Calculates the k point mesh in direct or cartersian coordinates.

Parameters:	direct : boolean Selects the k-point grid in direct (True) or cartesian coordinates (False) ired : boolean Selects the ireducible k-point grid (True), or the full grid (False)
Returns:	ndarray Dimension: (M,3) Contains M k-points representing the k-point mesh.

fetch_kmesh_step_size(self, direct=False)¶

Returns the step size along each direction.

Parameters:	direct : boolean, optional If True the step size is returned in direct coordinates, otherwise it is returned in AA^{-1} units. Defaults to False.
Returns:	stepx, stepy, stepz : float, float, float The step size along each reciprocal lattice vector.

Notes

Regularly spaced and ordered grids are assumed. Also, the step size returned is with respect to the reciprocal unit cells unit vectors. If direct is True the step size between 0 and 1 is returned, while for False, this step size is scaled by the length of the reciprocal unit vectors in $AA^{-1}$ .

fetch_kmesh_unit_vecs(self, direct=True)¶

Calculates the k-point mesh sampling points along the unit vectors.

Works in direct or cartesian coordinates.

Parameters:	direct : boolean Selects to return direct (True) or cartesian (False) unit vectors.
Returns:	ndarray Dimension: (3) The unit vectors of the k-point mesh.

fetch_kpoints_along_line(self, kstart, kend, stepping, direct=True)¶

Calculates the k - points along a line in the full BZ k - point mesh

Parameters:	kstart: ndarray Dimension: (3) The start k - point in direct coordinates. kend: ndarray Dimension: (3) The end k - point in direct coordinates. stepping: int The N number of steps along the line. direct: boolean If True direct coordinates are returned, else cartesian coordinates are returned.
Returns:	ndarray Dimension: (N) The N number of k - point cartesian coordinates along the line.

fetch_ksampling_from_stepsize(self, step_sizes)¶

Calculates the ksampling based on the step size.

Parameters:	step_sizes : ndarray Dimension: (3) The step size along each reciprocal unit vector
Returns:	ksampling : float, float, float The suggested sampling along each reciprocal unit vector

fetch_length_runitcell_vecs(self)¶

Returns the length of each reciprocal lattice vector.

Parameters:	None
Returns:	ndarray Dimension: (3) The lenght of each reciprocal lattice vector in inverse AA.

generate_consistent_mesh(self)¶

Calculates the k-point mesh and sets up proper mapping.

Also makes sure the IBZ or BZ supplied is similar to the one generated by spglib given the symmetry used.

Parameters:	None
Returns:	None

Notes

This should be reconsidered in the future as this is bound to give the user problems. Consider writing an interface which can accept the symmetry operators and use these directly.

real_to_rec(self, unitcell=None)¶

Calculates the reciprocal unitcell from the real unitcell.

Parameters:	unitcell: ndarray, optional Dimension: (3, 3) A real unitcell. Defaults to the unitcell for the current Lattice() object.
Returns:	ndarray Dimension: (3, 3) The reciprocal unitcell, with: math: \vec{b_1} = [0][:] etc.

rec_to_real(self, unitcell=None)¶

Calculates the real unitcell from the reciprocal unitcell.

Parameters:	unitcell: ndarray, optional Dimension: (3, 3) A reciprocal unitcell. Defaults to the internal runitcell for the current Lattice() object.
Returns:	ndarray Dimension: (3, 3) The real unitcell, with: math: \vec{a_1} = [0][:] etc.

regularcell(self)¶

Checks that all the vectors in the unit cell is orthogonal and thus if the cell is regular.

Parameters:	None
Returns:	regular: boolean True if regular, False otherwise.

lattice.calculate_cell_volume(cell)¶

Calculates the cell volume.

Parameters:	cell : ndarray Dimension: (3,3) Contains the i basis vectors of the cell, [i,:].
Returns:	volume : float The volume of the cell in units of the units along the input axis cubed.

lattice.check_sensible_ksampling(ksampling)¶

Check if the ksampling is sensible.

Parameters:	ksampling : ndarray Dimension: (3) The k-point sampling along each reciprocal lattice vector.
Returns:	None