.. GitLab Pages with Sphinx documentation master file, created by
   sphinx-quickstart on Thu Jan  9 10:28:38 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

=====================================================================
EPWpy: A High-Level Python Interface for Electron–Phonon Calculations
=====================================================================

.. 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>



.. raw:: html

   <div style="text-align:center;">
       <a href="https://mybinder.org/v2/gl/epwpy%2Fepwpy_binder_image/main?urlpath=%2Fdoc%2Ftree%2Ftransport.ipynb"
          style="padding: 8px 16px; border-radius: 8px; background:#1f77b4; color:white; text-decoration:none; font-weight:bold; font-size:16px;">
          🚀 Launch EPWpy Demo on Binder
       </a>
   </div>

.. raw:: html

   <div style="height:20px;"></div>

EPWpy is a lightweight Python framework that simplifies running
**electron–phonon**, **transport**, and **spectral** simulations powered by
Quantum ESPRESSO + EPW. It provides a high-level, user-friendly interface to
automate workflows, manage inputs, generate efficient computational
pipelines, and analyze results. All without requiring complex shell scripting.

Whether you are a researcher building high-throughput pipelines or a student
exploring electron–phonon interactions for the first time, EPWpy makes the
workflow intuitive, reproducible, and portable.

----------------
Key Capabilities
----------------

- 🔧 **Seamless EPW Workflow Automation**
  Automate SCF, NSCF, Wannierization, electron–phonon calculations, and many-body physical observable calculations (e.g., optical absorption and trnasport coefficients).

- 📦 **Integrated Quantum ESPRESSO Build System**
  Automatically builds QE + EPW through setuptools (no manual compilation needed).

- 📈 **Interactive Analysis Tools**
  Built-in post-processing utilities for interpolated bandstructures, phonons,
  linewidths, mobility calculations, and more.

.. - 🧊 **2D Materials Ready**
..  Designed and tested extensively for large-scale 2D materials transport simulations.

- 🚀 **Cloud-Ready**
  Works on Binder, HPC clusters, Google Colab, and local development environments.

- 🧩 **Extensible**
  Clean Python API for building reproducible workflows and custom analysis modules.

- 🔥 **Full Data Provenance Tracking**  
    EPWpy maintains *complete, reproducible provenance* across complex workflows
    including file hashes, inputs, outputs, configuration snapshots, and automated workflow DAGs.


---------------------
Quick Start (Terminal)
---------------------

Install directly:

.. code-block:: bash

   pip install epwpy-basic

To build Quantum ESPRESSO + EPW with EPWpy:

.. code-block:: bash

   python setup.py install --withQE True --cores 8 --config "with-scalapack=no"

This automatically downloads, configures, and compiles a compatible
Quantum ESPRESSO + EPW stack inside your environment.

---------------------------
Launch the Online Demo (📦)
---------------------------

Try EPWpy instantly in your browser — no installation required:

.. image:: https://mybinder.org/badge_logo.svg
   :target: https://mybinder.org/v2/gl/epwpy%2Fepwpy_binder_image/main?urlpath=%2Fdoc%2Ftree%2Ftransport.ipynb
   :align: center
   :alt: Launch EPWpy Binder

This Binder environment includes:

- a precompiled Quantum ESPRESSO + EPW build  
- example notebooks  
- the **transport.ipynb** demonstration notebook  
- ready-to-run workflows using EPWpy  

----------------
Project Links 🔗
----------------

- **Source Code:** https://gitlab.com/epwpy/epwpy  
- **Binder Demo:** https://mybinder.org/v2/gl/epwpy/epwpy_binder_image/main  
- **Issues / Bug Reports:** https://gitlab.com/epwpy/epwpy/-/issues  
- **EPW Documentation:** https://epw-code.org  
- **Quantum ESPRESSO:** https://quantum-espresso.org  

------------------
Citing This Project
------------------

If you use EPWpy in your research, please cite the project:

The most recent reference technical manuscript is:
`S. Tiwari, B. Cucco, M. Zacharias, J-L. Bartolome, S. Mishra, W. Yang, V-A. Ha, S. Ponce, E. Kioupakis, R. Margine, and F. Giustino,  Unpublished (2024) <https://www.nature.com/articles/s41524-023-01107-3>`_ 

.. .. figure:: /doc/images/ezgif-2-5cdc179f5b.gif
..   :width: 1200px

.. \\\**A
.. `H. Lee, S. Poncé, K. Bushick, S. Hajinazar, J. Lafuente-Bartolome, J. Leveillee, C. Lian, J.-M. Lihm, F.
.. Macheda, H. Mori, H. Paudyal, W. H. Sio, S. Tiwari, M. Zacharias, X. Zhang, N. Bonini, E. Kioupakis, E. R.
.. Margine, and F. Giustino, “Electron–phonon physics from first principles using the EPW code”, npj Comput.
.. Mater. 9, 156 (2023) <https://doi.org/10.1038/s41524-023-01107-3>`_.


.. toctree::
   :maxdepth: 2
   :caption: PROJECT
   :hidden:

   doc/About
   doc/Releases
   doc/Documentation2
   doc/HandsOn
   doc/Schools
   doc/Acknowledgement
   doc/Contact
..   doc/Tools
 

.. toctree::
   :maxdepth: 2
   :caption: NOTEBOOKS:
   :hidden:

   doc/notebooks/transport-v1.2 
   doc/notebooks/polaron_v1.2
   doc/notebooks/optics_v1.1
   doc/notebooks/quadrupole
   doc/notebooks/zg
   doc/notebooks/supercond_aniso_v1.2
   doc/notebooks/supercond_iso_v1.2
   doc/notebooks/zg_anharmonicity_PbTe
   doc/notebooks/phasediagram

.. toctree::
   :maxdepth: 5
   :caption: SOURCE CODE
   :hidden:

   doc/DownloadAndInstall
   GitLab <https://gitlab.com/epwpy/epwpy>
   doc/api/modules    
..
.. toctree::
   :maxdepth: 1
   :caption: DEVELOPERS
   :hidden:

.. doc/DevelopersMeetings
..   doc/SteeringCommitteeMeetings
..   doc/WebsiteMaintenance