Documentation#

EPWpy Logo

Overview#

EPWpy is an open-source Python library designed to wrap and automate workflows based on EPW (Quantum ESPRESSO + Wannier90). It provides Python objects and methods that streamline

  • DFT preparation,

  • phonon calculations,

  • Wannierisation,

  • EPW electron–phonon workflows,

  • post-processing, and

  • visualization tools.

Key Features#

  • Automated workflows: SCF, phonons, Wannierisation, EPW

  • Built-in plotting and visualization utilities

  • Example notebooks covering:

    • carrier mobility

    • polarons

    • optical absorption

    • superconductivity

    • temperature-dependent properties

  • Designed for automation and reproducibility of complex electron–phonon workflows

Installation#

Install from PyPI:

pip install epwpy-basic

Install the latest development version:

git clone https://gitlab.com/epwpy/epwpy.git
cd epwpy
python setup.py install

Install with Quantum ESPRESSO + EPW compilation:

git clone https://gitlab.com/epwpy/epwpy.git
cd epwpy
python setup.py install --withQE True --configs 'with-scalapack=intel' --cores 32 --version 6.0

Quick Start – Running Examples#

Example 1: Total energy calculation (Silicon)#

Adapted from the optical absorption tutorial.

import numpy as np
import matplotlib.pyplot as plt
from EPWpy import EPWpy as EP
from EPWpy.plotting import plot_bands

silicon = EP.EPWpy({
    'prefix': 'si',
    'calculation': '\'scf\'',
    'ibrav': 2,
    'nat': 2,
    'ntyp': 1,
    'atomic_species': ['Si'],
    'mass': [28.0855],
    'atoms': ['Si','Si'],
    'ecutwfc': '40',
    'celldm(1)': '10.262',
    'pseudo_auto': True
}, env='mpirun')

silicon.scf(name='scf', kpoints={'kpoints': [[6,6,6]]})
silicon.prepare(type_run='scf')
silicon.run(cores=4, type_run='scf')

silicon.pw_util = silicon.PW_utilities()
print('total energy in Ry: ', silicon.pw_util.total_energy)

Example 2: Phonon dispersion (Silicon)#

Adapted from the phonon-limited mobility tutorial.

import numpy as np
import matplotlib.pyplot as plt
from EPWpy import EPWpy as EP
from EPWpy.QE.band_util import BandUtil

silicon = EP.EPWpy({
    'prefix': 'si',
    'calculation': '\'scf\'',
    'structure_mp': 'mp-149',
    'pseudo_auto': True
}, env='mpirun')

silicon.run_serial = True

print('Pseudopotential:', silicon.pw_atomic_species['pseudo'][0])
print('Prefix:', silicon.prefix)

silicon.scf(name='scf', kpoints={'kpoints': [[6,6,6]]})
silicon.prepare(type_run='scf')
silicon.run(cores=4, type_run='scf')

silicon.ph(name='ph', {'nq1':6, 'nq2':6, 'nq3':6})
silicon.prepare(type_run='scf')
silicon.run(cores=4, type_run='ph')

silicon.q2r(name='q2r')
silicon.prepare(type_run='q2r')
silicon.run(1, type_run='q2r')

silicon.matdyn(
    name='matdyn',
    kpoints={'kpoints': [
                ['0.5','0.5','0.5','20'],  # L
                ['0.0','0.0','0.0','20'],  # Γ
                ['0.5','0.5','0.0','20']   # X
            ],
            'kpoints_type': '{crystal_b}'
    }
)

silicon.prepare(type_run='matdyn')
silicon.run(1, type_run='matdyn')

bnd_util = BandUtil(system='si', prefix='si')
bnd_util.plot_phonon_QE(xticks=['L', '$\\Gamma$', 'X'])

Tutorials#

Additional notebooks and guides are available at:

Examples include:

  • Calculation of transport coefficients

  • Optical absorption

  • Calculation of polarons

  • Temperature-dependent properties (ZG method)

  • Anisotropic superconductivity workflows

License#

EPWpy is licensed under the 3-Clause BSD License.

Cite EPWpy#

If you use EPWpy in your research, please cite:

Tiwari, S.,....., Giustino, F., et al. EPWpy: Automated Python Workflows for Electron–Phonon Coupling (2025).

API Reference#

For full function-by-function documentation and module-level detail, see the API Reference page.