Pseudopotentials and PAW potentials (POTCAR)
********************************************

VASP requires that pseudopotentials or PAW potentials be used for each
element. Such potentials are distributed with VASP in files called
POTCAR or POTCAR.Z.

AMS does not include such POTCAR files. You need to download them
separately.


POTCAR Library
==============

The AMS VASP Engine will construct combined POTCAR files from the
corresponding elemental POTCAR files. The elemental POTCAR files need
to be structured into a **POTCAR Library**.

For clarity, AMS includes a set of "dummy" POTCAR files in the
directory "$AMSHOME/atomicdata/VASP/test_potcars":

   $AMSHOME/atomicdata/VASP/test_potcars/C_compressed/POTCAR.Z
   $AMSHOME/atomicdata/VASP/test_potcars/C/POTCAR
   $AMSHOME/atomicdata/VASP/test_potcars/Cu/POTCAR
   $AMSHOME/atomicdata/VASP/test_potcars/H1.25/POTCAR
   $AMSHOME/atomicdata/VASP/test_potcars/H.75/POTCAR
   $AMSHOME/atomicdata/VASP/test_potcars/H/POTCAR
   $AMSHOME/atomicdata/VASP/test_potcars/Na/POTCAR
   $AMSHOME/atomicdata/VASP/test_potcars/Na_pv/POTCAR
   $AMSHOME/atomicdata/VASP/test_potcars/O_h/POTCAR
   $AMSHOME/atomicdata/VASP/test_potcars/O/POTCAR
   $AMSHOME/atomicdata/VASP/test_potcars/O_s/POTCAR
   $AMSHOME/atomicdata/VASP/test_potcars/Ti/POTCAR
   $AMSHOME/atomicdata/VASP/test_potcars/Zn/POTCAR

These POTCAR files just contain single lines of text. They cannot be
used to run real VASP calculations.

With the above structure, the directory
"$AMSHOME/atomicdata/VASP/test_potcars" can be set as the **POTCAR
Library** input option.

You should set up your own POTCAR Library directory with the real
POTCAR files.

Note:

  We recommend to manually uncompress the POTCAR.Z files, to not rely
  on the automatic extraction by the AMS VASP engine. The automatic
  extraction is not supported on Windows.


The VASP Engine uses vasp.label if set; otherwise the atomic symbol
===================================================================

The POTCAR file used for an atom depends on the "vasp.label" atom
attribute. If this is unset, the atomic element is used instead.

In AMSinput, you can set "vasp.label" on the **Model → Atom Details**
panel.

Example:

   System
     Atoms
       H 1.572 2.389 0.898 vasp.label=H.75          # H.75/POTCAR
       O 3.216 2.131 0.011                          # O/POTCAR
       C 0.679 0.837 0.000                          # C/POTCAR
       H 0.406 0.592 1.016 vasp.label=H1.25         # H1.25/POTCAR
       H 3.529 2.198 0.916                          # H/POTCAR
       C 1.847 1.840 0.010 vasp.label=C_compressed  # C_compressed/POTCAR.Z
       H -0.169 1.276 -0.505 vasp.label=H.75        # H.75/POTCAR
       H 1.569 2.408 -0.866                         # H/POTCAR
       H 0.980 -0.062 -0.518 vasp.label=H1.25       # H1.25/POTCAR
     End
     Lattice
       6.000 0.000 0.000
       0.000 6.000 0.000
       0.000 0.000 6.000
     End
   End


Specifying the POTCAR Library in the input
==========================================

Specify the POTCAR Library using the "POTCARLibrary" input option:

   Engine VASP
      POTCARLibrary /path/to/potcar/library
      ....
   EndEngine

"POTCARLibrary"
   Type:
      String

   GUI name:
      Path to POTCAR library

   Description:
      Path to the POTCAR (pseudopotential) library, as delivered with
      VASP. This library must be accessible on the machine currently
      running AMSinput.                   For example, setting this to
      /library/PBE/PAW/ will use /library/PBE/PAW/Cu/POTCAR as the
      POTCAR file for Cu atoms by default.                   Can also
      be left empty if VASP_PP_PATH is set as an environment variable.
      Special POTCARs (e.g. H.5 instead of H) can be used for
      individual atoms by using the vasp.label atom label.
      Alternatively, custom POTCAR files can be specified using the
      POTCAROverride tag.


Specifying the POTCAR library with the VASP_PP_PATH environment variable
========================================================================

You can also set the "VASP_PP_PATH" environment variable:

   export VASP_PP_PATH="/path/to/potcar/library"
   export SCM_DISABLE_MPI=1

   $AMSBIN/ams -n 1 <<eor
   # ...
   Engine VASP
      # ...
   EndEngine
   eor


Creating a custom POTCAR Library
================================

If you want to consistently use, for example, the hard "O_h"
potentials for all oxygen atoms, then create a new POTCAR Library
directory where "O/POTCAR" is identical to "O_h/POTCAR".

Then you will not need to remember to set the "vasp.label" for all O
atoms for every calculation.


One-off POTCAR override in the input file
=========================================

You can also use specific POTCAR files by setting the **Details →
Expert VASP → POTCARFiles** option. For example, by setting 'Label' to
'H' and setting the 'Path' to "/some/path/PBE_PAW/H.5/POTCAR", AMS
will use this POTCAR file for all H atoms (that do not have a custom
VASP Label).

POTCAR files can also be specified for entire groups of elements or
atoms with a unique VASP Label, using the "POTCAROverride" keyword.
For example:

   System
       Atoms
           H 0.0 0.0 0.0                     # /path/to/potcar/library/H/POTCAR
           H 0.0 0.0 0.8                     # /path/to/potcar/library/H/POTCAR
           O 0.0 0.5 0.4 vasp.label=O_s      # /path/to/potcar/library/O_s/POTCAR
           Ne 5.0 4.0 6.0 vasp.label=MyLabel # /path/to/my/custom/Ne/POTCAR
       End
       Lattice
           ...
       End
   End

   Engine VASP
       ...
       POTCARLibrary /path/to/potcar/library
       POTCAROverride
           POTCARFiles
               Label MyLabel
               Path /path/to/my/custom/Ne/POTCAR
           End
       End
   EndEngine

"POTCAROverride"
   Type:
      Block

   GUI name:
      POTCAR directory override

   Description:
      Selects the pseudopotentials to use for each atomic species.
      Choosing this overrides the default option for each element
      found in POTCARLibrary.

   "POTCARFiles"
      Type:
         Block

      Recurring:
         True

      Description:
         Selects the pseudopotentials to use for each atomic species.

      "Label"
         Type:
            String

         Description:
            Label for an atom corresponding to the vasp.label, or to
            the element symbol if vasp.label is not set.

      "Path"
         Type:
            String

         Description:
            Path to a POTCAR or POTCAR.Z file to use as a
            pseudopotential.
