Tutorial: Running Quantum Espresso in Galileo

Written and developed by
Matthew Gasperetti

matthew@hypernetlabs.io

Tutorial: Running Quantum Espresso in Galileo

Written and developed by
Matthew Gasperetti

matthew@hypernetlabs.io

Getting started with Quantum Espresso in Galileo

Getting started with Quantum ESPRESSO (QE) in Galileo

To get started with Galileo, log into your account using Firefox or Chrome, and download our quantum-espresso example file from GitHub.

In this walkthrough, we’re going to adapt one of the examples from the QE tutorials page. Specifically, we’re going to look at example 7 from day 3 of the Ljubljana QE summer school. This example was created by Iurii Timrov and Oscar Baseggip. The full GitLab repository for the summer school can be found here.

Our quantum-espresso example folder contains the following files:

plot_spectrum_hyb.gp plot_spectrum_nohyb.gp
pw.methane.in
runqe.sh
turbo_davidson.methane.in
turbo_spectrum.methane.in
Dockerfile

 

We’ll run this folder in Galileo by dropping it into the Galilei station, and then we’ll take a look at what’s happening behind the scenes. 

Let’s have a look at our files

First, we have a series of files to run our computations: pw.methane.in is an input file that conducts the SCF ground-state calculation, turbo_davidson.methane.in runs a Davidson calculation of our eigenvalues, and turbo_spectrum.methane.in completes a post-processing analysis of our spectrum.

We also have the files plot_spectrum_nohyb.gp and plot_spectrum_hyb.gp, which plot our spectrum using gnuplot with and without B3LYP pseudo-potential, respectively.

Finally, we have a shell script called runqe.sh that contains our QE commands and a Dockerfile that builds a Docker container with QE installed in a Linux environment.

When you log into Galileo, the first thing you’ll see is your Dashboard:

View of the Galileo Dashboard

To run the commands in runqe.sh, drag and drop the entire quantum-espresso folder you downloaded from our GitHub to the station Galilei at the top of the Dashboard:

Drag and drop the quantum-espresso folder to the Galilei station

After you drag and drop the quantum-espresso folder to the Galilei station in Galileo, you’ll be able to see the job running in the Your Recent Jobs panel:

The job runs quickly in Galileo – try running it locally and comparing

When the example job completes, hit the Download button under Action to download the results:

Download button

The results folder will be downloaded as a .zip that contains an output.log file returning the results of the analysis and a folder called filesys where plots and other files created by the analysis are stored.

The Downloaded .zip file contains a folder called filesys and a file called output.log

Let’s take a look at the top of the output.log file first, which returns the results of the analyses.

Summary of the results of our analyse

Next, if we look in the filesys folder, we can see the plots we made:

Calculation of Absorption Spectra of Methane

Running your own Quantum Espresso files in Galileo—
A closer look at how it works

A closer study of the files in our quantum-espresso folder will help illustrate how to modify them so you can run your own projects.

How to code a Dockerfile to run QE in Galileo

Let’s quickly review the example Dockerfile, which you can open with a text editor like Atom.

The first thing to notice is that the file is called Dockerfile with no extension. It cannot be called anything else—Dockerfile2, Dockerfile copy, or Dockerfile.txt won’t work.

Looking at the Dockerfile with our text editor, the first Docker command we see is:

FROM hypernetlabs/simulator:q-e

This tells Docker to pull the QE Docker image from our hypernetlabs Docker Hub repository. We want to leave it as is. 

Let’s look at the next line of code:

RUN apt-get update -y && apt-get install -y gnuplot

This line of code contains an Ubuntu command, starting with apt-get that is prefaced with the Docker RUN command and installs gnuplot in our Linux environment so we can make our plots.

The next line of code tells Docker where to look for, and where to save, our files and should be left as is:

COPY . .

The final command is:

ENTRYPOINT [“bash”,”runqe.sh”]

This tells Docker to open a bash shell and run the commands in runqe.sh, which is our shell script.

Here is the Dockerfile from the quantum-espresso folder in its entirety with comments:

