Electron–phonon

Electron-phonon coupling from EPW.

class elphmod.elph.Model(epmatwp=None, wigner=None, el=None, ph=None, Rk=None, dk=None, Rg=None, dg=None, old_ws=False, divide_mass=True, divide_ndegen=True, shared_memory=False)

Localized model for electron-phonon coupling.

Parameters:

epmatwpstr

File with electron-phonon coupling in localized bases from EPW.

wignerstr

File with definition of Wigner-Seitz supercells from modified EPW.

elelphmod.el.Model

Tight-binding model for the electrons.

phelphmod.ph.Model

Mass-spring model for the phonons.

Rk, Rgndarray

Lattice vectors of Wigner-Seitz supercells if wigner is omitted.

dk, dgndarray

Degeneracies of Wigner-Seitz points if wigner is omitted.

old_wsbool

Use previous definition of Wigner-Seitz cells? This is required if patches/qe-6.3-backports.patch has been used.

divide_massbool

Divide electron-phonon coupling by square root of atomic masses?

divide_ndegenbool

Divide real-space coupling by degeneracy of Wigner-Seitz point? Only True yields correct couplings. False should only be used for debugging.

shared_memorybool

Read coupling from EPW into shared memory?

Attributes:

elelphmod.el.Model

Tight-binding model for the electrons.

phelphmod.ph.Model

Mass-spring model for the phonons.

Rk, Rgndarray

