lammps/doc/molecule.txt

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line

molecule command :h3

[Syntax:]

molecule ID file1 file2 ... :pre

ID = user-assigned name for the molecule template
file1,file2,... = names of files containing molecule descriptions :ul

[Examples:]

molecule 1 mymol
molecule 1 co2.txt h2o.txt
molecule CO2 co2.txt :pre

[Description:]

Define a molecule template that can be used as part of other LAMMPS
commands, typically to define a collection of particles as a bonded
molecule or a rigid body.  Commands that currently use molecule
templates (or will in the future) include:

"fix deposit"_fix_deposit.html
"fix pour"_fix_pour.html
"fix rigid/small"_fix_rigid.html
"fix shake"_fix_shake.html
"fix gcmc"_fix_gcmc.html
"create_atoms"_create_atoms.html 
"atom_style template"_atom_style.html :ul

The ID of a molecule template can only contain alphanumeric characters
and underscores.

A single template can contain multiple molecules, listed one per file.
Many of the commands listed above currently use only the first
molecule in the template, and will issue a warning if the template
contains multiple molecules.  The "atom_style
template"_atom_style.html command allows multiple-molecule templates
to define a system with more than one templated molecule.

IMPORTANT NOTE: When using the "atom_style template"_atom_style.html
command with a molecule template that contains multiple molecules, you
should insure the atom types, bond types, angle_types, etc in all the
molecules are consistent.  E.g. if one molecule represents H2O and
another CO2, then you probably do not want each molecule file to
define 2 atom types and a single bond type, because they will conflict
with each other when a mixture system of H2O and CO2 molecules is
defined, e.g.  by the "read_data"_read_data.html command.  Rather the
H2O molecule should define atom types 1 and 2, and bond type 1.  And
the CO2 molecule should define atom types 3 and 4 (or atom types 3 and
2 if a single oxygen type is desired), and bond type 2.

The format of an individual molecule file is similar to the data file
read by the "read_data"_read_data.html commands, and is as follows.

A molecule 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.

These are the recognized header keywords.  Header lines can come in
any order.  The numeric value(s) are read from the beginning of the
line.  The keyword should appear at the end of the line.  All these
settings have default values, as explained below.  A line need only
appear if the value(s) are different than the default.

N {atoms} = # of atoms N in molecule, default = 0
Nb {bonds} = # of bonds Nb in molecule, default = 0
Na {angles} = # of angles Na in molecule, default = 0
Nd {dihedrals} = # of dihedrals Nd in molecule, default = 0
Ni {impropers} = # of impropers Ni in molecule, default = 0
Mtotal {mass} = total mass of molecule
Xc Yc Zc {com} = coordinates of center-of-mass of molecule
Ixx Iyy Izz Ixy Ixz Iyz {inertia} = 6 components of inertia tensor of molecule :ul

For {mass}, {com}, and {inertia}, the default is for LAMMPS to
calculate this quantity itself if needed, assuming the molecules
consists of a set of point particles.  You typically only need to
specify these values for a rigid body consisting of overlapping
finite-size particles.

The mass and center-of-mass coordinates (Xc,Yc,Zc) are
self-explanatory.  The 6 moments of inertia (ixx,iyy,izz,ixy,ixz,iyz)
should be the values consistent with the current orientation of the
rigid body around its center of mass.  The values are with respect to
the simulation box XYZ axes, not with respect to the prinicpal axes of
the rigid body itself.  LAMMPS performs the latter calculation
internally.

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

{Coords, Types, Charges, Diameters, Masses} = atom-property sections 
{Bonds, Angles, Dihedrals, Impropers} = molecular topology sections 
{Special Bond Counts, Special Bonds} = special neighbor info
{Shake Flags, Shake Atoms, Shake Bond Types} = SHAKE info :ul

IMPORTANT NOTE: Whether a section is required depends on how the
molecule template is used by other LAMMPS commands.  For example, to
add a molecule via the "fix deposit"_fix_deposit.html command, the
Coords and Types sections are required.  To add a rigid body via the
"fix pour"_fix_pout.html command, the Bonds (Angles, etc) sections are
not required, since the molecule will be treated as a rigid body.
Some sections are optional.  For example, the "fix pour"_fix_pour.html
command can be used to add "molecules" which are clusters of
finite-size granular particles.  If the Diameters section is not
specified, each particle in the molecule will have a default diameter
of 1.0.  See the doc pages for LAMMPS commands that use molecule
templates for more details.

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 whether it can appear in the data file.  In each
case the ID is ignored; it is simply included for readability, and
should be a number from 1 to Nlines for the section, indicating which
atom (or bond, etc) the entry applies to.  The lines are assumed to be
listed in order from 1 to Nlines, but LAMMPS does not check for this.

