ashtonmv / twod_materials

High throughput workflow tools for characterizing 2D materials in VASP.

Please Note this version of twod_materials is no longer slated to receive updates; it has been merged as a part of MPInterfaces, so please install and reference from that repository.

About twod_materials

The official documentation for twod_materials, which includes a pretty comprehensive set of tutorials, can be found here.

The wiki pages contain the unofficial but still well-maintained documentation for twod_materials, including the tutorials.

Overview

twod_materials is a library of functions that I've used in my research on discovering and characterizing 2D materials. Some of them I have used thousands of times, and others I have used less than five times. The functions in twod_materials have been designed with user-friendliness as a priority, which occasionally comes at the expense of flexibility. For example, some of the post-processing functions will assume you have used a certain directory structure when organizing your calculations. The goal here was not to be restrictive, but to be streamlined.

Installation and setup

The latest stable release can be installed with pip:

pip install numpy
pip install twod_materials

Alternatively, the very latest (no promises) version of twod_materials can be installed by cloning this repository. Once you've cloned it on your system, run pip install numpy and then pip install -r requirements.txt to install its dependencies. You should then add its location to your system's $PYTHONPATH so you can import its functions from anywhere. There are a few ways to do this, including adding the following line to your ~/.bashrc file:

  export PYTHONPATH=$PYTHONPATH:/path/to/twod_materials  # obviously change this

Edit config.yaml with your system's settings, following the template:

  mp_api: your_materials_project_api_key
  normal_binary: path_to_normal_vasp_executable
  twod_binary: path_to_twod_vasp_executable
  potentials: path_to_your_vasp_potentials
  vdw_kernel: path_to_your_vdw_kernel.bindat
  queue_system: slurm_or_pbs

and then copy or move it to your home directory (~).

How the package is structured

There are five mature modules in twod_materials: stability, electronic_structure, pourbaix, friction, and intercalation. The magnetism module is, for now, still in its infancy. The utils module is basically just a library of helper functions used throughout the other packages.

Each of these modules has two submodules: startup and analysis. For most modules, startup contains functions that set up and submit VASP calculations by interacting with your machine's queue system (PBS or SLURM). It might be helpful to think of the startup submodules as pre-processing tools. The analysis submodules, then, contain post-processing functions. These post-processing functions can be grouped into two main categories: functions for analyzing data and functions for plotting it. All plotting functions use matplotlib.

Throughout the package, there are a few configuration files that for the most part don't need to be changed (as opposed to config.yaml, which does): potcar_symbols.yaml and the yaml files under the pourbaix module.

See the tutorials for sample usage of every function in twod_materials.