EPWpy.utilities.EPW_util#

For epw related utilities

Functions

`generate_dtau_disp`(dtau[, direction])	Shift the polaron along the [100] direction
`get_connections`(x, y, z[, bond_leng, min_leng])
`get_gkk`(epw_file[, version])
`read_cube_file`(filein[, bond_leng])	Read a .cube file and return the scalar field data, grid dimensions, atomic positions, origin, and axis vectors.
`read_dtau`(filein)	reads the dtau
`read_dtau_plrn`(filename)	For reading dtau.plrn for further postprocessing
`read_epsilon2_files`(folder_path)	Reads all epsilon2 files in the given folder and categorizes them into: - direct: 'dirabs' - indirect: 'indabs' without number suffix - qdpt: 'indabs' with number suffix (e.g., _12, _5, etc.)
`read_gkk`(filn, nbnd, nq, nk, nmode[, version])	Read the g matrix
`read_grr`(filn, nbnd, nq, nmode)
`read_ibndmax`(file)	Reads the maximum number of bands
`read_ibndmin`(file)	Reads the minimum bands used
`read_inv_taucb`(filein)	reads inverse taucb
`read_mobility`(file, T[, typ])
`read_plrn`(file1)
`read_psir_plrn`(filein[, bond_leng])	reads the psir_plrn
`read_wfc`(filein)	reads the psir_plrn
`sig2eig`(filename, outfile[, eigs])
`write_dtau_disp`(initial, final, ntau, fileout)	Generate the dtau_disp.plrn_* files

Classes

EPWProperties(file, system[, energy_range, ...])

Class representing computed properties from EPW (Electron-Phonon Wannier) calculations.

class EPWpy.utilities.EPW_util.EPWProperties(file, system, energy_range=None, epw_fold='epw', epw_params=None, version=5.9)[source]#

Bases: object

Class representing computed properties from EPW (Electron-Phonon Wannier) calculations.

This class stores and organizes EPW-calculated quantities such as electron-phonon coupling matrices and polaronic displacements. It is typically used to read, process, and analyze EPW output data.

file#

Name of the EPW output file containing computed properties.

Type:: str

system#

Name or prefix of the system being studied.

Type:: str

prefix#

Alias for the system, used to construct file paths.

Type:: str

energy_range#

Energy range for properties extraction or analysis (e.g., around Fermi level).

Type:: float, optional

epw_params#

Dictionary of EPW parameters used for calculations (can include grid size, smearing, interpolation settings, etc.).

Type:: dict, optional

epw_fold#

Name of the EPW output folder. Default is 'epw'.

Type:: str

epw_file#

Full path to the EPW output file, constructed from system, folder, and filename.

Type:: str

Notes

This class is intended for post-processing EPW output.
The primary properties handled include:
- dtau : polaronic displacements.
- gkk : electron-phonon matrix elements.

Examples

>>> props = EPWProperties(file='epw2.out', system='graphene', energy_range=0.5)
>>> print(props.epw_file)
'graphene/epw/epw1.out'

property Eform#

property dtau#

Polaron displacement from EPW.

Returns:: Returns the polaron displacement if the EPW file exists; otherwise, returns None.
Return type:: array-like or None

elph()[source]#

Retrieve electron-phonon (el-ph) data from EPW output.

Returns a dictionary containing the electron-phonon matrix and derived properties such as the number of k-points, q-points, modes, and bands.

Returns:: Dictionary with keys: - 'gkk' : electron-phonon matrix elements g(ibnd, jbnd, imode, ik, iq) - 'nk' : number of k-points - 'nq' : number of q-points - 'nmode' : number of phonon modes - 'nband' : number of electronic bands
Return type:: dict

Example

>>> props = EPWProperties(file='epw1.out', system='graphene')
>>> elph_data = props.elph()
>>> print(elph_data['nk'])

eps1(eps0=1.0, leng=100)[source]#

eps2(eps0=1, leng=100)[source]#

property gkk#

Electron-phonon matrix elements.

The returned array has dimensions g(ibnd, jbnd, imode, ik, iq).

