lammps/doc/read_data.html

580 lines
17 KiB
HTML

<HTML>
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<HR>
<H3>read_data command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>read_data file
</PRE>
<UL><LI>file = name of data file to read in
</UL>
<P><B>Examples:</B>
</P>
<PRE>read_data data.lj
read_data ../run7/data.polymer.gz
</PRE>
<P><B>Description:</B>
</P>
<P>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 <A HREF = "read_restart.html">read_restart</A> and
<A HREF = "create_atoms.html">create_atoms</A> commands for alternative methods.
</P>
<P>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.
</P>
<P>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.
</P>
<P>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.
</P>
<P>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.
</P>
<HR>
<P>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 <I>atoms</I> should be in a line like "1000 atoms" and the
keyword <I>ylo yhi</I> 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.
</P>
<UL><LI><I>atoms</I> = # of atoms in system
<LI><I>bonds</I> = # of bonds in system
<LI><I>angles</I> = # of angles in system
<LI><I>dihedrals</I> = # of dihedrals in system
<LI><I>impropers</I> = # of impropers in system
<LI><I>atom types</I> = # of atom types in system
<LI><I>bond types</I> = # of bond types in system
<LI><I>angle types</I> = # of angle types in system
<LI><I>dihedral types</I> = # of dihedral types in system
<LI><I>improper types</I> = # of improper types in system
<LI><I>xlo xhi</I> = simulation box boundaries in x dimension
<LI><I>ylo yhi</I> = simulation box boundaries in y dimension
<LI><I>zlo zhi</I> = simulation box boundaries in z dimension
</UL>
<P>For 2d simulations, the <I>zlo zhi</I> 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.
</P>
<P>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
<A HREF = "boundary.html">boundary</A> command.
</P>
<P>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.
</P>
<P>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.
</P>
<HR>
<P>These are the section keywords for the body of the file.
</P>
<UL><LI><I>Atoms, Velocities, Masses, Dipoles</I> = atom-property sections
<LI><I>Bonds, Angles, Dihedrals, Impropers</I> = molecular topolgy sections
<LI><I>Pair Coeffs, Bond Coeffs, Angle Coeffs, Dihedral Coeffs, Improper Coeffs</I> = force field sections
<LI><I>BondBond Coeffs, BondAngle Coeffs, MiddleBondTorsion Coeffs, EndBondTorsion Coeffs, AngleTorsion Coeffs, AngleAngleTorsion Coeffs, BondBond13 Coeffs, AngleAngle Coeffs</I> = class 2 force field sections
</UL>
<P>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.
</P>
<P>Any individual line in the various sections can have a trailing
comment starting with "#" for annotation purposes. E.g. in the
Atoms section:
</P>
<PRE>10 1 17 -1.0 10.0 5.0 6.0 # salt ion
</PRE>
<HR>
<P><I>Angle Coeffs</I> section:
</P>
<UL><LI>one line per angle type
<LI>line syntax: ID coeffs
<PRE> ID = angle type (1-N)
coeffs = list of coeffs
</PRE>
<LI>example:
<PRE> 6 70 108.5 0 0
</PRE>
</UL>
<P>The number and meaning of the coefficients are specific to the defined
angle style. See the <A HREF = "angle_style.html">angle_style</A> and
<A HREF = "angle_coeff.html">angle_coeff</A> commands for details. Coefficients can
also be set via the <A HREF = "angle_coeff.html">angle_coeff</A> command in the
input script.
</P>
<HR>
<P><I>AngleAngle Coeffs</I> section:
</P>
<UL><LI>one line per improper type
<LI>line syntax: ID coeffs
<PRE> ID = improper type (1-N)
coeffs = list of coeffs (see <A HREF = "improper_coeff.html">improper_coeff</A>)
</PRE>
</UL>
<HR>
<P><I>AngleAngleTorsion Coeffs</I> section:
</P>
<UL><LI>one line per dihedral type
<LI>line syntax: ID coeffs
<PRE> ID = dihedral type (1-N)
coeffs = list of coeffs (see <A HREF = "dihedral_coeff.html">dihedral_coeff</A>)
</PRE>
</UL>
<HR>
<P><I>Angles</I> section:
</P>
<UL><LI>one line per angle
<LI>line syntax: ID type atom1 atom2 atom3
<PRE> ID = number of angle (1-Nangles)
type = angle type (1-Nangletype)
atom1,atom2,atom3 = IDs of 1st,2nd,3rd atoms in angle
</PRE>
example:
<BR>
<PRE> 2 2 17 29 430
</PRE>
</UL>
<P>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 <I>Angles</I> section must appear
after the <I>Atoms</I> section. All values in this section must be
integers (1, not 1.0).
</P>
<HR>
<P><I>AngleTorsion Coeffs</I> section:
</P>
<UL><LI>one line per dihedral type
<LI>line syntax: ID coeffs
<PRE> ID = dihedral type (1-N)
coeffs = list of coeffs (see <A HREF = "dihedral_coeff.html">dihedral_coeff</A>)
</PRE>
</UL>
<HR>
<P><I>Atoms</I> section:
</P>
<UL><LI>one line per atom
<LI>line syntax: depends on atom style
</UL>
<P>An <I>Atoms</I> 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 <A HREF = "atom_style.html">atom style</A> in LAMMPS:
</P>
<DIV ALIGN=center><TABLE WIDTH="0%" BORDER=1 >
<TR><TD >angle</TD><TD > atom-ID molecule-ID atom-type x y z</TD></TR>
<TR><TD >atomic</TD><TD > atom-ID atom-type x y z</TD></TR>
<TR><TD >bond</TD><TD > atom-ID molecule-ID atom-type x y z</TD></TR>
<TR><TD >charge</TD><TD > atom-ID atom-type q x y z</TD></TR>
<TR><TD >dpd</TD><TD > atom-ID atom-type x y z</TD></TR>
<TR><TD >full</TD><TD > atom-ID molecule-ID atom-type q x y z</TD></TR>
<TR><TD >granular</TD><TD > atom-ID atom-type diameter density x y z</TD></TR>
<TR><TD >molecular</TD><TD > atom-ID molecule-ID atom-type x y z
</TD></TR></TABLE></DIV>
<P>where the keywords have these meanings:
</P>
<UL><LI>atom-ID = integer ID of atom
<LI>molecule-ID = integer ID of molecule the atom belongs to
<LI>type-ID = type of atom (1-Ntype)
<LI>q = charge on atom
<LI>diameter = diameter of atom
<LI>density = density of atom
<LI>x,y,z = coordinates of atom
</UL>
<P>The units for these quantities depend on the unit style; see the
<A HREF = "units.html">units</A> command for details.
</P>
<P>For 2d simulations specify z as 0.0, or a value is within the <I>zlo
zhi</I> setting in the data file header.
</P>
<P>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 <A HREF = "atom_modify.html">atom_modify</A> 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.
</P>
<P>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.
</P>
<P>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 <A HREF = "dump.html">dump</A> command. If nx,ny,nz values are not set in
the data file, LAMMPS initializes them to 0.
</P>
<P>Atom velocities are set to 0.0 when the <I>Atoms</I> section is read. They
may later be set by a <I>Velocities</I> section in the data file or by a
<A HREF = "velocity.html">velocity</A> command in the input script.
</P>
<HR>
<P><I>Bond Coeffs</I> section:
</P>
<UL><LI>one line per bond type
<LI>line syntax: ID coeffs
<PRE> ID = bond type (1-N)
coeffs = list of coeffs
</PRE>
<LI>example:
<PRE> 4 250 1.49
</PRE>
</UL>
<P>The number and meaning of the coefficients are specific to the defined
bond style. See the <A HREF = "bond_style.html">bond_style</A> and
<A HREF = "bond_coeff.html">bond_coeff</A> commands for details. Coefficients can
also be set via the <A HREF = "bond_coeff.html">bond_coeff</A> command in the input
script.
</P>
<HR>
<P><I>BondAngle Coeffs</I> section:
</P>
<UL><LI>one line per angle type
<LI>line syntax: ID coeffs
<PRE> ID = angle type (1-N)
coeffs = list of coeffs (see class 2 section of <A HREF = "angle_coeff.html">angle_coeff</A>)
</PRE>
</UL>
<HR>
<P><I>BondBond Coeffs</I> section:
</P>
<UL><LI>one line per angle type
<LI>line syntax: ID coeffs
<PRE> ID = angle type (1-N)
coeffs = list of coeffs (see class 2 section of <A HREF = "angle_coeff.html">angle_coeff</A>)
</PRE>
</UL>
<HR>
<P><I>BondBond13 Coeffs</I> section:
</P>
<UL><LI>one line per dihedral type
<LI>line syntax: ID coeffs
<PRE> ID = dihedral type (1-N)
coeffs = list of coeffs (see class 2 section of <A HREF = "dihedral_coeff.html">dihedral_coeff</A>)
</PRE>
</UL>
<HR>
<P><I>Bonds</I> section:
</P>
<UL><LI>one line per bond
<LI>line syntax: ID type atom1 atom2
<PRE> ID = bond number (1-Nbonds)
type = bond type (1-Nbondtype)
atom1,atom2 = IDs of 1st,2nd atoms in bond
</PRE>
<LI>example:
<PRE> 12 3 17 29
</PRE>
</UL>
<P>The <I>Bonds</I> section must appear after the <I>Atoms</I> section. All values
in this section must be integers (1, not 1.0).
</P>
<HR>
<P><I>Dihedral Coeffs</I> section:
</P>
<UL><LI>one line per dihedral type
<LI>line syntax: ID coeffs
<PRE> ID = dihedral type (1-N)
coeffs = list of coeffs
</PRE>
<LI>example:
<PRE> 3 0.6 1 0 1
</PRE>
</UL>
<P>The number and meaning of the coefficients are specific to the defined
dihedral style. See the <A HREF = "dihedral_style.html">dihedral_style</A> and
<A HREF = "dihedral_coeff.html">dihedral_coeff</A> commands for details.
Coefficients can also be set via the
<A HREF = "dihedral_coeff.html">dihedral_coeff</A> command in the input script.
</P>
<HR>
<P><I>Dihedrals</I> section:
</P>
<UL><LI>one line per dihedral
<LI>line syntax: ID type atom1 atom2 atom3 atom4
<PRE> ID = number of dihedral (1-Ndihedrals)
type = dihedral type (1-Ndihedraltype)
atom1,atom2,atom3,atom4 = IDs of 1st,2nd,3rd,4th atoms in dihedral
</PRE>
<LI>example:
<PRE> 12 4 17 29 30 21
</PRE>
</UL>
<P>The 4 atoms are ordered linearly within the dihedral. The <I>Dihedrals</I>
section must appear after the <I>Atoms</I> section. All values in this
section must be integers (1, not 1.0).
</P>
<HR>
<P><I>Dipoles</I> section:
</P>
<UL><LI>one line per atom type
line syntax: ID dipole-moment
<PRE> ID = atom type (1-N)
dipole-moment = value of dipole moment
</PRE>
<LI>example:
<PRE> 2 0.5
</PRE>
</UL>
<P>This defines the dipole moment of each atom type (which can be 0.0 for
some types). This can also be set via the <A HREF = "dipole.html">dipole</A>
command in the input script.
</P>
<HR>
<P><I>EndBondTorsion Coeffs</I> section:
</P>
<UL><LI>one line per dihedral type
<LI>line syntax: ID coeffs
<PRE> ID = dihedral type (1-N)
coeffs = list of coeffs (see class 2 section of <A HREF = "dihedral_coeff.html">dihedral_coeff</A>)
</PRE>
</UL>
<HR>
<P><I>Improper Coeffs</I> section:
</P>
<UL><LI>one line per improper type
<LI>line syntax: ID coeffs
<PRE> ID = improper type (1-N)
coeffs = list of coeffs
</PRE>
<LI>example:
<PRE> 2 20 0.0548311
</PRE>
</UL>
<P>The number and meaning of the coefficients are specific to the defined
improper style. See the <A HREF = "improper_style.html">improper_style</A> and
<A HREF = "improper_coeff.html">improper_coeff</A> commands for details.
Coefficients can also be set via the
<A HREF = "improper_coeff.html">improper_coeff</A> command in the input script.
</P>
<HR>
<P><I>Impropers</I> section:
</P>
<UL><LI>one line per improper
<LI>line syntax: ID type atom1 atom2 atom3 atom4
<PRE> ID = number of improper (1-Nimpropers)
type = improper type (1-Nimpropertype)
atom1,atom2,atom3,atom4 = IDs of 1st,2nd,3rd,4th atoms in improper
</PRE>
<LI>example:
<PRE> 12 3 17 29 13 100
</PRE>
</UL>
<P>The <I>Impropers</I> section must appear after the <I>Atoms</I> section. All
values in this section must be integers (1, not 1.0).
</P>
<HR>
<P><I>Masses</I> section:
</P>
<UL><LI>one line per atom type
<LI>line syntax: ID mass
<PRE> ID = atom type (1-N)
mass = mass value
</PRE>
<LI>example:
<PRE> 3 1.01
</PRE>
</UL>
<P>This defines the mass of each atom type. This can also be set via the
<A HREF = "mass.html">mass</A> 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.
</P>
<HR>
<P><I>MiddleBondTorsion Coeffs</I> section:
</P>
<UL><LI>one line per dihedral type
<LI>line syntax: ID coeffs
<PRE> ID = dihedral type (1-N)
coeffs = list of coeffs (see class 2 section of <A HREF = "dihedral_coeff.html">dihedral_coeff</A>)
</PRE>
</UL>
<HR>
<P><I>Pair Coeffs</I> section:
</P>
<UL><LI>one line per atom type
<LI>line syntax: ID coeffs
<PRE> ID = atom type (1-N)
coeffs = list of coeffs
</PRE>
<LI>example:
<PRE> 3 0.022 2.35197 0.022 2.35197
</PRE>
</UL>
<P>The number and meaning of the coefficients are specific to the defined
pair style. See the <A HREF = "pair_style.html">pair_style</A> and
<A HREF = "pair_coeff.html">pair_coeff</A> commands for details. Coefficients can
also be set via the <A HREF = "pair_coeff.html">pair_coeff</A> command in the input
script.
</P>
<HR>
<P><I>Velocities</I> section:
</P>
<UL>one line per atom
<LI>line syntax: atom-ID vx vy vz
<PRE> atom-ID = integer ID of atom to assign velocity to
vx,vy,vz = components of velocity of the atom
</PRE>
<LI>example:
<PRE> 45 -3.4 0.05 1.25
</PRE>
</UL>
<P>The velocity lines can appear in any order. This section can only be
used after an <I>Atoms</I> section. The <I>Atoms</I> 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 <A HREF = "velocity.html">velocity</A>
command in the input script.
</P>
<HR>
<P><B>Restrictions:</B>
</P>
<P>To read gzipped data files, you must compile LAMMPS with the -DGZIP
option - see the <A HREF = "Section_start.html#2_2">Making LAMMPS</A> section of the
documentation.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "read_restart.html">read_restart</A>, <A HREF = "create_atoms.html">create_atoms</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>