Documentation
========================================================================


.. raw:: html

   <p align="center">
     <img src="https://epwpy.org/_static/epwpy_logo_v3.png" alt="EPWpy Logo" width="250">
   </p>

.. raw:: html

   <p>
   <a href="https://pypi.org/project/EPWpy-basic/">
       <img src="https://img.shields.io/pypi/v/EPWpy-basic.svg">
   </a>
   <a href="https://gitlab.com/epwpy/epwpy/-/pipelines">
       <img src="https://gitlab.com/epwpy/epwpy/badges/develop/pipeline.svg">
   </a>
   <a href="https://opensource.org/licenses/BSD-3-Clause">
       <img src="https://img.shields.io/badge/License-BSD_3--Clause-blue.svg">
   </a>
   </p>

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:

.. code-block:: bash

    pip install epwpy-basic

Install the latest development version:

.. code-block:: bash

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

Install with Quantum ESPRESSO + EPW compilation:

.. code-block:: bash

    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.

.. code-block:: python

    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.

.. code-block:: python

    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:

* `Transport Notebook (v1.2) <https://epwpy.oden.utexas.edu/doc/notebooks/transport-v1.2.html>`_.. 

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 :doc:`API Reference <modules>` page.