:line

{Coords} section:

one line per atom
line syntax: ID x y z
x,y,z = coordinate of atom :ul

:line

{Types} section:

one line per atom
line syntax: ID type
type = atom type of atom :ul

:line

{Charges} section:

one line per atom
line syntax: ID q
q = charge on atom :ul

This section is only allowed for "atom styles"_atom_style.html that
support charge.  If this section is not included, the default charge
on each atom in the molecule is 0.0.

:line

{Diameters} section:

one line per atom
line syntax: ID diam
diam = diameter of atom :ul

This section is only allowed for "atom styles"_atom_style.html that
support finite-size spherical particles, e.g. atom_style sphere.  If
not listed, the default diameter of each atom in the molecule is 1.0.

:line

{Masses} section:

one line per atom
line syntax: ID mass
mass = mass of atom :ul

This section is only allowed for "atom styles"_atom_style.html that
support per-atom mass, as opposed to per-type mass.  See the
"mass"_mass.html command for details.  If this section is not
included, the default mass for each atom is derived from its volume
(see Diameters section) and a default density of 1.0, in
"units"_units.html of mass/volume.

:line

{Bonds} section:

one line per bond
line syntax: ID type atom1 atom2
type = bond type (1-Nbondtype)
atom1,atom2 = IDs of atoms in bond :ul

The IDs for the two atoms in each bond should be values
from 1 to Natoms, where Natoms = # of atoms in the molecule.

:line

{Angles} section:

one line per angle
line syntax: ID type atom1 atom2 atom3
type = angle type (1-Nangletype)
atom1,atom2,atom3 = IDs of atoms in angle :ul

The IDs for the three atoms in each angle should be values from 1 to
Natoms, where Natoms = # of atoms in the molecule.  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.

:line

{Dihedrals} section:

one line per dihedral
line syntax: ID type atom1 atom2 atom3 atom4
type = dihedral type (1-Ndihedraltype)
atom1,atom2,atom3,atom4 = IDs of atoms in dihedral :ul

The IDs for the four atoms in each dihedral should be values from 1 to
Natoms, where Natoms = # of atoms in the molecule.  The 4 atoms are
ordered linearly within the dihedral.

:line

{Impropers} section:

one line per improper
line syntax: ID type atom1 atom2 atom3 atom4
type = improper type (1-Nimpropertype)
atom1,atom2,atom3,atom4 = IDs of atoms in improper :ul

The IDs for the four atoms in each improper should be values from 1 to
Natoms, where Natoms = # of atoms in the molecule.  The ordering of
the 4 atoms determines the definition of the improper angle used in
the formula for the defined "improper style"_improper_style.html.  See
the doc pages for individual styles for details.

:line

{Special Bond Counts} section:

one line per atom
line syntax: ID N1 N2 N3
N1 = # of 1-2 bonds
N2 = # of 1-3 bonds
N3 = # of 1-4 bonds :ul

N1, N2, N3 are the number of 1-2, 1-3, 1-4 neighbors respectively of
this atom within the topology of the molecule.  See the
"special_bonds"_special_bonds.html doc page for more discussion of
1-2, 1-3, 1-4 neighbors.  If this section appears, the Special Bonds
section must also appear.  If this section is not specied, the
atoms in the molecule will have no special bonds.

:line

{Special Bonds} section:

one line per atom
line syntax: ID a b c d ...
a,b,c,d,... = IDs of atoms in N1+N2+N3 special bonds :ul

A, b, c, d, etc are the IDs of the n1+n2+n3 atoms that are 1-2, 1-3,
1-4 neighbors of this atom.  The IDs should be values from 1 to
Natoms, where Natoms = # of atoms in the molecule.  The first N1
values should be the 1-2 neighbors, the next N2 should be the 1-3
neighbors, the last N3 should be the 1-4 neighbors.  No atom ID should
appear more than once.  See the "special_bonds"_special_bonds.html doc
page for more discussion of 1-2, 1-3, 1-4 neighbors.  If this section
appears, the Special Bond Counts section must also appear.  If this
section is not specied, the atoms in the molecule will have no special
bonds.

