git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@11116 f3b2605a-c512-4ea7-a41b-209d697bcdaa

This commit is contained in:
sjplimp 2013-12-17 00:22:24 +00:00
parent 8e179220ec
commit 1f291d91bb
4 changed files with 710 additions and 124 deletions

View File

@ -19,42 +19,44 @@
<LI>deposit = style name of this fix command
<LI>N = # of atoms to insert
<LI>N = # of atoms or molecules to insert
<LI>type = atom type to assign to inserted atoms
<LI>type = atom type to assign to inserted atoms (for atom insertion)
<LI>M = insert a single particle every M steps
<LI>M = insert a single atom or molecule every M steps
<LI>seed = random # seed (positive integer)
<LI>one or more keyword/value pairs may be appended to args
<LI>keyword = <I>region</I> or <I>id</I> or <I>global</I> or <I>local</I> or <I>near</I> or <I>attempt</I> or <I>rate</I> or <I>vx</I> or <I>vy</I> or <I>vz</I> or <I>units</I>
<LI>keyword = <I>region</I> or <I>mol</I> or <I>id</I> or <I>global</I> or <I>local</I> or <I>near</I> or <I>attempt</I> or <I>rate</I> or <I>vx</I> or <I>vy</I> or <I>vz</I> or <I>units</I>
<PRE> <I>region</I> value = region-ID
region-ID = ID of region to use as insertion volume
<I>mol</I> value = template-ID
template-ID = ID of molecule template specified in a separate <A HREF = "molecule.html">molecule</A> command
<I>id</I> value = <I>max</I> or <I>next</I>
max = atom ID for new atom is max ID of all current atoms plus one
next = atom ID for new atom increments by one for every deposition
max = atom ID for new atom(s) is max ID of all current atoms plus one
next = atom ID for new atom(s) increments by one for every deposition
<I>global</I> values = lo hi
lo,hi = put new particle a distance lo-hi above all other particles (distance units)
lo,hi = put new atom/molecule a distance lo-hi above all other atoms (distance units)
<I>local</I> values = lo hi delta
lo,hi = put new particle a distance lo-hi above any nearby particle beneath it (distance units)
lo,hi = put new atom/molecule a distance lo-hi above any nearby atom beneath it (distance units)
delta = lateral distance within which a neighbor is considered "nearby" (distance units)
<I>near</I> value = R
R = only insert particle if further than R from existing particles (distance units)
R = only insert atom/molecule if further than R from existing particles (distance units)
<I>attempt</I> value = Q
Q = attempt a single insertion up to Q times
<I>rate</I> value = V
V = z velocity (y in 2d) at which insertion volume moves (velocity units)
<I>vx</I> values = vxlo vxhi
vxlo,vxhi = range of x velocities for inserted particle (velocity units)
vxlo,vxhi = range of x velocities for inserted atom/molecule (velocity units)
<I>vy</I> values = vylo vyhi
vylo,vyhi = range of y velocities for inserted particle (velocity units)
vylo,vyhi = range of y velocities for inserted atom/molecule (velocity units)
<I>vz</I> values = vzlo vzhi
vzlo,vzhi = range of z velocities for inserted particle (velocity units)
vzlo,vzhi = range of z velocities for inserted atom/molecule (velocity units)
<I>target</I> values = tx ty tz
tx,ty,tz = location of sputtering target (distance units)
tx,ty,tz = location of target point (distance units)
<I>units</I> value = <I>lattice</I> or <I>box</I>
lattice = the geometry is defined in lattice units
box = the geometry is defined in simulation box units
@ -64,28 +66,35 @@
<P><B>Examples:</B>
</P>
<PRE>fix 3 all deposit 1000 2 100 29494 region myblock local 1.0 1.0 1.0 units box
fix 2 newatoms deposit 10000 1 500 12345 region disk near 2.0 vz -1.0 -0.8
</PRE>
<PRE>fix 4 sputter deposit 1000 2 500 12235 region sphere vz -1.0 -1.0 target 5.0 5.0 0.0 units lattice
fix 2 newatoms deposit 10000 1 500 12345 region disk near 2.0 vz -1.0 -0.8
fix 4 sputter deposit 1000 2 500 12235 region sphere vz -1.0 -1.0 target 5.0 5.0 0.0 units lattice
</PRE>
<P><B>Description:</B>
</P>
<P>Insert a single particle into the simulation domain every M timesteps
until N particles have been inserted. This is useful for simulating
the deposition of particles onto a surface.
<P>Insert a single atom or molecule into the simulation domain every M
timesteps until N atoms or molecules have been inserted. This is
useful for simulating deposition onto a surface. For the remainder of
this doc page, a single inserted atom or molecule is referred to as a
"particle".
</P>
<P>Inserted particles have the specified atom type and are assigned to
two groups: the default group "all" and the group specified in the fix
deposit command (which can also be "all").
<P>If inserted particles are individual atoms, they are assigned the
specified atom type. For molecules the specified type is ignored, and
the type of each atom in the inserted molecule is specified in the
file read by the <A HREF = "molecule.html">molecule</A> command.
</P>
<P>All atoms in the inserted particle are assigned to two groups: the
default group "all" and the group specified in the fix deposit command
(which can also be "all").
</P>
<P>If you are computing temperature values which include inserted
particles, you will want to use the <A HREF = "compute_modify.html">compute_modify</A>
dynamic option, which insures the current number of atoms is used as a
normalizing factor each time temperature is computed.
particles, you will want to use the
<A HREF = "compute_modify.html">compute_modify</A> dynamic option, which insures the
current number of atoms is used as a normalizing factor each time the
temperature is computed.
</P>
<P>Care must be taken that inserted particles are not too near existing
particles, using the options described below. When inserting
particles above a surface in a non-periodic box (see the
atoms, using the options described below. When inserting particles
above a surface in a non-periodic box (see the
<A HREF = "boundary.html">boundary</A> command), the possibility of a particle
escaping the surface and flying upward should be considered, since the
particle may be lost or the box size may grow infinitely large. A
@ -93,17 +102,36 @@ particle may be lost or the box size may grow infinitely large. A
prevent this behavior. Note that if a shrink-wrap boundary is used,
it is OK to insert the new particle outside the box, however the box
will immediately be expanded to include the new particle. When
simulating a sputtering experiment it is probably more realistic
to ignore those atoms using the <A HREF = "thermo_modify.html">thermo_modify</A>
command with the <I>lost ignore</I> option and a fixed <A HREF = "boundary.html">boundary</A>.
simulating a sputtering experiment it is probably more realistic to
ignore those atoms using the <A HREF = "thermo_modify.html">thermo_modify</A>
command with the <I>lost ignore</I> option and a fixed
<A HREF = "boundary.html">boundary</A>.
</P>
<P>This command must use the <I>region</I> keyword to define an insertion
volume. The specified region must have been previously defined with a
<A HREF = "region.html">region</A> command. It must be defined with side = <I>in</I>.
<P>The fix deposit command must use the <I>region</I> keyword to define an
insertion volume. The specified region must have been previously
defined with a <A HREF = "region.html">region</A> command. It must be defined with
side = <I>in</I>.
</P>
<P>Each timestep a particle is to be inserted, its coordinates are chosen
as follows. A random position within the insertion volume is
generated. If neither the <I>global</I> or <I>local</I> keyword is used, that
<P>Individual atoms are inserted, unless the <I>mol</I> keyword is used. It
specifies a previously defined <I>template-ID</I> used by the
<A HREF = "molecule.html">molecule</A> command which reads a file that defines the
molecule. The coordinates, atom types, charges, etc, as well as any
bond/angle/etc information for the molecule must be specified in the
molecule file. See the <A HREF = "molecule.html">molecule</A> command for details.
The only required settings from this file are the coordinates and
types of atoms in the molecule.
</P>
<P>Each timestep a particle is inserted, the coordinates for its atoms
are chosen as follows. For insertion of individual atoms, the
"position" referred to in the following description is the coordinate
of the atom. For insertion of molecule, the "position<A HREF = "molecule.html"> is the
geometric center of the molecule; see the (molecule</A> doc
page for details. A random rotation of the molecule around its center
point is performed, which determines the coordinates all the
individual atoms.
</P>
<P>A random position within the region insertion volume is generated. If
neither the <I>global</I> or <I>local</I> keyword is used, the random position
is the trial position. If the <I>global</I> keyword is used, the random
x,y values are used, but the z position of the new particle is set
above the highest current atom in the simulation by a distance
@ -112,14 +140,18 @@ the y position.) If the <I>local</I> keyword is used, the z position is
set a distance between lo/hi above the highest current atom in the
simulation that is "nearby" the chosen x,y position. In this context,
"nearby" means the lateral distance (in x,y) between the new and old
particles is less than the delta parameter.
particles is less than the <I>delta</I> setting.
</P>
<P>Once a trial x,y,z location has been computed, the insertion is only
performed if no current particle in the simulation is within a
distance R of the new particle. If this test fails, a new random
position within the insertion volume is chosen and another trial is
made. Up to Q attempts are made. If an atom is not successfully
deposited, LAMMPS prints a warning message.
<P>Once a trial x,y,z position has been selected, the insertion is only
performed if no current atom in the simulation is within a distance R
of any atom in the new particle. Note that the default value for R is
0.0, which will allow atoms to strongly overlap if you are inserting
where other atoms are present. This distance test is performed
independently for each atom in an inserted molecule, based on the
randomly rotated configuration of the molecule. If this test fails, a
new random position within the insertion volume is chosen and another
trial is made. Up to Q attempts are made. If the particle is not
successfully inserted, LAMMPS prints a warning message.
</P>
<P>The <I>rate</I> option moves the insertion volume in the z direction (3d)
or y direction (2d). This enables particles to be inserted from a
@ -130,22 +162,31 @@ options choose a z-coordinate for insertion independently.
<P>The vx, vy, and vz components of velocity for the inserted particle
are set using the values specified for the <I>vx</I>, <I>vy</I>, and <I>vz</I>
keywords. Note that normally, new particles should be a assigned a
negative vertical velocity so that they move towards the surface.
negative vertical velocity so that they move towards the surface. For
molecules, the same velocity is given to every particle (no rotation
or bond vibration).
</P>
<P>In case the <I>target</I> option is used, the velocity vector of the
inserted particle will be changed in a way so that it would pass
through the specified coordinate. This allows convenient simulation
of a sputtering process.
<P>If the <I>target</I> option is used, the velocity vector of the inserted
particle is changed so that it points from the insertion position
towards the specified target point. The magnitude of the velocity is
unchanged. This can be useful, for example, for simulating a
sputtering process. E.g. the target point can be far away, so that
all incident particles strike the surface as if they are in an
incident beam of particles at a prescribed angle.
</P>
<P>The <I>id</I> keyword determines how an atom ID is assigned to newly
deposited atoms. For the <I>max</I> setting, the IDs of all current atoms
are checked and the new ID is the current maximum value plus one.
This means that if atoms have left the system, the new ID may reflect
this fact. For the <I>next</I> setting, the maximum ID of all atoms is
stored at the time the fix is defined. Each time a deposited atom is
added, this value is incremented by one and assigned to the new atom.
Thus atom IDs for deposited atoms will be consecutive even if atoms
leave the system over time.
<P>The <I>id</I> keyword determines how atom IDs and molecule IDs are assigned
to newly deposited particles. Molecule IDs are only assigned if
molecules are being inserted. For the <I>max</I> setting, the atom and
molecule IDs of all current atoms are checked. Atoms in the new
particle are assigned IDs starting with the current maximum plus one.
If a molecule is inserted it is assigned an ID = current maximum plus
one. This means that if particles leave the system, the new IDs may
replace the lost ones. For the <I>next</I> setting, the maximum ID of any
atom and molecule is stored at the time the fix is defined. Each time
a new particle is added, this value is incremented to assign IDs to
the new atom(s) or molecule. Thus atom and molecule IDs for deposited
particles will be consecutive even if particles leave the system over
time.
</P>
<P>The <I>units</I> keyword determines the meaning of the distance units used
for the other deposition parameters. A <I>box</I> value selects standard
@ -159,9 +200,9 @@ units of distance or velocity.
<P><B>Restart, fix_modify, output, run start/stop, minimize info:</B>
</P>
<P>This fix writes the state of the deposition to <A HREF = "restart.html">binary restart
files</A>. This includes information about how many atoms
have been depositied, the random number generator seed, the next
timestep for deposition, etc. See the
files</A>. This includes information about how many
particles have been depositied, the random number generator seed, the
next timestep for deposition, etc. See the
<A HREF = "read_restart.html">read_restart</A> command for info on how to re-specify
a fix in an input script that reads a restart file, so that the
operation of the fix continues in an uninterrupted fashion.
@ -184,8 +225,9 @@ defined by the <A HREF = "region.html">region</A> command.
</P>
<P><B>Default:</B>
</P>
<P>The option defaults are id = max, delta = 0.0, near = 0.0, attempt =
10, rate = 0.0, vx = 0.0 0.0, vy = 0.0 0.0, vz = 0.0 0.0, and units =
lattice.
<P>Insertions are performed for individual atoms, i.e. no <I>mol</I> setting
is defined. Additional option defaults are id = max, delta = 0.0,
near = 0.0, attempt = 10, rate = 0.0, vx = 0.0 0.0, vy = 0.0 0.0, vz =
0.0 0.0, and units = lattice.
</P>
</HTML>

View File

@ -14,36 +14,38 @@ fix ID group-ID deposit N type M seed keyword values ... :pre
ID, group-ID are documented in "fix"_fix.html command :ulb,l
deposit = style name of this fix command :l
N = # of atoms to insert :l
type = atom type to assign to inserted atoms :l
M = insert a single particle every M steps :l
N = # of atoms or molecules to insert :l
type = atom type to assign to inserted atoms (for atom insertion) :l
M = insert a single atom or molecule every M steps :l
seed = random # seed (positive integer) :l
one or more keyword/value pairs may be appended to args :l
keyword = {region} or {id} or {global} or {local} or {near} or {attempt} or {rate} or {vx} or {vy} or {vz} or {units} :l
keyword = {region} or {mol} or {id} or {global} or {local} or {near} or {attempt} or {rate} or {vx} or {vy} or {vz} or {units} :l
{region} value = region-ID
region-ID = ID of region to use as insertion volume
{mol} value = template-ID
template-ID = ID of molecule template specified in a separate "molecule"_molecule.html command
{id} value = {max} or {next}
max = atom ID for new atom is max ID of all current atoms plus one
next = atom ID for new atom increments by one for every deposition
max = atom ID for new atom(s) is max ID of all current atoms plus one
next = atom ID for new atom(s) increments by one for every deposition
{global} values = lo hi
lo,hi = put new particle a distance lo-hi above all other particles (distance units)
lo,hi = put new atom/molecule a distance lo-hi above all other atoms (distance units)
{local} values = lo hi delta
lo,hi = put new particle a distance lo-hi above any nearby particle beneath it (distance units)
lo,hi = put new atom/molecule a distance lo-hi above any nearby atom beneath it (distance units)
delta = lateral distance within which a neighbor is considered "nearby" (distance units)
{near} value = R
R = only insert particle if further than R from existing particles (distance units)
R = only insert atom/molecule if further than R from existing particles (distance units)
{attempt} value = Q
Q = attempt a single insertion up to Q times
{rate} value = V
V = z velocity (y in 2d) at which insertion volume moves (velocity units)
{vx} values = vxlo vxhi
vxlo,vxhi = range of x velocities for inserted particle (velocity units)
vxlo,vxhi = range of x velocities for inserted atom/molecule (velocity units)
{vy} values = vylo vyhi
vylo,vyhi = range of y velocities for inserted particle (velocity units)
vylo,vyhi = range of y velocities for inserted atom/molecule (velocity units)
{vz} values = vzlo vzhi
vzlo,vzhi = range of z velocities for inserted particle (velocity units)
vzlo,vzhi = range of z velocities for inserted atom/molecule (velocity units)
{target} values = tx ty tz
tx,ty,tz = location of sputtering target (distance units)
tx,ty,tz = location of target point (distance units)
{units} value = {lattice} or {box}
lattice = the geometry is defined in lattice units
box = the geometry is defined in simulation box units :pre
@ -52,27 +54,35 @@ keyword = {region} or {id} or {global} or {local} or {near} or {attempt} or {rat
[Examples:]
fix 3 all deposit 1000 2 100 29494 region myblock local 1.0 1.0 1.0 units box
fix 2 newatoms deposit 10000 1 500 12345 region disk near 2.0 vz -1.0 -0.8 :pre
fix 2 newatoms deposit 10000 1 500 12345 region disk near 2.0 vz -1.0 -0.8
fix 4 sputter deposit 1000 2 500 12235 region sphere vz -1.0 -1.0 target 5.0 5.0 0.0 units lattice :pre
[Description:]
Insert a single particle into the simulation domain every M timesteps
until N particles have been inserted. This is useful for simulating
the deposition of particles onto a surface.
Insert a single atom or molecule into the simulation domain every M
timesteps until N atoms or molecules have been inserted. This is
useful for simulating deposition onto a surface. For the remainder of
this doc page, a single inserted atom or molecule is referred to as a
"particle".
Inserted particles have the specified atom type and are assigned to
two groups: the default group "all" and the group specified in the fix
deposit command (which can also be "all").
If inserted particles are individual atoms, they are assigned the
specified atom type. For molecules the specified type is ignored, and
the type of each atom in the inserted molecule is specified in the
file read by the "molecule"_molecule.html command.
All atoms in the inserted particle are assigned to two groups: the
default group "all" and the group specified in the fix deposit command
(which can also be "all").
If you are computing temperature values which include inserted
particles, you will want to use the "compute_modify"_compute_modify.html
dynamic option, which insures the current number of atoms is used as a
normalizing factor each time temperature is computed.
particles, you will want to use the
"compute_modify"_compute_modify.html dynamic option, which insures the
current number of atoms is used as a normalizing factor each time the
temperature is computed.
Care must be taken that inserted particles are not too near existing
particles, using the options described below. When inserting
particles above a surface in a non-periodic box (see the
atoms, using the options described below. When inserting particles
above a surface in a non-periodic box (see the
"boundary"_boundary.html command), the possibility of a particle
escaping the surface and flying upward should be considered, since the
particle may be lost or the box size may grow infinitely large. A
@ -80,17 +90,36 @@ particle may be lost or the box size may grow infinitely large. A
prevent this behavior. Note that if a shrink-wrap boundary is used,
it is OK to insert the new particle outside the box, however the box
will immediately be expanded to include the new particle. When
simulating a sputtering experiment it is probably more realistic
to ignore those atoms using the "thermo_modify"_thermo_modify.html
command with the {lost ignore} option and a fixed "boundary"_boundary.html.
simulating a sputtering experiment it is probably more realistic to
ignore those atoms using the "thermo_modify"_thermo_modify.html
command with the {lost ignore} option and a fixed
"boundary"_boundary.html.
This command must use the {region} keyword to define an insertion
volume. The specified region must have been previously defined with a
"region"_region.html command. It must be defined with side = {in}.
The fix deposit command must use the {region} keyword to define an
insertion volume. The specified region must have been previously
defined with a "region"_region.html command. It must be defined with
side = {in}.
Each timestep a particle is to be inserted, its coordinates are chosen
as follows. A random position within the insertion volume is
generated. If neither the {global} or {local} keyword is used, that
Individual atoms are inserted, unless the {mol} keyword is used. It
specifies a previously defined {template-ID} used by the
"molecule"_molecule.html command which reads a file that defines the
molecule. The coordinates, atom types, charges, etc, as well as any
bond/angle/etc information for the molecule must be specified in the
molecule file. See the "molecule"_molecule.html command for details.
The only required settings from this file are the coordinates and
types of atoms in the molecule.
Each timestep a particle is inserted, the coordinates for its atoms
are chosen as follows. For insertion of individual atoms, the
"position" referred to in the following description is the coordinate
of the atom. For insertion of molecule, the "position" is the
geometric center of the molecule; see the (molecule"_molecule.html doc
page for details. A random rotation of the molecule around its center
point is performed, which determines the coordinates all the
individual atoms.
A random position within the region insertion volume is generated. If
neither the {global} or {local} keyword is used, the random position
is the trial position. If the {global} keyword is used, the random
x,y values are used, but the z position of the new particle is set
above the highest current atom in the simulation by a distance
@ -99,14 +128,18 @@ the y position.) If the {local} keyword is used, the z position is
set a distance between lo/hi above the highest current atom in the
simulation that is "nearby" the chosen x,y position. In this context,
"nearby" means the lateral distance (in x,y) between the new and old
particles is less than the delta parameter.
particles is less than the {delta} setting.
Once a trial x,y,z location has been computed, the insertion is only
performed if no current particle in the simulation is within a
distance R of the new particle. If this test fails, a new random
position within the insertion volume is chosen and another trial is
made. Up to Q attempts are made. If an atom is not successfully
deposited, LAMMPS prints a warning message.
Once a trial x,y,z position has been selected, the insertion is only
performed if no current atom in the simulation is within a distance R
of any atom in the new particle. Note that the default value for R is
0.0, which will allow atoms to strongly overlap if you are inserting
where other atoms are present. This distance test is performed
independently for each atom in an inserted molecule, based on the
randomly rotated configuration of the molecule. If this test fails, a
new random position within the insertion volume is chosen and another
trial is made. Up to Q attempts are made. If the particle is not
successfully inserted, LAMMPS prints a warning message.
The {rate} option moves the insertion volume in the z direction (3d)
or y direction (2d). This enables particles to be inserted from a
@ -117,22 +150,31 @@ options choose a z-coordinate for insertion independently.
The vx, vy, and vz components of velocity for the inserted particle
are set using the values specified for the {vx}, {vy}, and {vz}
keywords. Note that normally, new particles should be a assigned a
negative vertical velocity so that they move towards the surface.
negative vertical velocity so that they move towards the surface. For
molecules, the same velocity is given to every particle (no rotation
or bond vibration).
In case the {target} option is used, the velocity vector of the
inserted particle will be changed in a way so that it would pass
through the specified coordinate. This allows convenient simulation
of a sputtering process.
If the {target} option is used, the velocity vector of the inserted
particle is changed so that it points from the insertion position
towards the specified target point. The magnitude of the velocity is
unchanged. This can be useful, for example, for simulating a
sputtering process. E.g. the target point can be far away, so that
all incident particles strike the surface as if they are in an
incident beam of particles at a prescribed angle.
The {id} keyword determines how an atom ID is assigned to newly
deposited atoms. For the {max} setting, the IDs of all current atoms
are checked and the new ID is the current maximum value plus one.
This means that if atoms have left the system, the new ID may reflect
this fact. For the {next} setting, the maximum ID of all atoms is
stored at the time the fix is defined. Each time a deposited atom is
added, this value is incremented by one and assigned to the new atom.
Thus atom IDs for deposited atoms will be consecutive even if atoms
leave the system over time.
The {id} keyword determines how atom IDs and molecule IDs are assigned
to newly deposited particles. Molecule IDs are only assigned if
molecules are being inserted. For the {max} setting, the atom and
molecule IDs of all current atoms are checked. Atoms in the new
particle are assigned IDs starting with the current maximum plus one.
If a molecule is inserted it is assigned an ID = current maximum plus
one. This means that if particles leave the system, the new IDs may
replace the lost ones. For the {next} setting, the maximum ID of any
atom and molecule is stored at the time the fix is defined. Each time
a new particle is added, this value is incremented to assign IDs to
the new atom(s) or molecule. Thus atom and molecule IDs for deposited
particles will be consecutive even if particles leave the system over
time.
The {units} keyword determines the meaning of the distance units used
for the other deposition parameters. A {box} value selects standard
@ -146,9 +188,9 @@ units of distance or velocity.
[Restart, fix_modify, output, run start/stop, minimize info:]
This fix writes the state of the deposition to "binary restart
files"_restart.html. This includes information about how many atoms
have been depositied, the random number generator seed, the next
timestep for deposition, etc. See the
files"_restart.html. This includes information about how many
particles have been depositied, the random number generator seed, the
next timestep for deposition, etc. See the
"read_restart"_read_restart.html command for info on how to re-specify
a fix in an input script that reads a restart file, so that the
operation of the fix continues in an uninterrupted fashion.
@ -171,6 +213,7 @@ defined by the "region"_region.html command.
[Default:]
The option defaults are id = max, delta = 0.0, near = 0.0, attempt =
10, rate = 0.0, vx = 0.0 0.0, vy = 0.0 0.0, vz = 0.0 0.0, and units =
lattice.
Insertions are performed for individual atoms, i.e. no {mol} setting
is defined. Additional option defaults are id = max, delta = 0.0,
near = 0.0, attempt = 10, rate = 0.0, vx = 0.0 0.0, vy = 0.0 0.0, vz =
0.0 0.0, and units = lattice.

253
doc/molecule.html Normal file
View File

@ -0,0 +1,253 @@
<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 file
</PRE>
<UL><LI>ID = user-assigned name or template ID for the molecule
<LI>file = name of file containing molecule description
</UL>
<P><B>Examples:</B>
</P>
<PRE>molecule 1 mymol
molecule CO2 co2.txt
</PRE>
<P><B>Description:</B>
</P>
<P>Define a molecule 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 use molecule definitions include (or will
include) <A HREF = "fix_deposit.html">fix deposit</A>, <A HREF = "fix_pour.html">fix pour</A>, and
<A HREF = "fix_gcmc.html">fix gcmc</A>.
</P>
<P>The ID of a molecule can only contain alphanumeric characters and
underscores.
</P>
<P>The format of the molecule description 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 value(s) are read from the beginning of the line.
Thus the keyword <I>atoms</I> should be in a line like "10 atoms"; the
keyword <I>ylo yhi</I> should be in a line like "-10.0 10.0 ylo yhi"; the
keyword <I>xy xz yz</I> 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.
</P>
<UL><LI><I>atoms</I> = # of atoms in molecule
<LI><I>bonds</I> = # of bonds in molecule
<LI><I>angles</I> = # of angles in molecule
<LI><I>dihedrals</I> = # of dihedrals in molecule
<LI><I>impropers</I> = # of impropers in molecule
</UL>
<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
</UL>
<P>IMPORTANT NOTE: Whether a section is required depends on how the
molecule definition 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 add finite-size granular particles. If the Diameters
section is not specified, added particles will have a default diameter
of 1.0. See the doc pages for LAMMPS commands that use read-in
molecules 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 as a
number from 1 to Nlines for the section, indicating which atom (or
bond, etc) the entry applies to. The lines must be listed in order
from 1 to Nlines.
</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 not listed, 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 not listed, 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><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> none
</P>
</HTML>

248
doc/molecule.txt Normal file
View File

@ -0,0 +1,248 @@
"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 file :pre
ID = user-assigned name or template ID for the molecule
file = name of file containing molecule description :ul
[Examples:]
molecule 1 mymol
molecule CO2 co2.txt :pre
[Description:]
Define a molecule 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 use molecule definitions include (or will
include) "fix deposit"_fix_deposit.html, "fix pour"_fix_pour.html, and
"fix gcmc"_fix_gcmc.html.
The ID of a molecule can only contain alphanumeric characters and
underscores.
The format of the molecule description 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 value(s) are read from the beginning of the line.
Thus the keyword {atoms} should be in a line like "10 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.
{atoms} = # of atoms in molecule
{bonds} = # of bonds in molecule
{angles} = # of angles in molecule
{dihedrals} = # of dihedrals in molecule
{impropers} = # of impropers in molecule :ul
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 :ul
IMPORTANT NOTE: Whether a section is required depends on how the
molecule definition 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 add finite-size granular particles. If the Diameters
section is not specified, added particles will have a default diameter
of 1.0. See the doc pages for LAMMPS commands that use read-in
molecules 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 as a
number from 1 to Nlines for the section, indicating which atom (or
bond, etc) the entry applies to. The lines must be listed in order
from 1 to Nlines.
: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 not listed, 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 not listed, 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
[Restrictions:] none
[Related commands:]
"fix deposit"_fix_deposit.html, "fix pour"_fix_pour.html,
"fix_gcmc"_fix_gcmc.html
[Default:] none