Plugins: Difference between revisions

From VASP Wiki
No edit summary
 
(27 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Implementing features over VASP carries a somewhat significant overhead, both in term of code development and maintenance.
Implementing features over VASP carries a significant overhead, both in term of code development and maintenance.
An alternative approach is to use our Plugin infrastructure. Simply write [https://www.python.org/ Python] functions in a pre-defined format and VASP will recognize and execute your code while it is running.
An alternative approach is to use our Python plugin infrastructure. Simply write [https://www.python.org/ 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.
This page describes the steps that you will need to write your first Python script and link it with VASP.


==Installation==
==Python scripting==
Create a new [https://conda.io/projects/conda/en/latest/user-guide/getting-started.html conda] environment.
Start by creating a file called <code>vasp_plugin.py</code> in the folder in which you are running a VASP calculation.
    conda create -n vasp_plugin python=3.10
An alternative route through entry-points is also possible (see below for further instructions).
Enter the create <code>vasp_plugin</code> conda environment
In <code>vasp_plugin.py</code> implement one or all of the following Python functions.
    conda activate vasp_plugin
 
Navigate to the <code>plugins</code> directory within VASP source code,
<syntaxhighlight lang="python" line>
    cd </path/to/vasp/source/code>/src/plugins
def structure(constants, additions):
Install the VASP Python package through [https://pip.pypa.io/en/stable/installation pip]
     """Defines the PLUGINS/STRUCTURE interface"""
    pip install .
Add the following lines to your <code>makefile.include</code>
    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 [[Installing_VASP.5.X.X|guide to installing VASP.6.X.X]]
{{NB|mind|Make sure to be within the conda environment when you compile VASP.}}


==Run-time instructions==
def force_and_stress(constants, additions):
When running VASP with the python interface you will need to add the <code>lib</code> directory of your python to <code>LD_LIBRARY_PATH</code>.
    """Defines the PLUGINS/FORCE_AND_STRESS interface"""
You can do this somewhat easily with <code>conda</code> by running <code>python3-config --ldflags</code>, followed by
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<path-from-earlier-command>


==Python Scripting==
def local_potential(constants, additions):
Start by creating a file called <code>vasp_plugin.py</code> in the folder in which you are running a VASP calculation.
    """Defines the PLUGINS/LOCAL_POTENTIAL interface"""
An alternative route through entry-points is also possible (see below for further instructions).
 
def machine_learning():
    """Defines the PLUGINS/MACHINE_LEARNING interface"""
 
def occupancies(constants, additions):
    """Defines the PLUGINS/OCCUPANCIES interface"""
</syntaxhighlight>


The relevant lines of python code to access data from vasp through the any of the interfaces listed above are:
As the names of the input variables suggest,
# <code>constants</code> provides a [https://docs.python.org/3/library/dataclasses.html dataclass] with quantities computed in VASP that must stay constant through the interface. Typically these include "metadata" such as the lattice vectors, number of grid points, etc. Some interfaces also pass in quantities such as the charge density as <code>constants</code>. Please check the page of the specific plugins' tag for more details on which quantities are available as constants. Alternatively, you may print the contents of <code>constants</code>.
# <code>additions</code> stores quantities that are allowed to change in the interface. You must use the syntax <code>additions.<quantity-name> += ...</code> in order to change additions. That is, quantities must be "added" (or subtracted) to <code>additions</code> instead assigning them a new value. We use additions for two reasons. First, it makes sure that you use the memory from VASP; otherwise assigning might create a new array in memory and return zero to VASP. Secondly, adding the values allows multiple compatible plugins running at the same time.
The machine-learning plugin works a bit different. Please refer to [[PLUGINS/MACHINE_LEARNING|its documentation]] for more details.


     def local_potential(constants, additions):
Each of the above interfaces may be called by VASP depending on the following {{FILE|INCAR}} tags
         """Defines the PLUGINS/LOCAL_POTENTIAL interface"""
     {{TAG|PLUGINS/FORCE_AND_STRESS}} = T        ! Modifies the force and stress at the end of the SCF loop
    {{TAG|PLUGINS/LOCAL_POTENTIAL}} = T         ! Modifies the local potential every SCF step
    {{TAG|PLUGINS/MACHINE_LEARNING}} = T        ! Replaces the VASP force/stress engine with a machine-learned interatomic potential
    {{TAG|PLUGINS/OCCUPANCIES}} = T            ! Modifies NELECT, EFERMI, SIGMA, ISMEAR, EMIN, EMAX, NUPDOWN at the end of the SCF loop
    {{TAG|PLUGINS/STRUCTURE}} = T              ! Modifies the structure at the end of the SCF loop
Navigate to the relevant {{FILE|INCAR}} tag pages for further information.


    def force_and_stress(constants, additions):
==Exposing interfaces through entry-points (advanced)==
        """Defines the PLUGINS/FORCE_AND_STRESS interface"""
Consider using [https://packaging.python.org/en/latest/specifications/entry-points/ entry points] in cases where you do not want to move <code>vasp_plugin.py</code> to each new VASP calculation directory. This is also the approach you should take, if you want to distribute your plugin to other users. Within the group "vasp", add the following lines to your <code>pyproject.toml</code> file for each interface you would like to introduce new functions. For example, if you wanted to access the <code>force_and_stress</code> interface through an entry point, add the following lines to your <code>pyproject.toml</code> file,
    force_and_stress = "/path/to/python_function:force_and_stress"


    def structure(constants, additions):
== Related tags ==
        """Defines the PLUGINS/STRUCTURE interface"""
{{TAG|PLUGINS/FORCE_AND_STRESS}},
{{TAG|PLUGINS/LOCAL_POTENTIAL}},
{{TAG|PLUGINS/MACHINE_LEARNING}},
{{TAG|PLUGINS/OCCUPANCIES}},
{{TAG|PLUGINS/STRUCTURE}}


    def occupancies(constants, additions):
[[Category:Howto]]
        """Defines the PLUGINS/OCCUPANCIES interface"""

Latest revision as of 12:50, 19 December 2024

Implementing features over VASP carries a significant overhead, both in term of code development and maintenance. An alternative approach is to use our Python 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.

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 structure(constants, additions):
    """Defines the PLUGINS/STRUCTURE interface"""

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

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

def machine_learning():
    """Defines the PLUGINS/MACHINE_LEARNING interface"""

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

As the names of the input variables suggest,

  1. constants provides a dataclass with quantities computed in VASP that must stay constant through the interface. Typically these include "metadata" such as the lattice vectors, number of grid points, etc. Some interfaces also pass in quantities such as the charge density as constants. Please check the page of the specific plugins' tag for more details on which quantities are available as constants. Alternatively, you may print the contents of constants.
  2. additions stores quantities that are allowed to change in the interface. You must use the syntax additions.<quantity-name> += ... in order to change additions. That is, quantities must be "added" (or subtracted) to additions instead assigning them a new value. We use additions for two reasons. First, it makes sure that you use the memory from VASP; otherwise assigning might create a new array in memory and return zero to VASP. Secondly, adding the values allows multiple compatible plugins running at the same time.

The machine-learning plugin works a bit different. Please refer to its documentation for more details.

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

   PLUGINS/FORCE_AND_STRESS = T        ! Modifies the force and stress at the end of the SCF loop
   PLUGINS/LOCAL_POTENTIAL = T         ! Modifies the local potential every SCF step
   PLUGINS/MACHINE_LEARNING = T        ! Replaces the VASP force/stress engine with a machine-learned interatomic potential
   PLUGINS/OCCUPANCIES = T             ! Modifies NELECT, EFERMI, SIGMA, ISMEAR, EMIN, EMAX, NUPDOWN at the end of the SCF loop
   PLUGINS/STRUCTURE = T               ! Modifies the structure at the end of the SCF loop

Navigate to the relevant INCAR tag pages for further information.

Exposing interfaces through entry-points (advanced)

Consider using entry points in cases where you do not want to move vasp_plugin.py to each new VASP calculation directory. This is also the approach you should take, if you want to distribute your plugin to other users. Within the group "vasp", add the following lines to your pyproject.toml file for each interface you would like to introduce new functions. For example, if you wanted to access the force_and_stress interface through an entry point, add the following lines to your pyproject.toml file,

   force_and_stress = "/path/to/python_function:force_and_stress"

Related tags

PLUGINS/FORCE_AND_STRESS, PLUGINS/LOCAL_POTENTIAL, PLUGINS/MACHINE_LEARNING, PLUGINS/OCCUPANCIES, PLUGINS/STRUCTURE