:line

{Shake Flags} section:

one line per atom
line syntax: ID flag
flag = 0,1,2,3,4 :ul

This section is only needed when molecules created using the template
will be constrained by SHAKE via the "fix shake" command.  The other
two Shake sections must also appear in the file, following this one.

The meaning of the flag for each atom is as follows.  See the "fix
shake"_fix_shake.html doc page for a further description of SHAKE
clusters.

0 = not part of a SHAKE cluster
1 = part of a SHAKE angle cluster (two bonds and the angle they form)
2 = part of a 2-atom SHAKE cluster with a single bond
3 = part of a 3-atom SHAKE cluster with two bonds
4 = part of a 4-atom SHAKE cluster with three bonds :ul

:line

{Shake Atoms} section:

one line per atom
line syntax: ID a b c d
a,b,c,d = IDs of atoms in cluster :ul

This section is only needed when molecules created using the template
will be constrained by SHAKE via the "fix shake" command.  The other
two Shake sections must also appear in the file.

The a,b,c,d values are atom IDs (from 1 to Natoms) for all the atoms
in the SHAKE cluster that this atom belongs to.  The number of values
that must appear is determined by the shake flag for the atom (see the
Shake Flags section above).  All atoms in a particular cluster should
list their a,b,c,d values identically.

If flag = 0, no a,b,c,d values are listed on the line, just the
(ignored) ID.

If flag = 1, a,b,c are listed, where a = ID of central atom in the
angle, and b,c the other two atoms in the angle.

If flag = 2, a,b are listed, where a = ID of atom in bond with the the
lowest ID, and b = ID of atom in bond with the highest ID.

If flag = 3, a,b,c are listed, where a = ID of central atom,
and b,c = IDs of other two atoms bonded to the central atom.

If flag = 4, a,b,c,d are listed, where a = ID of central atom,
and b,c,d = IDs of other three atoms bonded to the central atom.

See the "fix shake"_fix_shake.html doc page for a further description
of SHAKE clusters.

:line

{Shake Bond Types} section:

one line per atom
line syntax: ID a b c
a,b,c = bond types (or angle type) of bonds (or angle) in cluster :ul

This section is only needed when molecules created using the template
will be constrained by SHAKE via the "fix shake" command.  The other
two Shake sections must also appear in the file.

The a,b,c values are bond types (from 1 to Nbondtypes) for all bonds
in the SHAKE cluster that this atom belongs to.  The number of values
that must appear is determined by the shake flag for the atom (see the
Shake Flags section above).  All atoms in a particular cluster should
list their a,b,c values identically.

If flag = 0, no a,b,c values are listed on the line, just the
(ignored) ID.

If flag = 1, a,b,c are listed, where a = bondtype of the bond between
the central atom and the first non-central atom (value b in the Shake
Atoms section), b = bondtype of the bond between the central atom and
the 2nd non-central atom (value c in the Shake Atoms section), and c =
the angle type (1 to Nangletypes) of the angle between the 3 atoms.

If flag = 2, only a is listed, where a = bondtype of the bond between
the 2 atoms in the cluster.

If flag = 3, a,b are listed, where a = bondtype of the bond between
the central atom and the first non-central atom (value b in the Shake
Atoms section), and b = bondtype of the bond between the central atom
and the 2nd non-central atom (value c in the Shake Atoms section).

If flag = 4, a,b,c are listed, where a = bondtype of the bond between
the central atom and the first non-central atom (value b in the Shake
Atoms section), b = bondtype of the bond between the central atom and
the 2nd non-central atom (value c in the Shake Atoms section), and c =
bondtype of the bond between the central atom and the 3rd non-central
atom (value d in the Shake Atoms section).

See the "fix shake"_fix_shake.html doc page for a further description
of SHAKE clusters.

:line

[Restrictions:] none

[Related commands:]

"fix deposit"_fix_deposit.html, "fix pour"_fix_pour.html,
"fix_gcmc"_fix_gcmc.html

[Default:] none