Quantum ESPRESSO Hands-on Tutorial (Graphene) | Suecreamm

Building Quantum ESPRESSO and Submitting Jobs

Fri, 11 Apr 2025 00:00:00 +0000

Below is a brief overview of the basic steps required to install Quantum ESPRESSO (QE) and run calculations on a computing cluster.

Download the source code

Download the desired version of the QE source code from the official Quantum ESPRESSO website (quantum-espresso.org) or its GitHub repository. You can also download it directly using commands such as wget or git.

Build QE

Move to the downloaded source directory and run the following commands to configure and compile QE. Depending on your system, you may need to specify compilers, library paths, or optimization options during the ./configure step.

./configure
make all

Submit a calculation to a cluster

First prepare a QE input file (.in), then submit the calculation through the job scheduler used by your cluster, such as SLURM or PBS.

For example, on a SLURM system, a job can be submitted using:

sbatch job_script.sh

The job script typically contains an MPI command such as:

mpirun -np 16 pw.x -in input.in > output.out

1. Downloading and Building Quantum ESPRESSO

First, download the latest or desired version of QE from the official Quantum ESPRESSO website or its GitHub repository.

In this tutorial, I assume that all work starts from the /home/hwang/ directory.

On Linux systems, a home directory is the personal working directory assigned to each user. It usually follows the form /home/username. Since the username used in this example is hwang, /home/hwang/ will be used as the home directory throughout this tutorial.

1.1 Check the current directory (`pwd`)

After logging into a cluster, you will usually start in your home directory. For this tutorial, I will assume that the directory is initially empty.

You can check your current location using:

pwd

Since this tutorial is also intended for users who are relatively new to Linux:

pwd (print working directory) displays the full path of your current directory.

Expected output:

/home/hwang

1.2 Download the source code (`wget` or `git`)

If your current directory is /home/hwang, you can download QE using either wget or git.

This tutorial uses the QE 7.4.1 source archive downloaded with wget:

wget https://gitlab.com/QEF/q-e/-/archive/qe-7.4.1/q-e-qe-7.4.1.tar.gz
ls

Expected output:

q-e-qe-7.4.1.tar.gz

Alternatively, you can clone the GitHub repository:

git clone https://github.com/QEF/q-e.git
ls

Expected output:

q-e

Some useful Linux commands:

wget: Downloads files from the internet.
git clone: Creates a local copy of a Git repository.
ls (list): Displays files and directories in the current directory. It is similar to dir on Windows.

1.3 Extract the archive and enter the directory

The downloaded file is a .tar.gz archive, so it must first be extracted:

tar -xvf q-e-qe-7.4.1.tar.gz

tar -xvf: Extracts the archive.
- x: extract
- v: verbose
- f: file

After extraction, move into the newly created directory:

cd q-e-qe-7.4.1

cd (change directory) moves into another directory.

The command itself does not print anything, but your current directory should now be:

/home/hwang/q-e-qe-7.4.1

1.4 Configure and build QE (`./configure` and `make`)

Standard desktop environment

Before compiling QE, the build system must first be configured for your machine.

For a standard Linux or WSL environment where you are not specifically configuring parallel computing libraries, you can usually start with:

./configure

./configure: Detects the available compilers and libraries and prepares the build configuration.

Additional options can be specified when necessary, for example to configure MPI support or external libraries.

Systems with parallel computing libraries, such as Intel MKL

One of the reasons I originally wrote this note was to keep a record of the configuration options I used for an Intel-based HPC environment.

An example configuration is:

./configure \
 MPIF90=mpiifort F90=ifort CC=icc \
 --prefix=/usr/local \
 --with-scalapack='-lmkl_scalapack_lp64 -lmkl_blacs_intelmpi_lp64' \
 --with-blas='-lmkl_intel_lp64 -lmkl_sequential -lmkl_core' \
 --enable-openmp

The exact configuration depends on the compilers, MPI implementation, and mathematical libraries available on your system. If you are using a university or institutional cluster, it is usually best to check its documentation or available environment modules first.

What do Intel MKL and HPC have to do with DFT calculations?