Lattice vectors \(\vec R', \vec R\) of Wigner-Seitz supercells.

dk, dgndarray

Degeneracies of Wigner-Seitz points.

datandarray

Corresponding electron-phonon matrix elements in Ry^3/2.

\[g_{\vec R i \vec R' \alpha \beta} = \frac \hbar {\sqrt M_i} \bra{0 \alpha} \frac{\partial V}{\partial u_{\vec R i}} \ket{\vec R' \beta}\]

If not divide_mass, the prefactor \(\hbar / \sqrt{M_i}\) is absent and the units are Ry/bohr instead. If ph.lr, this is only the short-range component of the matrix elements.

divide_massbool

Has real-space coupling been divided by atomic masses?

divide_ndegenbool

Has real-space coupling been divided by degeneracy of Wigner-Seitz point?

node, imagesMPI.Intracomm

Communicators between processes that share memory or same node.rank if shared_memory.

qndarray

Previously sampled q point, if any.

gqndarray

Rk-dependent coupling for above q point for possible reuse.

cellslist of tuple of int, optional

Lattice vectors of unit cells if the model describes a supercell.

g0ndarray

Coupling on original q and k meshes.

Rk0int

Index of electronic lattice vector at origin.

asr(report=True)

Apply acoustic sum rule correction to electron-phonon coupling.

This will suppress all coupling of electrons to acoustic phonon modes. The matrix elements are subject to a constant relative change so that zeros remain zeros and the largest values change the most. There might be a better way to accomplish this.

reportbool

Print sums before and after correction?

clear()

Delete all lattice vectors and associated matrix elements.

decay_epmate()

Plot maximum matrix element as a function of hopping distance.

Use divide_mass=False to recreate EPW’s decay.epmate file.

Returns:

ndarray

Distances.

ndarray

Maximum absolute matrix elements.

decay_epmatp()

Plot maximum matrix element as a function of displacement distance.

Use divide_mass=False to recreate EPW’s decay.epmatp file.

Returns:

ndarray

Distances.

ndarray

Maximum absolute matrix elements.

divide_degeneracy(g)

Divide real-space coupling by degeneracy of Wigner-Seitz point.

Parameters:

gndarray

Real-space coupling.

g(q1=0, q2=0, q3=0, k1=0, k2=0, k3=0, elbnd=False, phbnd=False, broadcast=True, comm=<elphmod.MPI.Communicator object>)

Calculate electron-phonon coupling for arbitary points k and k + q.

Parameters:

q1, q2, q2float, default 0.0

q point in crystal coordinates with period \(2 \pi\).

k1, k2, k3float, default 0.0

Ingoing k point in crystal coordinates with period \(2 \pi\).

elbndbool

Transform to electronic band basis? Provided for convenience. Since the Hamiltonian is diagonalized on the fly for each requested matrix element, this option lacks efficiency and control of complex phases. Consider the method sample of this class instead.

phbndbool

Transform to phononic band basis? Provided for convenience. Since the dynamical matrix is diagonalized on the fly for each requested matrix element, this option lacks efficiency and control of complex phases. Consider the method sample of this class instead.

broadcastbool

Broadcast result to all processors? If False, returns None on all but the first processor.

commMPI.Intracomm

Group of processors running this function (for parallelization of Fourier transforms). Please note: To run this function serially, e.g., when parallelizing over q or k points, use elphmod.MPI.I.

Returns:

ndarray

Fourier transform of data, possibly plus a long-range term and transformed into the band basis.

gR(Rq1=0, Rq2=0, Rq3=0, Rk1=0, Rk2=0, Rk3=0)

Get electron-phonon matrix elements for arbitrary lattice vectors.

Parameters:

Rq1, Rq2, Rq3, Rk1, Rk2, Rk3int, default 0

Lattice vectors in units of primitive vectors.

Returns:

ndarray

Element of data or zero.

g_lr(q1=0, q2=0, q3=0)

Calculate long-range part of electron-phonon coupling.

sample(*args, **kwargs)

Sample coupling.

See also

sample

sample_orig(shared_memory=True)

Sample coupling on original q and k meshes.

standardize(eps=0.0, symmetrize=False)

Standardize real-space coupling data.

• Keep only nonzero coupling matrices.

• Sum over repeated lattice vectors.

• Sort lattice vectors.

• Optionally symmetrize coupling:

\[g_{\vec q, \vec k} = g_{-\vec q, \vec k + \vec q}^\dagger, g_{\vec R, \vec R'} = g_{\vec R - \vec R', -\vec R'}^\dagger\]

Parameters:

epsfloat

Threshold for “nonzero” matrix elements in units of the maximum matrix element.

symmetrizebool

Symmetrize coupling?

supercell(N1=1, N2=1, N3=1, shared_memory=False, sparse=False)

Map localized model for electron-phonon coupling onto supercell.

Parameters:

N1, N2, N3tuple of int or int, default 1

Supercell lattice vectors in units of primitive lattice vectors.

shared_memorybool, default False

Store mapped coupling in shared memory?

sparsebool, default False

Only calculate q = k = 0 coupling as a list of sparse matrices to save memory? The result, which is assumed to be real, is stored in the attribute gs. Consider using standardize() with nonzero eps and symmetrize before.

Returns:

object

Localized model for electron-phonon coupling for supercell.

See also

elphmod.bravais.supercell

symmetrize()

Symmetrize electron-phonon coupling.

to_epmatwp(prefix)

Save coupling to .epmatwp and .wigner files.

If divide_ndegen, the division by the degeneracies of the Wigner-Seitz points is not undone before writing the .epmatwp file. Instead, all degeneracies in the .wiger file are set to one.

Parameters:

prefixstr

Filename stem.

update_short_range(shared_memory=True)

Update short-range part of real-space coupling.

elphmod.elph.coupling(filename, nQ, nmodes, nk, bands, Q=None, nq=None, offset=0, completion=True, complete_k=False, squeeze=False, status=False, phase=False)

Read and complete electron-phonon matrix elements.

elphmod.elph.ph2epw(fildyn='dyn', outdir='work', dvscf_dir='save')

Convert PHonon output to EPW input.

Based on script pp.py provided with EPW code (C) 2015 Samuel Ponce.

All arguments can be overwritten by environment variables of the same name.

Parameters:

dynstr

Prefix of dynamical-matrix files.

outdirstr

QE output directory.

dvscf_dirstr

EPW input directory.

elphmod.elph.q2r(elph, nq, nk, g, r=None, divide_mass=True, shared_memory=False)

Fourier-transform electron-phonon coupling from reciprocal to real space.

Parameters:

elphModel

Localized model for electron-phonon coupling.

nq, nktuple of int

Number of q and k points along axes, i.e., shapes of uniform meshes.

gndarray

Electron-phonon coupling on complete uniform q- and k-point meshes.

rndarray, optional

Positions of orbital centers. If given, the Wigner-Seitz lattice vectors are determined again, whereby the distances to the displaced atom and the initial orbital are are both measured from the final orbital in the unit cell at the origin (first orbital index). This argument is required when changing nq or nk.

divide_massbool, default True

Has input coupling been divided by square root of atomic mass? This is independent of elph.divide_mass, which is always respected.

shared_memorybool, default False

Store real-space coupling in shared memory?

elphmod.elph.read_EPW_output(epw_out, q, nq, nmodes, nk, bands=1, eps=0.0001, squeeze=False, status=False, epf=False, defpot=False)

Read electron-phonon coupling from EPW output file (using prtgkk).

Currently, the coupling must be defined on a uniform 2D k mesh (corresponding to triangular or square lattice).

Parameters:

epw_outstr

Name of EPW output file.

qlist of int

List of q points as integer recriprocal lattice units.

nqint

Number of q points per dimension.

nmodesint

Number of phonon modes.

nkint

Number of k points per dimension.

bandsint

Number of electronic bands.

epsfloat

Tolerance for q and k points.

squeezebool

In single-band case, skip dimensions of output arrary corresponding to electronic bands?

statusbool

Report currently processed q point?

epfbool

Read real and imaginary part of the coupling of dimension energy to the power of 2/3 from last two columns? A modified version of EPW is needed. Otherwise, the modulus of the coupling of dimension energy is read.

defpotbool

Multiply coupling by square root of twice the phonon energy to obtain a quantity of dimension energy to the power of 2/3?

elphmod.elph.read_L(epw_out)

Read range-separation parameter from EPW output

Parameters:

epw_outstr

Name of EPW output file.

Returns:

float

Range-separation parameter if found, None otherwise.

elphmod.elph.read_data(filename)

Read array from ASCII file.

elphmod.elph.read_patterns(filename, q, nrep, status=True)

Read XML files with displacement patterns from QE.

elphmod.elph.read_prtgkk(epw_out, nq, nmodes, nk, nbnd)

Read frequencies and coupling from EPW output (using prtgkk).

Parameters:

epw_outstr

Name of EPW output file.

nqint

Number of q points.

nmodesint

Number of phonon modes.

nkint

Number of k points.

nbndint

Number of electronic bands.

Returns:

ndarray

Phonon frequencies (meV).

ndarray

Electron-phonon coupling (meV).

elphmod.elph.read_xml_files(filename, q, rep, bands, nbands, nk, squeeze=True, status=True, angle=120, angle0=0, old=False)

Read XML files with coupling in displacement basis from QE (nosym).

elphmod.elph.sample(g, q, nk=None, U=None, u=None, squared=False, broadcast=True, shared_memory=False)

Sample coupling for given q and k points and transform to band basis.

One purpose of this routine is full control of the complex phase.

Parameters:

gfunction

Electron-phonon coupling in the basis of electronic orbitals and Cartesian ionic displacements as a function of q and k in crystal coordinates with period \(2 \pi\).

qlist of tuple

List of q points in crystal coordinates \(q_i \in [0, 2 \pi)\).

nkint or tuple of int

Number of k points per dimension, i.e., size of uniform mesh. Different numbers of k points along different axes can be specified via a tuple. Alternatively, nk is inferred from the shape of U.

Undarray, optional

Electron eigenvectors for given k mesh. If present, transform from orbital to band basis.

undarray, optional

Phonon eigenvectors for given q points. If present, transform from displacement to band basis.

squaredbool

Sample squared complex modulus instead? This is more memory-efficient than sampling the complex coupling and taking the squared modulus later.

broadcastbool

Broadcast result from rank 0 to all processes?

shared_memorybool, optional

Store transformed coupling in shared memory?

elphmod.elph.transform(g, q, nk, U=None, u=None, squared=False, broadcast=True, shared_memory=False)

Transform q- and k-dependent coupling to band basis.

See also

sample

elphmod.elph.write_data(filename, data)

Write array to ASCII file.

elphmod.elph.write_xml_files(filename, data, angle=120, angle0=0)

Write XML files with coupling in displacement basis.