\(\renewcommand{\AA}{\text{Å}}\)

fix pour command

Syntax

fix ID group-ID pour N type seed keyword values ...

• ID, group-ID are documented in fix command

• pour = style name of this fix command

• N = # of particles to insert

• type = atom type to assign to inserted particles (offset for molecule insertion)

• seed = random # seed (positive integer)

• one or more keyword/value pairs may be appended to args

• keyword = region or diam or id or vol or rate or dens or vel or mol or molfrac or rigid or shake or ignore

  region value = region-ID
    region-ID = ID of region to use as insertion volume
  diam values = dstyle args
    dstyle = one or range or poly
      one args = D
        D = single diameter for inserted particles (distance units)
      range args = Dlo Dhi
        Dlo,Dhi = range of diameters for inserted particles (distance units)
      poly args = Npoly D1 P1 D2 P2 ...
        Npoly = # of (D,P) pairs
        D1,D2,... = diameter for subset of inserted particles (distance units)
        P1,P2,... = percentage of inserted particles with this diameter (0-1)
  id values = idflag
    idflag = max or next = how to choose IDs for inserted particles and molecules
  vol values = fraction Nattempt
    fraction = desired volume fraction for filling insertion volume
    Nattempt = max # of insertion attempts per particle
  rate value = V
    V = z velocity (3d) or y velocity (2d) at which
        insertion volume moves (velocity units)
  dens values = Rholo Rhohi
    Rholo,Rhohi = range of densities for inserted particles (mass/volume units)
  vel values (3d) = vxlo vxhi vylo vyhi vz
  vel values (2d) = vxlo vxhi vy
    vxlo,vxhi = range of x velocities for inserted particles (velocity units)
    vylo,vyhi = range of y velocities for inserted particles (velocity units)
    vz = z velocity (3d) assigned to inserted particles (velocity units)
    vy = y velocity (2d) assigned to inserted particles (velocity units)
  mol value = template-ID
    template-ID = ID of molecule template specified in a separate molecule command
  molfrac values = f1 f2 ... fN
    f1 to fN = relative probability of creating each of N molecules in template-ID
  rigid value = fix-ID
    fix-ID = ID of fix rigid/small command
  shake value = fix-ID
    fix-ID = ID of fix shake command
  ignore value = none
    skip any line or triangle particles when detecting possible
      overlaps with inserted particles

Examples

fix 3 all pour 1000 2 29494 region myblock
fix 2 all pour 10000 1 19985583 region disk vol 0.33 100 rate 1.0 diam range 0.9 1.1
fix 2 all pour 10000 1 19985583 region disk diam poly 2 0.7 0.4 1.5 0.6
fix ins all pour 500 1 4767548 vol 0.8 10 region slab mol object rigid myRigid

Description

Insert finite-size particles or molecules into the simulation box every few timesteps within a specified region until N particles or molecules have been inserted. This is typically used to model the pouring of granular particles into a container under the influence of gravity. For the remainder of this doc page, a single inserted atom or molecule is referred to as a “particle”.

If inserted particles are individual atoms, they are assigned the specified atom type. If they are molecules, the type of each atom in the inserted molecule is specified in the file read by the molecule command, and those values are added to the specified atom type. E.g. if the file specifies atom types 1,2,3, and those are the atom types you want for inserted molecules, then specify type = 0. If you specify type = 2, the in the inserted molecule will have atom types 3,4,5.

All atoms in the inserted particle are assigned to two groups: the default group “all” and the group specified in the fix pour command (which can also be “all”).

This command must use the region keyword to define an insertion volume. The specified region must have been previously defined with a region command. It must be of type block or a z-axis cylinder and must be defined with side = in. The cylinder style of region can only be used with 3d simulations.

Individual atoms are inserted, unless the mol keyword is used. It specifies a template-ID previously defined using the molecule command, which reads a file that defines the molecule. The coordinates, atom types, center-of-mass, moments of inertia, etc, as well as any bond/angle/etc and special neighbor information for the molecule can be specified in the molecule file. See the molecule command for details. The only settings required to be in this file are the coordinates and types of atoms in the molecule.

If the molecule template contains more than one molecule, the relative probability of depositing each molecule can be specified by the molfrac keyword. N relative probabilities, each from 0.0 to 1.0, are specified, where N is the number of molecules in the template. Each time a molecule is inserted, a random number is used to sample from the list of relative probabilities. The N values must sum to 1.0.

If you wish to insert molecules via the mol keyword, that will be treated as rigid bodies, use the rigid keyword, specifying as its value the ID of a separate fix rigid/small command which also appears in your input script.

Note

If you wish the new rigid molecules (and other rigid molecules) to be thermostatted correctly via fix rigid/small/nvt or fix rigid/small/npt, then you need to use the fix_modify dynamic/dof yes command for the rigid fix. This is to inform that fix that the molecule count will vary dynamically.

If you wish to insert molecules via the mol keyword, that will have their bonds or angles constrained via SHAKE, use the shake keyword, specifying as its value the ID of a separate fix shake command which also appears in your input script.

Each timestep particles are inserted, they are placed randomly inside the insertion volume so as to mimic a stream of poured particles. If they are molecules they are also oriented randomly. Each atom in the particle is tested for overlaps with existing particles, including effects due to periodic boundary conditions if applicable. If an overlap is detected, another random insertion attempt is made; see the vol keyword discussion below. The larger the volume of the insertion region, the more particles that can be inserted at any one timestep. Particles are inserted again after enough time has elapsed that the previously inserted particles fall out of the insertion volume under the influence of gravity. Insertions continue every so many timesteps until the desired # of particles has been inserted.