Density functional theory (DFT) codes such as VASP and Quantum ESPRESSO perform electronic-structure calculations that involve computationally expensive operations, including large matrix operations, diagonalization, and fast Fourier transforms (FFTs).

Intel MKL: Intel Math Kernel Library provides optimized implementations of numerical libraries such as BLAS, LAPACK, and FFT routines. These libraries can significantly improve the performance of operations that frequently appear in DFT calculations.
HPC: DFT calculations can become computationally demanding as the number of atoms, k-points, bands, or other numerical parameters increases. High-performance computing (HPC) clusters allow calculations to be distributed across many CPU cores or multiple nodes using parallelization frameworks such as MPI and OpenMP.
Why are they useful? Optimized numerical libraries improve the performance of mathematical operations, while HPC resources make it possible to distribute larger workloads across multiple processors. Together, they can substantially reduce the time required for large electronic-structure calculations.

HPC is also widely used outside electronic-structure calculations, including weather forecasting, fluid dynamics, molecular simulations, and machine learning.

1.5 Verify the build

If all required dependencies are available and the configuration succeeds without errors, the ./configure step should generate a make.inc file.

Next, compile QE using:

make all

If the build completes successfully, check whether a bin/ directory has been created inside the QE directory.

It should contain executables such as:

pw.x
ph.x
pp.x
...

Among these, pw.x is one of the main executables used for Quantum ESPRESSO calculations.

Once the required executables have been successfully built, QE is ready to run calculations.

2. Preparing and Submitting a Calculation

To perform an actual QE calculation on a cluster, you need two main things:

A QE input file
A job script for the cluster scheduler

2.1 Prepare an input file

QE includes example and benchmark input files in its test-suite directory.

For this example, I will use:

/home/hwang/q-e-qe-7.4.1/test-suite/benchmarks/pw/ausurf.in

You can also use another appropriate input file from the test-suite directory.

First, create a directory for the calculation if necessary:

mkdir qe-test
cd qe-test

Then copy the example input file into the current directory:

cp /home/hwang/q-e-qe-7.4.1/test-suite/benchmarks/pw/ausurf.in .

cp (copy) copies a file.
. represents the current directory.

A QE .in file contains the information required to define the physical system and the type of calculation you want to perform.

In other words, this is where you specify the problem that QE will solve.

2.2 Create a job script

Calculations on HPC clusters are generally submitted through a job scheduler.

Common schedulers include:

SLURM
PBS
LSF

The exact job script depends on the cluster you are using. If your university or institution provides a computing cluster, follow its documentation for resource allocation, modules, and MPI commands.

Here, I will use SLURM as an example.

Create a file called job_script.sh:

vi job_script.sh

Then add something similar to the following:

#!/bin/bash
#SBATCH --job-name=qe_ausurf
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=16
#SBATCH --time=01:00:00

module load mpi

mpirun -np 16 /home/hwang/q-e-qe-7.4.1/bin/pw.x -in ausurf.in > ausurf.out

A few important lines are:

#!/bin/bash: Specifies that the script should be executed using the Bash shell.
#SBATCH --nodes=1: Requests one compute node.
#SBATCH --ntasks-per-node=16: Requests 16 tasks on that node.
#SBATCH --time=01:00:00: Sets a maximum runtime of one hour.

The main execution command is:

mpirun -np 16 /home/hwang/q-e-qe-7.4.1/bin/pw.x -in ausurf.in > ausurf.out

This runs pw.x using 16 MPI processes, reads the calculation settings from ausurf.in, and writes the output to ausurf.out.

The path

/home/hwang/q-e-qe-7.4.1/bin/pw.x

points to the pw.x executable generated when QE was compiled.

The correct MPI command and module configuration depend on the cluster. Some systems use srun instead of mpirun, so always check the documentation for your HPC environment.

2.3 Submit the job

Submit the job script to SLURM using:

sbatch job_script.sh

Once submitted, the scheduler will allocate the requested resources and start the calculation when those resources become available.

You can check your current jobs using:

squeue -u $USER

sbatch: Submits a job script to SLURM.
squeue -u $USER: Displays jobs submitted by the current user.
$USER: Automatically expands to your current username.

When the calculation finishes, the QE output should be stored in:

ausurf.out

2.4 Check the output

To display the output file:

cat ausurf.out

