The xyz.in input file

From GPUMD
Jump to navigation Jump to search

Purpose

  • This file defines the simulation model, such as the initial conditions and boundary conditions.

File format

  • This file should have one of the following formats (empty lines and comments are not allowed):

Format A:

   N M cutoff 0 has_velocity number_of_grouping_methods
   pbc_x pbc_y pbc_z L_x L_y L_z
   t1 x1 y1 z1 m1 [vx1] [vy1] [vz1] [group1_1] [group2_1] ...
   t2 x2 y2 z2 m2 [vx2] [vy2] [vz2] [group1_2] [group2_2] ...
   ...

Format B:

   N M cutoff 1 has_velocity number_of_grouping_methods
   pbc_a pbc_b pbc_c a_x a_y a_z b_x b_y b_z c_x c_y c_z
   t1 x1 y1 z1 m1 [vx1] [vy1] [vz1] [group1_1] [group2_1] ...
   t2 x2 y2 z2 m2 [vx2] [vy2] [vz2] [group1_2] [group2_2] ...
   ...
  • Line 1 of the xyz.in input file
    • N is the number of atoms
    • M is the maximum number of neighbors any atom can ever has. It is the responsibility of the user to use a large enough value of M. If some atom can have more than M neighbors during the simulation, unexpected error may occur and there may be no useful error message. If M is too large, it just wastes some memory. For programmers: the Verlet neighbor list will be allocated a memory chunk of size sizeof(int) * N * M.
    • cutoff is the initial cutoff distance used for building the neighbor list.
    • The next number can be either 1 or 0. If it is 0, the simulation box will be orthogonal; if it is 1, the simulation box will be triclinic.
    • has_velocity can be 1 or 0, which means this file contains or does not contain the initial velocities, respectively.
    • number_of_grouping_methods can be integers from 0 to 2, which is the number of grouping methods that can be referred to in some keywords in the run.in file.
  • Line 2 of the xyz.in input file
    • If the box is orthogonal, the first three items, pbc_x, pbc_y, and pbc_z, can only be 1 or 0. If pbc_x is 1, it means that periodic boundary conditions will be applied to the x direction; if pbc_x is 0, it means that free boundary conditions will be applied to the x direction. Similar descriptions apply to the other two directions. The next three items, L_x, L_y, and L_z, are the initial lengths of the (rectangular) simulation box along the x, y, and z directions, respectively.
    • If the box is triclinic, the first three numbers correspond to pbc_a, pbc_b, and pbc_c, which have similar meanings as pbc_x, pbc_y, and pbc_z, but for the [math]\boldsymbol{a}[/math], [math]\boldsymbol{b}[/math], and [math]\boldsymbol{c}[/math] directions as specified by the remaining nine numbers in this line:

$$\boldsymbol{a} = a_x \boldsymbol{e}_x + a_y \boldsymbol{e}_y + a_z \boldsymbol{e}_z;$$ $$\boldsymbol{b} = b_x \boldsymbol{e}_x + b_y \boldsymbol{e}_y + b_z \boldsymbol{e}_z;$$ $$\boldsymbol{c} = c_x \boldsymbol{e}_x + c_y \boldsymbol{e}_y + c_z \boldsymbol{e}_z;$$

These vectors define the simulation box and there is no restriction on the values of the vector components, but the user is responsible for the compatibility between the initial atom coordinates and the simulation box.

  • Line 3 of the xyz.in input file
    • t1 is the type of atom 1. The atom type will be used to determine which potential parameters to use. We use integers to record the atom types and the indices start from 0.
    • x1, y1, and z1 are the coordinates of this atom.
    • m1 is the mass of this atom.
    • if has_velocity is 1, the next 3 items are the initial velocity components of this atom.
    • if number_of_grouping_methods is larger than zero, the next items are the group labels of this atom in these grouping methods. That is, group1_1 specifies which group this atom belongs to using the first grouping method; group2_1 specifies which group this atom belongs to using the second grouping method. We use integers to record the group labels and the indices start from 0. The group labels will be used for some keywords in the run.in file.
  • Similarly, the [math](m+2)[/math]th line gives the information for the [math]m[/math]th atom. This file should have (N+2) lines.
  • Units:
    • The mass should be given in units of the unified atomic mass unit (amu).
    • The cutoff distance, box lengths and atom coordinates should be given in units of angstrom.
    • Velocities should be in the natural units adopted in GPUMD, i.e., eV [math]^{1/2}[/math] amu[math]^{-1/2}[/math]. This is usually guaranteed, because one will probably use the dump_restart command to produce an xyz.in file which contains the velocity data. Otherwise, one would probably not prepare velocity data in the xyz.in file.

Tips

  • All the keywords but compute in the run.in file will use the first grouping method and there is no need (or no way) to choose a grouping method for these keywords. In contrast, one needs to specify a grouping method for the compute keyword. This might be changed in a future version. The user needs to make sure that the required grouping data have been properly prepared in the xyz.in file.
  • A valid xyz.in file is a valid XYZ file that can be visualized by the VMD code. Before this, one has to rename the file, giving it a suffix of .xyz.
  • To distinguish between different layers of a layered material, one can assign different groups to layers and use the potential_definition keyword to define the potentials through those groups.

How to prepare the xyz.in file?

  • There are no functionalities for building simulation models within GPUMD. Users of GPUMD are supposed to be able to build simulation models by their own.
  • You can use any programming language to generate this file. In our tutorials, we have used Matlab.
  • One of the developers, Alexander J. Gabourie, has written some python scripts for pre-processing and post-processing data related to GPUMD.
  • A graduate student, Ke Xu, is also publishing some python scripts for pre-processing and post-processing data related to GPUMD.