doc/src/fix_ave_atom.txt

   1 "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
   2
   3 :link(lws,http://lammps.sandia.gov)
   4 :link(ld,Manual.html)
   5 :link(lc,Section_commands.html#comm)
   6
   7 :line
   8
   9 fix ave/atom command :h3
  10
  11 [Syntax:]
  12
  13 fix ID group-ID ave/atom Nevery Nrepeat Nfreq value1 value2 ... :pre
  14
  15 ID, group-ID are documented in "fix"_fix.html command :ulb,l
  16 ave/atom = style name of this fix command :l
  17 Nevery = use input values every this many timesteps :l
  18 Nrepeat = # of times to use input values for calculating averages :l
  19 Nfreq = calculate averages every this many timesteps
  20 one or more input values can be listed :l
  21 value = x, y, z, vx, vy, vz, fx, fy, fz, c_ID, c_ID\[i\], f_ID, f_ID\[i\], v_name :l
  22   x,y,z,vx,vy,vz,fx,fy,fz = atom attribute (position, velocity, force component)
  23   c_ID = per-atom vector calculated by a compute with ID
  24   c_ID\[I\] = Ith column of per-atom array calculated by a compute with ID, I can include wildcard (see below)
  25   f_ID = per-atom vector calculated by a fix with ID
  26   f_ID\[I\] = Ith column of per-atom array calculated by a fix with ID, I can include wildcard (see below)
  27   v_name = per-atom vector calculated by an atom-style variable with name :pre
  28 :ule
  29
  30 [Examples:]
  31
  32 fix 1 all ave/atom 1 100 100 vx vy vz
  33 fix 1 all ave/atom 10 20 1000 c_my_stress\[1\]
  34 fix 1 all ave/atom 10 20 1000 c_my_stress\[*\] :pre
  35
  36 [Description:]
  37
  38 Use one or more per-atom vectors as inputs every few timesteps, and
  39 average them atom by atom over longer timescales.  The resulting
  40 per-atom averages can be used by other "output
  41 commands"_Section_howto.html#howto_15 such as the "fix
  42 ave/chunk"_fix_ave_chunk.html or "dump custom"_dump.html commands.
  43
  44 The group specified with the command means only atoms within the group
  45 have their averages computed.  Results are set to 0.0 for atoms not in
  46 the group.
  47
  48 Each input value can be an atom attribute (position, velocity, force
  49 component) or can be the result of a "compute"_compute.html or
  50 "fix"_fix.html or the evaluation of an atom-style
  51 "variable"_variable.html.  In the latter cases, the compute, fix, or
  52 variable must produce a per-atom vector, not a global quantity or
  53 local quantity.  If you wish to time-average global quantities from a
  54 compute, fix, or variable, then see the "fix
  55 ave/time"_fix_ave_time.html command.
  56
  57 Each per-atom value of each input vector is averaged independently.
  58
  59 "Computes"_compute.html that produce per-atom vectors or arrays are
  60 those which have the word {atom} in their style name.  See the doc
  61 pages for individual "fixes"_fix.html to determine which ones produce
  62 per-atom vectors or arrays.  "Variables"_variable.html of style {atom}
  63 are the only ones that can be used with this fix since they produce
  64 per-atom vectors.
  65
  66 Note that for values from a compute or fix, the bracketed index I can
  67 be specified using a wildcard asterisk with the index to effectively
  68 specify multiple values.  This takes the form "*" or "*n" or "n*" or
  69 "m*n".  If N = the size of the vector (for {mode} = scalar) or the
  70 number of columns in the array (for {mode} = vector), then an asterisk
  71 with no numeric values means all indices from 1 to N.  A leading
  72 asterisk means all indices from 1 to n (inclusive).  A trailing
  73 asterisk means all indices from n to N (inclusive).  A middle asterisk
  74 means all indices from m to n (inclusive).
  75
  76 Using a wildcard is the same as if the individual columns of the array
  77 had been listed one by one.  E.g. these 2 fix ave/atom commands are
  78 equivalent, since the "compute stress/atom"_compute_stress_atom.html
  79 command creates a per-atom array with 6 columns:
  80
  81 compute my_stress all stress/atom NULL
  82 fix 1 all ave/atom 10 20 1000 c_my_stress\[*\]
  83 fix 1 all ave/atom 10 20 1000 c_my_stress\[1\] c_my_stress\[1\] &
  84                               c_my_stress\[3\] c_my_stress\[4\] &
  85                               c_my_stress\[5\] c_my_stress\[6\] :pre
  86
  87 :line
  88
  89 The {Nevery}, {Nrepeat}, and {Nfreq} arguments specify on what
  90 timesteps the input values will be used in order to contribute to the
  91 average.  The final averaged quantities are generated on timesteps
  92 that are a multiple of {Nfreq}.  The average is over {Nrepeat}
  93 quantities, computed in the preceding portion of the simulation every
  94 {Nevery} timesteps.  {Nfreq} must be a multiple of {Nevery} and
  95 {Nevery} must be non-zero even if {Nrepeat} is 1.  Also, the timesteps
  96 contributing to the average value cannot overlap,
  97 i.e. Nrepeat*Nevery can not exceed Nfreq.
  98
  99 For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then values on
 100 timesteps 90,92,94,96,98,100 will be used to compute the final average
 101 on timestep 100.  Similarly for timesteps 190,192,194,196,198,200 on
 102 timestep 200, etc.
 103
 104 :line
 105
 106 The atom attribute values (x,y,z,vx,vy,vz,fx,fy,fz) are
 107 self-explanatory.  Note that other atom attributes can be used as
 108 inputs to this fix by using the "compute
 109 property/atom"_compute_property_atom.html command and then specifying
 110 an input value from that compute.
 111
 112 NOTE: The x,y,z attributes are values that are re-wrapped inside the
 113 periodic box whenever an atom crosses a periodic boundary.  Thus if
 114 you time average an atom that spends half its time on either side of
 115 the periodic box, you will get a value in the middle of the box.  If
 116 this is not what you want, consider averaging unwrapped coordinates,
 117 which can be provided by the "compute
 118 property/atom"_compute_property_atom.html command via its xu,yu,zu
 119 attributes.
 120
 121 If a value begins with "c_", a compute ID must follow which has been
 122 previously defined in the input script.  If no bracketed term is
 123 appended, the per-atom vector calculated by the compute is used.  If a
 124 bracketed term containing an index I is appended, the Ith column of
 125 the per-atom array calculated by the compute is used.  Users can also
 126 write code for their own compute styles and "add them to
 127 LAMMPS"_Section_modify.html.  See the discussion above for how I can
 128 be specified with a wildcard asterisk to effectively specify multiple
 129 values.
 130
 131 If a value begins with "f_", a fix ID must follow which has been
 132 previously defined in the input script.  If no bracketed term is
 133 appended, the per-atom vector calculated by the fix is used.  If a
 134 bracketed term containing an index I is appended, the Ith column of
 135 the per-atom array calculated by the fix is used.  Note that some
 136 fixes only produce their values on certain timesteps, which must be
 137 compatible with {Nevery}, else an error will result.  Users can also
 138 write code for their own fix styles and "add them to
 139 LAMMPS"_Section_modify.html.  See the discussion above for how I can
 140 be specified with a wildcard asterisk to effectively specify multiple
 141 values.
 142
 143 If a value begins with "v_", a variable name must follow which has
 144 been previously defined in the input script as an "atom-style
 145 variable"_variable.html Variables of style {atom} can reference
 146 thermodynamic keywords, or invoke other computes, fixes, or variables
 147 when they are evaluated, so this is a very general means of generating
 148 per-atom quantities to time average.
 149
 150 :line
 151
 152 [Restart, fix_modify, output, run start/stop, minimize info:]
 153
 154 No information about this fix is written to "binary restart
 155 files"_restart.html.  None of the "fix_modify"_fix_modify.html options
 156 are relevant to this fix.  No global scalar or vector quantities are
 157 stored by this fix for access by various "output
 158 commands"_Section_howto.html#howto_15.
 159
 160 This fix produces a per-atom vector or array which can be accessed by
 161 various "output commands"_Section_howto.html#howto_15.  A vector is
 162 produced if only a single quantity is averaged by this fix.  If two or
 163 more quantities are averaged, then an array of values is produced.
 164 The per-atom values can only be accessed on timesteps that are
 165 multiples of {Nfreq} since that is when averaging is performed.
 166
 167 No parameter of this fix can be used with the {start/stop} keywords of
 168 the "run"_run.html command.  This fix is not invoked during "energy
 169 minimization"_minimize.html.
 170
 171 [Restrictions:] none
 172
 173 [Related commands:]
 174
 175 "compute"_compute.html, "fix ave/histo"_fix_ave_histo.html, "fix
 176 ave/chunk"_fix_ave_chunk.html, "fix ave/time"_fix_ave_time.html,
 177 "variable"_variable.html,
 178
 179 [Default:] none