pythtb.Mesh

class Mesh(axis_types, axis_names=None, dim_k=None)

Store and manage a mesh in \((k, \lambda)\)-space.

Added in version 2.0.0.

This class is responsible for constructing a mesh sampling of the combined reciprocal space and additional adiabatic parameters, i.e. \((k, \lambda)\)-space. It provides methods to build both grid and path representations of the mesh, or a custom mesh with user-defined points. The mesh can be a pure k-space mesh, a pure parameter space mesh, or a mixed mesh with axes in both spaces. The mesh can also be a grid or a path.

A grid mesh has an axis for each dimension of the mesh, while a path mesh has a single axis that traces a path through the combined \((k, \lambda)\)-space. For example, in 2D k-space, a grid will have 2 axes that sample the kx and ky directions independently, while a path mesh would have a single axis that samples along some direction in the combined space, varying one or more k-components. The last axis of the array represents the vector components in \((k, \lambda)\)-space.

Parameters:

axis_typeslist[str]

A list of axis types, which can be "k" or "l" for k-space and parametric space respectively. The length of this list will determine the number of dimensions in the mesh.

axis_nameslist[str], optional

A list of axis names, which can be used for parametrically populating a pythtb.WFArray. If unspecified, default names will be generated. See examples listed below for more details.

dim_kint, optional

The dimensionality of k-space. If unspecified, this will default to the number of "k" axes specified in axis_types. Specifying this parameter is useful when creating a mesh with fewer k-axes than the full k-space dimensionality, such as when creating a path through 2D k-space using only a single k-axis. This will determine the dimension of the vector at each mesh point. Must be at least equal to the number of "k" axes specified in axis_types.

See also

Berry phase and curvature in the Haldane model

Hybrid Wannier centers in the Kane-Mele model

Three-site Thouless pump

Hybrid Wannier functions in cubic slab

Hybrid Wannier centers in the Haldane model

Notes

• The mesh points are stored in reduced units, i.e., in units of the reciprocal lattice vectors for k-space and in units of the full parameter range for parameter space.

• The parameter space is assumed to be orthogonal to the k-space. This means that when varying the parameter along its axis, the k-components are held fixed.

• The dimension of parameter space is dim_k plus the number of "l" axes specified in axis_types. This means that it is currently not supported to have a path through adiabatic parameter space, we must have a separate axis for each parameter dimension.

Examples

We can create a full grid by specifying the shape of the grid.

>>> mesh = Mesh(axis_types=['k', 'k'])
>>> mesh.build_grid(shape=(10, 10), gamma_centered=True)
>>> mesh.grid.shape
(10, 10, 2)

Or suppose we have a 3D k-space model with an additional lambda dimension.

>>> mesh = Mesh(axis_types=['k', 'k', 'k', 'l'])
>>> mesh.build_grid(shape=(10, 10, 10, 100), gamma_centered=True)
>>> mesh.grid.shape
(10, 10, 10, 100, 4)

Since we have a gamma-centered grid, the k-axes go from [-0.5, 0.5) non-inclusive. The endpoints for the lambda axis are included by default.

>>> mesh.grid[0, 0, 0, 0, 0]
array([-0.5, -0.5, -0.5,  0. ])
>>> mesh.grid[-1, -1, -1, -1, -1]
array([ 0.49,  0.49,  0.49,  1. ])

Suppose instead we have a custom path through k-space that is not a regular grid. We would then need to initialize the Mesh with a single ‘k’ axis type.

>>> path_points = np.random.rand(100, 2)  # 100 point path in 2D k-space
>>> mesh = Mesh(axis_types=['k'], dim_k=2)
>>> mesh.build_custom(path_points)

Methods