cat: Prints the entire contents of a file to the terminal.

For longer calculations, it is often more useful to monitor the output while the calculation is running:

tail -f ausurf.out

tail -f: Displays the last few lines of a file and continuously updates the terminal whenever new output is written.

Other useful commands include:

less ausurf.out
more ausurf.out

You can also edit or inspect files using editors such as:

nano ausurf.out
vim ausurf.out

The best choice depends on your workflow and personal preference.

If a QE calculation terminates abnormally, a file named CRASH may be created in the working directory. You can check for it using:

ls

The CRASH file and the main QE output file usually provide useful information for debugging.

Errors can arise for many reasons, including incorrectly formatted input files, missing or incorrect pseudopotentials, invalid calculation parameters, insufficient resources, or problems with the software environment.

1. Graphene SCF Calculation

Tue, 01 Sep 2026 00:00:00 +0000

In this example, we perform a self-consistent field (SCF) calculation for graphene using QE.

The SCF calculation determines the ground-state electron density and provides the starting point for later calculations such as band structures and density of states.

Prepare the graphene structure

Define a two-atom graphene unit cell with sufficient vacuum along the $z$-direction.

Prepare the SCF input

Set the plane-wave cutoffs, k-point mesh, pseudopotential, and electronic convergence parameters.

Run the calculation

Execute pw.x locally or submit the calculation to an HPC cluster.

Check convergence

Inspect the output file and confirm that the SCF cycle has converged successfully.

1. Graphene Structure

Graphene is a two-dimensional material consisting of carbon atoms arranged in a honeycomb lattice.

Because QE uses periodic boundary conditions in all three directions, vacuum is added along the $z$-direction to separate periodically repeated graphene layers.

In this example, the graphene unit cell contains two carbon atoms and a cell length of 20 Å along the $z$-direction.

For two-dimensional materials, the vacuum region should be large enough to reduce artificial interactions between periodically repeated layers.

2. SCF Input File

Before running the calculation, prepare the pseudopotential used in the input file.

Pseudopotential

For this tutorial, pseudopotentials can be obtained from PseudoDojo ↗.

Download a pseudopotential appropriate for the exchange-correlation functional and calculation setup you intend to use, then place the file in the directory specified by pseudo_dir.

In this example:

pseudo_dir = 'pseudo/'

so the pseudopotential file should be placed inside the pseudo/ directory.

The pseudopotential, ecutwfc, and ecutrho should be treated as a consistent set. When changing the pseudopotential, check the recommended cutoff values and perform convergence tests for the quantities relevant to your calculation.

Input File

The input file used in this example is available in my GitHub repository:

View 1scf.in on GitHub ↗

&CONTROL
calculation = 'scf'
etot_conv_thr = 2.0000d-05
forc_conv_thr = 1.0000d-04
outdir = './out/'
prefix = 'graphene'
pseudo_dir = 'pseudo/'
tprnfor = .true.
tstress = .true.
verbosity = 'high'
/

&SYSTEM
degauss = 0.01
ecutrho = 200
ecutwfc = 40
ibrav = 0
nat = 2
nosym = .false.
ntyp = 1
occupations = 'smearing'
smearing = 'mv'
/

&ELECTRONS
conv_thr = 4.000d-10
electron_maxstep = 80
mixing_beta = 0.4
/

ATOMIC_SPECIES
C 12.011 C.upf

ATOMIC_POSITIONS angstrom
C 0.0000000000 1.4202816622 0.0000000000
C 1.2300000000 0.7101408311 0.0000000000

K_POINTS automatic
12 12 1 0 0 0

CELL_PARAMETERS angstrom
2.4600000000 0.0000000000 0.0000000000
-1.2300000000 2.1304224933 0.0000000000
0.0000000000 0.0000000000 20.0000000000

The pseudopotential filename shown in ATOMIC_SPECIES must match the actual file stored in pseudo_dir.

3. Understanding the Input

CONTROL

calculation = 'scf'

specifies a self-consistent field calculation.

prefix = 'graphene'
outdir = './out/'
pseudo_dir = 'pseudo/'

prefix defines the common name used for files generated during the calculation.
outdir specifies where temporary calculation data are stored.
pseudo_dir points to the directory containing the pseudopotential files.

