POSCAR: Difference between revisions

From VASP Wiki
VisualWikitext
No edit summary
No edit summary
Line 58: Line 58:
| 1<br />
| 1<br />
| yes
| yes
|  
| The first line is reserved for a free user comment, e.g. a system description. The maximum line length is 40 characters, extra characters are truncated.
|-
|-
| Scaling factor(s)
| Scaling factor(s)
| 1<br />
| 1<br />
| yes
| yes
|  
| This line may contain one or three numbers. If one number is provided it specifies a universal lattice scaling factor <math>s</math>. It is multiplied with the three vectors in the following section to obtain the lattice vectors of the unit cell. Also, the ion positions are scaled with this factor if the "Cartesian" mode is selected (see section "Ion positions"). If the number is negative, it is interpreted as the desired cell volume. Then, the scaling factor <math>s</math> is computed automatically to obtain the desired volume. If three numbers are provided in this line they act as individual scaling factors for the x-,y- and z-Cartesian components for the lattice vectors (and "Cartesian" mode ion positions). In this case all three numbers must be positive.
|-
|-
| Lattice
| Lattice
| 3
| 3
| yes
| yes
|  
| This sections contains three lines defining the lattice vectors. Each line holds the unscaled Cartesian components of one lattice vector. The actual lattice vectors  <math>{\vec a}_1, {\vec a}_2</math> and <math>{\vec a}_3</math> are the product of the given numbers with the lattice scaling factor <code>s</code>. Set the universal scaling factor to 1 if you want to enter the lattice vectors directly and avoid any additional scaling.
|-
| Element names
| 1
| no
| This line lists the elements of the present ions. The given order should match the order of elements appearing in the {{FILE|POTCAR}} file. This line is optional, if omitted the element names are taken from the {{FILE|POTCAR}} file.
|-
| Ions per element
| 1
| yes
| This mandatory line lists how many ions of each element are present. The given order should match the order of elements appearing in the {{FILE|POTCAR}} file.
|-
|-
| Selective dynamics
| Selective dynamics
| 1
| 1
| no
| no
|  
| If the line after the "Ions per element" section contains <code>Selective dynamics</code> it enables the "selective dynamics" feature (actually only the first character is relevant and must be ''S'' or ''s''). This allows to provide extra flags for each atom signaling whether the respective coordinate(s) of this atom will be allowed to change during the ionic relaxation. This setting is useful if only certain shells around a defect or layers near a surface should relax. See also the {{TAG|IBRION}} tag.
|-
|-
| Atom positions<br />
| Ion positions<br />
| #atoms + 1
| #atoms + 1
| yes
| yes
|  
| Here, the ion positions are listed. The first line selects one of the two possible modes how the coordinates <math>x_1, x_2</math> and <math>x_3</math> given in the following lines are interpreted:
 
* "Direct" means the positions are provided in direct (fractional) coordinates:<p><math>{\vec R} = x_1 {\vec a}_1 + x_2 {\vec a}_2 +  x_3 {\vec a}_3,</math></p><p>where <math>{\vec R}</math> is the position vector of an ion.</p>
 
* "Cartesian" specifies that positions are provided in a Cartesian coordinate system. However, the actual ion positions are also multiplied with the universal scaling factor, i.e.<p><math> {\vec R} = s \left( \begin{array}{c}x_1 \\ x_2 \\ x_3\end{array} \right).</math></p>
 
Actually, only the first character on the line is significant and the only key characters recognized are <code>C</code>, <code>c</code>, <code>K</code> or <code>k</code> for switching to the "Cartesian" mode. Everything else will be interpreted as "Direct" mode.
 
The total number of lines with positions must match the total number of ions given in the "Ions per element" section. The ion elements are also derived from there, e.g. if the "Ions per element" section lists <code>5 8</code>, then there must be five ion position lines for the first species, followed by eight ions of the second element. If your are not sure whether you have a correct input please check the {{TAG|OUTCAR}} file, which contains both the final Cartesian components of the vector <math>{\vec R}</math> and the positions in direct (fractional) coordinates.
 
