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) are read from the beginning of the line. Thus the keyword atoms should be in a line like "1000 atoms"; the keyword ylo yhi should be in a line like "-10.0 10.0 ylo yhi"; the keyword xy xz yz should be in a line like "0.0 5.0 6.0 xy xz yz". 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.
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 xy xz yz line does not appear, then LAMMPS will set up an axis-aligned (orthogonal) simulation box. If the line does appear, LAMMPS creates a non-orthogonal simulation domain shaped as a parallelepiped with triclinic symmetry. See the region prism command for a description of how the extent of the parallelepiped is defined. The parallelepiped has its "origin" at (xlo,ylo,zlo) and 3 edge vectors starting from the origin given by a = (xhi-xlo,0,0); b = (xy,yhi-ylo,0); c = (xz,yz,zhi-zlo). Note that if your simulation will tilt the box, e.g. via the fix deform command, the simulation box must be triclinic, even if the tilt factors are initially 0.0.
The tilt factors (xy,xz,yz) can not skew the box more than half the distance of the parallel box length. For example, if xlo = 2 and xhi = 12, then the x box length is 10 and the xy tilt factor must be between -5 and 5. Similarly, both xz and yz must be between -(xhi-xlo)/2 and +(yhi-ylo)/2. Note that this is not a limitation, since if the maximum tilt factor is 5 (as in this example), then configurations with tilt = ..., -15, -5, 5, 15, 25, ... are all equivalent.
When a triclinic system is used, the simulation domain must be periodic in any dimensions with a non-zero tilt factor, as defined by the boundary command. I.e. if the xy tilt factor is non-zero, then both the x and y dimensions must be periodic. Similarly, x and z must be periodic if xz is non-zero and y and z must be periodic if yz is non-zero.
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. For 2d triclinic simulations, the xz and yz tilt factors must be 0.0.
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 listed below 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:
ID = angle type (1-N) coeffs = list of coeffs
6 70 108.5 0 0
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:
ID = improper type (1-N) coeffs = list of coeffs (see improper_coeff)
AngleAngleTorsion Coeffs section:
ID = dihedral type (1-N) coeffs = list of coeffs (see dihedral_coeff)
Angles section:
ID = number of angle (1-Nangles) type = angle type (1-Nangletype) atom1,atom2,atom3 = IDs of 1st,2nd,3rd atoms in angleexample:
2 2 17 29 430
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:
ID = dihedral type (1-N) coeffs = list of coeffs (see dihedral_coeff)
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. As discussed below, each line can optionally have 3 flags (nx,ny,nz) appended to it, which indicate which image of a periodic simulation box the atom is in. These may be important to include for some kinds of analysis.
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 |
dipole | atom-ID atom-type q x y z mux muy muz |
dpd | atom-ID atom-type x y z |
ellipsoid | atom-ID atom-type x y z quatw quati quatj quatk |
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 |
hybrid | atom-ID atom-type x y z sub-style1 sub-style2 ... |
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 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.
The values quatw, quati, quatj, and quatk set the orientation of the atom as a quaternion (4-vector). Note that the shape command or "Shapes" section of the data file specifies the aspect ratios of an ellipsoidal particle, which is oriented by default with its x-axis along the simulation box's x-axis, and similarly for y and z. If this body is rotated (via the right-hand rule) by an angle theta around a unit vector (a,b,c), then the quaternion that represents its new orientation is given by (cos(theta/2), a*sin(theta/2), b*sin(theta/2), c*sin(theta/2)). These 4 components are quatw, quati, quatj, and quatk as specfied above. LAMMPS normalizes each atom's quaternion in case (a,b,c) was not a unit vector.
For atom_style hybrid, following the 5 initial values (ID,type,x,y,z), specific values for each sub-style must be listed. The order of the sub-styles is the same as they were listed in the atom_style command. The sub-style specific values are those that are not the 5 standard ones (ID,type,x,y,z). For example, for the "charge" sub-style, a "q" value would appear. For the "full" sub-style, a "molecule-ID" and "q" would appear. These are listed in the same order they appear as listed above.
Thus if
atom_style hybrid charge granular
were used in the input script, each atom line would have these fields:
atom-ID atom-type x y z q diameter density
Atom lines (all lines or none of them) can optionally list 3 trailing 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 it is inside 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. If image information is needed for later analysis and they are not all initially 0, it's important to set them correctly in the data file. Also, if you plan to use the replicate command to generate a larger system, these flags must be listed correctly for bonded atoms when the bond crosses a periodic boundary. I.e. the values of the image flags should be different by 1 (in the appropriate dimension) for the two atoms in such a bond.
Atom velocities and other atom quantities not defined above are set to 0.0 when the Atoms section is read. Velocities can be set later by a Velocities section in the data file or by a velocity or set command in the input script.
Bond Coeffs section:
ID = bond type (1-N) coeffs = list of coeffs
4 250 1.49
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:
ID = angle type (1-N) coeffs = list of coeffs (see class 2 section of angle_coeff)
BondBond Coeffs section:
ID = angle type (1-N) coeffs = list of coeffs (see class 2 section of angle_coeff)
BondBond13 Coeffs section:
ID = dihedral type (1-N) coeffs = list of coeffs (see class 2 section of dihedral_coeff)
Bonds section:
ID = bond number (1-Nbonds) type = bond type (1-Nbondtype) atom1,atom2 = IDs of 1st,2nd atoms in bond
12 3 17 29
The Bonds section must appear after the Atoms section. All values in this section must be integers (1, not 1.0).
Dihedral Coeffs section:
ID = dihedral type (1-N) coeffs = list of coeffs
3 0.6 1 0 1
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:
ID = number of dihedral (1-Ndihedrals) type = dihedral type (1-Ndihedraltype) atom1,atom2,atom3,atom4 = IDs of 1st,2nd,3rd,4th atoms in dihedral
12 4 17 29 30 21
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:
ID = atom type (1-N) dipole-moment = value of dipole moment
2 0.5
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:
ID = dihedral type (1-N) coeffs = list of coeffs (see class 2 section of dihedral_coeff)
Improper Coeffs section:
ID = improper type (1-N) coeffs = list of coeffs
2 20 0.0548311
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:
ID = number of improper (1-Nimpropers) type = improper type (1-Nimpropertype) atom1,atom2,atom3,atom4 = IDs of 1st,2nd,3rd,4th atoms in improper
12 3 17 29 13 100
The ordering of the 4 atoms determines the definition of the improper angle used in the formula for each improper style. See the doc pages for individual styles for details.
The Impropers section must appear after the Atoms section. All values in this section must be integers (1, not 1.0).
Masses section:
ID = atom type (1-N) mass = mass value
3 1.01
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:
ID = dihedral type (1-N) coeffs = list of coeffs (see class 2 section of dihedral_coeff)
Pair Coeffs section:
ID = atom type (1-N) coeffs = list of coeffs
3 0.022 2.35197 0.022 2.35197
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.
Shapes section:
ID = atom type (1-N) x = x diameter y = y diameter z = z diameter
3 2.0 1.0 1.0
This defines the shape of each atom type. This can also be set via the shape command in the input script. This section should only be used for atom styles that define a shape, e.g. atom style dipole or ellipsoid.
Velocities section:
all styles except those listed | atom-ID vx vy vz |
dipole | atom-ID vx vy vz wx wy wz |
ellipsoid | atom-ID vx vy vz lx ly lz |
granular | atom-ID vx vy vz wx wy wz |
where the keywords have these meanings:
The velocity lines can appear in any order. This section can only be used after an Atoms section. This is because the Atoms section must have assigned a unique atom ID to each atom so that velocities can be assigned to them.
Vx,vy,vz are in units of velocity. Lx, ly, lz are in units of angular momentum (distance-velocity-mass). Wx,Wy,Wz are in units of angular velocity (radians/time).
Translational 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:
Default: none