tprnfor = .true.
tstress = .true.

These options request the calculation of atomic forces and the stress tensor.

SYSTEM

ibrav = 0

means that the lattice vectors are defined explicitly using CELL_PARAMETERS.

nat = 2
ntyp = 1

The unit cell contains two atoms and one atomic species.

ecutwfc = 40
ecutrho = 200

These parameters define the kinetic-energy cutoffs for the wavefunctions and charge density.

Smearing

occupations = 'smearing'
smearing = 'mv'
degauss = 0.01

This calculation uses Marzari-Vanderbilt smearing with a smearing width of 0.01 Ry.

Why use smearing for graphene?

Graphene is a zero-gap semimetal: the valence and conduction bands meet at the Dirac point.

A small amount of smearing can make Brillouin-zone integration and SCF convergence more stable when electronic states lie very close to the Fermi level.

The smearing width should still be chosen carefully because an unnecessarily large value can broaden electronic features and affect calculated quantities.

Electronic Convergence

conv_thr = 4.000d-10
electron_maxstep = 80
mixing_beta = 0.4

conv_thr controls the convergence threshold of the electronic SCF cycle.
electron_maxstep sets the maximum number of SCF iterations.
mixing_beta controls how strongly the charge density is mixed between iterations.

4. Atomic Structure and Vacuum

The atomic coordinates are defined as:

ATOMIC_POSITIONS angstrom
C 0.0000000000 1.4202816622 0.0000000000
C 1.2300000000 0.7101408311 0.0000000000

The lattice vectors are specified explicitly:

CELL_PARAMETERS angstrom
2.4600000000 0.0000000000 0.0000000000
-1.2300000000 2.1304224933 0.0000000000
0.0000000000 0.0000000000 20.0000000000

The third lattice vector gives a 20 Å cell length along the $z$-direction.

Since graphene lies in the $xy$-plane, most of this length acts as vacuum separating periodic images.

5. K-point Sampling

K_POINTS automatic
12 12 1 0 0 0

A $12 \times 12 \times 1$ k-point mesh is used.

The dense sampling is applied in the two periodic in-plane directions, while only one k-point is used along the vacuum direction.

The k-point mesh should also be tested for convergence.

For graphene and other two-dimensional materials, the important sampling is primarily in the in-plane directions.

6. Run the Calculation

Local execution

For a simple local run, QE can be executed directly from the terminal.

Serial execution

pw.x -in 1scf.in > 1scf.out

Parallel execution using MPI

mpirun -np 16 pw.x -in 1scf.in > 1scf.out

Here, -np 16 launches 16 MPI processes.

HPC job submission

On an HPC cluster, calculations are usually submitted to a job scheduler rather than run directly in the login shell.

For example, on a SLURM-based cluster, I submit my QE calculation with:

sbatch qe_job_submit.sh

The scheduler places the job in a queue and starts it when the requested computational resources become available.

View my qe_job_submit.sh on GitHub ↗

The exact execution command depends on the cluster configuration.

Some systems use mpirun, while others may use srun or another MPI launcher. Resource requests and module settings should follow the documentation of the HPC system you are using.

For a more detailed walkthrough of building QE and submitting jobs on a cluster:

Building Quantum ESPRESSO and Submitting Jobs

QE installation, HPC setup, and SLURM job submission.

7. Check the Output

After the calculation finishes, inspect the output file:

tail -50 1scf.out

A converged SCF calculation should contain:

convergence has been achieved

The final total energy can be found using:

grep "!" 1scf.out

Quantum ESPRESSO marks the final total energy with an exclamation mark (!).

What should I check if the SCF calculation does not converge?

If the calculation does not converge, useful parameters to inspect include:

conv_thr
mixing_beta
electron_maxstep
the k-point mesh
the smearing settings
the pseudopotential and cutoff energies

The output file usually contains the most useful clues for identifying where the calculation failed.

8. What Comes Next?

The converged ground-state electron density can be reused in subsequent electronic-structure calculations.

In the next examples, we will use this graphene calculation to obtain:

the electronic band structure,
the density of states,
and phonon properties.

Graphene Band Structure