If the selective dynamics feature is enabled on each coordinate triplet is followed by three additional logical flags, i.e. each is either <code>T</code> or <code>F</code> for true and false, respectively. This determines whether to allow changes of the coordinates or not. If the line selective dynamics is removed from the {{TAG|POSCAR}} file this flag will be ignored (and internally set to <code>T</code>).
{{NB|mind|The flags refer to the positions of the ions in direct coordinates, no matter whether the positions are entered in "Cartesian" or "Direct" coordinate modes.}} For example, consider the following ion specification:
...
<span style="color:#A82C35">Selective dynamics</span>
Cartesian
0.00 0.00 0.00 <span style="color:#A82C35">T F T</span>
1.27 0.98 0.32 <span style="color:#A82C35">F T F</span>
...
Here, the first atom is allowed to move into the direction of the first and third direct lattice vector. The second atom may only move in the second lattice vector direction.
 
If no initial velocities are provided, the file may end here.
|-
|-
| Lattice velocities<br />
| Lattice velocities<br />
Line 93: Line 123:
| variable
| variable
| no
| no
|  
| Entering velocities by hand is rarely done (one important case is e.g. using the tags {{TAG|IBRION}}=0 and {{TAG|SMASS}}=-2), but if done the velocities are provided at the end of the {{TAG|POSCAR}} file very similalry to the positions.  As previously the first line supplies a switch between cartesian coordinates and direct coordinates. On the next lines the initial velocities are provided. They are given in units <math>\AA</math>/fs (no multiplication with the scaling factor in this case) or (direct lattice vector/timestep).
When the initial velocities are supplied in the {{TAG|POSCAR}} and the tags {{TAG|IBRION}}=0 and {{TAG|SMASS}}=-2) are set, the velocities are kept constant during the MD allowing to calculate the energy for a set of different linear dependent positions (for instance frozen phonons and dimers with varying bond-length).
 
'''Mind''': For {{TAG|IBRION}}=0 and {{TAG|SMASS}}=-2 the actual steps taken are {{TAG|POTIM}} times read velocities. To avoid ambiguities, set {{TAG|POTIM}} to 1. In this case
the velocities are simply interpreted as vectors, along which the ions are moved. For the ''cartesian'' switch, the vector is given in cartesian coordinates (<math>\AA</math>, no multiplication with the scaling factor in this case) for the ''direct'' switch the vector is given in direct coordinates.
|-
|-
| MD extra
| MD extra
| variable
| variable
| no
| no
|  
| The predictor-corrector coordinates are only provided to continue a molecular dynamic run from a {{TAG|CONTCAR}} file of a previous run, they can not be entered by hand.
|}
|}


* '''Line 1''' The first line is treated as a comment line (you should write down the name of the system).
===Examples===


  Cubic BN
  Cubic BN
Line 121: Line 155:
   ....
   ....
   ....
   ....
or
Cubic BN
    3.57
  0.0 0.5 0.5
  0.5 0.0 0.5
  0.5 0.5 0.0
    B N
    1 1
Direct
  0.00 0.00 0.00
  0.25 0.25 0.25
* '''Line 1''' The first line is treated as a comment line (you should write down the name of the system).
* '''Line 2''' The second line provides a universal scaling factor (lattice constant), which is used to scale all lattice vectors and all atomic coordinates (of this value is negative it is interpreted as the total volume of the cell).
* '''Lines 3-5''' On the following three lines the three lattice vectors defining the unit cell of the system are given (first line corresponding to the first lattice vector, second to the second, and third to the third).
* '''Line 6''' The sixth line specifies the constituting elements (in the order how they appear in the {{TAG|POTCAR}} file).
* '''Line 7''' The seventh line supplies the number of atoms per atomic species (one number for each atomic species). The ordering must be consistent with the {{TAG|POTCAR}} and the {{TAG|INCAR}} file.
* '''Line 8 (optional)''' The eighth line switches to selective dynamics (only the first character is relevant and must be ''S'' or ''s''). This mode allows to provide extra flags for each atom signaling whether the respective coordinate(s) of this atom will be allowed to change during the ionic relaxation. This setting is useful if only certain shells around a defect or layers near a surface should relax.
'''Mind''': The selective dynamics input tag is optional: the seventh line supplies the switch between cartesian and direct lattice if the Selective dynamics tag is omitted.
* '''Section: atom coordinates''' The eighth line (or ninth line if selective dynamics is switched on) specifies whether the atomic positions are provided in cartesian coordinates or in direct coordinates (respectively fractional coordinates). Only the first character on the line is significant and the only key characters recognized by VASP are ''C'', ''c'', ''K'' or ''k'' for switching to the cartesian mode.
The next lines give the three coordinates for each atom. In the direct mode the positions are given by <br />
<math>{\vec R} = x_1 {\vec a}_1 + x_2 {\vec a}_2 +  x_3 {\vec a}_3</math> <br />
where <math>{\vec a}_{1...3}</math> are the three basis vectors, and <math>x_{1...3}</math> are the supplied values. In the cartesian mode the positions are only scaled by the factor <math>s</math> on the second line of the {{TAG|POSCAR}} file
<math> {\vec R} = s \left( \begin{array}{c}
                        x_1 \\ x_2 \\ x_3
                      \end{array} \right). </math>
