The VASP Scripter AddOn

This tutorial shows how to use the graphical user interface QuantumATK to set up your VASP calculations. The plugin can be used to generate VASP input files for a wide range of tasks, including for instance total energy calculations, bandstructures, relaxations, molecular dynamics and NEB calculations.



Click to read information about all input () and output () VASP files.




This tutorial is not a user guide to VASP, nor does QuantumWise provide access to the VASP code. It is assumed that the user has already obtained and installed VASP from its official source, and is familiar with the code.


The VASP pseudopotential libraries

You can use the VASP Scripter in QuantumATK to create the POTCAR file as well. In order to do that you need the VASP pseudopotential libraries (POTCAR files). Follow the instruction below to set up the VASP Scripter correctly.

This step can be skipped in case the pseudopotential libraries are not installed on the machine where you run QuantumATK. You will however then have to create your POTCAR file manually.

Even if VASP is not configured to run on the platform where you use QuantumATK, you can still copy the pseudopotential libraries over to it, in order to have the plugin generate POTCAR files properly. The plugin does not attempt to launch VASP, it just looks for the pseudopotential files.

Ensure first that you have installed the VASP plugin on QuantumATK. If not, open QuantumATK and go to the Help ‣ AddOn Manager to install it:


Create the structure in QuantumATK

  • Let’s create a structure in QuantumATK (a candidate object for VASP). So, open the Builder (click the builder_icon icon) and click Add ‣ From Database then (for example) select the AgGaS2 configuration, and add it to the Stash by clicking the plus_icon icon:


Export the structure to the VASP scripter

  • Open the VASP scripter: Custom Scripter ‣ Scripters ‣ VASP Scripter (see the picture above) and drag ‘n’ drop the AgGaS2 structure from the stash to the VASP scripter. Then this structure is shown in the Configuration tab of the VASP scripter.


Setup tab

  • The next steps are to set up the main computational parameters and methods in the VASP scripter. To do that, click the Setup tab, and you will see the following layout:


  • In there click the Manage pseudopotential directories button to set the path to the pseudopotential libraries:



These settings affect the Element-specifying settings in the Setup tab, as well as some other settings.

For each exchange-correlation functional, e.g., US-LDA or PAW-PBE, you can individually specify the directory containing the corresponding pseudopotential library. It is not possible to type in the path; instead, use the Change… buttons.


If your psedopotential libraries all reside in sub-directories of a common reference directory, you can facilitate the process by first specifying this directory in the top of the widget, and then click Apply. This will append the conventional sub-directory names to the reference directory. If your sub-directories are named differently, you will still need to select them individually, but the reference directory will then be used as a starting point.

When you click Close and save, your directory choices are stored for the future use in the file PPdirconfig.json, located in .quantumatk/VASPScripter in your home directory. The Pseudopotential version column on the Setup tab should now change, reflecting the available choices for each element. To make sure you have specified the correct directories for each type of pseudopotential, you can go over the different exchange-correlation (XC) functionals and the pseudopotential types on the Setup tab, i.e., you should make sure that none of them displays None available. However, only the basic XC types need to be checked, i.e., LDA, PBE and GGA-91.

The other objects on the setup tab

  • Presently, the scripter can be used for setting up some predefined type of VASP calculations (tasks):


If you choose the Bandstructure task, then the corresponding Bandstructure tab is activated.


To learn about NEB simulations for VASP, you may read the Using QuantumATK to work with Nudged Elastic Band calculations in VASP tutorial.

  • Use the corresponding drop-down lists to select the Pseudopotential type, and Exchange-correlation functional:



  • Use the checkboxes to specify whether Spin-orbit coupling should be included or not (and if so, what Quantization axis to use), or to perform a Spin-polarized calculation:



