httk.atomistic.wavefunction module

class httk.atomistic.wavefunction.PlaneWaveFunctions(file_ref=None, recpos_func=None, nkpts=None, nbands=None, nspins=None, nplws=None, encut=None, cell=None, kpts=None, kgrid_size=None, double_precision=None, eigs=None, occups=None, pwcoeffs=None, is_gamma=None, gamma_half=None, kgrid=None)

Bases: HttkObject

PlaneWaveFunction is a proxy for a collection of wavefunctions contained in output files of plane-wave basis DFT codes.

This object stores the energy, occupation and plane-wave coefficients from a calculation, contained in a wavefunction file (e.g. a VASP WAVECAR). The access to the plane-wave coefficients is done in a lazy fashion, only caching the requested orbitals at specified K-points

In addition, it caches the k-vectors/g-vectors associated with the basis set and parameters necessary to generate these (e.g. VASP energy cutoff)

NOTE: Currently does not support non-collinear (SOC) output formats

NOTE: As fourier transforms and similar rely on the numpy/scipy/jax library, read-in FracVectors are in working functions converted to numpy arrays during processing

copy(spins=None, ikpts=None, bands=None, file_ref=None, format=None, gamma_half='x')

classmethod create(file_wrapper=None, rec_pos_func=None, nplws=None, encut=None, cell=None, kpts=None, double_precision=None, eigs=None, occups=None, pwcoeffs=None, is_gamma=None, gamma_half='x')

Factory function for the proxy object for wavefunctions file.

Input: file_wrapper: File wrapper for the wavefunction file. If None, the wavefunction coefficients must be provided directly rec_pos_func: Function taking spin, kpoint and band indices, returning the record position in the binary file. If None, the coefficients must be provided directly nplws: Number of plane-waves for each k-point. encut: Energy cutoff for the plane-wave basis set cell: Cell object containing the basis vectors of the supercell kpts: List of k-points for the wavefunction coefficients double_precision: If the wavefunction coefficients are stored in double precision (True) or single precision (False) eigs: Eigenvalues of the wavefunctions occups: Occupation numbers of the wavefunctions pwcoeffs: Coefficients of the wavefunctions. Either a nested list of coefficients, or a dictionary with keys (spin, kpt, band) and values as list-like objects of coefficients is_gamma: If the wavefunction is gamma-compressed (True) or not (False). If None, the function tries to determine the format from the k-point list and the number of plane-waves gamma_half: If the wavefunction is gamma-compressed, which axis of k-space was used for the compression. Either “x” or “z”, but defaults to “x”. Only relevant if is_gamma is True.

Either file_wrapper and rec_pos_func must be provided, or pwcoeffs must be provided directly. If both are provided, the pwcoeffs are ignored.

eigenval(s, k, b)

property encut

Returns the energy cutoff for the plane-wave basis set.

property gamma_half

Returns the axis of k-space used for gamma-compression, if the wavefunction is gamma-compressed.

get_gvecs(kpt_ind=None, kpt=None, gamma=None, gamma_half=None, kgrid=None, cache=True)

Getter function for the g-vectors of the wavefunction. Can either be used to generate a new set of g-vectors, or to retrieve a cached set of g-vectors for the current object.

Input: kpt_ind: K-point index of the wavefunction (1-indexed) kpt: K-point vector of the wavefunction (3D numpy array), if kpt_ind is not provided gamma: Whether to generate gamma-compressed g-vectors (True) or not (False). If None, use the gamma-format of the wavefunction object. gamma_half: Which axis of k-space to use for the gamma-compression. Either “x” or “z”. Only relevant if gamma is True. kgrid: The k-grid to use for the generation of the g-vectors. If None, generate a new k-grid for current object.

get_plws(spin, kpt, band, cache=True)

Getter function for the plane-wave coefficients of the wavefunction. The function will check if the coefficients are already cached, and if not, read them from the file.

Input: spin: Spin index of the wavefunction (1-indexed) kpt: K-point index of the wavefunction (1-indexed) band: Band index of the wavefunction (1-indexed) cache: If True, the coefficients are cached in the object. If False, the coefficients are not cached and read from the file every time.

Output: coeffs: 3D numpy array of complex numbers, containing the plane-wave coefficients of the wavefunction

get_wavr(spin, kpt, band, norm=True)

Getter function for the real-space form of the wavefunction at given indices.

Input: spin: Spin index of the wavefunction (1-indexed) kpt: K-point index of the wavefunction (1-indexed) band: Band index of the wavefunction (1-indexed) norm: If True, the wavefunction is normalized to unit length. Otherwise, the wavefunction is transformed as found in the WAVECAR.

