EPWpy.EPWpy#

Classes

EPWpy([type_input, system, code, env, ...])

The central interface class of the EPWpy framework.
class EPWpy.EPWpy.EPWpy(type_input=None, system='si', code=None, env='mpirun', QE_ver=7.4, EPW_ver=5.9)[source]#

Bases: SetDefaultVals, FlowManager, PyBGW, PyQE, PyAnalysis, JobStatus, Lattice

The central interface class of the EPWpy framework.

EPWpy provides a unified Python interface for ab initio electronic-structure and many-body codes, including Quantum ESPRESSO (QE), EPW, and BerkeleyGW (BGW). It automates input preparation, execution, and output parsing, enabling scalable workflows for electron–phonon and many-body physics simulations.

This class can be initialized directly to set up and run complete workflows, or used as a base for higher-level automated pipelines.

Collaborating Institutions#

  • The University of Texas at Austin (Prof. Feliciano Giustino)

  • Binghamton University (Prof. Roxana Margine)

  • University of Michigan (Prof. Emmanouil Kioupakis)

  • Université Catholique de Louvain (Prof. Samuel Poncé)

Output Structure#

All simulation results and parameters are stored internally in dictionaries. These can be accessed via the respective attributes of QE, PH, EPW, or BGW modules. Example:

>>> self.pw_atomic_species["atomic_species"]

Common dictionary attributes include: - pw_system: system inputs and outputs - pw_control: control inputs and outputs - pw_electrons: electron-related inputs and outputs - pw_ions: ion dynamics inputs/outputs (enabled if iondynamics=True) - pw_cell: cell dynamics inputs/outputs (enabled if celldynamics=True) - pw_atomic_positions: atomic positions - pw_atomic_species: atomic species, pseudopotentials, and masses - pw_cell_parameters: lattice vectors - pw_bands: band-structure inputs and outputs - ph_params: PHonon code parameters - epw_params: EPW parameters - wannier_params: Wannierization parameters - pw2wann_params: pw2wannier90 parameters - BGW_*: various BerkeleyGW stages (init, epsilon, sigma, kernel, etc.) - zg_params, q2r_params, eps_inputpp: miscellaneous utilities

Inherited Classes#

  • PyBGW: Interface to the BerkeleyGW package

  • PyQE: Interface to Quantum ESPRESSO

  • PyAnalysis: Property extraction and analysis utilities

  • JobStatus: Status tracking for running jobs

  • Lattice: Lattice construction and pseudopotential management

  • SetDefaultVals: Handles default initialization values

Composed Classes#

  • PyRun: Executes individual simulations (PW, PH, EPW, BGW)

  • PyPrepare: Prepares inputs and manages calculation setup

type type_input:

dict, optional

type system:

str

param system:

Folder name or system identifier for the current calculation.

type system:

str, default="si"

type code:

Optional[str]

param code:

Path to the executable code (QE, EPW, or BGW). If None, the code path is determined from the global cd_loc.code_set variable.

type code:

str, optional

type env:

str

param env:

Environment launcher for parallel execution. Typical values include: "mpirun", "srun", or "ibrun".

type env:

str, default="mpirun"

param ---------------------------------------------------------------------------:

Run#

Manages execution of QE, PH, EPW, or BGW binaries.

Type:

PyRun

Prepare#

Handles creation of input files and directory setup.

Type:

PyPrepare

verbosity#

Level of console output verbosity.

Type:

int

state#

Internal EPWpy state dictionary containing runtime parameters.

Type:

dict

writer#

Writer utility for generating formatted input files.

Type:

object

transfer_file#

Files to be transferred across stages.

Type:

list

dont_do#

Steps to skip in automated flows.

Type:

list

run_serial#

Whether to enforce serial execution mode.

Type:

bool

Whether to create symbolic links between run directories.

Type:

bool

---------------------------------------------------------------------------

Example

>>> from epwpy import EPWpy
>>> epw = EPWpy(system="graphene", env="ibrun", code="/path/to/pw.x")
>>> epw.Run    # Access the run manager
<PyRun object>
>>> epw.Prepare  # Prepare input files
<PyPrepare object>

Print EPWpy logo

classmethod load_EPWpy(filename)[source]#
new_system_reset(type_input=None, system='si', code=None, env='mpirun')[source]#