Calculate the electronic bands along a high-symmetry path.

2. Graphene Band Structure Calculation

Wed, 02 Sep 2026 00:00:00 +0000

This tutorial continues from the graphene SCF calculation and calculates the electronic band structure along the high-symmetry path $\Gamma \rightarrow M \rightarrow K \rightarrow \Gamma$.

The important point is that the band calculation reuses the converged ground-state data from the previous SCF calculation.

Create a working directory

Make a separate directory for the band-structure calculation and copy the SCF input using a relative path.

Prepare the band input

Reuse the SCF setup, change the calculation type to bands, and define a high-symmetry k-point path.

Run `pw.x`

Calculate the Kohn-Sham eigenvalues along the selected path.

Post-process with `bands.x`

Collect the calculated eigenvalues into a convenient band-data file for plotting.

1. Create a Band-Calculation Directory

Start from the directory where the previous SCF calculation was prepared.

Create a separate directory for the band calculation:

mkdir 99band
cd 99band

Copy the previous SCF input into the new directory using a relative path:

cp ../1scf.in ./99band.1pw.in

Here, .. means the parent directory and . means the current directory.

The copied file will be used as the starting point for the band input, so the lattice, atomic positions, pseudopotential, cutoffs, and other basic settings remain consistent with the SCF calculation.

The band calculation must use the same prefix and the same SCF data stored in outdir.

Because 99band/ is a subdirectory, the relative paths to the SCF output and pseudopotential directories need to be adjusted.

For example:

outdir = '../out/'
pseudo_dir = '../pseudo/'

For the SCF setup used in this tutorial:

Graphene SCF Calculation

Ground-state calculation used as the starting point for the band structure.

The original SCF input is also available on GitHub:

View 1scf.in on GitHub ↗

2. Prepare the Band Input

Open the copied file:

vi 99band.1pw.in

The main changes from the SCF calculation are:

change calculation = 'scf' to calculation = 'bands'
point outdir and pseudo_dir to the directories in the parent folder
optionally specify nbnd
replace the automatic k-point mesh with a high-symmetry path

A band input based on the previous graphene SCF calculation can be written as:

&CONTROL
calculation = 'bands'
etot_conv_thr = 2.0000d-05
forc_conv_thr = 1.0000d-04
outdir = '../out/'
prefix = 'graphene'
pseudo_dir = '../pseudo/'
tprnfor = .true.
tstress = .true.
verbosity = 'high'
/

&SYSTEM
degauss = 0.01
ecutrho = 200
ecutwfc = 40
ibrav = 0
nat = 2
nbnd = 8
nosym = .false.
ntyp = 1
occupations = 'smearing'
smearing = 'mv'
/

&ELECTRONS
conv_thr = 4.000d-10
electron_maxstep = 80
mixing_beta = 0.4
/

ATOMIC_SPECIES
C 12.011 C.upf

ATOMIC_POSITIONS angstrom
C 0.0000000000 1.4202816622 0.0000000000
C 1.2300000000 0.7101408311 0.0000000000

K_POINTS crystal_b
4
0.000000000 0.000000000 0.000000000 30
0.500000000 0.000000000 0.000000000 30
0.333333333 0.333333333 0.000000000 30
0.000000000 0.000000000 0.000000000 0

CELL_PARAMETERS angstrom
2.4600000000 0.0000000000 0.0000000000
-1.2300000000 2.1304224933 0.0000000000
0.0000000000 0.0000000000 20.0000000000

nbnd = 8 is an example value chosen to include several conduction bands above the occupied states.

The number of bands should be adjusted depending on the energy range you want to visualize.

3. Define the High-Symmetry Path

For graphene, a commonly used path through the two-dimensional Brillouin zone is:

\[ \Gamma \rightarrow M \rightarrow K \rightarrow \Gamma \]

In the input above, this is specified using:

K_POINTS crystal_b
4
0.000000000 0.000000000 0.000000000 30
0.500000000 0.000000000 0.000000000 30
0.333333333 0.333333333 0.000000000 30
0.000000000 0.000000000 0.000000000 0

The fourth number on each line controls the number of points generated between that high-symmetry point and the next one.

Why not use K_POINTS automatic for a band structure?