#The line below determines the build image to use
FROM hypernetlabs/simulator:q-e
#This line passes Ubuntu commands to Docker
RUN apt-get update -y && apt-get install -y gnuplot
#This line determines where to copy project files from, and where to copy them to
COPY . .
ENTRYPOINT [“bash”,”runqe.sh”]

 

Now, Let’s have a look at our runqe.sh file

The runqe.sh file should look familiar. In the first line, we specify mpi as our launcher with mpirun, set the number of processors with the -np flag, and run pw.methane.in using pw.x. This will print the SCF ground-state calculation to the output.log file.

mpirun -np 8 pw.x < pw.methane.in

Optional Alternative: Alternatively, we can save the output as a file that will be returned in the filesys directory by adding pw.methane.out like this:

mpirun -np 8 pw.x < pw.methane.in > pw.methane.out

In the next line we, again, specify mpi as our launcher with mpirun, set the number of processors with the -np flag, and then run turbo_davidson.methane.in using turbo_davidson.x. This prints the results of the Davidson algorithm (without B3LYP pseudo-potential) to our output.log file.

mpirun -np 8 turbo_davidson.x < turbo_davidson.methane.in

Optional Alternative: Once again, we can also save the results to the filesys folder by adding turbo_davidson.methane.out to the line of code:

mpirun -np 8 turbo_davidson.x < turbo_davidson.methane.in > turbo_davidson.methane.out

In the next line we, again, use mpirun to specify mpi as our launcher, specify the number of processors with the -np flag, and then run turbo_spectrum.methane.in using turbo_spectrum.x. This prints the results of our spectrum analysis to the output.log file.

mpirun -np 8 turbo_spectrum.x < turbo_spectrum.methane.in

Optional Alternative: Adding turbo_spectrum.methane.out saves the results to the filesys folder.

mpirun -np 8 turbo_spectrum.x < turbo_spectrum.methane.in > turbo_spectrum.methane.out

Finally, we can create our plot using gnuplot and save it to the filesys directory like this:

gnuplot -> load ‘plot_spectrum_nohyb.gp’

The complete script should look like this:

mpirun -np 8 pw.x < pw.methane.in
mpirun -np 8 turbo_davidson.x < turbo_davidson.methane.in
mpirun -np 8 turbo_spectrum.x < turbo_spectrum.methane.in
gnuplot -> load ‘plot_spectrum_nohyb.gp’

 

Optional Alternative: If you would like to save the results in the filesys folder rather than printing them to output.log, your script should look like this:

mpirun -np 8 pw.x < pw.methane.in > pw.methane.out
mpirun -np 8 turbo_davidson.x < turbo_davidson.methane.in > turbo_davidson.methane.out
mpirun -np 8 turbo_spectrum.x < turbo_spectrum.methane.in > turbo_spectrum.methane.out
gnuplot -> load ‘plot_spectrum_nohyb.gp’

 

Running the Davidson calculation using B3LYP pseudo-potential

To perform the Davidson calculation using B3LYP pseudo-potential, we will modify the pw.methane.in file by adding input_dft = ‘B3LYP’ as follows:

&SYSTEM
ibrav = 1,
celldm(1) = 20,
nat = 5,
ntyp = 2,
ecutwfc = 50,
nbnd = 20,
input_dft = ‘B3LYP’


Next, in the file turbo_davidson.methane.in, we’ll change d0psi_rs = .false. to d0psi_rs = .true. as follows:

d0psi_rs = .true.

 

Finally, in runqe.sh, we’ll change plot_spectrum_nohyb.gp to

plot_spectrum_nohyb.gp:>
plot_spectrum_nohyb.gp

 

If you drag and drop the modified quantum-espresso folder and run it in Galileo, your plot should look like this:

 

Calculation of Absorption Spectra of Methane Using B3LYP pseudo-potential

I hope this tutorial was helpful. Please let me know if you have any questions or any problems using Galileo. Your feedback is extremely important to us. Contact me anytime at matthew@hypernetlabs.io.