# The xyz.in input file

Jump to navigation
Jump to search
## How to prepare the

## 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:

- If the box is orthogonal, the first three items,

$$\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`

. - Recently,
`ASE`

(https://gitlab.com/ase/ase) also supported reading and writing the`xyz.in`

input file for`GPUMD`

. Check the`read_gpumd`

and`write_gpumd`

functions in the`io`

module of`ASE`

.