Returns:: Electron-phonon matrix if the EPW file exists; otherwise, prints a message and returns None.
Return type:: array-like or None

property ibte_mobility_e#

property ibte_mobility_h#

nr(eps0=1, leng=100)[source]#

omega(eps0=1, leng=100)[source]#

optical_properties(eps=1, leng=None, Temps=None)[source]#

Extract and return optical properties from EPW output.

This method parses the dielectric response (ε₂) data obtained from EPW calculations. It reads the direct, indirect, and quasi-degenerate perturbation theory (QDPT) contributions to the imaginary part of the dielectric function from the epsilon2 output files.

Parameters:

eps (int, optional) -- Index specifying which dielectric tensor component to extract (default: 1).
leng (int, optional) -- Number of frequency points to read. If None, uses the full data length (default: None).
Temps (list or None, optional) -- List of temperatures at which the optical properties are computed. If not provided, attempts to read from self.epw_params['temps'].

Returns:

Dictionary containing dielectric data: - 'direct' : dict

Direct electronic transitions contribution.

'indirect' : dict Phonon-assisted (indirect) transitions contribution.
'qdpt' : dict QDPT-corrected optical response.

Return type:

dict

Notes

The method automatically detects available temperatures from EPW input parameters.
Currently, only ε₂ (imaginary part) is parsed; ε₁ and derived quantities (e.g., refractive index) can be added later.

Example

>>> epw = EPWProperties(file='epw2.out', system='Si', epw_fold='epw')
>>> data = epw.optical_properties()
>>> direct_eps2 = data['direct']

plot_polaron(psir_file='psir_plrn.xsf', view=None)[source]#

Plot the polaron wavefunction using Matplotlib.

Parameters:

psir_file (str, optional) -- Filename of the polaron wavefunction. Default is 'psir_plrn.xsf'.
view (dict, optional) -- Dictionary of plotting parameters. Can include 'iso_level' to set the isosurface threshold. Default is {}.

Returns:

Matplotlib figure object showing the polaron isosurface.

Return type:

matplotlib.figure.Figure

Example

>>> props = EPWProperties(file='epw1.out', system='graphene')
>>> fig = props.plot_polaron(iso_level=0.01)

plot_wannier(wannier_file=None, view=None, bond_length=5.0)[source]#

Plot Wannier functions (cube files) using Matplotlib.

Parameters:

wannier_file (str, optional) -- Filename of the cube file to plot. If None, the first available Wannier cube file in the folder is used.
view (dict, optional) -- Dictionary of plotting parameters (e.g., camera angles). Default is {}.
bond_length (float, optional) -- Bond length cutoff used to read the cube file. Default is 5.0 Å.

Returns:

Matplotlib figure object showing the Wannier isosurfaces.

Return type:

matplotlib.figure.Figure

Example

>>> props = EPWProperties(file='epw1.out', system='graphene')
>>> fig = props.plot_wannier(bond_length=4.0)

polaron(psir_file='psir_plrn.xsf', dtau_file='dtau_disp.plrn')[source]#

Retrieve polaron properties from EPW output files.

Reads the polaron wavefunction and displacement from EPW-generated files and returns them in a dictionary along with formation energy.

Parameters:

psir_file (str, optional) -- Filename for the polaron wavefunction. Default is 'psir_plrn.xsf'.
dtau_file (str, optional) -- Filename for the polaron displacement. Default is 'dtau_disp.plrn'.

Returns:

Dictionary containing: - 'dtau': polaronic displacement - 'psir_plrn': polaron wavefunction - 'Eform': polaron formation energy

Return type:

dict

Example

>>> props = EPWProperties(file='epw1.out', system='graphene')
>>> polaron_data = props.polaron()
>>> print(polaron_data['dtau'])

property psir_plrn#

Polaron wavefunction from EPW.

Returns:: Returns the polaron wavefunction if the EPW file exists; otherwise, returns None.
Return type:: array-like or None

property relaxation_time_e#: get electron relaxation time

property relaxation_time_h#: get hole relaxation time