Note

If you are monitoring the temperature of a system where the particle count is changing due to adding particles, you typically should use the compute_modify dynamic/dof yes command for the temperature compute you are using.

Implementation Notes

The exact insertion procedure depends on many factors (e.g. the range of diameters inserted or whether molecules are being inserted). However, in the simplest scenario of monodisperse atoms, the procedure works as follows. First, the number of timesteps between two insertion events is calculated as the time for a particle to fall through the insertion region, accounting for gravity and any region motion. Next, the target number of particles inserted per event (assuming no failed insertions due to overlaps) is calculated as the product of the volume fraction and the volume of the insertion region divided by the volume of a particle (or area in 2D). Events are repeated until all N particles have been inserted, where the final event is likely interrupted upon reaching N. Estimates of this process are printed to the log/screen at the start of a run.

---

All other keywords are optional with defaults as shown below.

The diam option is only used when inserting atoms and specifies the diameters of inserted particles. There are 3 styles: one, range, or poly. For one, all particles will have diameter D. For range, the diameter of each particle will be chosen randomly and uniformly between the specified Dlo and Dhi bounds. For poly, a series of Npoly diameters is specified. For each diameter a percentage value from 0.0 to 1.0 is also specified. The Npoly percentages must sum to 1.0. For the example shown above with “diam 2 0.7 0.4 1.5 0.6”, all inserted particles will have a diameter of 0.7 or 1.5. 40% of the particles will be small; 60% will be large.

Note that for molecule insertion, the diameters of individual atoms in the molecule can be specified in the file read by the molecule command. If not specified, the diameter of each atom in the molecule has a default diameter of 1.0.

The id option has two settings which are used to determine the atom or molecule IDs to assign to inserted particles/molecules. In both cases a check is done of the current system to find the maximum current atom and molecule ID of any existing particle. Newly inserted particles and molecules are assigned IDs that increment those max values. For the max setting, which is the default, this check is done at every insertion step, which allows for particles to leave the system, and their IDs to potentially be re-used. For the next setting this check is done only once when the fix is specified, which can be more efficient if you are sure particles will not be added in some other way.

The vol option specifies what volume fraction of the insertion volume will be filled with particles. For particles with a size specified by the diam range keyword, they are assumed to all be of maximum diameter Dhi for purposes of computing their contribution to the volume fraction.

The higher the volume fraction value, the more particles are inserted each timestep. Since inserted particles cannot overlap, the maximum volume fraction should be no higher than about 0.6. Each timestep particles are inserted, LAMMPS will make up to a total of M tries to insert the new particles without overlaps, where M = # of inserted particles * Nattempt. If LAMMPS is unsuccessful at completing all insertions, it prints a warning.

The dens and vel options enable inserted particles to have a range of densities or xy velocities. The specific values for a particular inserted particle will be chosen randomly and uniformly between the specified bounds. Internally, the density value for a particle is converted to a mass, based on the radius (volume) of the particle. The vz or vy value for option vel assigns a z-velocity (3d) or y-velocity (2d) to each inserted particle.

The rate option moves the insertion volume in the z direction (3d) or y direction (2d). This enables pouring particles from a successively higher height over time.

The ignore option is useful when running a simulation that used line segment (2d) or triangle (3d) particles, typically to define boundaries for spherical granular particles to interact with. See the atom_style line or tri command for details. Lines and triangles store their size, and if the size is large it may overlap (in a spherical sense) with the insertion region, even if the line/triangle is oriented such that there is no actual overlap. This can prevent particles from being inserted. The ignore keyword causes the overlap check to skip any line or triangle particles. Obviously you should only use it if there is in fact no overlap of the line or triangle particles with the insertion region.

---

Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. This means you must be careful when restarting a pouring simulation, when the restart file was written in the middle of the pouring operation. Specifically, you should use a new fix pour command in the input script for the restarted simulation that continues the operation. You will need to adjust the arguments of the original fix pour command to do this.

Also note that because the state of the random number generator is not saved in restart files, you cannot do “exact” restarts with this fix, where the simulation continues on the same as if no restart had taken place. However, in a statistical sense, a restarted simulation should produce the same behavior if you adjust the fix pour parameters appropriately.

None of the fix_modify options are relevant to this fix. This fix computes a global scalar, which can be accessed by various output commands. The scalar is the cumulative number of insertions. The scalar value calculated by this fix is “intensive”. No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.

Restrictions

This fix is part of the GRANULAR package. It is only enabled if LAMMPS was built with that package. See the Build package page for more info.

For 3d simulations, a gravity fix in the -z direction must be defined for use in conjunction with this fix. For 2d simulations, gravity must be defined in the -y direction.

The specified insertion region cannot be a “dynamic” region, as defined by the region command.

Related commands

fix deposit, fix gravity, region

Default

Insertions are performed for individual particles, i.e. no mol setting is defined. If the mol keyword is used, the default for molfrac is an equal probabilities for all molecules in the template. Additional option defaults are diam = one 1.0, dens = 1.0 1.0, vol = 0.25 50, rate = 0.0, vel = 0.0 0.0 0.0 0.0 0.0 (for 3d), vel = 0.0 0.0 0.0 (for 2d), and id = max.