POTCAR (cusp.potcar)

The class VaspPotcarData is used to represent the VASP pseudo-potentials used as the inputs for a VASP calculation. To this end the class implements the simple from_structure() method that creates the pseudo-potential inputs for VASP calculations. Based on the input structure and the optionally passed potcar names and versions this function queries the database for the requested potentials and automatically builds the list of potentials that can be passed via the calculation’s input.potcar option (see also the following section and the example given at the end of this section)


Note that the VaspPotcarData class was introduced to respect the copyright enforced on the VASP pseudo-potentials. Because of that no actual contents of the original pseudo-potential are stored to this node to avoid any copyright infringement when exporting and sharing the calculation. Rather than storing the actual contents only a link to the corresponding pseudo-potential data stored in the database is added such that the node is independent of the underlying data.

Generating Pseudo-Potential Inputs for VASP Calculations

classmethod VaspPotcarData.from_structure(structure, functional, potcar_params={})

Create potcar input data for a given structure and functional.

Reads elements present in the passed structure and builds the input list of VaspPotcarData instances defining the potentials to be used for each element. By default the potential names are assumed to equal the corresponding element names and potentials of the latest version are used. This default behavior can be changed on a per element basis by using the potcar_params dictionary to explicitly define the potential name and / or version to be used for a given element

Assume a structure containig elements ‘A’ and ‘B’. For both elements the potentials with name ‘A_pv’ and ‘B_pv’ should be used and additionally element ‘B’ requires the use of a specific potential version, i.e. version 10000101 (Note that the version number is simply an integer representation of the creation date found in the potcar files title in the format YYYYMMDD) The above can be achived by passing the following potcar_params to the method:

potcar_params = {
    'A': {'name': 'A_pv'},
    'B': {'name': 'B_pv', 'version': 10000101},


Alternatively it is also possible to use the potcar_params to pass a simple list defining the potential names (i.e. A_pv, B_pv, …) to be used for the calculation (for all elements in the structure not defined by the passed list the default potentials will be used!) In that case potentials of the latest version are used and the method tries to figure out the elements corresponding to the potential name automatically. Because of that: make sure that each potential name starts with the corresponding element name (case sensitive!) followed by any non-letter character, for instance: Ge_d_GW, Li_sv, Cu, H1.75, etc…

  • structure (Structure, Poscar, StructureData or VaspPoscarData) – input structure for which the potential list is generated
  • functional (str) – functional type of the used potentials, accepted functionals inputs are: ‘lda_us’, ‘lda’, ‘lda_52’, ‘pbe’, ‘pbe_52’, ‘pbe_54’, ‘pw91_us’ and ‘pw91’.
  • potcar_params (dict or list) – optional dictionary overriding the default potential name and version used for the element given as key or a list of potential names to be used for the calculation


In the following some examples are given to show how the aiida_cusp.data.VaspPotcarData.from_structure() method can be used to initialize the pseudo-potential inputs for a VASP calculation. To test this functionality a test structure is required. In the following example a simple fcc structure is used to demonstrate the process of the pseudo-potential setup:

>>> from pymatgen import Structure, Lattice
>>> from aiida.plugins import DataFactory
>>> VaspPotcarData = DataFactory('cusp.potcar')
>>> lattice = Lattice.cubic(3.524)
>>> structure = Structure.from_spacegroup(225, lattice, ["Cu"], [[0.0, 0.0, 0.0]])

Simply passing the structure and the desired functional to the method without specifying any potcar_params initializes the pseudo-potential list with the default settings. This means: For each element present in the structure the database is queried for a pseudo-potential with the defined functional and a potential name matching the element name. From the list of potentials matching these requirements the potential with the highest version number will be return as input potential:

>>> potcar = VaspPotcarData.from_structure(structure, 'pbe')
>>> potcar
{'Cu': <VaspPotcarData: uuid: 0ea424b7-9b9e-446a-8d44-7690cb0006d7 (unstored)>}
>>> print("{} {} {}".format(potcar['Cu'].name, potcar['Cu'].version, potcar['Cu'].functional))
Cu 20010105 pbe

If your calculation requires a different potential, for instance the Cu_pv potential, the above shown default behavior can be overridden by passing the desired potential parameters to the function using the potcar_params dictionary. To use the Cu_pv potential instead of the Cu potential, chosen by default, the following potcar_params need to passed:

>>> potcar = VaspPotcarData.from_structure(structure, 'pbe', potcar_params={'Cu': {'name': 'Cu_pv'}})
>>> potcar
{'Cu': <VaspPotcarData: uuid: c55928e9-3f3a-4d03-87f7-5b2c4be5fd9a (unstored)>}
>>> print("{} {} {}".format(potcar['Cu'].name, potcar['Cu'].version, potcar['Cu'].functional))
Cu_pv 20000906 pbe

Note that the potcar_params also allows a ‘version’ key for each element to not only define the potential’s name to be used but also potentially fix the potential’s version. However, since in the above example only the potential name is changed and the version remains unchanged (i.e. whatever highest version found) the above given is equivalent to passing the pseudo-potential name only:

>>> potcar = VaspPotcarData.from_structure(structure, 'pbe', potcar_params=['Cu_pv'])
>>> potcar
{'Cu': <VaspPotcarData: uuid: 1f6ea785-876f-4942-9f30-51a8eac39573 (unstored)>}
>>> print("{} {} {}".format(potcar['Cu'].name, potcar['Cu'].version, potcar['Cu'].functional))
Cu_pv 20000906 pbe