Back to main menu

## Format: GIN

Name: General Utility Lattice Package (GULP) input file

Extension: gin, grs or res

Specification: GULP documentation

Visualization programs: gdis

#### Restrictions

When reading GULP input files (gin, res or grs), Atomsk will always read the positions of atom cores. The "atom names" in the first column should always start with the species symbol (one or two letters) for Atomsk to recognize it. It may be appened by any string or characters (e.g. O1, Ti_2, etc.). If velocities are present, they are saved as auxiliary properties.

If electronic shells are present (in the sense of an ionic core-shell model potential) their positions are also read, but beware that they will be transferred for output only to formats that support it (like GULP files themselves, or DL_POLY CONFIG files). For Atomsk to associate cores and shells correctly, the position of each shell should always appear right after the position of the corresponding core (like in the example below), or all core positions should be contiguous and followed by all shells positions in a matching order. If it is not the case (i.e. if cores and shells are written in any other arbitrary order) one can use the option `-bind-shells`.

If the electric charges of cores (and shells) are defined in the section "species" then Atomsk will store them as auxiliary properties. If the charges appear after each particle coordinate, then they will override the ones defined in the "species" section.

The reading of GULP files come essentially with two restrictions. First, symmetry operations are not taken into account. So, if coordinates of a primitive lattice are used, only atoms in that primitive cell will be read and output. Symmetry is a whole other story to implement, so it was not done in this program. And second, since NEB was implemented in GULP (>3.4) the restart files (res or grs) can contain all atomic positions for all images of NEB. This is not recognized here, and only the positions of the 1st NEB image will be read and converted by Atomsk.

Atomsk can only write a basic GIN file, containing the cell parameters and the positions of the cores (and shells if any) with the following format:

##### example.gin

`opti
title
<comment>
end
vectors
<H(1,1)> <H(1,2)> <H(1,3)>
<H(2,1)> <H(2,2)> <H(2,3)>
<H(3,1)> <H(3,2)> <H(3,3)>
[1 1 1 1 1 1]
cartesian
<atom1> core <x1> <y1> <z1> [q1 [occ1 [0.0]]] [fixx1 fixy1 fixz1]
<atom1> shel <x1> <y1> <z1> [qs1 [occ1 [rad1]]] [1 1 1]
<atom2> core <x2> <y2> <z2> [q2 [occ2 [0.0]]] [fixx2 fixy2 fixz2]
<atom2> shel <x2> <y2> <z2> [qs2 [occ2 [rad2]]] [1 1 1]
... ... ...
<atomN> core <xN> <yN> <zN> [qN [occN [0.0]]] [fixxN fixyN fixzN]
<atomN> shel <xN> <yN> <zN> [qsN [occN [radN]]] [1 1 1]
[velocities angs/ps]
[...]
`

As shown in this example, if an atom is made of a core and a shell, the coordinates of the shell appear right after the ones of the core.

Values in square brackets will be written by Atomsk only if they are defined, either by being read from an input file or thanks to the option `-properties`.

So, if the electric charges of ions (q) are defined, they will be written. As stated in the GULP documentation, if electric charges are written, then the site occupancies (occ) may also be written (if they are defined). Similarly, if charges and occupancies are defined, then the radius for breathing shells (rad) may also be written. Note that the number of columns is always the same for cores and shells. A pair of core and shell will be given the same occupancy, and the breathing shell radius will be assigned only to the shell (for cores this column will contain 0.0).

The three flags ("`fixx fixy fixz`") at the end of each line mean that atoms will be free to move (1) or frozen (0) in the three directions of space. These flags will be written only if they are defined (e.g. if the option `-freeze` is used). Shells will never be fixed and therefore will always have the flags "`1 1 1`". The six flags "`1 1 1 1 1 1`" after the supercell parameters are written only if some atoms are frozen, and indicate that the three cell dimensions `a,b,c` and the three angles `α,β,γ` will be optimized. Replace them by 0 to fix one or all of these parameters. Beware that these flags can have a different use when specific keywords are used in the header (like `conv` or `conp`), refer to the GULP manual for more information.

If velocities are defined, then they are written in a separate section after all atom positions.

All these properties are fully transferable when converting a GULP file to another GULP file. Note however that only atoms and their properties are transferred, not other sections of the file (like interatomic potential, etc.).

By default coordinates are written in the cartesian basis, but output to fractional coordinates can be triggered by the option `-frac`.

Note that the GIN file that Atomsk writes is just a draft, it is NOT fully set for a simulation. It is up to the user to complete this GIN file with the simulation parameters (keywords, atomic potential, options for relaxation/MD, etc.) before running a simulation.

#### Examples

- `atomsk my_system.xsf -frac gin`

  This will read the file `my_system.xsf`, convert atom positions to fractional coordinates, and write the final result to `my_system.gin`.

- `atomsk relaxed.grs -sort species pack xsf`

  This will read the GULP restart file `relaxed.grs`, sort atoms according to their species, and write the final result to `relaxed.xsf`.

Back to main menu