property relaxation_time_imp#: get ionized impurity relaxation time

property serta_mobility_e#

property serta_mobility_h#

transport(tau=False)[source]#

Retrieve transport properties from EPW calculations.

Returns a dictionary of electron and hole mobilities, as well as relaxation times for both carrier types. Values are available for both semi-classical (SERTA) and fully iterated (IBTE) Boltzmann transport approaches.

Parameters:: tau (bool, optional) -- If True, may be used in future to scale properties by relaxation time (currently not implemented). Default is False.
Returns:: Dictionary containing transport properties: - 'serta_mobility_elec': electron mobility (SERTA) - 'serta_mobility_hole': hole mobility (SERTA) - 'ibte_mobility_elec': electron mobility (IBTE) - 'ibte_mobility_hole': hole mobility (IBTE) - 'relaxation_time_elec': electron relaxation time - 'relaxation_time_hole': hole relaxation time
Return type:: dict

Example

>>> props = EPWProperties(file='epw1.out', system='graphene')
>>> transport_data = props.transport()
>>> print(transport_data['serta_mobility_elec'])

wannier_files()[source]#

List all Wannier cube files in the EPW output folder.

This method scans the EPW output folder for files with the .cube extension, which are typically Wannier-related outputs for visualization.

Returns:: List of cube filenames present in the folder.
Return type:: list of str

Example

>>> props = EPWProperties(file='epw1.out', system='graphene')
>>> cube_files = props.wannier_files()
Present Wannier files are:
graphene_epw1.cube
graphene_epw2.cube

EPWpy.utilities.EPW_util.generate_dtau_disp(dtau, direction='x')[source]#: Shift the polaron along the [100] direction

EPWpy.utilities.EPW_util.get_connections(x, y, z, bond_leng=3.5, min_leng=0.4)[source]#

EPWpy.utilities.EPW_util.get_gkk(epw_file, version=5.9)[source]#

EPWpy.utilities.EPW_util.read_cube_file(filein, bond_leng=3.5)[source]#: Read a .cube file and return the scalar field data, grid dimensions, atomic positions, origin, and axis vectors.

EPWpy.utilities.EPW_util.read_dtau(filein)[source]#: reads the dtau

EPWpy.utilities.EPW_util.read_dtau_plrn(filename)[source]#: For reading dtau.plrn for further postprocessing

EPWpy.utilities.EPW_util.read_epsilon2_files(folder_path)[source]#

Reads all epsilon2 files in the given folder and categorizes them into: - direct: 'dirabs' - indirect: 'indabs' without number suffix - qdpt: 'indabs' with number suffix (e.g., _12, _5, etc.)

Returns:: dict of {filename: data} indirect: dict of {filename: data} qdpt: dict of {filename: data}
Return type:: direct

EPWpy.utilities.EPW_util.read_gkk(filn, nbnd, nq, nk, nmode, version=5.9)[source]#: Read the g matrix

EPWpy.utilities.EPW_util.read_grr(filn, nbnd, nq, nmode)[source]#

EPWpy.utilities.EPW_util.read_ibndmax(file)[source]#: Reads the maximum number of bands

EPWpy.utilities.EPW_util.read_ibndmin(file)[source]#: Reads the minimum bands used

EPWpy.utilities.EPW_util.read_inv_taucb(filein)[source]#: reads inverse taucb

EPWpy.utilities.EPW_util.read_mobility(file, T, typ='Elec')[source]#

EPWpy.utilities.EPW_util.read_plrn(file1)[source]#

EPWpy.utilities.EPW_util.read_psir_plrn(filein, bond_leng=2.5)[source]#: reads the psir_plrn

EPWpy.utilities.EPW_util.read_wfc(filein)[source]#: reads the psir_plrn

EPWpy.utilities.EPW_util.sig2eig(filename, outfile, eigs=11)[source]#

EPWpy.utilities.EPW_util.write_dtau_disp(initial, final, ntau, fileout)[source]#: Generate the dtau_disp.plrn_* files

Table of Contents

Previous topic

Next topic

EPWpy.utilities.EPW_util#