Plugins

Implementing features over VASP carries a somewhat significant overhead, both in term of code development and maintenance. An alternative approach is to use our Plugin infrastructure. Simply write Python functions in a pre-defined format and VASP will recognize and execute your code while it is running. This page describes the steps that you will need to write your first Python script and link it with VASP.

Installation

Create a new conda environment. Alternative environment creation packages should work, but we have not tested them.

   conda create -n vasp_plugin python=3.10

Enter the create vasp_plugin conda environment

   conda activate vasp_plugin

Navigate to the plugins directory within VASP source code,

   cd </path/to/vasp/source/code>/src/plugins

Install the VASP Python package through pip

   pip install .

Add the following lines to your makefile.include

   CPP_OPTIONS+= -DPLUGINS
   LLIBS      += $(shell python3-config --ldflags --embed) -lstdc++
   CXX_FLAGS   = -Wall -Wextra  $(shell python3 -m pybind11 --includes) -std=c++11

Compile VASP using the guide to installing VASP.6.X.X

Mind: Make sure to be within the conda environment when you compile VASP.

Run-time instructions

When running VASP with the python interface you will need to add the lib directory of your python to LD_LIBRARY_PATH. You can do this somewhat easily with conda by running python3-config --ldflags, followed by

   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<path-from-earlier-command>

Python scripting

Start by creating a file called vasp_plugin.py in the folder in which you are running a VASP calculation. An alternative route through entry-points is also possible (see below for further instructions). In vasp_plugin.py implement one or all of the following Python functions.

   def local_potential(constants, additions):
       """Defines the PLUGINS/LOCAL_POTENTIAL interface"""

   def force_and_stress(constants, additions):
       """Defines the PLUGINS/FORCE_AND_STRESS interface"""

   def structure(constants, additions):
       """Defines the PLUGINS/STRUCTURE interface"""

   def occupancies(constants, additions):
       """Defines the PLUGINS/OCCUPANCIES interface"""

Each of the above interfaces may be called by VASP depending on the following INCAR tags

   PLUGINS/LOCAL_POTENTIAL = T         ! Modifies the local potential every SCF step
   PLUGINS/FORCE_AND_STRESS = T        ! Modifies the force and stress at the end of the SCF loop
   PLUGINS/STRUCTURE = T               ! Modifies the structure at the end of the SCF loop
   PLUGINS/OCCUPANCIES = T             ! Modifies NELECT, EFERMI, SIGMA, ISMEAR, EMIN, EMAX, NUPDOWN at the end of the SCF loop

Navigate to the relevant INCAR tag pages for further information.