The ordering of these lines must be correct  and consistent with the number of atoms per species on the sixth line. If your are not sure whether you have a correct input please check the {{TAG|OUTCAR}} file, which contains both the final components of the vector <math>{\vec R}</math> and the positions in direct (fractional) coordinates. If selective dynamics are switched on each coordinate a triplet is followed by three additional logical flags determining whether to allow changes of the coordinates or not (in our example the 1. coordinate of atom 1 and all coordinates of atom 2 are fixed). If the line selective dynamics is removed from the {{TAG|POSCAR}} file this flag will be ignored (and internally set to ''.T.'').
'''Mind''': The flags refer to the positions of the ions in direct coordinates, no matter whether the positions are entered in cartesian or direct coordinates. Therefore, in the example given above the first ion is allowed to move into the direction of the first and second direct lattice vector.
If no initial velocities are provided, the file may end here. For molecular dynamics the velocities are initialised randomly according to a Maxwell-Boltzmann distribution at the initial temperature {{TAG|TEBEG}}.
* '''Section: atom velocities''' Entering velocities by hand is rarely done (one important case is e.g. using the tags {{TAG|IBRION}}=0 and {{TAG|SMASS}}=-2), but if done the velocities are provided at the end of the {{TAG|POSCAR}} file very similalry to the positions.  As previously the first line supplies a switch between cartesian coordinates and direct coordinates. On the next lines the initial velocities are provided. They are given in units <math>\AA</math>/fs (no multiplication with the scaling factor in this case) or (direct lattice vector/timestep).
When the initial velocities are supplied in the {{TAG|POSCAR}} and the tags {{TAG|IBRION}}=0 and {{TAG|SMASS}}=-2) are set, the velocities are kept constant during the MD allowing to calculate the energy for a set of different linear dependent positions (for instance frozen phonons and dimers with varying bond-length).
'''Mind''': For {{TAG|IBRION}}=0 and {{TAG|SMASS}}=-2 the actual steps taken are {{TAG|POTIM}} times read velocities. To avoid ambiguities, set {{TAG|POTIM}} to 1. In this case
the velocities are simply interpreted as vectors, along which the ions are moved. For the ''cartesian'' switch, the vector is given in cartesian coordinates (<math>\AA</math>, no multiplication with the scaling factor in this case) for the ''direct'' switch the vector is given in direct coordinates.
* '''Section: predictor-corrector coordinates'''
The predictor-corrector coordinates are only provided to continue a molecular dynamic run from a {{TAG|CONTCAR}} file of a previous run, they can not be entered by hand.
----
----
[[The_VASP_Manual|Contents]]
[[The_VASP_Manual|Contents]]


[[Category:Files]][[Category:Input files]]
[[Category:Files]][[Category:Input files]]

Revision as of 14:00, 8 April 2022

The POSCAR file is a mandatory VASP input file. It is a plain text file and contains at least the lattice geometry and the ionic positions. Optionally, also starting velocities for a molecular-dynamics simulation can be provided here. This file shares its format with VASP output file CONTCAR. That may contain an additional section with predictor-corrector coordinates necessary for restarting molecular-dynamics runs.

Creating a POSCAR file is often the starting point of VASP-supported research. It can be written manually or obtained from various online materials and crystallographic databases providing a download in the POSCAR file format.

File format