An SCF calculation samples the Brillouin zone with a mesh in order to obtain a converged ground-state electron density.

A band-structure calculation has a different purpose: it evaluates the eigenvalues along a selected path through reciprocal space.

Therefore, instead of an automatic mesh, we explicitly specify a sequence of high-symmetry points.

4. Run the Band Calculation

Local execution

pw.x -in 99band.1pw.in > 99band.1pw.out

For an MPI calculation:

mpirun -np 16 pw.x -in 99band.1pw.in > 99band.1pw.out

HPC job submission

On a SLURM-based cluster, the calculation can be submitted through the same job-submission workflow used for the SCF calculation.

sbatch qe_job_submit.sh

If the job script contains a fixed input filename, change it from 1scf.in to 99band.1pw.in before submission.

View my qe_job_submit.sh on GitHub ↗

The band calculation should read the converged SCF data associated with the same prefix and outdir.

If QE cannot find the previous calculation, check the relative outdir path first.

5. Check the Band Output

After the calculation finishes, inspect the end of the output file:

tail -50 99band.1pw.out

You can also check that the job finished normally:

grep "JOB DONE" 99band.1pw.out

At this stage, pw.x has calculated the eigenvalues along the selected k-point path.

The next step is to collect the band data using bands.x.

6. Post-process with `bands.x`

Create an input file named 99band.2pp.in:

&BANDS
prefix = 'graphene'
outdir = '../out/'
filband = 'graphene.bands'
/

Run:

bands.x -in 99band.2pp.in > 99band.2pp.out

This creates:

graphene.bands

which contains the band energies in a form that can be used for plotting.

bands.x does not perform a new electronic-structure calculation.

It post-processes the eigenvalues already calculated by pw.x during the bands calculation.

7. Workflow Summary

The complete workflow is:

SCF
 ↓
Converged ground-state density
 ↓
BANDS calculation along Γ-M-K-Γ
 ↓
bands.x
 ↓
Band data
 ↓
Plot

The characteristic feature to look for in graphene is the crossing of the valence and conduction bands at the $K$ point, forming the Dirac cone.

Why is the K point important in graphene?

In ideal graphene, the valence and conduction bands meet at the $K$ and $K'$ points of the Brillouin zone.

Near these points, the electronic bands are approximately linear in energy versus momentum, which gives rise to the well-known Dirac-cone dispersion.

Graphene Density of States

Calculate the electronic density of states using an NSCF calculation and dos.x.

Quantum ESPRESSO Hands-on Tutorial (Graphene) | Suecreamm

Building Quantum ESPRESSO and Submitting Jobs

Download the source code

Build QE

Submit a calculation to a cluster

1. Downloading and Building Quantum ESPRESSO

1.1 Check the current directory (pwd)

1.2 Download the source code (wget or git)

1.3 Extract the archive and enter the directory

1.4 Configure and build QE (./configure and make)

Standard desktop environment

Systems with parallel computing libraries, such as Intel MKL

1.5 Verify the build

2. Preparing and Submitting a Calculation

2.1 Prepare an input file

2.2 Create a job script

2.3 Submit the job

2.4 Check the output

1. Graphene SCF Calculation

Prepare the graphene structure

Prepare the SCF input

Run the calculation

Check convergence

1. Graphene Structure

2. SCF Input File

Pseudopotential

Input File

3. Understanding the Input

CONTROL

SYSTEM

Smearing

Electronic Convergence

4. Atomic Structure and Vacuum

5. K-point Sampling

6. Run the Calculation

Local execution

HPC job submission

7. Check the Output

8. What Comes Next?

Next

2. Graphene Band Structure Calculation

Create a working directory

Prepare the band input

Run pw.x

Post-process with bands.x

1. Create a Band-Calculation Directory

2. Prepare the Band Input

3. Define the High-Symmetry Path

4. Run the Band Calculation

Local execution

HPC job submission

5. Check the Band Output

6. Post-process with bands.x

7. Workflow Summary

Next

1.1 Check the current directory (`pwd`)

1.2 Download the source code (`wget` or `git`)

1.4 Configure and build QE (`./configure` and `make`)

Run `pw.x`

Post-process with `bands.x`

6. Post-process with `bands.x`