Syntax:
fix ID group-ID ave/spatial Nevery Nrepeat Nfreq dim origin delta value1 value2 ... keyword args ...
x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (velocity, force component) density/number, density/mass = number or mass density c_ID = per-atom scalar value calculated by a compute with ID c_ID[N] = Nth component of per-atom vector calculated by a compute with ID f_ID = per-atom scalar value calculated by a fix with ID f_ID[N] = Nth component of per-atom vector calculated by a fix with ID v_name = per-atom value calculated by an atom-style variable with name
units arg = box or lattice or reduced norm arg = all or sample file arg = filename filename = file to write results to ave args = one or running or window M one = output new average value every Nfreq steps running = output cummulative average of all previous Nfreq steps window M = output average of M most recent Nfreq steps
Examples:
fix 1 all ave/spatial 10000 1 10000 z lower 0.02 myCentro units reduced fix 1 flow ave/spatial 100 10 1000 y 0.0 1.0 vx vz norm sample file vel.profile fix 1 flow ave/spatial 100 5 1000 y 0.0 2.5 density/mass ave running
Description:
Calculate one or more instantaneous per-atom quantities every few timesteps, average them by layer in a chosen dimension, and average the layer values over a longer timescale. The resulting averages can be used by other output commands such as thermo_style custom, and can also be written to a file.
Each listed value is averaged independently. The group specified with the command means only atoms within the group contribute to the layer averages.
Each listed value can be an atom attribute (position, velocity, force component), a mass or number density, or the result of a compute or fix or the evaluation of an atom-style variable. In the latter cases, the compute, fix, or variable must produce a per-atom quantity, not a global quantity. If you wish to time-average global quantities from a compute, fix, or variable, then see the fix ave/time command.
Computes that produce per-atom quantities are those which have the word atom in their style name. See the doc pages for individual fixes to determine which ones produce per-atom quantities. Variables of style atom are the only ones that can be used with this fix since all other styles of variable produce global quantities.
The Nevery, Nrepeat, and Nfreq arguments specify on what timesteps the layer values will be generated in order to contribute to the average. The final averaged quantities are generated every Nfreq timesteps. The average is over Nrepeat quantities, computed in the preceeding portion of the simulation every Nevery timesteps. Nfreq must be a multiple of Nevery and Nevery must be non-zero even if Nrepeat is 1.
For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on timesteps 90,92,94,96,98,100 will be used to compute the final average on timestep 100. Similary for timesteps 190,192,194,196,198,200 on timestep 200, etc. If Nrepeat=1 and Nfreq = 100, then no time averaging is done; values are simply generated on timesteps 100,200,etc.
Each per-atom property is also averaged over atoms in each layer, where the layers are in a particular dim and have a thickness given by delta. Every Nfreq steps, when an averaging is being performed and the per-atom property is calculated for the first time, the number of layers and the layer boundaries are computed. Thus if the simlation box changes size during a simulation, the number of layers and their boundaries may also change. Layers are defined relative to a specified origin, which may be the lower/upper edge of the box (in dim) or its center point, or a specified coordinate value. Starting at the origin, sufficient layers are created in both directions to completely cover the box. On subsequent timesteps every atom is mapped to one of the layers. Atoms beyond the lowermost/uppermost layer are counted in the first/last layer.
For orthogonal simulation boxes, the layers are "slices" aligned with the xyz coordinate axes. For non-orthogonal (triclinic) simulation boxes, the layers are "tilted slices" that are parallel to the tilted faces of the box. See the region prism command for a discussion of the geometry of tilted boxes in LAMMPS. As described there, a tilted simulation box has edge vectors a,b,c. In that nomenclature, layers in the x dimension have faces with normals in the "b" cross "c" direction. Layers in y have faces normal to the "a" cross "c" direction. And layers in z have faces normal to the "a" cross "b" direction. Note that in order to define the thickness and position of these tilted layers in an unambiguous fashion, the units option must be set to reduced when using a non-orthogonal simulation box, as discussed below.
The atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are self-explanatory.
The density/number value means the number density is computed in each layer, i.e. a weighting of 1 for each atom. The density/mass value means the mass density is computed in each layer, i.e. each atom is weighted by its mass. The resulting density is normalized by the volume of the layer so that units of number/volume or mass/volume are output.
If a value begins with "c_", a compute ID must follow which has been previously defined in the input script. If no bracketed term is appended, the per-atom scalar calculated by the compute is used. If a bracketed term is appended, the Nth vector per-atom value calculated by the compute is used. Users can also write code for their own compute styles and add them to LAMMPS.
If a value begins with "f_", a fix ID must follow which has been previously defined in the input script. If no bracketed term is appended, the per-atom scalar calculated by the fix is used. If a bracketed term is appended, the Nth vector per-atom value calculated by the fix is used. Note that some fixes only produce their values on certain timesteps, which must be compatible with Nevery, else an error results. Users can also write code for their own fix styles and add them to LAMMPS.
If a value begins with "v_", a variable name must follow which has been previously defined in the input script. Variables of style atom can reference thermodynamic keywords, or invoke other computes, fixes, or variables when they are evaluated, so this is a very general means of generating per-atom quantities to spatially average.
Additional optional keywords also affect the operation of this fix.
The units keyword determines the meaning of the distance units used for the layer thickness delta and for origin if it is a coordinate value. For orthogonal simulation boxes, any of the 3 options may be used. For non-orthogonal (triclinic) simulation boxes, only the reduced option may be used.
A box value selects standard distance units as defined by the units command, e.g. Angstroms for units = real or metal. A lattice value means the distance units are in lattice spacings. The lattice command must have been previously used to define the lattice spacing. A reduced value means normalized unitless values between 0 and 1, which represent the lower and upper faces of the simulation box respectively. Thus an origin value of 0.5 means the center of the box in any dimension. A delta value of 0.1 means 10 layers span the box in any dimension.
Consider a non-orthogonal box, with layers in the x dimension. No matter how the box is tilted, an origin of 0.0 means start layers at the lower "b" cross "c" plane of the simulation box and an origin of 1.0 means to start layers at the upper "b" cross "c" face of the box. A delta value of 0.1 means there will be 10 layers from 0.0 to 1.0, regardless of the current size or shape of the simulation box.
The norm keyword affects how averaging is done for the output produced every Nfreq timesteps. For an all setting, a layer quantity is summed over all atoms in all Nrepeat samples, as is the count of atoms in the layer. The printed value for the layer is Total-quantity / Total-count. In other words it is an average over the entire Nfreq timescale.
For a sample setting, the layer quantity is summed over atoms for only a single sample, as is the count, and a "average sample value" is computed, i.e. Sample-quantity / Sample-count. The printed value for the layer is the average of the Nrepeat "average sample values", In other words it is an average of an average.
The file keyword allows a filename to be specified. Every Nfreq timesteps, layer info will be written to a text file in the following format. A line with the timestep and number of layers is written. Then one line per layer is written, containing the layer ID (1-N), the coordinate of the center of the layer, the number of atoms in the layer, and one or more calculated values. The number of values in each line corresponds to the number of values specified in the fix ave/spatial command. The number of atoms and the value(s) are average quantities. If the value of the units keyword is box or lattice, the "coord" is printed in box units. If the value of the units keyword is reduced, the "coord" is printed in reduced units (0-1).
The ave keyword determines how the layer values produced every Nfreq steps are averaged with layer values produced on previous steps that were multiples of Nfreq, before they are accessed by another output command or written to a file.
If the ave setting is one, then the layuer values produced on timesteps that are multiples of Nfreq are independent of each other; they are output as-is without further averaging.
If the ave setting is running, then the layer values produced on timesteps that are multiples of Nfreq are summed and averaged in a cummulative sense before being output. Each output layer value is thus the average of the layer value produced on that timestep with all preceeding values for the same layer. This running average begins when the fix is defined; it can only be restarted by deleting the fix via the unfix command, or re-defining the fix by re-specifying it.
If the ave setting is window, then the layer values produced on timesteps that are multiples of Nfreq are summed and averaged within a moving "window" of time, so that the last M values for the same layer are used to produce the output. E.g. if M = 3 and Nfreq = 1000, then the output on step 10000 will be the average of the individual layer values on steps 8000,9000,10000. Outputs on early steps will average over less than M values if they are not available.
Restart, fix_modify, output, run start/stop, minimize info:
No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.
This fix computes a global vector of quantities which can be accessed by various output commands. The values can only be accessed on timesteps that are multiples of Nfreq since that is when averaging is performed. The global vector is of length N = nlayers*nvalues where nlayers is the number of layers and nvalues is the number of values per layer that the fix is averaging. When accessed by another output command, a single index M is specified which is mapped into a layer I as I = M / nvalues + 1 and into value J as J = M % nvalues + 1. If I exceeds the current number of layers than a 0.0 is returned by the fix instead of an error, since the number of layers can vary as a simulation runs, depending on the simulation box size. The vector values calculated by this fix are "intensive", meaning they are independent of the number of atoms in the simulation, since they are already normalized by the count of atoms in each layer.
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:
When the ave keyword is set to running or window then the number of layers must remain the same during the simulation, so that the appropriate averaging can be done. This will be the case if the simulation box size doesn't change or if the units keyword is set to reduced.
Related commands:
Default:
The option defaults are units = lattice, norm = all, no file output, and ave = one.