Minimal example

In its simplest form the POSCAR file contains basic information about the lattice, per-element number of ions and their positions. This is sufficient in most situation where a VASP calculation is started from scratch. Have a look at this example for cubic boron nitride: 

Cubic BN
3.57
0.0 0.5 0.5
0.5 0.0 0.5
0.5 0.5 0.0
B N
1 1
Direct
0.00 0.00 0.00 
0.25 0.25 0.25

As indicated by the text coloring there are four blocks corresponding to the following file contents:

Comment line

The first line is reserved for a free user comment, e.g. a system description.

Scaling factor and lattice

In this block the first line specifies a universal lattice scaling factor Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): s . The next three lines define the lattice vectors. Each line holds the unscaled Cartesian components of one lattice vector. The actual lattice vectors Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {\displaystyle {\vec a}_1, {\vec a}_2} and Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {\displaystyle {\vec a}_3} are the product of the given numbers with the lattice scaling factor. Set the universal scaling factor to 1 if you want to enter the lattice vectors directly and avoid any additional scaling.

Ion elements and numbers:

This section defines how many ions of each element are present. The first line lists the element names, the second specifies the number of ions for each element. The given order should match the order of elements appearing in the POTCAR file.

Ion positions:

Finally, the ion positions are listed in this section. The first line selects one of the two possible modes how the coordinates Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {\displaystyle x_1, x_2} and Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {\displaystyle x_3} given in the following lines are interpreted:

  • "Direct" means the positions are provided in direct (fractional) coordinates:

    Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {\displaystyle {\vec R} = x_1 {\vec a}_1 + x_2 {\vec a}_2 + x_3 {\vec a}_3,}

    where Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {{\vec R}} is the position vector of an ion.

  • "Cartesian" specifies that positions are provided in a Cartesian coordinate system. However, the actual ion positions are also multiplied with the universal scaling factor, i.e.

    Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {\displaystyle {\vec R} = s \left( \begin{array}{c}x_1 \\ x_2 \\ x_3\end{array} \right).}

The total number of lines with positions must match the total number of ions given in the previous section. The ion elements are also derived from there, i.e. in the example above it is implied that the list of positions contains one boron ion, followed by one nitrogen nuclei.

Full format specification

The POSCAR file format is constructed from multiple sections arranged in a predefined order. Some sections contain only a single line, others span over many lines, some may even be omitted. The following list defines the section order and their contents:

Section Number of lines
 Mandatory
 Content
Comment 1
 yes The first line is reserved for a free user comment, e.g. a system description. The maximum line length is 40 characters, extra characters are truncated.
Scaling factor(s) 1
 yes This line may contain one or three numbers. If one number is provided it specifies a universal lattice scaling factor Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): s . It is multiplied with the three vectors in the following section to obtain the lattice vectors of the unit cell. Also, the ion positions are scaled with this factor if the "Cartesian" mode is selected (see section "Ion positions"). If the number is negative, it is interpreted as the desired cell volume. Then, the scaling factor Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): s is computed automatically to obtain the desired volume. If three numbers are provided in this line they act as individual scaling factors for the x-,y- and z-Cartesian components for the lattice vectors (and "Cartesian" mode ion positions). In this case all three numbers must be positive.
Lattice 3 yes This sections contains three lines defining the lattice vectors. Each line holds the unscaled Cartesian components of one lattice vector. The actual lattice vectors Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {\displaystyle {\vec a}_1, {\vec a}_2} and Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {\displaystyle {\vec a}_3} are the product of the given numbers with the lattice scaling factor s. Set the universal scaling factor to 1 if you want to enter the lattice vectors directly and avoid any additional scaling.
Element names 1 no This line lists the elements of the present ions. The given order should match the order of elements appearing in the POTCAR file. This line is optional, if omitted the element names are taken from the POTCAR file.
Ions per element 1 yes This mandatory line lists how many ions of each element are present. The given order should match the order of elements appearing in the POTCAR file.
Selective dynamics 1 no If the line after the "Ions per element" section contains Selective dynamics it enables the "selective dynamics" feature (actually only the first character is relevant and must be S or s). This allows to provide extra flags for each atom signaling whether the respective coordinate(s) of this atom will be allowed to change during the ionic relaxation. This setting is useful if only certain shells around a defect or layers near a surface should relax. See also the IBRION tag.
Ion positions
 #atoms + 1 yes Here, the ion positions are listed. The first line selects one of the two possible modes how the coordinates Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {\displaystyle x_1, x_2} and Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {\displaystyle x_3} given in the following lines are interpreted:
  • "Direct" means the positions are provided in direct (fractional) coordinates:

    Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {\displaystyle {\vec R} = x_1 {\vec a}_1 + x_2 {\vec a}_2 + x_3 {\vec a}_3,}

    where Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {{\vec R}} is the position vector of an ion.

  • "Cartesian" specifies that positions are provided in a Cartesian coordinate system. However, the actual ion positions are also multiplied with the universal scaling factor, i.e.

    Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {\displaystyle {\vec R} = s \left( \begin{array}{c}x_1 \\ x_2 \\ x_3\end{array} \right).}