Output: real_space_wave: 3D numpy array of complex numbers, containing the real-space form of the wavefunction

property is_gamma

Returns whether the wavefunction is gamma-compressed or not.

property kpoints

Returns the k-points of the wavefunction object as fracvector array.

property nbands

Returns the number of bands in the wavefunction object.

property nkpts

Returns the number of k-points in the wavefunction object.

property nplanewaves

Returns the number of plane-waves for each k-point in the wavefunction object.

property nspins

Returns the number of spin-channels in the wavefunction object.

occupation(s, k, b)

read_plws(spin, kpt, band)

Reads the plane-wave coefficients from the stored file wrapper. The function will check if the file reference is valid and if the record position function is valid.

rearrange(index_map)

Exchanges specified orbitals, exchanging band index or spin index according to given map. Note that orbitals cannot be exchanged between k-points, as the number of coefficients and g-vectors are k-dependent.

Input index_map: Dictionary with indices of orbitals to rearrange as keys, and target indices as values, on the form (spin_i, k_i, band_i). k_i of key and value has to be the same. The map has to be one-to-one for the given indices in both directions.

httk.atomistic.wavefunction.expand_gamma_coeffs(coeffs, std_gvecs, gam_gvecs, buffer=None)

Expands the gamma-compressed coefficients to the full set of coefficients, using provided g-vectors.

Input: coeffs: 3D numpy array of complex numbers, containing gamma-compressed wavefunction coefficients std_gvecs: g-vectors for the full set of coefficients gam_gvecs: g-vectors for the gamma-compressed coefficients (optional) buffer: buffer for intermediate full result. If None, a new buffer is allocated.

Output: expanded_coeffs: 3D numpy array of complex numbers, containing the full set of coefficients

httk.atomistic.wavefunction.expand_gamma_wav(buffer, xyz)

Reverses the gamma-compression of the buffer, by mirroring in provided g-vectors.

Input: buffer: 3D numpy array of complex numbers, containing gamma-compressed wavefunction coefficients in the positive half-space xyz: list of g-vectors for the gamma-compressed (negative) half-space. A Nx3 numpy array of integers.

httk.atomistic.wavefunction.gen_gvecs(kgrid, kvec, basis, encut)

Generates the G-vectors fullfilling the cutoff condition |k + G|**2/2 < ENCUT

Input kgrid: Rectangular kgrid containing states kvec: Reciprocal vector for k, as a list or numpy row vector basis: Supercell vectors encut: The energy cutoff to use

Returns numpy array of row vectors representing fulfilling G-vectors

httk.atomistic.wavefunction.gen_kgrid(grid_size, gamma, gamma_half='x')

Generates the (rectangular) kgrid containing all k-states within the given grid size (excluding gamma-compressed states if specified).

Input: grid_size: Size of the kgrid in each dimension (must be ueven) gamma: If the kgrid is gamma-compressed (True) or not (False) gamma_half: Which axis of k-space to use for the gamma-compression. Either “x” or “z”. Only relevant if gamma is True.

httk.atomistic.wavefunction.meshgrid(x, y, z)

Generates a 3D meshgrid of the given x,y,z vectors

Input: x, y, z: 1D numpy arrays

httk.atomistic.wavefunction.reduce_std_coeffs(coeffs, grid_size, std_gvecs, gam_gvecs, gamma_half='x')

Performs gamma compression of the coefficients, using provided g-vectors. This requires for the real-space wavefunction to be real-valued, so a transformation of the wavefunction is performed while retaining the same partial density. However, this transformation destroyes the phase information of the wavefunction.

Input: coeffs: 3D numpy array of complex numbers, containing the full set of coefficients std_gvecs: g-vectors for the full set of coefficients gam_gvecs: g-vectors for the gamma-compressed coefficients gamma_half: which axis of k-space gamma-compression is done along. Either “x” or “z”

Output: result: 3D numpy array of complex numbers, containing the gamma-compressed coefficients

httk.atomistic.wavefunction.to_real_wave(coeffs, grid_size, gvecs, gamma=False, gamma_half='x', norm=True)

Fourier-transform the given plane-wave coefficients into a real-space wavefunction

Input plane_wave: Plane wave coefficients (numpy array) gvecs: g-vectors for each coefficient gamma: if the wavefunction is gamma-compressed gamma_half: which axis of k-space gamma-compression was done along

Output Numpy array with real-space wave functions.