The EPWpy is a utility that wraps EPW

prepare(procs=1, type_run='scf', name=None, infile=None, transfer_file=[])[source]#

Prepare the environment, input files, and working directories for a specific EPWpy calculation stage.

This method configures a new calculation (e.g., SCF, NSCF, PH, EPW, BGW) by creating appropriate directories, linking pseudopotentials, assigning input/output file names, and storing the state for subsequent execution.

Parameters:

  • procs (int, optional) -- Number of processors to allocate for the run. Default is 1.

  • type_run (str, optional) -- Type of calculation to prepare. Common options include: - "scf" : self-consistent field run - "nscf" : non-self-consistent run - "ph" : phonon calculation - "epw" : electron–phonon coupling run - "gw" : BerkeleyGW run Default is "scf".

  • name (str, optional) -- Custom name for the run folder. If not provided, defaults to type_run.

  • infile (str, optional) -- Name of the input file to be prepared. Defaults to "{type_run}.in".

  • transfer_file (list of str, optional) -- List of additional files to copy or link into the run directory. These may include previously generated wavefunctions, dynamical matrices, or intermediate outputs.

Returns:

The method updates the internal EPWpy state and sets up a PyPrepare object (self.prep) to handle input generation.

Return type:

None

Notes

  • The method automatically initializes a PyPrepare instance and assigns it to self.prep.

  • Internal state is serialized to JSON using _save_json().

  • Working directories and filenames are configured via helper methods: set_folds(), set_files(), set_work(), and set_home().

  • Files listed in transfer_file are added to self.transfer_file for future use in multi-stage workflows.

Example

>>> epw = EPWpy(system="graphene", code="/path/to/pw.x")
>>> epw.prepare(type_run="nscf", procs=8)
>>> print(epw.prep.writer)
<InputWriter object for nscf run>
run(procs, type_run=None, infile=None, name=None, parallelization=None, flow_parallelization=None, flow_procs=None, flavor='cplx', util=None)[source]#

Execute a specific EPWpy workflow stage such as QE, PH, EPW, or BGW.

This method serves as the unified run interface for all EPWpy-supported codes, launching the appropriate binary (via PyRun) with user-defined parallel settings, environment, and input files. It can be invoked after prepare() or independently once inputs are in place.

Parameters:

  • procs (int) -- Number of processors to use for the execution.

  • type_run (str, optional) -- Type of calculation to execute. Common values include: - "scf" : self-consistent DFT calculation (pw.x) - "nscf" : non-self-consistent DFT calculation - "ph" : phonon calculation (ph.x) - "epw" : electron–phonon coupling calculation (epw.x) - "bgw" : BerkeleyGW execution Default is "scf".

  • infile (str, optional) -- Input file name to be used. Defaults to "{type_run}.in" if not provided.

  • name (str, optional) -- Label or directory name for this run. Defaults to type_run.

  • parallelization (dict, optional) -- Dictionary specifying explicit parallelization flags (e.g. {"npool": 4, "ndiag": 2}).

  • flow_parallelization (dict, optional) -- Parallelization scheme for distributed or multi-step workflows.

  • flow_procs (int, optional) -- Total number of processors assigned across a workflow stage.

  • flavor (str, optional) -- Computational flavor of the code to be executed. Default is "cplx" (complex version). Other possible values include "real" or code-specific tags for EPW or BGW variants.

  • util (str, optional) -- Utility or executable to be run manually (e.g. "bands.x", "dos.x", "epsilon.x"). Overrides type_run if specified.

Returns:

The method triggers execution of the selected binary and monitors job completion status.

Return type:

None

Notes

  • Automatically invokes PyRun with the current environment (mpirun, ibrun, srun).

  • Can be used in conjunction with prepare() to first set up and then execute runs in an automated workflow.

  • Parallelization flags are translated into command-line arguments for the target code.

  • Job progress and results are tracked through JobStatus.

Example

>>> epw = EPWpy(system="graphene", env="ibrun", code="/path/to/pw.x")
>>> epw.prepare(type_run="scf")
>>> epw.run(procs=8, type_run="scf")

To run an EPW calculation after SCF: >>> epw.run(procs=16, type_run="epw", infile="epw.in")

save_EPWpy(filename=None)[source]#