Actually, only the first character on the line is significant and the only key characters recognized are C, c, K or k for switching to the "Cartesian" mode. Everything else will be interpreted as "Direct" mode.

The total number of lines with positions must match the total number of ions given in the "Ions per element" section. The ion elements are also derived from there, e.g. if the "Ions per element" section lists 5 8, then there must be five ion position lines for the first species, followed by eight ions of the second element. If your are not sure whether you have a correct input please check the OUTCAR file, which contains both the final Cartesian components of the vector Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): {{\vec R}} and the positions in direct (fractional) coordinates.

If the selective dynamics feature is enabled on each coordinate triplet is followed by three additional logical flags, i.e. each is either T or F for true and false, respectively. This determines whether to allow changes of the coordinates or not. If the line selective dynamics is removed from the POSCAR file this flag will be ignored (and internally set to T).

Mind: The flags refer to the positions of the ions in direct coordinates, no matter whether the positions are entered in "Cartesian" or "Direct" coordinate modes.
For example, consider the following ion specification: 
...
Selective dynamics
Cartesian
0.00 0.00 0.00 T F T
1.27 0.98 0.32 F T F
...

Here, the first atom is allowed to move into the direction of the first and third direct lattice vector. The second atom may only move in the second lattice vector direction.

If no initial velocities are provided, the file may end here.

Lattice velocities
 ? no
Empty spheres
 ? no
Velocities variable no Entering velocities by hand is rarely done (one important case is e.g. using the tags IBRION=0 and SMASS=-2), but if done the velocities are provided at the end of the POSCAR file very similalry to the positions. As previously the first line supplies a switch between cartesian coordinates and direct coordinates. On the next lines the initial velocities are provided. They are given in units Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): \AA /fs (no multiplication with the scaling factor in this case) or (direct lattice vector/timestep).

When the initial velocities are supplied in the POSCAR and the tags IBRION=0 and SMASS=-2) are set, the velocities are kept constant during the MD allowing to calculate the energy for a set of different linear dependent positions (for instance frozen phonons and dimers with varying bond-length).

Mind: For IBRION=0 and SMASS=-2 the actual steps taken are POTIM times read velocities. To avoid ambiguities, set POTIM to 1. In this case the velocities are simply interpreted as vectors, along which the ions are moved. For the cartesian switch, the vector is given in cartesian coordinates (Failed to parse (SVG (MathML can be enabled via browser plugin): Invalid response ("Math extension cannot connect to Restbase.") from server "https://www.vasp.at/wiki/restbase/vasp.at/v1/":): \AA , no multiplication with the scaling factor in this case) for the direct switch the vector is given in direct coordinates.

MD extra variable no The predictor-corrector coordinates are only provided to continue a molecular dynamic run from a CONTCAR file of a previous run, they can not be entered by hand.

Examples

Cubic BN
3.57
0.0 0.5 0.5
0.5 0.0 0.5
0.5 0.5 0.0
B N
1 1
Selective dynamics
Cartesian
0.00 0.00 0.00 T T F
0.25 0.25 0.25 F F F
Cartesian
0.01 0.01 0.01
0.00 0.00 0.00
optionally predictor-corrector coordinates 
   given on file CONTCAR of MD-run
  ....
  ....

Contents

Retrieved from "https://www.vasp.at/wiki/index.php?title=POSCAR&oldid=16701"