How to import and use pseudopotentials#

In this guide we will go through how to import and use the pseudopotentials (PAW datasets) in aiida-vasp.

As we know, any VASP calculation relies on potentials provided by the POTCAR files.

The actual POTCAR in the calculation should be concatenated from multiple POTCARs provided by the dataset in the same order as the symbols appear in the POSCAR. Incorrectly ordering or misuse of the POTCAR files are common mistakes when deploying VASP calculation by hand.

When using aiida-vasp, the POTCAR files are managed automatically. First, we need to make them available to AiiDA-VASP. These are usually supplied by the VASP team and is part of the license. Each POTCAR dataset is an archive (.tar.gz or tgz) containing multiple subfolders, the name of the sub-folder is typically referred as the symbol of the POTCAR file it contains.

Hint

Since PAW data files are all named as POTCAR, the only way to tell them apart is to look at the content. However, early releases of the VASP PAW dataset contains mistakes such that the symbol of the POTCAR is not what it say in the file! This will disrupt the routines in aiida-vasp to assign the correct POTCAR for each element.

While aiida-vasp does allow importing only the sets (or even individual potentials) you require, it is more common to import the entire dataset and keep them grouped as a potential family.

AiiDA does more than prepare calculations and send them to a cluster. The main focus of AiiDA lies on tracking data provenance. Importing the POTCAR files into your working AiiDA database yields some advantages:

aiida-vasp stores a unique hash for each file. This can help users navigate when different potentials have very similar looking headers, but do in fact contain a different potential.
POTCAR files uploaded to the database cannot be modified accidentally, thus it is recorded unambiguously, which file was used for which execution of each run.
Storing the file’s contents rather than a link prevents accidentally breaking the link by moving the file away (or renaming it).

How to import a set of POTCAR files#

The command line tools for these tasks can be called through the aiida-vasp command:

$ (aiida-vasp) aiida-vasp potcar --help
Usage: aiida-vasp potcar [OPTIONS] COMMAND [ARGS]...

  Top level command for handling VASP POTCAR files.

Options:
  -v, --verbosity [notset|debug|info|report|warning|error|critical]
                                  Set the verbosity of the output.
  -h, --help                      Show this message and exit.

Commands:
  exportfamily              Export a POTCAR family into a compressed tar...
  fix-inconsistent-symbols  Fix inconsistent families
  integrity                 Check the integrity of a POTCAR family
  listfamilies              List available families of VASP potcar files.
  listsymbols               List available symbols in a POTCAR family group.
  migratefamilies           Migrate the type_string associated with the...
  upload-from-pymatgen      Upload a family of VASP potcar files from...
  uploadfamily              Upload a family of VASP potcar files.

$ aiida-vasp potcar uploadfamily --path=<path> --name=<potential_family> --description=<desc>

Where <path> is the path to the folder or tar archive containing the POTCAR set. The command expects the folder or archive to look like:

<path>/
|
+- Ac/
|  +- POTCAR
|  +- ...
|
+- Ag/
|  +- POTCAR
|  +- ...
...

If it encounters anything different, it will recursively search the given path for subpaths matching this structure and import all the POTCAR files found in that way.

<potential_family> is the label you will use to access the potentials from this set or to specify which potentials you want to use in a particular VASP run. The meaning of <description> is self-explanatory.

Custom sets can simply be arranged in a matching folder structure and then imported using the same command.

Uploading a set of potentials incrementally#

For this purpose, we can use that the uploadfamily command by default adds any POTCAR files not yet uploaded to the family of the given name, for example:

$ aiida-vasp potcar uploadfamily --path=path/to/Ac --name="PBE_custom" --description="A custom set"
$ aiida-vasp potcar uploadfamily --path=other/path/to/Ag --name="PBE_custom"

Note, that the description does not have to be given if the family already exists.

Due to the recursive nature of the search, this also works for combining several small sets of POTCARs in a few commands, without having to arrange them in a different way first.

How to check what potential families are present in the database#

$ aiida-vasp potcar listfamilies

How to access uploaded potentials and search#

The data structure used to find and retrieve potentials is called PotcarData and can be accessed through AiiDA’s data factory as DataFactory('vasp.potcar'). This class provides shortcuts for simple or frequent cases, for complex queries, please refer to the AiiDA documentation on querying the provenance graph.

More advanced searches, like for ranges of properties etc can be done using the QueryBuilder tool, which is part of AiiDA and documented there.

Use:

PotcarData.find(<property>=<value>, <property2>=<value2>, ...)

which returns a list of all stored PotcarData instances fulfilling the criteria. Some important supported <property> entries are:

sha512 - An SHA512 hash of the file contents

title - Title of the potential, typically the title of the POTCAR

element - The chemical element described by this potential

full_name - The name of the containing folder from which it was uploaded. This is used to specify a potential inside a family. Example: Zn_sv_GW

original_file_name - The filename (+ last three directories) from which it was uploaded (May help identifying exactly where it came from).

and for each you supply the <value> which is relevant for you given search.

To find one potential for each element in a list of element names, all from the same family:

mapping = {
   'Ac': 'Ac',
   'Ag': 'Ag_GW'  # or 'Ag_pv', 'Ag_sv_GW', ...
}
potcars_for_elements = PotcarData.get_potcars_dict(
   elements=['Ac', 'Ag', ..], <potential_family>, mapping=mapping)

The mapping dictionary is required to decide which of the variants should be chosen for each element. The mapping can also conveniently be stored in a Dict node for reuse. The potential family is specified with <potential_family>.

How to pass potentials to a VASP calculation#

For a single VASP calculation run, you should at the very minimum use the VaspWorkChain, which takes the family as a database-storable string and a dictionary mapping elements to a particular variant for that element:

from aiida.plugins import DataFactory
from aiida.common.extendeddicts import AttributeDict
from aiida.orm import Str

inputs = AttributeDict()
inputs.potential_family = Str('<potential_family>')
inputs.potential_mapping = DataFactory('dict')(dict={'In': 'In_d', 'As': 'As'})

The VaspWorkChain takes care of finding the right files and concatenating them for you.

For a more complex workflow, the process may be different, it may for example use heuristics to find a default potential for you.