262 lines
13 KiB
HTML
262 lines
13 KiB
HTML
<HTML>
|
|
<CENTER><A HREF = "http://www.cfdem.com">LIGGGHTS WWW Site</A> - <A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LIGGGHTS Documentation</A> - <A HREF = "Section_commands.html#comm">LIGGGHTS Commands</A>
|
|
</CENTER>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<HR>
|
|
|
|
<H3>fix insert/stream command
|
|
</H3>
|
|
<P><B>Syntax:</B>
|
|
</P>
|
|
<PRE>fix ID group-ID insert/stream seed seed_value distributiontemplate dist-ID general_keywords general_values stream_keywords stream_values ...
|
|
</PRE>
|
|
<UL><LI>ID, group-ID are documented in <A HREF = "fix.html">fix</A> command
|
|
|
|
<LI>insert/stream = style name of this fix command
|
|
|
|
<LI>seed = obligatory keyword
|
|
|
|
<LI>seed_value = random # seed (positive integer)
|
|
|
|
<LI>distributiontemplate = obligatory keyword
|
|
|
|
<LI>dist-ID = ID of a <A HREF = "fix_particledistribution_discrete.html">fix_particledistribution_discrete</A> to be used for particle insertion
|
|
|
|
<LI>one or more general keyword/value pairs can be appended
|
|
|
|
<LI>general_keywords = <I>verbose</I> or <I>maxattampt</I> or <I>nparticles</I> or <I>mass</I> or <I>particlerate</I> or <I>massrate</I> or <I>insert_every</I> or <I>overlapcheck</I> or <I>all_in</I> or <I>random_distribute</I> or<I>vel constant</I> or <I>vel uniform</I> or <I>vel gaussian</I> or <I>orientation</I> or <I>omega</I>
|
|
|
|
<PRE> <I>verbose</I> = yes or no
|
|
<I>maxattempt</I> value = ma
|
|
ma = max # of insertion attempts per atom (positive integer)
|
|
<I>nparticles</I> values = np or INF
|
|
np = number of particles to insert (positive integer)
|
|
INF = insert as many particles as possible
|
|
<I>mass</I> values = mp
|
|
mp = mass of particles to be inserted (positive float)
|
|
INF = insert as many particles as possible
|
|
<I>particlerate</I> values = pr
|
|
pr = particle inseration rate (particles/time units)
|
|
<I>massrate</I> values = mr
|
|
mr = mass inseration rate (mass/time units)
|
|
<I>insert_every</I> value = ie
|
|
ie = every how many time-steps particles are inserted - insertion happens periodically (positive integer)
|
|
<I>start</I> value = ts
|
|
ts = time-step at which insertion should start (positive integer larger than current time-step)
|
|
<I>all_in</I> value = yes or no
|
|
<I>random_distribute</I> value = exact or uncorrelated
|
|
<I>vel constant</I> values = vx vy vz
|
|
vx = x-velocity at insertion (velocity units)
|
|
vy = y-velocity at insertion (velocity units)
|
|
vz = z-velocity at insertion (velocity units)
|
|
<I>vel uniform</I> values = vx vy vz vFluctx vFlucty vFluctz
|
|
vx = mean x-velocity at insertion (velocity units)
|
|
vy = mean y-velocity at insertion (velocity units)
|
|
vz = mean z-velocity at insertion (velocity units)
|
|
vFluctx = amplitude of uniform x-velocity fluctuation at insertion (velocity units)
|
|
vFlucty = amplitude of uniform y-velocity fluctuation at insertion (velocity units)
|
|
vFluctz = amplitude of uniform z-velocity fluctuation at insertion (velocity units)
|
|
<I>vel gaussian</I> values = vx vy vz vFluctx vFlucty vFluctz
|
|
vx = mean x-velocity at insertion (velocity units)
|
|
vy = mean y-velocity at insertion (velocity units)
|
|
vz = mean z-velocity at insertion (velocity units)
|
|
vFluctx = standard deviation of Gaussian x-velocity fluctuation at insertion (velocity units)
|
|
vFlucty = standard deviation of Gaussian y-velocity fluctuation at insertion (velocity units)
|
|
vFluctz = standard deviation of Gaussian z-velocity fluctuation at insertion (velocity units)
|
|
<I>orientation</I> values = random or template
|
|
random = randomize rotational orientation
|
|
template = use orientation from particle template
|
|
<I>omega</I> values = constant omegax omegay omegaz
|
|
constant = obligatory word
|
|
omegax = x-comonent of angular velocity (1/time units)
|
|
omegay = y-comonent of angular velocity (1/time units)
|
|
omegaz = z-comonent of angular velocity (1/time units)
|
|
</PRE>
|
|
<LI>following the general keyword/value section, one or more stream keyword/value pairs can be appended for the fix insert/stream command
|
|
|
|
<LI>stream_keywords = <I>duration</I> or <I>parallel</I> or <I>insertion_face</I> or <I>extrude_length</I>
|
|
|
|
<PRE> <I>insertion_face</I> value = mesh-ID
|
|
mesh-ID = ID of the <A HREF = "fix_mesh_surface.html">fix mesh/surface or fix mesh/surface/planar</A> to use as starting face for particle generation
|
|
<I>extrude_length</I> values = L
|
|
L = length for extruding the insertion face in normal direction so to generate in insertion volume
|
|
<I>parallel</I> values = yes or no
|
|
yes, no = pre-calculate location of overlap of processor subdomains and extrusion volume to some extent
|
|
<I>duration</I> values = du
|
|
du = duration of insertion in time-steps
|
|
</PRE>
|
|
|
|
</UL>
|
|
<P><B>Examples:</B>
|
|
</P>
|
|
<P>fix ins all insert/stream seed 1001 distributiontemplate pdd1 nparticles 5000 vel constant 0. -0.5 -2. particlerate 1000 overlapcheck yes insertion_face ins_mesh extrude_length 0.6
|
|
</P>
|
|
<P><B>Description:</B>
|
|
</P>
|
|
<P>Insert particles into a granular run either once or every few timesteps
|
|
within a specified region until either np particles have been inserted
|
|
or the desired particle mass (mp) has been reached.
|
|
</P>
|
|
<P>The <I>verbose</I> keyword controlls whether statistics about particle
|
|
insertion is output to the screen each time particles are inserted.
|
|
</P>
|
|
<P>Each timestep particles are inserted, they are placed randomly inside
|
|
the insertion volume so as to mimic a stream of poured particles. The
|
|
insertion volume is generated by extruding the insertion face as
|
|
specified via <I>insertion_face</I> in the direction of the face normal.
|
|
The sign of this face normal is automatically flipped so that it
|
|
is opposite to the normal component of the insertion velocity.
|
|
</P>
|
|
<P>To specify the number of particles to be inserted, you must use either
|
|
the <I>nparticles</I> or the <I>mass</I> keyword (but not both). In the latter
|
|
case, the number of particles to be inserted is calculated from the
|
|
mass expectancy given by the particle distribution. The <I>start</I> keyword
|
|
can be used to set the time-step at which the insertion should start.
|
|
</P>
|
|
<P>Likewise, you can use the <I>particlerate</I> or the <I>massrate</I> keyword (but not both)
|
|
to control the insertion rate. Particles are not inserted continuously,
|
|
but in packets (for efficiency reasons). Particles are inserted again
|
|
after enough time has elapsed that the previously inserted particles
|
|
have left the insertion volume.
|
|
</P>
|
|
<P>One of the two keywords <I>insert_every</I> and <I>extrude_length</I> must be
|
|
provided by the user (but not both).
|
|
</P>
|
|
<P>In case <I>insert_every</I> is defined, this sets the frequency of the particle
|
|
insertion directly, i.e. the number of time-steps between two insertions.
|
|
The number of particles to be inserted at each insertion event is calculated
|
|
from the insertion rate and <I>insert_every</I>.
|
|
</P>
|
|
<P>If <I>extrude_length</I> is specified, the amount of extrusion is fixed and
|
|
the insertion frequency is calculated from <I>extrude_length</I> and the insertion
|
|
velocity normal to the insertion face.
|
|
</P>
|
|
<P>When defining <I>insert_every</I>, you have the possibility to define the duration
|
|
of each insertion via the <I>duration</I> keyword. <I>duration</I> < <I>insert_every</I>
|
|
will generate a "pulsed" stream as opposed to a continuous stream.
|
|
Example: Setting <I>insert_every</I> = 1000 and <I>duration</I> = 600 will produce
|
|
a stream that pours material for 600 time-steps, will pause for 400 time-steps,
|
|
pour for another 600 time-steps etc.
|
|
</P>
|
|
<P>As mentioned above, particles are inserted again after enough time has
|
|
elapsed that the previously inserted particles have left the insertion
|
|
volume. Until the time these particles reach the insertion face, no
|
|
other forces affect the particles (pair forces, gravity etc.). Fix
|
|
insert/stream internally issues a special integrator to take care
|
|
of this. This procedure guarantees that the specified velocity,
|
|
omega etc. values are perfectly met at the specified insertion face.
|
|
</P>
|
|
<P>The larger the volume, the more particles that can be inserted at one
|
|
insertion step. Insertions will continue until the desired # of particles
|
|
has been inserted.
|
|
</P>
|
|
<P>NOTE: The insertion face must be a planar face, and the insertion
|
|
velocity projected on the face normal must be non-zero.
|
|
</P>
|
|
<P>NOTE: Keywords <I>insert_every</I> and <I>extrude_length</I> may not be used
|
|
together
|
|
</P>
|
|
<P>NOTE: Keywords <I>duration</I> and <I>extrude_length</I> cannot be used together.
|
|
</P>
|
|
<P>This command must use the distributiontemplate keyword to refer to a
|
|
<A HREF = "fix_particledistribution_discrete.html">fix_particledistribution_discrete</A> (defined by dist-fix-ID) that defines the properties of the
|
|
inserted particles.
|
|
</P>
|
|
<P>Inserted particles are assigned the atom type specified by the
|
|
particledistribution defined via the
|
|
<A HREF = "fix_particledistribution_discrete.html">fix_particledistribution_discrete</A> and
|
|
are assigned to 4 groups: the default group "all" and the group
|
|
specified in the fix insert command, as well as the groups specified
|
|
in the <A HREF = "fix_particledistribution_discrete.html">fix_particledistribution_discrete</A>
|
|
and <A HREF = "fix_particletemplate_sphere.html">fix_particletemplate_sphere</A>
|
|
command (all of which can also be "all").
|
|
</P>
|
|
<P>If overlapcheck if performed, the number of insertion attempts per
|
|
particle can be specified via the <I>maxattempt</I> keyword. Each timestep
|
|
particles are inserted, the command will make up to a total of M tries
|
|
to insert the new particles without overlaps, where
|
|
M = # of inserted particles * ma. If unsuccessful at completing all
|
|
insertions, a warning will be printed.
|
|
</P>
|
|
<P>The <I>all_in</I> flag determines if the particle is completely contained
|
|
in the insertion region (<I>all_in = yes</I>) or only the particle center
|
|
(<I>all_in = no</I>).Using <I>all_in</I> = yes requires you to use an insertion
|
|
face of style <A HREF = "fix_mesh_surface.html">fix mesh/surface/planar</A>
|
|
</P>
|
|
<P>NOTE: You also have to use <A HREF = "fix_mesh_surface.html">fix mesh/surface/planar</A>
|
|
if there is a <A HREF = "run.html">run</A> command between the definition of the
|
|
insertion face and the fix insert/stream command. Otherwise, a
|
|
<A HREF = "fix_mesh_surface.html">fix mesh/surface/planar</A> will do.
|
|
</P>
|
|
<P>Keyword <I>random_distribute</I> controls how the number of particles to
|
|
be inserted is distributed among parallel processors and among the
|
|
particle templates in the particle distribution. For style <I>exact</I>,
|
|
the number of particles to be inserted each step is matched exactly.
|
|
For style <I>uncorrelated</I>, the number of particles to be inserted
|
|
for each particle template will be rounded in an uncorrelated way,
|
|
so the total number of inserted particles may vary for each insertion
|
|
step. However, statistically both ways should produce the same
|
|
result. Style <I>uncorrelated</I> may be faster in parallel since it
|
|
does not need global MPI operations.
|
|
Please note that if the # of particles to be inserted is calculated
|
|
e.g. from a particle mass to be inserted, the number of particles
|
|
to be inserted each insertion step will vary by 1, irrespective of
|
|
the <I>random_distribute</I> settings. This is because in this case the
|
|
# of particles to insert in each step will be a floating point number,
|
|
and applying a simple floor/ceil rounding operation would lead to a
|
|
statistical bias.
|
|
</P>
|
|
<P>If keyword <I>parallel</I> is set to 'yes', LIGGGHTS tries to pre-calculate
|
|
more accurately the overlap of process subdomains and extrusion volume.
|
|
For cases where the insertion volume is highly divided between different
|
|
processes, this can lead to a speed-up of insertion as random number generation
|
|
is more efficient. For cases where the extrusion volume is divided
|
|
among few processes this will impose a small computation overhead.
|
|
</P>
|
|
<P>The initial velocity and rotational velocity can be controlled via the
|
|
<I>vel</I> and <I>omega</I> keywords. <I>vel constant</I> simply patches a constant
|
|
velocity to the inserted particles, <I>vel uniform</I> sets uniformly distributed
|
|
velocities with mean and amplitude. <I>vel gaussian</I> sets Gaussian
|
|
distributed particle velocities with mean and std. deviation.
|
|
The insertion velocity must be non-zero.
|
|
</P>
|
|
<P><B>Restart, fix_modify, output, run start/stop, minimize info:</B>
|
|
</P>
|
|
<P>Information about this fix is written to <A HREF = "restart.html">binary restart
|
|
files</A>. This means you can restart a simulation simulation
|
|
while inserting particles, when the restart file was written during the
|
|
insertion operation.
|
|
</P>
|
|
<P>None of the <A HREF = "fix_modify.html">fix_modify</A> options are relevant to this
|
|
fix. A global vector is stored by this fix for access by various <A HREF = "Section_howto.html#4_15">output
|
|
commands</A>. The first component of the vector is the
|
|
number of particles already inserted, the second component is the mass
|
|
of particles already inserted. No parameter of this fix can be
|
|
used with the <I>start/stop</I> keywords of the <A HREF = "run.html">run</A> command.
|
|
This fix is not invoked during <A HREF = "minimize.html">energy minimization</A>.
|
|
</P>
|
|
<P><B>Restrictions:</B>
|
|
</P>
|
|
<P>Keywords <I>duration</I> and <I>extrude_length</I> can not be used together.
|
|
The insertion face cannot move.
|
|
</P>
|
|
<P><B>Related commands:</B>
|
|
</P>
|
|
<P><A HREF = "fix_insert_pack.html">fix_insert_pack</A>, <A HREF = "fix_insert_rate_region.html">fix_insert_rate_region</A>,
|
|
<A HREF = "fix_deposit.html">fix_deposit</A>, <A HREF = "fix_pour_dev.html">fix_pour_dev</A>, <A HREF = "fix_pour.html">fix_pour</A>
|
|
</P>
|
|
<P><B>Default:</B>
|
|
</P>
|
|
<P>The defaults are maxattempt = 50, all_in = no, overlapcheck = yes
|
|
vel = 0.0 0.0 0.0, omega = 0.0 0.0 0.0, start = next time-step,
|
|
duration = insert_every, random_distribute = exact, parallel = no
|
|
</P>
|
|
</HTML>
|