Syntax:
molecule ID file1 file2 ...
Examples:
molecule 1 mymol molecule 1 co2.txt h2o.txt molecule CO2 co2.txt
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 include:
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 command allows multiple-molecule templates to define a system with more than one templated molecule.
IMPORTANT NOTE: When using the atom_style template 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 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 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.
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.
If a Bonds section is specified then the Special Bond Counts and Special Bonds sections must be also, since the latter is needed for LAMMPS to properly exclude or weight bonded pairwise interactions between bonded atoms. See the special_bonds command for more details.
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 command, the Coords and Types sections are required. To add a rigid body via the fix pour 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 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.
Coords section:
Types section:
Charges section:
This section is only allowed for atom styles that support charge. If this section is not included, the default charge on each atom in the molecule is 0.0.
Diameters section:
This section is only allowed for atom styles 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.
Masses section:
This section is only allowed for atom styles that support per-atom mass, as opposed to per-type mass. See the mass 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 of mass/volume.
Bonds section:
The IDs for the two atoms in each bond should be values from 1 to Natoms, where Natoms = # of atoms in the molecule.
Angles section:
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.
Dihedrals section:
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.
Impropers section:
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. See the doc pages for individual styles for details.
Special Bond Counts section:
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 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.
Special Bonds section:
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 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.
Shake Flags section:
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 doc page for a further description of SHAKE clusters.
Shake Atoms section:
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 doc page for a further description of SHAKE clusters.
Shake Bond Types section:
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 doc page for a further description of SHAKE clusters.
Restrictions: none
Related commands:
fix deposit, fix pour, fix_gcmc
Default: none