Wavefunction (Wfc)¶

class dopyqo.Wfc(ik: int, xk: ndarray, ispin: int, gamma_only: bool, scalef: float, ngw: int, igwx: int, npol: int, nbnd: int, b1: ndarray, b2: ndarray, b3: ndarray, mill: ndarray, evc: ndarray, output_xml: str, pseudopots: list[Pseudopot] = None, kpoint_idx: int | None = None)[source]¶

Bases: object

Class storing wavefunction and crystal information from Quantum ESPRESSO output files

See from_file(…) function to create object from Quantum ESPRESSO output files.

classmethod from_file(file: str, output_xml: str, pseudopots: list[Pseudopot] = None, kpoint_idx: int | None = None)[source]¶

Create Wfc object from a .dat or .hdf5 Quantum ESPRESSO output file. Calls Wfc.from_dat_file or Wfc.from_hdf5_file depending on the provided file.

Parameters:

file (str) – Path to the .dat or .hdf5 file.
output_xml (str) – Path to the XML-file Quantum ESPRESSO outputs.
pseudopots (list[Pseudopot], optional) – List of dopyqo.Pseudopot objects, one object per atom type. Defaults to None.
kpoint_idx (int | None, optional) – k-point index starting from 0. Is set to 0, if None and Quantum ESPRESSO calculation only involved one k-point. Has to match ik+1, if Quantum ESPRESSO calculation involved multiple k-points. Defaults to None.

Raises:

NotImplementedError – If the provided file is not a .dat and not .hdf5 file.

Returns:

Wfc object

Return type:

Wfc

classmethod from_hdf5_file(hdf5_file: str, output_xml: str, pseudopots: list[Pseudopot] = None, kpoint_idx: int | None = None)[source]¶

Create Wfc object from a .hdf5 Quantum ESPRESSO output file.

Parameters:

hdf5_file (str) – Path to the .hdf5 file.
output_xml (str) – Path to the XML-file Quantum ESPRESSO outputs.
pseudopots (list[Pseudopot], optional) – List of dopyqo.Pseudopot objects, one object per atom type. Defaults to None.
kpoint_idx (int | None, optional) – k-point index starting from 0. Is set to 0, if None and Quantum ESPRESSO calculation only involved one k-point. Has to match ik+1, if Quantum ESPRESSO calculation involved multiple k-points. Defaults to None.

Returns:

Wfc object

Return type:

Wfc

classmethod from_dat_file(dat_file: str, output_xml: str, pseudopots: list[Pseudopot] = None, kpoint_idx: int | None = None)[source]¶

Create Wfc object from a .dat Quantum ESPRESSO output file.

Parameters:

dat_file (str) – Path to the .dat file.
output_xml (str) – Path to the XML-file Quantum ESPRESSO outputs.
pseudopots (list[Pseudopot], optional) – List of dopyqo.Pseudopot objects, one object per atom type. Defaults to None.
kpoint_idx (int | None, optional) – k-point index starting from 0. Is set to 0, if None and Quantum ESPRESSO calculation only involved one k-point. Has to match ik+1, if Quantum ESPRESSO calculation involved multiple k-points. Defaults to None.

Returns:

Wfc object

Return type:

Wfc

classmethod from_file_all_kpoints(files: list[str], output_xml: str, pseudopots: list[Pseudopot] = None, verbose: bool = False)[source]¶

Create Wfc object from a list of .dat or .hdf5 Quantum ESPRESSO output files and return a list of Wfc objects. Calls Wfc.from_file for each file in the list of files.

Parameters:

files (list[str]) – List of .dat or .hdf5 files
output_xml (str) – Path to the XML-file Quantum ESPRESSO outputs.
pseudopots (list[dopyqo.Pseudopot], optional) – List of dopyqo.Pseudopot objects, one object per atom type. Defaults to None.

Returns:

List of Wfc objects

Return type:

list[Wfc]

get_overlaps(orbitals=None)[source]¶

check_norm()[source]¶

get_orbitals_by_index(indices: list | ndarray | None = None, binary_occupations=True)[source]¶

active_space(active_electrons: int, active_orbitals: int) → tuple[list[int], list[int]][source]¶

set_atom_positions(atom_positions: ndarray, unit: Unit)[source]¶

Change the atom positions

Parameters:

