GASpy: Generalized Adsorption Simulator for Python

We use Density Functional Theory (DFT) to calculate adsorption energies of adsorbates onto slabs, but we try to do it in a general way such that we may perform these calculations for an arbitrary number of configurations---e.g., different bulk materials, facets, adsorption sites, adsorbates, etc.

Overview

GASpy is written in Python 3, and we use various tools (below) that enable us to perform high-throughput DFT relaxations. You can find a full list of our dependencies in our Dockerfile.

ASE, VASP, PyMatGen, FireWorks, Materials Project, Docker, Luigi, MongoDB

We created various Python classes (referred to as tasks by Luigi) to automate adsorption energy calculations. For example: We have a task to fetch bulk structures from the Materials Project and then turn them into ASE atoms objects; we have a task that uses PyMatGen to cut slabs out of these bulk structures; we have a task that use PyMatGen to enumerate adsorption sites on these slabs; we have a task to add adsorbates onto these sites; and we have a task to calculate adsorption energies from slab, adsorbate, and slab+adsorbate relaxations.

We use Luigi to manage the dependencies between these tasks (e.g., our slab cutting class requires that we fetch the bulk structure), and we use FireWorks to manage/submit our DFT simulations across multiple clusters. Thus, we can simply tell GASpy to "calculate the adsorption energy of CO on Pt", and it automatically performs all of the necessary steps (e.g., fetch Pt from Materials Project; cut slabs; relax the slabs; add CO onto the slab and then relax; then calculate the adsorption energy).

To submit calculations, we create wrapper tasks that call on the appropriate sub-tasks, and then use either Luigi or our Python wrapping functions to execute the classes that you made. For example:

from gaspy.tasks import schedule_tasks
from gaspy.gasdb import get_catalog_docs
from gaspy.tasks.metadata_calculators import CalculateAdsorptionEnergy


# Get all of the sites that we have enumerated
all_site_documents = get_catalog_docs()

# Pick the sites that we want to run. In this case, it'll be sites on
# palladium (as per Materials Project ID 2, mp-2) on (111) facets.
site_documents_to_calc = [doc for doc in all_site_documents
                          if (doc['mpid'] == 'mp-2' and
                              doc['miller'] == [1, 1, 1])]

# Turn the sites into GASpy/Luigi tasks
tasks = [CalculateAdsorptionEnergy(adsorbate_name='CO',
                                   adsorption_site=doc['adsorption_site'],
                                   mpid=doc['mpid'],
                                   miller_indices=doc['miller'],
                                   shift=doc['shift'],
                                   top=doc['top'])
         for doc in site_documents_to_calc]

# Schedule/run all of the tasks
schedule_tasks(tasks)

This snippet will calculate CO adsorption energies of all sites on the (1, 1, 1) facet of Pd.

Installation

You will need five things to run GASpy:

1. a locally cloned version of this repository,

2. Docker,

3. a MongoDB server,

4. FireWorks set up on your computing cluster(s), and

5. A properly configured .gaspyrc.json file placed in your local GASpy folder.

Docker

Our image---ulissigroup/gaspy---contains the infrastructure that we use to run our code. Note that this image does not actually contain the GASpy source code. If it did, we would need to constantly rebuild the image, because we are constantly changing and redeveloping GASpy. We instead mount our local repository to the container that we use to run our code: docker run -v "/local/path/to/GASpy:/home/GASpy" ulissigroup/gaspy:latest foo You can also see how we open an interactive Docker container here.

MongoDB

You will need to set up your own Mongo database and then put the appropriate information into your .gaspyrc.json file. You will need to make an atoms collection in your database, which will contain one document for every DFT calculation you run. You will also need an adsorption collection that will contain one document for every adsorption energy you calculate, and a relaxed_bulk_catalog collection that will contain one document for every adsorption site you enumerate using this script.

We also have read-only mirrors to our catalog collections that allow for faster reading. If you do not want to set this up, simply re-enter your catalog collection's information into the readonly sections of the .gaspyrc.json file.

FireWorks

GASpy only submits jobs to FireWorks. You will need to set up your own FireWorks database and rocket launchers on your computing clusters. You will also need to enter the appropriate FireWorks data into the lpad* sections of your gaspyrc.json file.

.gaspyrc.json

In addition to the aforementioned items you need to populate in your .gaspyrc.json file, you will also need to set up a few other things:

• A dedicated folder to store the pickle files that Luigi will use to manage the task dependencies. This folder should be put it the gasdb_path field.
• A constantly running Luigi daemon. You can do this by simply running nohup docker run -v "/local/path/to/GASpy:/home/GASpy" ulissigorup/gaspy:latest /miniconda3/bin/luigid &. Then you enter the IP address of the machine that you ran that command on into the luigi_host field.
• You will need to get an API key from The Materials Project and then enter it into the matproj_api_key field

You may notice the gasdb_server field. We use that to interface with a web-based data viewing service that we still have under development. You will not need to populate this field.

Submodules

You may notice that we have two submodules: GASpy_regressions and GASpy_feedback. We use our regression submodule to analyze and perform regressions on our DFT data, and we use our feedback submodule to choose which calculations to [automatically] perform next.

Reference

Active learning across intermetallics to guide discovery of electrocatalysts for CO2 reduction and H2 evolution. Note that the repository which we reference in this paper is version 0.1 of GASpy, which can stil be found here.

Versions

Current GASpy version: 0.20

For an up-to-date list of our software dependencies, you can simply check out how we build our docker image here.