General

Note

This manual applies only to AMS2023 or later, where QuantumESPRESSO exists as an AMS engine. You can only use this feature from the command-line or PLAMS.

This manual does not apply to Quantum ESPRESSO in the AMS GUI (AMSinput).

The QuantumESPRESSO engine for the AMS driver is not yet available on Windows.

What’s new in AMS2023.1?

  • Quantum ESPRESSO is now an AMS engine. This means that it can be used with all tasks from the AMS driver and from Python with PLAMS.

  • The QE version is now 7.1.

Installation with AMSpackages

Use the AMSpackages package manager to install Quantum ESPRESSO. This will install a version of Quantum ESPRESSO 7.1 that has been modified to support communicating with the AMS driver via the AMSpipe interface. This is the recommended way to install Quantum ESPRESSO.

How to run Quantum ESPRESSO via AMS driver

Quantum ESPRESSO should be installed through the package manager as explained above. That version contains some modifications by SCM that makes it compatible with the AMS driver.

You must run ams in serial. This will still let you run pw.x (Quantum ESPRESSO) in parallel.

To run ams in serial we recommend setting the environment variable SCM_DISABLE_MPI=1, as this will make sure that the AMS driver is not launched through mpirun (or a batch system specific equivalent launcher such as srun on SLURM).

export SCM_DISABLE_MPI=1

If you launch AMS through PLAMS, set:

settings.runscript.preamble_lines = ['export SCM_DISABLE_MPI=1']

The Quantum ESPRESSO binaries are executed by the AMS driver using the $AMSBIN/startqe script. How exactly they are launched can be influenced through a number of environment variables:

  • SCM_USE_LOCAL_QE: When set, instead using the AMSpackage version of Quantum ESPRESSO, use a local version of QE. The Quantum ESPRESSO binaries (like pw.x, projwfc.x, …) of the local QE version should then be accessible on $PATH.

  • SCM_QESTARTCMD: Command called to launch Quantum ESPRESSO binaries (like pw.x, projwfc.x, …). If not set, srun will be used if running under SLURM (aka SLURM_JOB_ID is set), and exec will be used otherwise. Might need to be changed when running jobs with the Quantum ESPRESSO through a batch system.

  • SCM_QESTARTCMD_OPTIONS: Options, to be passed to the QE start command defined by SCM_QESTARTCMD.

  • SCM_QERC: Can be set to the (absolute) path to a shell script that will be source right before a Quantum ESPRESSO binary is executed. (Environment setup that might be needed to run QE binaries can then be put into that script.)

Tip

The combination of all these environment variables should give users full flexibility for executing Quantum ESPRESSO. Here are some examples for common use-cases. (The SCM_DISABLE_MPI=1 environment variable should always be set, and we assume this is already done in the myqejob.run script.)

OpenMP parallelization of QE: the default for running locally.

OMP_NUM_THREADS=8 ./myqejob.run

MPI parallelization of QE: only available on Linux, but likely more efficient than the OpenMP parallelization above.

SCM_QESTARTCMD=mpirun SCM_QESTARTCMD_OPTIONS="-n 8" OMP_NUM_THREADS=1 ./myqejob.run

MPI parallel QE under SLURM: will automatically use srun as the SCM_QESTARTCMD.

sbatch -p myqueue -N 2 --ntasks-per-node=32 ./myqejob.run

Manual compilation and installation

Alternatively you can compile the modified version of Quantum ESPRESSO yourself. It is available as a fork in Gitlab:

gitlab.com/robertrueger/q-e/-/tree/amspipe

Instructions on how to build Quantum ESPRESSO can be found on the official Wiki:

gitlab.com/QEF/q-e/-/wikis/Developers/CMake-build-system

You will have to build it using CMake and set QE_ENABLE_AMSPIPE=ON to enable the integration with the AMS driver. The following script may be a good starting point for compiling the modified Quantum ESPRESSO version on your machine.

git clone https://gitlab.com/robertrueger/q-e.git
cd q-e
git checkout amspipe
mkdir build
cd build
cmake -DQE_ENABLE_AMSPIPE=ON ..
cmake --build .

By default the AMS driver will always try to use the AMSpackages version of QuantumESPRESSO. If you compiled your own binaries and want to use them, make sure that your pw.x is available on $PATH and set the SCM_USE_LOCAL_QE environment variable:

export PATH="/path/to/my/q-e/build/bin:$PATH"
export SCM_USE_LOCAL_QE=1