LAMMPS WWW Site - LAMMPS Documentation - LAMMPS Commands

read_data command

Syntax:

read_data file 

Examples:

read_data data.lj
read_data ../run7/data.polymer.gz 

Description:

Read in a data file containing information LAMMPS needs to run a simulation. The file can be ASCII text or a gzipped text file (detected by a .gz suffix). This is one of 3 ways to specify initial atom coordinates; see the read_restart and create_atoms commands for alternative methods.

The structure of the data file is important, though many settings and sections are optional or can come in any order. See the examples directory for sample data files for different problems.

A data file has a header and a body. The header appears first. The first line of the header is always skipped; it typically contains a description of the file. Then lines are read one at a time. Lines can have a trailing comment starting with '#' that is ignored. If the line is blank (only whitespace after comment is deleted), it is skipped. If the line contains a header keyword, the corresponding value(s) is read from the line. If it doesn't contain a header keyword, the line begins the body of the file.

The body of the file contains zero or more sections. The first line of a section has only a keyword. The next line is skipped. The remaining lines of the section contain values. The number of lines depends on the section keyword as described below. Zero or more blank lines can be used between sections. Sections can appear in any order, with a few exceptions as noted below.

The formatting of individual lines in the data file (indentation, spacing between words and numbers) is not important except that header and section keywords (e.g. atoms, xlo xhi, Masses, Bond Coeffs) must be capitalized as shown and can't have extra white space between their words - e.g. two spaces or a tab between "Bond" and "Coeffs" is not valid.


These are the recognized header keywords. Header lines can come in any order. The value(s) is read from the beginning of the line. Thus the keyword atoms should be in a line like "1000 atoms" and the keyword ylo yhi should be in a line like "-10.0 10.0 ylo yhi". All these settings have a default value of 0, except the lo/hi box size defaults are -0.5 and 0.5. A line need only appear if the value is different than the default.

For 2d simulations, the zlo zhi values should be set to bound the z coords for atoms that appear in the file; the default of -0.5 0.5 is valid if all z coords are 0.0.

The initial simulation box size is determined by the lo/hi settings. In any dimension, the system may be periodic or non-periodic; see the boundary command.

If the system is non-periodic (in a dimension), then all atoms in the data file should have coordinates (in that dimension) between the lo and hi values. Furthermore, if running in parallel, the lo/hi values should be just a bit smaller/larger than the min/max extent of atoms. For example, if your atoms extend from 0 to 50, you should not specify the box bounds as -10000 and 10000. Since LAMMPS uses the specified box size to layout the 3d grid of processors, this will be sub-optimal and may cause a parallel simulation to lose atoms when LAMMPS shrink-wraps the box to the atoms.

If the system is periodic (in a dimension), then atom coordinates can be outside the bounds; they will be remapped (in a periodic sense) back inside the box.


These are the section keywords for the body of the file.

Each section is now listed in alphabetic order. The format of each section is described including the number of lines it must contain and rules (if any) for where it can appear in the data file.

Any individual line in the various sections can have a trailing comment starting with "#" for annotation purposes. E.g. in the Atoms section:

10 1 17 -1.0 10.0 5.0 6.0   # salt ion 

Angle Coeffs section:

The number and meaning of the coefficients are specific to the defined angle style. See the angle_style and angle_coeff commands for details. Coefficients can also be set via the angle_coeff command in the input script.


AngleAngle Coeffs section:


AngleAngleTorsion Coeffs section:


Angles section:

The 3 atoms are ordered linearly within the angle. Thus the central atom (around which the angle is computed) is the atom2 in the list. E.g. H,O,H for a water molecule. The Angles section must appear after the Atoms section. All values in this section must be integers (1, not 1.0).


AngleTorsion Coeffs section:


Atoms section:

An Atoms section must appear in the data file if natoms > 0 in the header section. The atoms can be listed in any order. These are the line formats for each atom style in LAMMPS:

angle atom-ID molecule-ID atom-type x y z
atomic atom-ID atom-type x y z
bond atom-ID molecule-ID atom-type x y z
charge atom-ID atom-type q x y z
dpd atom-ID atom-type x y z
full atom-ID molecule-ID atom-type q x y z
granular atom-ID atom-type diameter density x y z
molecular atom-ID molecule-ID atom-type x y z

where the keywords have these meanings:

The units for these quantities depend on the unit style; see the units command for details.

For 2d simulations specify z as 0.0, or a value is within the zlo zhi setting in the data file header.

The atom-ID is used to identify the atom throughout the simulation and in dump files. Normally, it is a unique value from 1 to Natoms for each atom. Unique values larger than Natoms can be used, but they will cause extra memory to be allocated on each processor, if an atom map array is used (see the atom_modify command). If an atom map array is not used (e.g. an atomic system with no bonds), velocities are not assigned in the data file, and you don't care if unique atom IDs appear in dump files, then the atom-IDs can all be set to 0.

The molecule ID is a 2nd identifier attached to an atom. Normally, it is a number from 1 to N, identifying which molecule the atom belongs to. It can be 0 if it is an unbonded atom or if you don't care to keep track of molecule assignments.

Atom lines (all lines or none of them) can optionally list 3 final integer values: nx,ny,nz. For periodic dimensions, they specify which image of the box the atom is considered to be in. An image of 0 means the box as defined. A value of 2 means add 2 box lengths to get the true value. A value of -1 means subtract 1 box length to get the true value. LAMMPS updates these flags as atoms cross periodic boundaries during the simulation. The flags can be output with atom snapshots via the dump command. If nx,ny,nz values are not set in the data file, LAMMPS initializes them to 0.

Atom velocities are set to 0.0 when the Atoms section is read. They may later be set by a Velocities section in the data file or by a velocity command in the input script.


Bond Coeffs section:

The number and meaning of the coefficients are specific to the defined bond style. See the bond_style and bond_coeff commands for details. Coefficients can also be set via the bond_coeff command in the input script.


BondAngle Coeffs section:


BondBond Coeffs section:


BondBond13 Coeffs section:


Bonds section:

The Bonds section must appear after the Atoms section. All values in this section must be integers (1, not 1.0).


Dihedral Coeffs section:

The number and meaning of the coefficients are specific to the defined dihedral style. See the dihedral_style and dihedral_coeff commands for details. Coefficients can also be set via the dihedral_coeff command in the input script.


Dihedrals section:

The 4 atoms are ordered linearly within the dihedral. The Dihedrals section must appear after the Atoms section. All values in this section must be integers (1, not 1.0).


Dipoles section:

This defines the dipole moment of each atom type (which can be 0.0 for some types). This can also be set via the dipole command in the input script.


EndBondTorsion Coeffs section:


Improper Coeffs section:

The number and meaning of the coefficients are specific to the defined improper style. See the improper_style and improper_coeff commands for details. Coefficients can also be set via the improper_coeff command in the input script.


Impropers section:

The Impropers section must appear after the Atoms section. All values in this section must be integers (1, not 1.0).


Masses section:

This defines the mass of each atom type. This can also be set via the mass command in the input script. This section should not be used for atom styles that define a mass for individual atoms - e.g. atom style granular.


MiddleBondTorsion Coeffs section:


Pair Coeffs section:

The number and meaning of the coefficients are specific to the defined pair style. See the pair_style and pair_coeff commands for details. Coefficients can also be set via the pair_coeff command in the input script.


Velocities section:

The velocity lines can appear in any order. This section can only be used after an Atoms section. The Atoms section must have assigned a unique atom ID to each atom so that velocities can be assigned in this way. Velocities can also be set by the velocity command in the input script.


Restrictions:

To read gzipped data files, you must compile LAMMPS with the -DGZIP option - see the Making LAMMPS section of the documentation.

Related commands:

read_restart, create_atoms

Default: none