We notice that there exist a few additional options for hybrid potentials. Be aware that hybrid functionals cannot be combined, however, with the Hubbard U model. And including spin-orbit interaction results in a much more intensive computation, in part due to some limitations of VASP. So, keep the Spin-orbit coupling checkbox unchecked for scalar-relativistic calculations.

  • To use an onsite Coulomb interaction term, the so-called Hubbard U model, tick the corresponding checkbox. A few choices are offered for the algorithm and verbosity.


  • Each element in the configuration is represented by a row in the table of element-specific settings. If any of the elements has more than one variant of a pseudopotential (e.g., differing by whether semi-core states are treated as valence electrons or not), you can select which version you want to use via the dropdown list in the Pseudopotential version column.
  • If you turn on the onsite Coulomb interaction term, you can then specify the on-site parameters U and J (the element-specific U and J values will be discussed afterwards), as well as the quantum number \(l\) of the orbitals to which these parameters would be applied for each element.


Accuracy tab

  • Next switch to the Accuracy tab. Here, you can select the general precision settings (the PREC tag in VASP, defining the FFT meshes and the default energy cut-off), and the size and type of the k-point sampling mesh. The number of divisions along each unit vector can be chosen independently, and you can use the buttons on the right to quickly make the mesh more dense or sparse.

You can either manually set the energy cutoff for the plane-wave basis set - e.g., if you need to keep it constant across a series of calculations involving different structures with different elements - or (by selecting Default) leave it up to VASP to determine the cut-off depending on the elements in your configuration.


Electrons tab

  • On the Electrons tab you select the algorithm to be used for the optimization of the electron wave functions and the charge density during the self-consistent calculation of the Kohn-Sham equations, and the number of bands to include. Under Smearing you select the algorithm for broadening the step-like Fermi distribution, and the broadening width Sigma (if applicable). Under Convergence you select the minimum and maximum number of electronic iterations to be done in the self-consistent calculation, and the total energy change between iterations that will be used as the stopping criterion.


Ions tab

  • The Ions tab is only available if one chooses a task in the Setup tab that allows atoms to move during the run, i.e., for structural optimization, MD, or NEB tasks. For a Structural optimization you can select the maximum number of steps, the force scaling parameter (POTIM), the algorithm to use for performing the relaxation, and which of the cell parameters (volume, shape and/or internal parameters) are allowed to relax.


It is not possible to fix the cell shape and relax both volume and internal positions in a single VASP run. If you make this selection, the Scripter will adjust it for you. Also, the stopping criterion for the relaxation is, by default, the energy change equal to 10x the electronic stopping criterion. You can specify a different criterion, either in terms of energy change or in terms of forces.


  • Clicking the Constraints button you open the Constraints Editor as shown in the picture above. In this editor, you can see the structure you have built (assuming you have already drop it from the Stash to the VASP Scripter). You can edit it by clicking the Add tag from selection, and then the set of tags appears at the right sub-area of the scripter’s window where you can select an atom or a group of atoms and set constraints on atom movements along specific directions.

Properties tab

  • By ticking the available options on the Properties tab, you select to save quantities like the charge density, wave functions, etc. into the corresponding VASP output files (CHG/CHRCAR, WAVECAR, ELFCAR, LOCPOT):


Configuaration tab

  • The Configuration tab is just the first tab you see when you paste an object from the Builder’s Stash in the VASP scripter:


Bandstructure tab

  • Choosing Setup ‣ Task ‣ Bandstructure (in the Setup tab) the Bandstructure tab is activated. Here, you can set the symmetry points of the Brillouin zone route as well as the number of k-points per segment (symmetry line):



You can use the Brillouin zone viewer plugin to visualize the Brillouin zone of your structure with the high symmetry points highlighted. You can find the plugin in the Builder under Bulk Tools ‣ Brillouin Zone Viewer


Custom Options tab


  • This tab gives the option to extend the INCAR file’s content by adding more computational parameters to it. You can find more detailed information, e.g., here. Note that you can also see the INCAR file clicking Setup ‣ INCAR Preview button:


Generate VASP files

  • Once you are satisfied with your settings, select the directory where you want to save the VASP files by clicking the “” button at the top of the Scripter in the Setup tab, and press the save button in the top left corner (or select Save from the menu).


For a NEB simulation, the POSCAR files for each image are placed in sub-directories called 00, 01, 02, … .

You should now be able to use the generated files to run a VASP calculation, either directly in the directory where the files were saved, or by copying this directory to a different machine where VASP is installed.