Examples¶
These examples show how to run Quantum ESPRESSO (pw.x) through the AMS driver.
Important
These examples do not necessarily contain scientifically good settings!
See also
PLAMS (python) example for running QE via the AMS Driver.
Single-point calculation + band structure¶
Single-point calculation of bulk Si with a regular k-point grid.
At the end of the calculation the band structure is calculated. You can view the resulting band structure with the program $AMSBIN/amsbands.
#!/bin/sh
export SCM_DISABLE_MPI=1 # must be set when using the Quantum ESPRESSO engine, see documentation
"$AMSBIN/ams" --delete-old-results << EOF
Task SinglePoint
System
Atoms
Si -0.67520366 -0.67520366 -0.67520366
Si 0.67520366 0.67520366 0.67520366
End
Lattice
0.00000000 2.70081465 2.70081465
2.70081465 0.00000000 2.70081465
2.70081465 2.70081465 0.00000000
End
End
Engine QuantumEspresso
System
ecutwfc 50
ecutrho 400
occupations smearing
degauss 0.001
End
K_Points automatic
5 5 5 0 0 0
End
Pseudopotentials
Family pslibrary-US
Functional PBE
End
Properties
BandStructure Yes
End
EndEngine
EOF
Lattice optimization of silicon¶
#!/bin/sh
export SCM_DISABLE_MPI=1 # required for Quantum ESPRESSO - see documentation
#============================================================================
# Example showing how to run a lattice optimization with Quantum ESPRESSO.
#
# This example is also available as a tutorial using the
# graphical user interface
#
# Important: always use carefully converged k-points and energy cutoffs
# for lattice optimizations!
#
# You may want to symmetrize the optimized structure using the "star"
# button in AMSinput.
#============================================================================
"$AMSBIN/ams" --delete-old-results <<EOF
Task GeometryOptimization
GeometryOptimization
OptimizeLattice Yes
End
System
Atoms
Si -0.67875000 -0.67875000 -0.67875000
Si 0.67875000 0.67875000 0.67875000
End
Lattice
0.0 3.0 3.0
3.0 0.0 3.0
3.0 3.0 0.0
End
End
Engine QuantumEspresso
K_Points automatic
10 10 10 0 0 0
End
Pseudopotentials
Family SSSP-Efficiency
Functional PBE
End
System
ecutwfc 40.0
ecutrho 320.0
occupations Fixed
End
EndEngine
EOF
DFT+U (Hubbard U) calculation for anti-ferromagnetic FeO¶
Single-point calculation for anti-ferromagnetic FeO with DFT+U.
Note how QE.Label= is used to create two distinct Fe species for Quantum ESPRESSO, which are then given an opposite initial magnetization, leading to an anti-ferromagnetic solution.
#!/bin/sh
# Run AMS driver without MPI, so that QE can be MPI parallel.
export SCM_DISABLE_MPI=1
"$AMSBIN/ams" --delete-old-results << EOF
Task SinglePoint
System
Atoms
Fe 0.0 0.0 0.0 QE.Label=Fe1
Fe 2.165 2.165 0.0 QE.Label=Fe2
O 0.0 2.165 0.0
O 2.165 0.0 0.0
End
Lattice
4.33 0.0 0.0
0.0 4.33 0.0
2.165 0.0 2.165
End
End
Engine QuantumEspresso
System
ecutwfc 40.0
ecutrho 160.0
occupations smearing
smearing mv
degauss 0.02
nspin 2
starting_magnetization label=Fe1 value=0.5
starting_magnetization label=Fe2 value=-0.5
End
Pseudopotentials
Family pslibrary-PAW
Functional PBEsol
End
K_Points automatic
5 5 5 0 0 0
End
Hubbard ortho-atomic
U Fe1-3d 4.6
U Fe2-3d 4.6
End
EndEngine
EOF
Pseudopotential selection¶
#!/bin/sh
export SCM_DISABLE_MPI=1 # required for engine Quantum ESPRESSO, see documentation
# =======================================================================================
# Example illustrating various ways of selecting Pseudopotentials with the QE engine.
# =======================================================================================
#
# All jobs run into this example should give the exact same result,
# as they are using the same PPs.
# All that differs is the way that the PPs were selected.
# Make a folder with "custom" PP files to test with:
#
# We will use the SG15 pseudopotentials directory that comes
# with the AMS QE package as an example.
# You could use any other directory with .upf files ...
PPDIR="$("$AMSBIN/amspackages" loc qe)/upf_files/GGA/PBE/SR/SG15-1.2/UPFs"
# Make a custom directory containing files named element.upf:
mkdir -p my_pp_directory
cp "$PPDIR"/C_ONCV_PBE-1.2.upf my_pp_directory/C.upf # rename to element.upf
cp "$PPDIR"/H_ONCV_PBE-1.2.upf my_pp_directory/H.upf # rename to element.upf
# If using special QE labels, the file name should be label.upf:
cp "$PPDIR"/H_ONCV_PBE-1.2.upf my_pp_directory/H1.upf
# Get an absolute path to the directory the jobs starts in:
if test "$OS" = "Windows_NT"; then
# Absolute paths should be Windows style (with drive letters like C:)
STARTDIR=$(pwd -W)
else
STARTDIR=$(pwd)
fi
# Make a system to test with:
echo "
System
Atoms
C 0.9685 1.9663 0.0000
H 1.6614 2.2162 0.7898
H 0.0162 1.6927 0.4297
H 0.8388 2.8201 -0.6485
H 1.3576 1.1363 -0.5710 QE.Label=H1
End
Lattice
5.0 0.0 0.0
0.0 5.0 0.0
0.0 0.0 5.0
End
End
" > system.in
# Option 1: Pseudopotentials%Family
# ---------------------------------
#
# The easiest way is to just use the Pseudopotentials%Family key and
# let the engine figure out which PPs to use.
AMS_JOBNAME=1_family "$AMSBIN/ams" << EOF
Task SinglePoint
@include system.in
Engine QuantumEspresso
Pseudopotentials
Family SG15
Functional PBE
End
K_points Gamma
End
EndEngine
EOF
# Option 2: Pseudopotentials%Directory
# ------------------------------------
#
# Specifies a path to a directory with PP files named element.upf or label.upf.
# The path to the directory can be absolute or relative.
AMS_JOBNAME=2a_directory_relpath "$AMSBIN/ams" << EOF
Task SinglePoint
@include system.in
Engine QuantumEspresso
Pseudopotentials
Directory my_pp_directory
End
K_points Gamma
End
EndEngine
EOF
AMS_JOBNAME=2b_directory_abspath "$AMSBIN/ams" << EOF
Task SinglePoint
System
Atoms
C 0.9685 1.9663 0.0000 QE.Label=C1 # no PP file for C1 in folder, fallback to C
H 1.6614 2.2162 0.7898
H 0.0162 1.6927 0.4297
H 0.8388 2.8201 -0.6485
H 1.3576 1.1363 -0.5710 QE.Label=H1
End
Lattice
5.0 0.0 0.0
0.0 5.0 0.0
0.0 0.0 5.0
End
End
Engine QuantumEspresso
Pseudopotentials
Directory $STARTDIR/my_pp_directory
End
K_points Gamma
End
EndEngine
EOF
# Option 3: Pseudopotentials%Files
# ------------------------------------
#
# Individually specify paths to files for each element or label.
# By default relative paths are relative to the root of the
# PP library installed via AMSpackages.
AMS_JOBNAME=3a_files_relpath "$AMSBIN/ams" << EOF
Task SinglePoint
@include system.in
Engine QuantumEspresso
Pseudopotentials
Files Label=C Path=GGA/PBE/SR/SG15-1.2/UPFs/C_ONCV_PBE-1.2.upf
Files Label=H Path=GGA/PBE/SR/SG15-1.2/UPFs/H_ONCV_PBE-1.2.upf
Files Label=H1 Path=GGA/PBE/SR/SG15-1.2/UPFs/H_ONCV_PBE-1.2.upf
End
K_points Gamma
End
EndEngine
EOF
# Paths relative to the starting directory of AMS should be prefixed with "./".
AMS_JOBNAME=3b_files_exrelpath "$AMSBIN/ams" << EOF
Task SinglePoint
@include system.in
Engine QuantumEspresso
Pseudopotentials
Files Label=C Path=./my_pp_directory/C.upf
Files Label=H Path=./my_pp_directory/H.upf
Files Label=H1 Path=./my_pp_directory/H1.upf
End
K_points Gamma
End
EndEngine
EOF
# Absolute paths are also supported.
AMS_JOBNAME=3c_files_abspath "$AMSBIN/ams" << EOF
Task SinglePoint
@include system.in
Engine QuantumEspresso
Pseudopotentials
Files Label=C Path="$STARTDIR/my_pp_directory/C.upf"
Files Label=H Path="$STARTDIR/my_pp_directory/H.upf"
Files Label=H1 Path="$STARTDIR/my_pp_directory/H1.upf"
End
K_points Gamma
End
EndEngine
EOF
# Combinations between absolute, relative and explicit relative paths also work.
AMS_JOBNAME=3d_files_mixed "$AMSBIN/ams" << EOF
Task SinglePoint
@include system.in
Engine QuantumEspresso
Pseudopotentials
Files Label=C Path=GGA/PBE/SR/SG15-1.2/UPFs/C_ONCV_PBE-1.2.upf
Files Label=H Path=./my_pp_directory/H.upf
Files Label=H1 Path="$STARTDIR/my_pp_directory/H1.upf"
End
K_points Gamma
End
EndEngine
EOF
Slab with dipole correction, work function¶
Calculation of an LiF layer on top of a Al, using the dipole correction to simulate a slab system.
#!/bin/sh
export SCM_DISABLE_MPI=1
#============================================================================
# Example showing how to apply a dipole correction for a slab system.
# This gives two separate vacuum levels on the different sides of the slab.
# The respective work functions are calculated as differences
# between the vacuum levels and the Fermi energy.
#
# This example uses the pp.x and average.x utilities from Quantum ESPRESSO
# to get the plane-averaged electrostatic potential. Those utilities are
# included with the Quantum ESPRESSO package in AMS but are not part of
# the AMS interface. For this reason they are used directly from the
# standalone Quantum ESPRESSO.
#
# For details about the input to pp.x, and average.x, see:
# - https://www.quantum-espresso.org/Doc/INPUT_PP.html
# - https://gitlab.com/QEF/q-e/-/blob/qe-7.1/PP/src/average.f90
#
# This example is based on the work function tutorial for BAND and the
# work function example in Quantum ESPRESSO (PP/examples/WorkFct_example).
#
# Better-converged numbers can be obtained by increasing the k-space
# sampling and energy cutoff.
#============================================================================
"$AMSBIN/ams" --delete-old-results <<EOF
Task SinglePoint
System
Atoms
Al 1.4319 1.4319 8.925
Al 0.0000 0.0000 10.95
Al 1.4319 1.4319 12.975
Al 0.0000 0.0000 15
F 0.0000 0.0000 18.27
Li 1.4319 1.4319 18.27
F 1.4319 1.4319 20.295
Li 0.0000 0.0000 20.295
End
Lattice
2.86378246 0.00000000 0.00000000
0.00000000 2.86378246 0.00000000
0.0 0.0 30.0
End
End
Engine QuantumEspresso
K_Points automatic
2 2 1 1 1 1
End
Pseudopotentials
Family GBRV
Functional PBE
End
System
ecutwfc 40.0
occupations smearing
smearing gaussian
degauss 0.02
edir 3
emaxpos 0.90
eopreg 0.10
End
Electrons
conv_thr 1.0e-10
End
Control
tefield Yes
dipfield Yes
End
EndEngine
EOF
#-------------------------------------------------------------
# Using the QE utilities from the standalone Quantum ESPRESSO.
#-------------------------------------------------------------
# Change working directory
cd ams.results || exit
$AMSBIN/startqe pp.x <<EOF
&INPUTPP
prefix='quantumespresso',
filplot='pot.dat'
plot_num =11
/
EOF
$AMSBIN/startqe average.x <<EOF
1
pot.dat
1.0
3000
3
3.00000
EOF
# Change back
cd .. || exit
#-------------------------------------------------------------
# Get vacuum levels and fermi energy and print work functions
#-------------------------------------------------------------
$AMSBIN/amspython -c '
from scm.libbase import Units
from scm.akfreader import AKFReader
import numpy as np
akf = AKFReader("ams.results/quantumespresso.rkf")
Efermi = akf.read("QE_BandStructure%fermiEnergy") * Units.get_factor("hartree", "eV")
plane_avg_pot = np.loadtxt("ams.results/avg.dat")
# these indices work because emaxpos=0.9 and eopreg=0.1 !
# the potential is in the second column
bottom_vacuum_index = 0
top_vacuum_index = int(0.9 * len(plane_avg_pot))
avg_pot_bottom = plane_avg_pot[bottom_vacuum_index, 1] * Units.get_factor("Rydberg", "eV")
avg_pot_top = plane_avg_pot[top_vacuum_index, 1] * Units.get_factor("Rydberg", "eV")
wf_top = avg_pot_top - Efermi
wf_bottom = avg_pot_bottom - Efermi
wf_delta = wf_top - wf_bottom
print(f"Efermi: {Efermi:.3f} eV")
print(f"VacuumLevelBottom: {avg_pot_bottom:.3f} eV")
print(f"VacuumLevelTop: {avg_pot_top:.3f} eV")
print(f"Work function bottom: {wf_bottom:.3f} eV")
print(f"Work function top: {wf_top:.3f} eV")
print(f"Work function shift {wf_delta:.3f} eV")
'