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

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")
'