molecule.html
7a68ceb57a2dlammps-icms

molecule.html
View Options

			<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>molecule command
			</H3>
			<P><B>Syntax:</B>
			</P>
			<PRE>molecule ID file1 keyword values ... file2 keyword values ... fileN ...
			</PRE>
			<UL><LI>ID = user-assigned name for the molecule template

			<LI>file1,file2,... = names of files containing molecule descriptions

			<LI>zero or more keyword/value pairs may be appended after each file

			<LI>keyword = <I>offset</I> or <I>toff</I> or <I>boff</I> or <I>aoff</I> or <I>doff</I> or <I>ioff</I> or <I>scale</I>

			<PRE> <I>offset</I> values = Toff Boff Aoff Doff Ioff
			Toff = offset to add to atom types
			Boff = offset to add to bond types
			Aoff = offset to add to angle types
			Doff = offset to add to dihedral types
			Ioff = offset to add to improper types
			<I>toff</I> value = Toff
			Toff = offset to add to atom types
			<I>boff</I> value = Boff
			Boff = offset to add to bond types
			<I>aoff</I> value = Aoff
			Aoff = offset to add to angle types
			<I>doff</I> value = Doff
			Doff = offset to add to dihedral types
			<I>ioff</I> value = Ioff
			Ioff = offset to add to improper types
			<I>scale</I> value = sfactor
			sfactor = scale factor to apply to the size and mass of the molecule
			</PRE>

			</UL>
			<P><B>Examples:</B>
			</P>
			<PRE>molecule 1 mymol.txt
			molecule 1 co2.txt h2o.txt
			molecule CO2 co2.txt boff 3 aoff 2
			molecule 1 mymol.txt offset 6 9 18 23 14
			molecule objects file.1 scale 1.5 file.1 scale 2.0 file.2 scale 1.3
			</PRE>
			<PRE>
			</PRE>
			<P><B>Description:</B>
			</P>
			<P>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:
			</P>
			<UL><LI><A HREF = "fix_deposit.html">fix deposit</A>
			<LI><A HREF = "fix_pour.html">fix pour</A>
			<LI><A HREF = "fix_rigid.html">fix rigid/small</A>
			<LI><A HREF = "fix_shake.html">fix shake</A>
			<LI><A HREF = "fix_gcmc.html">fix gcmc</A>
			<LI><A HREF = "create_atoms.html">create_atoms</A>
			<LI><A HREF = "atom_style.html">atom_style template</A>
			</UL>
			<P>The ID of a molecule template can only contain alphanumeric characters
			and underscores.
			</P>
			<P>A single template can contain multiple molecules, listed one per file.
			Some 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 <A HREF = "atom_style.html">atom_style
			template</A> command allows multiple-molecule templates
			to define a system with more than one templated molecule.
			</P>
			<P>Each filename can be followed by optional keywords which are applied
			only to the molecule in the file as used in this template. This is to
			make it easy to use the same molecule file in different molecule
			templates or in different simulations. You can specify the same file
			multiple times with different optional keywords.
			</P>
			<P>The <I>offset</I>, <I>toff</I>, <I>aoff</I>, <I>doff</I>, <I>ioff</I> keywords add the
			specified offset values to the atom types, bond types, angle types,
			dihedral types, and/or improper types as they are read from the
			molecule file. E.g. if <I>toff</I> = 2, and the file uses atom types
			1,2,3, then each created molecule will have atom types 3,4,5. For the
			<I>offset</I> keyword, all five offset values must be specified, but
			individual values will be ignored if the molecule template does not
			use that attribute (e.g. no bonds).
			</P>
			<P>The <I>scale</I> keyword scales the size of the molecule. This can be
			useful for modeling polydisperse granular rigid bodies. The scale
			factor is applied to each of these properties in the molecule file, if
			they are defined: the individual particle coordinates (Coords
			section), the individual mass of each particle (Masses section), the
			individual diameters of each particle (Diameters section), the total
			mass of the molecule (header keyword = mass), the center-of-mass of
			the molecule (header keyword = com), and the moments of inertia of the
			molecule (header keyword = inertia).
			</P>
			<P>IMPORTANT NOTE: The molecule command can be used to define molecules
			with bonds, angles, dihedrals, imporopers, or special bond lists of
			neighbors within a molecular topology, so that you can later add the
			molecules to your simulation, via one or more of the commands listed
			above. If such molecules do not already exist when LAMMPS creates the
			simulation box, via the <A HREF = "create_box.html">create_box</A> or
			<A HREF = "read_data.html">read_data</A> command, when you later add them you may
			overflow the pre-allocated data structures which store molecular
			topology information with each atom, and an error will be generated.
			Both the <A HREF = "create_box.html">create_box</A> command and the data files read
			by the <A HREF = "read_data.html">read_data</A> command have "extra" options which
			insure space is allocated for storing topology info for molecules that
			are added later.
			</P>
			<P>The format of an individual molecule file is similar to the data file
			read by the <A HREF = "read_data.html">read_data</A> commands, and is as follows.
			</P>
			<P>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.
			</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>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.
			</P>
			<UL><LI>N <I>atoms</I> = # of atoms N in molecule, default = 0
			<LI>Nb <I>bonds</I> = # of bonds Nb in molecule, default = 0
			<LI>Na <I>angles</I> = # of angles Na in molecule, default = 0
			<LI>Nd <I>dihedrals</I> = # of dihedrals Nd in molecule, default = 0
			<LI>Ni <I>impropers</I> = # of impropers Ni in molecule, default = 0
			<LI>Mtotal <I>mass</I> = total mass of molecule
			<LI>Xc Yc Zc <I>com</I> = coordinates of center-of-mass of molecule
			<LI>Ixx Iyy Izz Ixy Ixz Iyz <I>inertia</I> = 6 components of inertia tensor of molecule
			</UL>
			<P>For <I>mass</I>, <I>com</I>, and <I>inertia</I>, the default is for LAMMPS to
			calculate this quantity itself if needed, assuming the molecules
			consists of a set of point particles or finite-size particles (with a
			non-zero diameter) that do not overlap. If finite-size particles in
			the molecule do overlap, LAMMPS will not account for the overlap
			effects when calculating any of these 3 quantities, so you should
			pre-compute them yourself and list the values in the file.
			</P>
			<P>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.
			</P>
			<P>These are the allowed section keywords for the body of the file.
			</P>
			<UL><LI><I>Coords, Types, Charges, Diameters, Masses</I> = atom-property sections
			<LI><I>Bonds, Angles, Dihedrals, Impropers</I> = molecular topology sections
			<LI><I>Special Bond Counts, Special Bonds</I> = special neighbor info
			<LI><I>Shake Flags, Shake Atoms, Shake Bond Types</I> = SHAKE info
			</UL>
			<P>If a Bonds section is specified then the Special Bond Counts and
			Special Bonds sections can also be used, if desired, to explicitly
			list the 1-2, 1-3, 1-4 neighbors within the molecule topology (see
			details below). This is optional since if these sections are not
			included, LAMMPS will auto-generate this information. Note that
			LAMMPS uses this info to properly exclude or weight bonded pairwise
			interactions between bonded atoms. See the
			<A HREF = "special_bonds.html">special_bonds</A> command for more details. One
			reason to list the special bond info explicitly is for the
			<A HREF = "tutorial_drude.html">thermalized Drude oscillator model</A> which treats
			the bonds between nuclear cores and Drude electrons in a different
			manner.
			</P>
			<P>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 <A HREF = "fix_deposit.html">fix deposit</A> command, the
			Coords and Types sections are required. To add a rigid body via the
			<A HREF = "fix_pout.html">fix pour</A> 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 <A HREF = "fix_pour.html">fix pour</A>
			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.
			</P>
			<P>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.
			</P>
			<HR>

			<P><I>Coords</I> section:
			</P>
			<UL><LI>one line per atom
			<LI>line syntax: ID x y z
			<LI>x,y,z = coordinate of atom
			</UL>
			<HR>

			<P><I>Types</I> section:
			</P>
			<UL><LI>one line per atom
			<LI>line syntax: ID type
			<LI>type = atom type of atom
			</UL>
			<HR>

			<P><I>Charges</I> section:
			</P>
			<UL><LI>one line per atom
			<LI>line syntax: ID q
			<LI>q = charge on atom
			</UL>
			<P>This section is only allowed for <A HREF = "atom_style.html">atom styles</A> that
			support charge. If this section is not included, the default charge
			on each atom in the molecule is 0.0.
			</P>
			<HR>

			<P><I>Diameters</I> section:
			</P>
			<UL><LI>one line per atom
			<LI>line syntax: ID diam
			<LI>diam = diameter of atom
			</UL>
			<P>This section is only allowed for <A HREF = "atom_style.html">atom styles</A> 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.
			</P>
			<HR>

			<P><I>Masses</I> section:
			</P>
			<UL><LI>one line per atom
			<LI>line syntax: ID mass
			<LI>mass = mass of atom
			</UL>
			<P>This section is only allowed for <A HREF = "atom_style.html">atom styles</A> that
			support per-atom mass, as opposed to per-type mass. See the
			<A HREF = "mass.html">mass</A> 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
			<A HREF = "units.html">units</A> of mass/volume.
			</P>
			<HR>

			<P><I>Bonds</I> section:
			</P>
			<UL><LI>one line per bond
			<LI>line syntax: ID type atom1 atom2
			<LI>type = bond type (1-Nbondtype)
			<LI>atom1,atom2 = IDs of atoms in bond
			</UL>
			<P>The IDs for the two atoms in each bond should be values
			from 1 to Natoms, where Natoms = # of atoms in the molecule.
			</P>
			<HR>

			<P><I>Angles</I> section:
			</P>
			<UL><LI>one line per angle
			<LI>line syntax: ID type atom1 atom2 atom3
			<LI>type = angle type (1-Nangletype)
			<LI>atom1,atom2,atom3 = IDs of atoms in angle
			</UL>
			<P>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.
			</P>
			<HR>

			<P><I>Dihedrals</I> section:
			</P>
			<UL><LI>one line per dihedral
			<LI>line syntax: ID type atom1 atom2 atom3 atom4
			<LI>type = dihedral type (1-Ndihedraltype)
			<LI>atom1,atom2,atom3,atom4 = IDs of atoms in dihedral
			</UL>
			<P>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.
			</P>
			<HR>

			<P><I>Impropers</I> section:
			</P>
			<UL><LI>one line per improper
			<LI>line syntax: ID type atom1 atom2 atom3 atom4
			<LI>type = improper type (1-Nimpropertype)
			<LI>atom1,atom2,atom3,atom4 = IDs of atoms in improper
			</UL>
			<P>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 <A HREF = "improper_style.html">improper style</A>. See
			the doc pages for individual styles for details.
			</P>
			<HR>

			<P><I>Special Bond Counts</I> section:
			</P>
			<UL><LI>one line per atom
			<LI>line syntax: ID N1 N2 N3
			<LI>N1 = # of 1-2 bonds
			<LI>N2 = # of 1-3 bonds
			<LI>N3 = # of 1-4 bonds
			</UL>
			<P>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
			<A HREF = "special_bonds.html">special_bonds</A> 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.
			</P>
			<HR>

			<P><I>Special Bonds</I> section:
			</P>
			<UL><LI>one line per atom
			<LI>line syntax: ID a b c d ...
			<LI>a,b,c,d,... = IDs of atoms in N1+N2+N3 special bonds
			</UL>
			<P>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 <A HREF = "special_bonds.html">special_bonds</A> 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.
			</P>
			<HR>

			<P><I>Shake Flags</I> section:
			</P>
			<UL><LI>one line per atom
			<LI>line syntax: ID flag
			<LI>flag = 0,1,2,3,4
			</UL>
			<P>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.
			</P>
			<P>The meaning of the flag for each atom is as follows. See the <A HREF = "fix_shake.html">fix
			shake</A> doc page for a further description of SHAKE
			clusters.
			</P>
			<UL><LI>0 = not part of a SHAKE cluster
			<LI>1 = part of a SHAKE angle cluster (two bonds and the angle they form)
			<LI>2 = part of a 2-atom SHAKE cluster with a single bond
			<LI>3 = part of a 3-atom SHAKE cluster with two bonds
			<LI>4 = part of a 4-atom SHAKE cluster with three bonds
			</UL>
			<HR>

			<P><I>Shake Atoms</I> section:
			</P>
			<UL><LI>one line per atom
			<LI>line syntax: ID a b c d
			<LI>a,b,c,d = IDs of atoms in cluster
			</UL>
			<P>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.
			</P>
			<P>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.
			</P>
			<P>If flag = 0, no a,b,c,d values are listed on the line, just the
			(ignored) ID.
			</P>
			<P>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.
			</P>
			<P>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.
			</P>
			<P>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.
			</P>
			<P>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.
			</P>
			<P>See the <A HREF = "fix_shake.html">fix shake</A> doc page for a further description
			of SHAKE clusters.
			</P>
			<HR>

			<P><I>Shake Bond Types</I> section:
			</P>
			<UL><LI>one line per atom
			<LI>line syntax: ID a b c
			<LI>a,b,c = bond types (or angle type) of bonds (or angle) in cluster
			</UL>
			<P>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.
			</P>
			<P>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.
			</P>
			<P>If flag = 0, no a,b,c values are listed on the line, just the
			(ignored) ID.
			</P>
			<P>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.
			</P>
			<P>If flag = 2, only a is listed, where a = bondtype of the bond between
			the 2 atoms in the cluster.
			</P>
			<P>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).
			</P>
			<P>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).
			</P>
			<P>See the <A HREF = "fix_shake.html">fix shake</A> doc page for a further description
			of SHAKE clusters.
			</P>
			<HR>

			<P><B>Restrictions:</B> none
			</P>
			<P><B>Related commands:</B>
			</P>
			<P><A HREF = "fix_deposit.html">fix deposit</A>, <A HREF = "fix_pour.html">fix pour</A>,
			<A HREF = "fix_gcmc.html">fix_gcmc</A>
			</P>
			<P><B>Default:</B>
			</P>
			<P>The default keywords values are offset 0 0 0 0 0 and scale = 1.0.
			</P>
			</HTML>

lammps/doc/doc2/molecule.html7a68ceb57a2dlammps-icms

molecule.htmlView Options

lammps/doc/doc2/molecule.html
7a68ceb57a2dlammps-icms

molecule.html
View Options