Tutorials

Run QEpy as QE (command line)

QEpy can replace standard QE executables. List supported packages:

python -m qepy -h

Options ending in .x mirror QE executables; options ending in .py are QEpy-specific tools.

python -m qepy --pw.x -i qe.in

mpirun -n 4 python -m qepy --pw.x -i qe.in

QEpy-specific example: analyze and convert pw.x output:

python -m qepy --pw2pp.py -h

Use QEpy in Python code

The Driver class is the main entry point. Import qepy before mpi4py to avoid FFT allocation errors (see FAQ).

Serial execution

Pass comm=None (default) for a single-process run:

import qepy
from qepy import Driver

driver = Driver('si.scf.in', comm=None)
driver.scf()
energy = driver.get_energy()
driver.stop()

Parallel execution with mpi4py

Pass an MPI communicator so Python and Fortran share the same process layout. Only rank 0 (driver.is_root) should print or write files unless you gather data explicitly.

import qepy
from mpi4py import MPI
from qepy import Driver

comm = MPI.COMM_WORLD
driver = Driver('si.scf.in', comm=comm)

if driver.is_root:
    print(f"Running on {driver.nproc} MPI ranks")

driver.scf()
if driver.is_root:
    print("Total energy:", driver.get_energy())
driver.stop()

Launch with your MPI runner, e.g.:

# OpenMPI / Intel MPI
mpirun -n 4 python my_script.py

# SLURM (example)
srun --mpi=pmi2 -n 4 python my_script.py

Iterative SCF (step-by-step control)

Set iterative=True to run one SCF iteration at a time: useful for custom mixing, external potentials, or coupling to other models.

driver = Driver('si.scf.in', iterative=True, comm=comm)

while not driver.check_convergence():
    driver.diagonalize()
    driver.mix()
    rho = driver.get_density()
    # inspect or modify rho, set external potentials, etc.

driver.end_scf()
driver.stop()

External potentials & custom XC

# Add an external potential on the real-space grid (Ry units)
v_ext = driver.create_array(kind='rho')
# ... fill v_ext ...
driver.set_external_potential(v_ext)

# Swap XC functional (requires DFTpy integration)
driver.update_exchange_correlation(xc='PBE')

ASE calculator

from ase.build import bulk
from qepy.calculator import QEpyCalculator

atoms = bulk('Si')
calc = QEpyCalculator(inputfile='si.scf.in', comm=comm)
atoms.calc = calc
energy = atoms.get_potential_energy()

Note: ASE uses Å and eV; the Driver uses Bohr and Rydberg. The calculator handles unit conversion.

Jupyter notebooks

Interactive examples live in the QEpy repository under examples/jupyter/. Clone the repo and open them locally, or try the Google Colab notebooks. Notebooks marked with 👉 in the Beginners column are good starting points.

Video tutorials

QEpy YouTube playlist ↗

For the full Python API, see The code.