atom_positions (np.ndarray) – New atom positions. Shape (# of atoms, 3).
unit (dopyqo.Unit) – Unit in which the new atom positions are given

Raises:

ValueError – If the unit is not supported.

set_lattice_vectors(lattice_vectors: ndarray, unit: Unit)[source]¶

Change the lattice vectors

Parameters:

lattice_vectors (np.ndarray) – New lattice vectors. Shape (3, 3). Each row is one lattice vector.
unit (dopyqo.Unit) – Unit in which the new atom positions are given

Raises:

ValueError – If the unit is not supported.

wigner_seitz_cell() → list[list[ndarray]][source]¶

Calculate all facets of the Wigner-Seitz cell. See dopyqo.wfc.plot_wigner_seitz_cell to plot the return values of this function.

Returns:: List of facets
Return type:: list[list[np.ndarray]]

wigner_seitz_in_radius() → float[source]¶

Calculate the inner radius of the Wigner-Seitz cell.

Returns:: Inner radius of the Wigner-Seitz cell
Return type:: float

to_qe_input(filename: str, prefix: str, outdir: str = './', pseudo_dir: str | None = None)[source]¶

Generates a Quantum ESPRESSO (QE) input file for a self-consistent field (SCF) calculation. Author: Erik Hansen

Parameters:

filename (str) – Full path and filename of the input file to create
prefix (str) – Prefix for the QE calculation
outdir (str) – Output directory specified in the input file (‘outdir’)
pseudo_dir (str | None, optional) – Directory with the pseudopotential files specified in the input file (‘pseudo_dir’). Not written to input file if None. Defaults to None.

plot_real_space(isosurfaces: int | list[float], band_idc: list | ndarray | None = None, plot_abs: bool = True, plot_lattice_vectors: bool = True, extend_data: bool = False, plotter: pyvista.Plotter = None, **kwargs) → pyvista.Plotter[source]¶

Plot the real-space representation of the Kohn-Sham orbitals

Parameters:

isosurfaces (int | list[float]) – Number of isosurfaces, if int. Values of isosurfaces if list of floats
band_idc (list | np.ndarray | None, optional) – Indices of Kohn-Sham orbitals to plot. Plots all Kohn-Sham orbitals if None. Defaults to None.
plot_abs (bool, optional) – If the absolute values of the Kohn-Sham orbitals are plotted. Defaults to True.
plot_lattice_vectors (bool, optional) – If the lattice vectors are plotted as arrows. Defaults to True.
extend_data (bool, optional) – If the orbitals are also plotted for all neighbouring cells besides the computational cell. Defaults to False.
plotter (pv.Plotter, optional) – PyVista plotter object used for plotting. A new one is created if None. Defaults to None.
kwargs – Arguments passed to dopyqo.plotting.plot_3d_data

Returns:

PyVista plotter object

Return type:

pv.Plotter

plot_real_space_from_c_ip(c_ip: np.ndarray, isosurfaces: int | list[float], plot_abs: bool = True, plot_lattice_vectors: bool = True, extend_data: bool = False, extend_atoms: bool = False, plotter: pv.Plotter | None = None, **kwargs) → pv.Plotter[source]¶

Plot the real-space representation of the Kohn-Sham orbitals, given their coefficients in the plane wave basis

Parameters:

c_ip (np.ndarray) – Numpy array of plane wave coefficients of shape (nbnd, npw), where nbnd is the number of bands and npw is the number of plane waves
isosurfaces (int | list[float]) – Number of isosurfaces, if int. Values of isosurfaces if list of floats
plot_abs (bool, optional) – If the absolute values of the Kohn-Sham orbitals are plotted. Defaults to True.
plot_lattice_vectors (bool, optional) – If the lattice vectors are plotted as arrows. Defaults to True.
extend_data (bool, optional) – If the orbitals are also plotted for all neighbouring cells besides the computational cell. Defaults to False.
extend_atoms (bool, optional) – If the atoms are also plotted for all neighbouring cells besides the computational cell. Defaults to False.
plotter (pv.Plotter | None, optional) – PyVista plotter object used for plotting. A new one is created if None. Defaults to None.
kwargs – Arguments passed to dopyqo.plotting.plot_3d_data

Returns:

PyVista plotter object

Return type:

pv.Plotter

plot_real_space_from_3d_data(coordinates: np.ndarray, isosurfaces: int | list[float], psi_r: list[np.ndarray], plot_lattice_vectors: bool = True, extend_data: bool = False, extend_atoms: bool = False, plotter: pv.Plotter | None = None, **kwargs) → pv.Plotter[source]¶

_summary_

Parameters:

coordinates (np.ndarray) – Numpy array of coordinates of shape (nx,ny,nz,3) or of shape (nx*ny*nz,3)
isosurfaces (int | list[float]) – Number of isosurfaces, if int. Values of isosurfaces if list of floats
psi_r (list[np.ndarray]) – List of numpy arrays. Each numpy array represents scalar field data of shape (nx,ny,nz) or of shape (nx*ny*nz)
plot_lattice_vectors (bool, optional) – If the lattice vectors are plotted as arrows. Defaults to True.
extend_data (bool, optional) – If the orbitals are also plotted for all neighbouring cells besides the computational cell. Defaults to False.
extend_atoms (bool, optional) – If the atoms are also plotted for all neighbouring cells besides the computational cell. Defaults to False.
plotter (pv.Plotter | None, optional) – _description_. Defaults to None.
kwargs – Arguments passed to dopyqo.plotting.plot_3d_data

Returns:

PyVista plotter object

Return type:

pv.Plotter

dopyqo.runQE(input_file: str, num_cpus: int = 1, nk: int = 1, nb: int = 1, nt: int = 1)[source]¶

Executes a Quantum Espresso (QE) simulation by generating the necessary input files, running the QE executable, and managing the working directory. Author: Erik Hansen

See https://www.quantum-espresso.org/Doc/user_guide/node20.html for arguments nk, nb, nt.

Side Effects:

Creates a new folder for the QE run and generates input files.
Executes the Quantum Espresso pw.x command using mpirun.
Changes the working directory to the QE run folder and back to the original path.
Writes output to a file named <prefix_of_QE_current>_scf.out.

Notes

Ensure that Quantum Espresso is installed and accessible via the pw.x command.
The mpirun command assumes 10 cores are available for parallel execution.

Parameters:

input_file (str) – Full path and filename of the input file.
num_cpus (int) – Number of MPI processes
nk (int) – number of processes for k-point parallelization
nb (int) – number of processes for KS-band parallelization
nt (int) – number of processes for plane wave parallelization