pythtb.Mesh.build_custom	Build a custom mesh from the given points.
pythtb.Mesh.build_grid	Build a regular Monkhorst-Pack k-space and lambda space grid.
pythtb.Mesh.build_path	Build a k-path in the Brillouin zone.
pythtb.Mesh.gen_hyper_cube	Generate a hypercube of points in the specified dimensions.
pythtb.Mesh.get_axis_range	Return the 1D range along a mesh axis/component pair.
pythtb.Mesh.get_k_points	Return the k-point mesh from the full grid, with shape (nk1, nk2, ..., dim_k).
pythtb.Mesh.get_param_points	Return the unique parameter-point mesh from the full grid, with shape (nl1, nl2, ..., dim_lambda).
pythtb.Mesh.info	Information summary about the mesh.
pythtb.Mesh.is_axis_bz_winding	Return True iff sampling axis axis_idx winds around the BZ for at least one component.
pythtb.Mesh.is_axis_closed	Return True iff sampling axis axis_idx contains endpoint for at least one component.
pythtb.Mesh.is_axis_looped	Return True iff sampling axis axis_idx wraps at least one component.
pythtb.Mesh.loop	Declare an axis loops a specified component of the mesh vector.
pythtb.Mesh.unloop	Declare an axis as not looping a specified component of the mesh vector.

Attributes

pythtb.Mesh.axes	List of Axis objects defining the mesh axes.
pythtb.Mesh.axis_names	List of axis names.
pythtb.Mesh.axis_types	List of axis types.
pythtb.Mesh.bz_winding_axes	List of Axis objects that wind around the BZ to form a loop.
pythtb.Mesh.bz_winding_mask	Boolean array of shape (naxes, dim_total) marking which axes wind around the BZ.
pythtb.Mesh.component_types	Tuple of length dim_total() labeling vector components as 'k' or 'l'.
pythtb.Mesh.dim_k	Dimension of k-space.
pythtb.Mesh.dim_lambda	Dimension of lambda-space.
pythtb.Mesh.dim_total	Dimension of the full mesh space (dim_k() + dim_lambda()).
pythtb.Mesh.endpoint_axes	List of Axis objects that have equal endpoints.
pythtb.Mesh.endpoint_mask	Boolean array of shape (naxes, dim_total) marking which axes have equal endpoints.
pythtb.Mesh.filled	True if the mesh is filled (i.e., contains points).
pythtb.Mesh.flat	Mesh point array of shape (N1*N2*...*Nd, dim_k + dim_lambda).
pythtb.Mesh.is_grid	True if the mesh is a grid (as opposed to a path).
pythtb.Mesh.is_k_torus	Does the mesh wind around the BZ in all k-directions?
pythtb.Mesh.k_axes	List of Axis objects of k-type.
pythtb.Mesh.k_axis_indices	List of indices of the k-axes.
pythtb.Mesh.k_component_indices	List of indices of k components of the vector.
pythtb.Mesh.lambda_axes	List of Axis objects of lambda-type.
pythtb.Mesh.lambda_axis_indices	List of indices of the lambda-axes.
pythtb.Mesh.lambda_component_indices	List of indices of lambda components of the vector.
pythtb.Mesh.loop_axes	List of Axis objects that wind to form a loop.
pythtb.Mesh.loop_mask	Boolean array of shape (naxes, dim_total) marking which axes wind to form a loop.
pythtb.Mesh.naxes	Total number of axes.
pythtb.Mesh.nk_axes	Number of k-axes.
pythtb.Mesh.nl_axes	Number of lambda-axes.
pythtb.Mesh.nodes	For path meshes, the original nodes used to build the path.
pythtb.Mesh.npoints	Number of mesh points.
pythtb.Mesh.points	Mesh point array of shape (N1, ..., Nd, dim_k + dim_lambda).
pythtb.Mesh.shape	Shape of mesh points (*shape_axes, dim_k + dim_lambda).
pythtb.Mesh.shape_axes	Tuple of axis sizes (N1, N2, ..., Nd).
pythtb.Mesh.shape_k	Size of each k-axis.
pythtb.Mesh.shape_lambda	Size of each lambda-axis.