Skip to content

qttools.utils.input_utils#

source module qttools.utils.input_utils

Functions

  • read_hr_dat — Parses the contents of a seedname_hr.dat file.

  • read_wannier_wout — Parses the contents of a seedname.wout file and returns the Wannier centers and lattice vectors.

  • cutoff_hr — Cutoffs the Hamiltonian matrix elements based on their values and/or the wigner-seitz cell indices.

  • get_hamiltonian_block — Constructs a supercell hamiltonian block from an hr array.

  • create_coordinate_grid — Creates a grid of coordinates for Wannier functions in a supercell.

  • create_hamiltonian — Creates a block-tridiagonal Hamiltonian matrix from a Wannier Hamiltonian. The transport cell (same as supercell) is the cell that is repeated in the transport direction, and is only connected to nearest-neighboring cells. NOTE: interactions outside nearest neighbors are not included in the block-tridiagonal Hamiltonian (see below). It can therefore be important to make sure that the transport cell is large enough, such that each row have the same number of neighbouring cells. Not setting a transport cell will default to a cell that includes all interactions of hR.

source read_hr_dat(path: Path, return_all: bool = False, dtype: _DType = xp.complex128, read_fast=False) → tuple[NDArray, ...]

Parses the contents of a seedname_hr.dat file.

The first line gives the date and time at which the file was created. The second line states the number of Wannier functions num_wann. The third line gives the number of Wigner-Seitz grid-points.

The next block of integers gives the degeneracy of each Wigner-Seitz grid point, arranged into 15 values per line.

Finally, the remaining lines each contain, respectively, the components of the Wigner-Seitz cell index, the Wannier center indices m and n, and and the real and imaginary parts of the Hamiltonian matrix element HRmn in the localized basis.

Parameters

  • path : Path — Path to a seedname_hr.dat file.

  • return_all : bool, optional — Whether to return all the data or just the Hamiltonian in the localized basis. When True, the degeneracies and the Wigner-Seitz cell indices are also returned. Defaults to False.

  • dtype : dtype, optional — The data type of the Hamiltonian matrix elements. Defaults to numpy.complex128.

  • read_fast : bool, optional — Whether to assume that the file is well-formatted and all the data is sorted correctly. Defaults to False.

Returns

  • hr : ndarray — The Hamiltonian matrix elements in the localized basis.

  • degeneracies : ndarray, optional — The degeneracies of the Wigner-Seitz grid points.

  • R : ndarray, optional — The Wigner-Seitz cell indices.

source read_wannier_wout(path: Path, transform_home_cell: bool = True) → tuple[NDArray, NDArray]

Parses the contents of a seedname.wout file and returns the Wannier centers and lattice vectors.

TODO: Add tests.

Parameters

  • path : Path — Path to a seedname.wout file.

  • transform_home_cell : bool, optional — Whether to transform the Wannier centers to the home cell. Defaults to True.

Returns

  • wannier_centers : ndarray — The Wannier centers.

  • lattice_vectors : ndarray — The lattice vectors.

source cutoff_hr(hr: NDArray, value_cutoff: float | None = None, R_cutoff: int | tuple[int, int, int] | None = None, remove_zeros: bool = False) → NDArray

Cutoffs the Hamiltonian matrix elements based on their values and/or the wigner-seitz cell indices.

TODO: Add tests.

Parameters

  • hr : ndarray — Wannier Hamiltonian.

  • value_cutoff : float, optional — Cutoff value for the Hamiltonian. Defaults to None.

  • R_cutoff : int or tuple, optional — Cutoff distance for the Hamiltonian. Defaults to None.

  • remove_zeros : bool, optional — Whether to remove cell planes with only zeros. Defaults to False.

Returns

  • ndarray — The cutoff Hamiltonian.

source get_hamiltonian_block(hr: NDArray, supercell_size: tuple, global_shift: tuple) → xp.ndarray

Constructs a supercell hamiltonian block from an hr array.

Parameters

  • hr : ndarray — Wannier Hamiltonian.

  • supercell_size : tuple — Size of the supercell. E.g. (2, 2, 1) for a 2x2 xy-supercell.

  • global_shift : tuple — Shift in the supercell system. If you want a R-shift of 1 cell in x direction, you would pass (1, 0, 0). NOTE: this is for the supercell and NOT the unit cell.

Returns

  • ndarray — The supercell hamiltonian block.

Raises

  • IndexError

source create_coordinate_grid(wannier_centers: NDArray, super_cell: tuple, lattice_vectors: NDArray) → NDArray

Creates a grid of coordinates for Wannier functions in a supercell.

source create_hamiltonian(hR: NDArray, num_transport_cells: int, transport_dir: int | str = 'x', transport_cell: list = None, block_start: int = None, block_end: int = None, return_sparse: bool = True, cutoff: float = xp.inf, coords: NDArray = None, lattice_vectors: NDArray = None) → list[NDArray]

Creates a block-tridiagonal Hamiltonian matrix from a Wannier Hamiltonian. The transport cell (same as supercell) is the cell that is repeated in the transport direction, and is only connected to nearest-neighboring cells. NOTE: interactions outside nearest neighbors are not included in the block-tridiagonal Hamiltonian (see below). It can therefore be important to make sure that the transport cell is large enough, such that each row have the same number of neighbouring cells. Not setting a transport cell will default to a cell that includes all interactions of hR.

| o o o | o o o | x | o o o | o o o | x x <- cells outside nearest neighbors are not included | o o o | o o o | x x x

| o o o | o o o | o o o | | o o o | o o o | o o o | | o o o | o o o | o o o |

x x x | o o o | o o o | x x | o o o | o o o | x | o o o | o o o | ------- -------

Parameters

  • hR : ndarray — Wannier Hamiltonian.

  • num_transport_cells : int — Number of transport cells.

  • transport_dir : int or str, optional — Direction of transport. Can be 0, 1, 2, 'x', 'y', or 'z'.

  • transport_cell : tuple, optional — Size of the transport cell. E.g. [2, 2, 1] for a 2x2 xy-transport cell.

  • block_start : int, optional — Starting block index for arrow shape partition. Defaults to None.

  • block_end : int, optional — Ending block index for arrow shape partition. Defaults to None.

  • return_sparse : bool, optional — Whether to return the block-tridiagonal Hamiltonian as a sparse matrix. Defaults to False.

  • cutoff : float, optional — Cutoff distance for connections between wannier functions. Defaults to np.inf.

  • coords : ndarray, optional — Coordinates of the Wannier functions in a unit cell. Defaults to None.

  • lattice_vectors : ndarray, optional — Lattice vectors of the system. Defaults to None.

Returns

  • list[ndarray] or tuple[sparse.coo_matrix, ndarray] — The block-tridiagonal Hamiltonian matrix as either a tuple of arrays or a sparse matrix and block sizes.

Raises

  • ValueError